IBM Watson Discovery v1 と v2 の API のバージョン間で Request / Response を比較してみました(ドキュメント関連)

# はじめに

- [IBM Watson Discovery v1 の非推奨の発表](https://www.ibm.com/blogs/solutions/jp-ja/ibm-watson-discovery-v1-deprecation-announcement/) を受けて、v1 から v2 へのアプリ改修にどの程度のインパクトがありそうか、v1 と v2 の API のバージョン間で Request / Response を比較してみました。
- 今回は、[API バージョンの比較](https://cloud.ibm.com/docs/discovery-data?topic=discovery-data-migrate-to-v2-api) を参考にドキュメント関連にフォーカスしてまとめたいと思います。

# 前提

- [Watson Developer Cloud Python SDK](https://github.com/watson-developer-cloud/python-sdk) を使用した確認になります。
- Python のバージョンは 3.9.7 です。 

# 調査対象

|操作| v1 API | v1 API サンプルコード | v2 API | v2 API サンプルコード | 
|:-|:-|:-|:-|:-|
|0. ドキュメントのリスト|v1にはない（本記事の対象外）|-|[関数 list_documents()](https://cloud.ibm.com/apidocs/discovery-data?code=python#listdocuments)|-|
|1. ドキュメントの追加|[関数 add_document()](https://cloud.ibm.com/apidocs/discovery?code=python#adddocument)|[add.py](https://github.com/to-tomo/ws-samples/blob/main/scripts/discovery_v1/document/add.py)|[関数 add_document()](https://cloud.ibm.com/apidocs/discovery-data?code=python#adddocument)|[add.py](https://github.com/to-tomo/ws-samples/blob/main/scripts/discovery_v2/document/add.py)|
|2. ドキュメントの更新|[関数 update_document()](https://cloud.ibm.com/apidocs/discovery?code=python#updatedocument)|[update.py](https://github.com/to-tomo/ws-samples/blob/main/scripts/discovery_v1/document/update.py)|[関数 update_document()](https://cloud.ibm.com/apidocs/discovery-data?code=python#updatedocument)|[update.py](https://github.com/to-tomo/ws-samples/blob/main/scripts/discovery_v2/document/update.py)|
|3. ドキュメントの詳細取得|[関数 get_document_status()](https://cloud.ibm.com/apidocs/discovery?code=python#getdocumentstatus)|[get.py](https://github.com/to-tomo/ws-samples/blob/main/scripts/discovery_v1/document/get.py)|[関数 get_document()](https://cloud.ibm.com/apidocs/discovery-data?code=python#getdocument)|[get.py](https://github.com/to-tomo/ws-samples/blob/main/scripts/discovery_v2/document/get.py)|
|4. ドキュメントの削除|[関数 delete_document()](https://cloud.ibm.com/apidocs/discovery?code=python#deletedocument)|[delete.py](https://github.com/to-tomo/ws-samples/blob/main/scripts/discovery_v1/document/delete.py)|[関数 delete_document()](https://cloud.ibm.com/apidocs/discovery-data?code=python#deletedocument)|[delete.py](https://github.com/to-tomo/ws-samples/blob/main/scripts/discovery_v2/document/delete.py)|


# 1. ドキュメントの追加

## v1 API の Request / Response
### 関数 (Request)
```python
add_document(self,
        environment_id: str,
        collection_id: str,
        *,
        file: BinaryIO = None,
        filename: str = None,
        file_content_type: str = None,
        metadata: str = None,
        **kwargs
    ) -> DetailedResponse
```
### Response の具体例
```json
{
  "document_id": "cbad851c-4ddb-4b02-8b9d-280519a826dc",
  "status": "pending"
}
```
## v2 API の Request / Response
### 関数 (Request)
```python
add_document(self,
        project_id: str,
        collection_id: str,
        *,
        file: BinaryIO = None,
        filename: str = None,
        file_content_type: str = None,
        metadata: str = None,
        x_watson_discovery_force: bool = None,
        **kwargs
    ) -> DetailedResponse
```
### Response の具体例
```json
{
  "document_id": "106b205a-d538-44cb-86a9-0cea929c77a8",
  "status": "pending"
}
```
## 比較結果
- v2 API では、`environment` の概念はなく、`collection` は `project` で編成するように変更されており、関数の引数が異なります。
- v2 API では新しいパラメータ `x_watson_discovery_force` が登場しましたが、デフォルトは `false` のため影響はなさそうです。
- それ以外は特に違いはなさそうです。

# 2. ドキュメントの更新

## v1 API の Request / Response
### 関数 (Request)
```python
update_document(self,
        environment_id: str,
        collection_id: str,
        document_id: str,
        *,
        file: BinaryIO = None,
        filename: str = None,
        file_content_type: str = None,
        metadata: str = None,
        **kwargs
    ) -> DetailedResponse
```
### Response の具体例
```json
{
  "document_id": "115-json",
  "status": "pending"
}
```
## v2 API の Request / Response
### 関数 (Request)
```python
update_document(self,
        project_id: str,
        collection_id: str,
        document_id: str,
        *,
        file: BinaryIO = None,
        filename: str = None,
        file_content_type: str = None,
        metadata: str = None,
        x_watson_discovery_force: bool = None,
        **kwargs
    ) -> DetailedResponse
```
### Response の具体例
```json
{
  "document_id": "142-json",
  "status": "pending"
}
```
## 比較結果
- v2 API では、`environment` の概念はなく、`collection` は `project` で編成するように変更されており、関数の引数が異なります。
- v2 API では新しいパラメータ `x_watson_discovery_force` が登場しましたが、デフォルトは `false` のため影響はなさそうです。
- それ以外は特に違いはなさそうです。

# 3. ドキュメントの詳細取得

## v1 API の Request / Response
### 関数 (Request)
```python
get_document_status(self,
        environment_id: str,
        collection_id: str,
        document_id: str,
        **kwargs
    ) -> DetailedResponse
```
### Response の具体例
```json
{
  "document_id": "115-json",
  "filename": "data/115.json",
  "file_type": "json",
  "sha1": "4013f6ecefbcae913ef08e7280b3555190e10b71",
  "status": "available",
  "status_description": "Document is successfully ingested and indexed with no warnings",
  "notices": []
}
```
## v2 API の Request / Response
### 関数 (Request)
```python
get_document(self,
        project_id: str,
        collection_id: str,
        document_id: str,
        **kwargs
    ) -> DetailedResponse
```
### Response の具体例
```json
{
  "document_id": "171-json",
  "created": "2022-08-24T06:48:16.707Z",
  "updated": "2022-08-24T06:51:36.358Z",
  "status": "available",
  "notices": [],
  "children": {
    "count": 0,
    "have_notices": false
  },
  "filename": "data/171.json",
  "file_type": "json",
  "sha256": "23e9aa0f5a70b791191eb3bd66dcd0ace8cc6b0ddcad411e2b0009266bddb395"
}
```
## 比較結果
- v2 API では、`environment` の概念はなく、`collection` は `project` で編成するように変更されており、関数の引数が異なります。
- v2 API では新しいパラメータ `x_watson_discovery_force` が登場しましたが、デフォルトは `false` のため影響はなさそうです。
- v1 API: `get_document_status()` から v2 API: `get_document()` に関数名が変更されています。
- v2 API では追加の情報が出力されていますが、v1 API からの移行といった観点では影響は小さそうです。
- なお、[マニュアル]("https://cloud.ibm.com/apidocs/discovery-data?code=python#getdocument")によるとこの v2 APIは、PlusもしくはEnterprise、または CP4D 4.0.9 以降のみ利用できるようです。
  
# 4. ドキュメントの削除

## v1 API の Request / Response
### 関数 (Request)
```python
delete_document(self,
        environment_id: str,
        collection_id: str,
        document_id: str,
        **kwargs
    ) -> DetailedResponse
```
### Response の具体例
```json
{
  "document_id": "197-json",
  "status": "deleted"
}
```
## v2 API の Request / Response
### 関数 (Request)
```python
delete_document(self,
        project_id: str,
        collection_id: str,
        document_id: str,
        *,
        x_watson_discovery_force: bool = None,
        **kwargs
    ) -> DetailedResponse
```
### Response の具体例
```json
{
  "document_id": "109-json",
  "status": "deleted"
}
```
## 比較結果
- v2 API では、`environment` の概念はなく、`collection` は `project` で編成するように変更されており、関数の引数が異なります。
- v2 API では新しいパラメータ `x_watson_discovery_force` が登場しましたが、デフォルトは `false` のため影響はなさそうです。
- それ以外は特に違いはなさそうです。

# 終わりに

v1 から v2 へのアプリ改修へのインパクトという点では、以下が主な違いでした。
- `environment` から `project` への構成変更に伴い、引数が変わった
    - 具体的には、`environment_id` から `project_id`に変更
- `3. ドキュメントの詳細取得` のAPI名が v1 と v2 で異なる
    - 具体的には `get_document_status()` から `get_document()` に変更 

v1 API から v2 API への移行に伴う影響は少なさそうな印象です。

なお、v2ではプロジェクトの中にコレクションを作る構成になりましたが、v1から移行する場合は、プロジェクト対コレクションの関係を １:１ にすると移行がシンプルになると思います。 


# 参考

- [Qiita 記事 | Watson Discoveryをv1からv2に移行してみた](https://qiita.com/nsatoh/items/1f9638cd58730213a4e5#4-discovery-v1%E3%81%AE%E9%96%A2%E9%80%A3%E6%80%A7%E3%83%88%E3%83%AC%E3%83%BC%E3%83%8B%E3%83%B3%E3%82%B0%E3%83%87%E3%83%BC%E3%82%BF%E3%82%92%E5%8F%96%E5%BE%97%E3%81%99%E3%82%8B)
- [IBM ソリューションブログ | IBM Watson Discovery v1 の非推奨の発表](https://www.ibm.com/blogs/solutions/jp-ja/ibm-watson-discovery-v1-deprecation-announcement/)
- [IBM Cloud 資料 | API バージョンの比較](https://cloud.ibm.com/docs/discovery-data?topic=discovery-data-migrate-to-v2-api)
- [IBM Cloud 資料 | Discovery > Documents](https://cloud.ibm.com/docs/discovery-data?topic=discovery-data-migrate-to-v2-api#migrate-to-v2-api-documents)

# お断り

このサイトの掲載内容は私自身の見解であり、必ずしも所属会社の立場、戦略、意見を代表するものではありません。 記事は執筆時点の情報を元に書いているため、必ずしも最新情報であるとはかぎりません。 記事の内容の正確性には責任を負いません。自己責任で実行してください。