はじめに

oneWEXを使ってみた時のメモです。
ここでは、oneWEXが提供するREST APIを試してみたいと思います。

API Reference

さて、そもそもどういうAPIが提供されているのかReferenceを見てみようと思ったら...
参考: Watson Explorer API

IBM Watson® Explorer をインストールすると、Watson™ Explorer を自動化するための REST API を使用できるようになります。
RST API の資料には、URL https://<hostname>/docs/ からアクセスできます。このページから、使用可能な REST コマンドを参照したり、Web ページで試したりできます。

おおっと！お金払って製品を購入して、インストールして、起動して、そこにアクセスしたら、ようやくAPI Referenceにたどり着けるってか。そこまでしないとReferenceも見せてはくれないのね。優しくないですねぇ。

oneWEXの環境の、https://<hostname>/docs/wex-public-apis.yaml にswagger文書が提供されていたので(このファイル名もマニュアルに書いてくれていないという...)、以下にアップしておきました。
wex-public-apis.yaml

Swagger UI

oneWEXを起動して、https://<hostname>/docs/にアクセスすると、Swagger UIでAPIが確認できます。
簡易的なテストもできます。

検索を試す

検索のAPIはExplorationという所にあるやつを使えばよさそうです。

Query syntax is based on Apache Solr's Extended Dismax Query Parser.
Query response writer 'csv_facet' also use parameter in CSV Parameters except csv.header and csv.null.
Basic query examples:
- Free text search
Query: computer software
Result: Returns engine defined processing. Linguistic processing will be applied to the whole query string.
- Boolean search (AND)
Query: (computer AND software)
Result: Returns documents including both words of computer and software. Note that linguistic processing is applied separately to each keyword.
- Boolean search (OR)
Query: (computer OR software)
Result: Returns documents including either word of computer or software. Note that linguistic processing is applied separately to each keyword.
- Phrase search
Query: "computer software"
Result: Returns documents including a pharse "computer software". Note that words in the phrase must appear in the specified order.
- Field search
Query: lastname:smith div:software
Result: Returns all documents about employees with the last name Smith (lastname:smith) who work for the Software division (div:software).
- Wildcard search
Query: app*
Result: Finds documents that include terms beginning app such as apple, apples, application.
It is not guaranteed all variations of terms are expanded and searched.
Especially wildcard terms starting * easily reach that expansion limit and cause slow performance.

とりあえず検索用のAPIはこんな感じ。
/api/v1/explore/{collectionId}/query
QueryStringとして必須なのはqで検索キーワードを指定します。
collectionIdは、検索対象のコレクションのID(作成時に動的に割り当てられるID)です。

とりあえず、検索キーワードとして"トランザクション"を指定するケースだと、こんな感じのcurlリクエストが作成されます。

curl -X GET "https://aha00527/api/v1/explore/e8d1c521-b10b-f9be-0000-016ccd54e938/query?q=%E3%83%88%E3%83%A9%E3%83%B3%E3%82%B6%E3%82%AF%E3%82%B7%E3%83%A7%E3%83%B3&facet.stats=none&facet.mincount=1" -H  "accept: application/json"

json形式で以下のような結果が返されます。
api_exploration_result01.json (サイズが大きのでファイルで添付)

このAPIのパラメーターでsortというのが指定できるようで、結果のソート順を変更できそうなんですが...。説明を見ると、こんな感じになっています。

Specifies sort fields of search results in either ascending (asc) or descending (desc) order. For example, “genre asc, price asc” sorts by the contents of the genre field in descending order, then within those results sorts in ascending order by the contents of the price field. By default, relevancy is used as the only sort key.

デフォルトだと"relevancy"がソートキーとして使われると書いてある。が、sortを何も指定せずにAPI発行して、返された結果を見ると、"relevancy"なんていうフィールドは無さそうで、一体何の順で返されているのかが不明でした。

おまけ

AppBuilderのウィジェットを使った時に、内部的にどのようなAPIが発行されているのか追ってみると、一部Swaggerに載っていないAPIが出されてるっぽい。

例えば...
"照会の推奨"ウィジェットでは以下のようなAPIが使われているらしい。

https://aha00527/api/v1/explore/e8d1c521-b10b-f9be-0000-016ccd54e938/assist/candidates?q=%22A002%22&facet.limit=100&num=10&pos=true&shortCircuit=false&wt=json

"クラスタリング"ウィジェットでは以下のようなAPIが使われているらしい。

https://aha00527/api/v1/explore/e8d1c521-b10b-f9be-0000-016cf471ac66/query?q=*%3A*&start=0&rows=250&fl=id&userid=admin&hl.defaultSummary=true&clustering=true&fl=id&hl=false

Swagger文書には、explore/{collectionId}/assist というAPIも、explore/{collectionId}/queryのclustering=trueオプションも載ってないんですが、コレを素で流すとちゃんと結果返ってきた...。
んー、提供されているAPIを使って独自アプリを作るってのが現実解だと思ったのですが、API周りのドキュメントもあまり充実していないようで、使いこなすのがなかなか難しいですねぇ...。

oneWEX検証メモ - (7)REST API

はじめに

関連記事

API Reference

Swagger UI

検索を試す

おまけ