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

はじめに

• IBM Watson Discovery v1 の非推奨の発表 を受けて、v1 から v2 へのアプリ改修にどの程度のインパクトがありそうか、v1 と v2 の API のバージョン間で Request / Response を比較してみました。
• 今回は、API バージョンの比較 を参考にドキュメント関連にフォーカスしてまとめたいと思います。

前提

• Watson Developer Cloud Python SDK を使用した確認になります。
• Python のバージョンは 3.9.7 です。

調査対象

操作	v1 API	v1 API サンプルコード	v2 API	v2 API サンプルコード
0. ドキュメントのリスト	v1にはない（本記事の対象外）	-	関数 list_documents()	-
1. ドキュメントの追加	関数 add_document()	add.py	関数 add_document()	add.py
2. ドキュメントの更新	関数 update_document()	update.py	関数 update_document()	update.py
3. ドキュメントの詳細取得	関数 get_document_status()	get.py	関数 get_document()	get.py
4. ドキュメントの削除	関数 delete_document()	delete.py	関数 delete_document()	delete.py

1. ドキュメントの追加

v1 API の Request / Response

関数 (Request)

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 の具体例

{
  "document_id": "cbad851c-4ddb-4b02-8b9d-280519a826dc",
  "status": "pending"
}

v2 API の Request / Response

関数 (Request)

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 の具体例

{
  "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)

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 の具体例

{
  "document_id": "115-json",
  "status": "pending"
}

v2 API の Request / Response

関数 (Request)

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 の具体例

{
  "document_id": "142-json",
  "status": "pending"
}

比較結果

• v2 API では、environment の概念はなく、collection は project で編成するように変更されており、関数の引数が異なります。
• v2 API では新しいパラメータ x_watson_discovery_force が登場しましたが、デフォルトは false のため影響はなさそうです。
• それ以外は特に違いはなさそうです。

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

v1 API の Request / Response

関数 (Request)

get_document_status(self,
        environment_id: str,
        collection_id: str,
        document_id: str,
        **kwargs
    ) -> DetailedResponse

Response の具体例

{
  "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)

get_document(self,
        project_id: str,
        collection_id: str,
        document_id: str,
        **kwargs
    ) -> DetailedResponse

Response の具体例

{
  "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 からの移行といった観点では影響は小さそうです。
• なお、マニュアルによるとこの v2 APIは、PlusもしくはEnterprise、または CP4D 4.0.9 以降のみ利用できるようです。

4. ドキュメントの削除

v1 API の Request / Response

関数 (Request)

delete_document(self,
        environment_id: str,
        collection_id: str,
        document_id: str,
        **kwargs
    ) -> DetailedResponse

Response の具体例

{
  "document_id": "197-json",
  "status": "deleted"
}

v2 API の Request / Response

関数 (Request)

delete_document(self,
        project_id: str,
        collection_id: str,
        document_id: str,
        *,
        x_watson_discovery_force: bool = None,
        **kwargs
    ) -> DetailedResponse

Response の具体例

{
  "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に移行してみた
• IBM ソリューションブログ | IBM Watson Discovery v1 の非推奨の発表
• IBM Cloud 資料 | API バージョンの比較
• IBM Cloud 資料 | Discovery > Documents

お断り

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