Discovery Premium やってみた 〜APIでプロジェクト作成からクエリーまで〜

# 目次
はじめに
前提
1.プロジェクト作成
2.コレクション作成
3.文書追加
4.クエリー
おわりに
参考情報


# はじめに
IBMの自然言語処理系の製品であるDiscovery Premium。
いざ使ってみよう！と公式の[API DOC](https://cloud.ibm.com/apidocs/discovery-data#introduction)を参照すると、RequestはおろかResponseのSampleも載っていない場合が多い。
ということで、APIでProject作成してコレクション追加してクエリーを投げるところまでやってみました。

# 前提
以下の環境・読者を想定しています。

* Discovery Premiumが利用可能な状態である
* curlコマンドが使える（この記事はcurlを使ってRequestを送っています）


# 1.プロジェクト作成


プロジェクト作成と、作成したプロジェクトの一覧の取得をしてみます。

* プロジェクト作成

[API DOC](https://cloud.ibm.com/apidocs/discovery-data#createproject)によると、以下のパラメータを設定するらしい。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/135365/dbe56d1a-f4a2-7291-4675-82b6adeb2167.png)


```curl:CreateProjects
curl -v -H "Content-Type: application/json" "X-Accept: application/json" POST -d '{"name":"api_project2","type":"content_mining"}' -u "apikey:xxxxxxxxxxxxxxxxxxxxxxxxxx" "https://api.jp-tok.discovery.watson.cloud.ibm.com/instances/xxxxxxxxxxxxxxxxxxxxxxxxxxx/v2/projects?version=2019-11-29"
```

<details><summary>結果</summary><div>

```response:CreateProjects.json
{
  "project_id" : "xxxxxxxxxxxxxxxxxxxxxxxxxx",
  "type" : "content_mining",
  "name" : "api_project2",
  "collection_count" : 0,
  "default_query_parameters" : {
    "aggregation" : "",
    "count" : 10,
    "sort" : "",
    "return" : [ ],
    "passages" : {
      "enabled" : false,
      "count" : 10,
      "fields" : [ "text", "title" ],
      "characters" : 200,
      "per_document" : true,
      "max_per_document" : 1,
      "find_answers" : false,
      "max_answers_per_passage" : 1
    },
    "highlight" : false,
    "spelling_suggestions" : true,
    "table_results" : {
      "enabled" : false,
      "count" : 10,
      "per_document" : 0
    },
    "suggested_refinements" : {
      "enabled" : false,
      "count" : 10
    }
  }
* Connection #1 to host api.jp-tok.discovery.watson.cloud.ibm.com left intact
```

</div></details>

GUIの方で見てみると、作成されていることがわかります。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/135365/630832d9-48b1-26f8-a98d-49408c5ae4dd.png)


# 2.コレクション作成
[API DOC](https://cloud.ibm.com/apidocs/discovery-data#createcollection)によると、以下のパラメータを設定するようです。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/135365/f92bcf01-9ffe-7a62-97b4-0898bc65f1b8.png)

```curl:CreateCollection
curl -v -H "Content-Type: application/json" "X-Accept: application/json" -X POST -d '{"name":"api_sample_collection","description":"created by api","language":"ja"}' -u "apikey:xxxxxxxxxxxxxxxxxxx" "https://api.jp-tok.discovery.watson.cloud.ibm.com/instances/xxxxxxxxxxxxxxxxx/v2/projects/xxxxxxxxxxxxxxxxxxxx/collections?version=2019-11-29"

```

<details><summary>結果</summary><div>
{
  "name" : "api_sample_collection",
  "collection_id" : "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "description" : "created by api",
  "created" : "2021-05-06T06:49:20.506Z",
  "language" : "ja",
  "enrichments" : [ {
    "enrichment_id" : "701db916-fc83-57ab-0000-000000000002",
    "fields" : [ "text" ]
  } ]
* Connection #0 to host api.jp-tok.discovery.watson.cloud.ibm.com left intact

</div></details>

# 3.文書追加
[API DOC](https://cloud.ibm.com/apidocs/discovery-data#adddocument)によると、以下のパラメータが必須のようです(パラメータの全量は省略)。


![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/135365/ff54e833-9e5a-6624-a1f7-f9304d938e2b.png)

データについて、今回は以下のような国土交通省から公開されている車の故障データをCSVにしたものを使用します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/135365/df27c403-0f8e-010c-8720-9600ad8a5052.png)


```curl:AddDocument
curl -X POST -F "file=@/<ファイルパス>/国交省.csv" -F metadata='{"creater": "xxxxx xxxxxxxxx"}' -u "apikey:xxxxxxxxxxxxxxxxxxxx" "https://api.jp-tok.discovery.watson.cloud.ibm.com/instances/xxxxxxxxxxxxxxxxxxxxx/v2/projects/xxxxxxxxxxxxxxxxxx/collections/xxxxxxxxxxxxxxxxxxxxxxxxxx/documents?version=2019-11-29"


```

<details><summary>結果</summary><div>
{
  "document_id" : "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "status" : "pending"
}
</div></details>

# 4.クエリー

[API DOC](https://cloud.ibm.com/apidocs/discovery-data#query)によると、以下のパラメータが必須のようです(パラメータの全量は省略)。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/135365/31eec33e-d477-243b-d6c0-82fde22f5055.png)

```curl:Query
curl -X POST -H "Content-Type: application/json" -d "{ \"collection_ids\": [ \"xxxxxxxxxxxxxxxxxxx\", \"xxxxxxxxxxxxxxxxxxxxxx\" ], \"query\": \"申告内容の要約:ABS\" }" -u "apikey:xxxxxxxxxxxxxxxxxxx" "https://api.jp-tok.discovery.watson.cloud.ibm.com/instances/xxxxxxxxxxxxxxxxxxxx/v2/projects/xxxxxxxxxxxxxxxxxxxxx/query?version=2019-11-29"
```

<details><summary>結果</summary><div>
{
		"matching_results": 4,
		"retrieval_details": {
			"document_retrieval_strategy": "untrained"
		},
		"results": [{
			"document_id": "81dd724e-8644-49cb-9e0c-fcca937664c4_18",
			"result_metadata": {
				"collection_id": "8f34d65f-a1cf-f3c2-0000-017940701ae2"
			},
			"受付日": "2016-06-18T00:00:00Z",
			"初度登録年月": "2013年3月",
			"metadata": {
				"creater": "sonoda hiyuko",
				"parent_document_id": "81dd724e-8644-49cb-9e0c-fcca937664c4"
			},
			"番号": 19,
			"extracted_metadata": {
				"sha1": "DB750194445A28EDD870A7B90E7D12B2BC59B0C1",
				"filename": "国交省_part.csv",
				"file_type": "csv"
			},
			"総走行距離": "18,600 Km",
			"原動機型式": "P515",
			"型式": "EBL-VP56A",
			"申告内容の要約": "ステーターコイルの断線により、走行中に突然ＡＢＳランプが点灯して、メーターがフリーズし、エンジンが停止して走行不能となった。",
			"車名": "スズキ",
			"不具合装置": "電気装置",
			"性別": "男性",
			"住所": "千葉",
			"creater": "sonoda hiyuko",
			"通称名": "Ｖストローム６５０ＡＢＳ",
			"申告方法": "ＨＰ",
			"発生時期": "２０１５年５月ころ"
		}, {
			"document_id": "a408e43c-741a-4b01-94fb-4b8b6709a33a_18",
			"result_metadata": {
				"collection_id": "f1c6c3bb-2a46-c3aa-0000-01795a5fbc8c"
			},
			"受付日": "2016-06-18T00:00:00Z",
			"初度登録年月": "2013年3月",
			"metadata": {
				"creater": "sonoda hiyuko",
				"parent_document_id": "a408e43c-741a-4b01-94fb-4b8b6709a33a"
			},
			"番号": 19,
			"extracted_metadata": {
				"sha1": "DB750194445A28EDD870A7B90E7D12B2BC59B0C1",
				"filename": "国交省_part.csv",
				"file_type": "csv"
			},
			"総走行距離": "18,600 Km",
			"原動機型式": "P515",
			"型式": "EBL-VP56A",
			"申告内容の要約": ["ステーターコイルの断線により、走行中に突然ＡＢＳランプが点灯して、メーターがフリーズし、エンジンが停止して走行不能となった。"],
			"車名": "スズキ",
			"不具合装置": "電気装置",
			"性別": "男性",
			"住所": "千葉",
			"creater": "sonoda hiyuko",
			"通称名": "Ｖストローム６５０ＡＢＳ",
			"申告方法": "ＨＰ",
			"発生時期": "２０１５年５月ころ"
		}, {
			"document_id": "a408e43c-741a-4b01-94fb-4b8b6709a33a_0",
			"result_metadata": {
				"collection_id": "f1c6c3bb-2a46-c3aa-0000-01795a5fbc8c"
			},
			"受付日": "2016-06-30T00:00:00Z",
			"初度登録年月": "2009年4月",
			"metadata": {
				"creater": "sonoda hiyuko",
				"parent_document_id": "a408e43c-741a-4b01-94fb-4b8b6709a33a"
			},
			"番号": 1,
			"extracted_metadata": {
				"sha1": "DB750194445A28EDD870A7B90E7D12B2BC59B0C1",
				"filename": "国交省_part.csv",
				"file_type": "csv"
			},
			"総走行距離": "67,000 Km",
			"原動機型式": "BWA",
			"型式": "ABA-1KAXX",
			"申告内容の要約": ["ＡＢＳユニットの不良により、警告灯が点灯したり、ステアリングの警告灯が点いてハンドルが重くなる。ギアが自動でローギアになる。エキゾースト警告灯が点灯する。などの症状が次々に出るようになった。"],
			"車名": "フォルクスワーゲン",
			"不具合装置": "制動装置",
			"性別": "男性",
			"住所": "福島",
			"creater": "sonoda hiyuko",
			"通称名": "ゴルフバリアントＧＴＩ",
			"申告方法": "ﾌﾘｰﾀﾞｲｱﾙ",
			"発生時期": "１か月くらい前から"
		}, {
			"document_id": "81dd724e-8644-49cb-9e0c-fcca937664c4_0",
			"result_metadata": {
				"collection_id": "8f34d65f-a1cf-f3c2-0000-017940701ae2"
			},
			"受付日": "2016-06-30T00:00:00Z",
			"初度登録年月": "2009年4月",
			"metadata": {
				"creater": "sonoda hiyuko",
				"parent_document_id": "81dd724e-8644-49cb-9e0c-fcca937664c4"
			},
			"番号": 1,
			"extracted_metadata": {
				"sha1": "DB750194445A28EDD870A7B90E7D12B2BC59B0C1",
				"filename": "国交省_part.csv",
				"file_type": "csv"
			},
			"総走行距離": "67,000 Km",
			"原動機型式": "BWA",
			"型式": "ABA-1KAXX",
			"申告内容の要約": "ＡＢＳユニットの不良により、警告灯が点灯したり、ステアリングの警告灯が点いてハンドルが重くなる。ギアが自動でローギアになる。エキゾースト警告灯が点灯する。などの症状が次々に出るようになった。",
			"車名": "フォルクスワーゲン",
			"不具合装置": "制動装置",
			"性別": "男性",
			"住所": "福島",
			"creater": "sonoda hiyuko",
			"通称名": "ゴルフバリアントＧＴＩ",
			"申告方法": "ﾌﾘｰﾀﾞｲｱﾙ",
			"発生時期": "１か月くらい前から"
		}]
	}
</div></details>

# おわりに
クエリーについては基本的に照会構文はDiscovery Liteを踏襲している(ように見える)ものの、プロジェクト作成が必要だったり、複数のコレクションに同時にクエリーできたりと、少しずつ違うところがある印象でした。使っていって慣れていきたいと思います。

記載の内容は個人の見解であって、組織を代表するものではありません。
また、記載時点(2021/6/15)の内容です。

# 参考情報
* [IBM Cloud 資料　Discovery](https://cloud.ibm.com/docs/discovery-data)
* [IBM Cloud API Docs Discovery v2](https://cloud.ibm.com/docs/discovery-data)


[^1]: ...