oneWEX検証メモ - (7)REST API

#はじめに

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

##関連記事

インストール関連
[oneWEX導入メモ / Ubuntu編](https://qiita.com/tomotagwork/items/bdd48adf45140b584678)
[oneWEX導入メモ / RHEL7.6 オフライン編](https://qiita.com/tomotagwork/items/6ad047d0b72e199b7878)

検索関連
[oneWEX検証メモ - (0) 概要理解](https://qiita.com/tomotagwork/items/2c00007f45a3d2e482ea)
[oneWEX検証メモ - (1)ファイルシステムクローラーによるデータの取り込み / データセット、コレクションの作成](https://qiita.com/tomotagwork/items/00301322d4336b52d1e3)
[oneWEX検証メモ - (2)Windowsファイルシステムクローラーによるデータの取り込み](https://qiita.com/tomotagwork/items/1619624af8a64cf330d4)
[oneWEX検証メモ - (3)ContentMinerによる文書の検索](https://qiita.com/tomotagwork/items/24b5bbcc85c6bada41da)
[oneWEX検証メモ - (4)ApplicationBuilderによるWebアプリの作成と文書の検索](https://qiita.com/tomotagwork/items/a53b2c7f52cb1dcb68d9)

分析関連
[oneWEX検証メモ - (5)ContentMinerによる分析 / ガイド付きモード](https://qiita.com/tomotagwork/items/a9c381a477594453e2b1)
[oneWEX検証メモ - (6)ContentMinerによる分析 / 各種"ID情報"をベースとした分析](https://qiita.com/tomotagwork/items/9269fd31109638e6dd89)

API関連
[oneWEX検証メモ - (7)REST API](https://qiita.com/tomotagwork/items/7c1340f41333896f8fe3)


# API Reference

さて、そもそもどういうAPIが提供されているのかReferenceを見てみようと思ったら...
参考: [Watson Explorer API](https://www.ibm.com/support/knowledgecenter/ja/SS8NLW_12.0.0/com.ibm.watson.wex.ee.doc/c_ce_api.html)

>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](https://github.com/tomotagwork/WEXTest01/blob/master/api/wex-public-apis.yaml)

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

![Screen Shot 2019-08-28 at 16.05.47-fullpage.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/132331/e98749c3-ae24-07a5-9b4e-b6dd92ed1864.png)

# 検索を試す

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

>Query syntax is based on [Apache Solr's Extended Dismax Query Parser](https://lucene.apache.org/solr/guide/7_4/the-extended-dismax-query-parser.html).
Query response writer 'csv_facet' also use parameter in [CSV Parameters](https://lucene.apache.org/solr/guide/7_4/response-writers.html#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](https://github.com/tomotagwork/WEXTest01/blob/master/api/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周りのドキュメントもあまり充実していないようで、使いこなすのがなかなか難しいですねぇ...。