IBM Cloud Docs
API バージョンの比較

API バージョンの比較

ほとんどの API メソッドで、要求パラメーターと応答本体は v1 と v2で異なります。 v1 API でサポートされるアクションを実行するために使用できる、同等または代替の v2 メソッドについて説明します。

比較情報は、 v1 API (バージョン 2019-04-30) の最新バージョンを使用していることを前提とし、それを v2 API (バージョン 2020-08-30) の最新バージョンと比較します。

環境

v2には、 環境 の概念はありません。 サイズや索引容量などのデプロイメントの詳細は、サービス・プラン・タイプに基づいて管理されます。 v2では、コレクションはプロジェクトに編成されます。 さまざまなタイプのプロジェクトを作成して、プロジェクトに追加するコレクションにデフォルトの構成設定を適用できます。

v2 には、 v1 環境メソッドと同等のメソッドはありません。 ただし、以下の表は、対応する v1 メソッドと類似した機能を提供する v2 メソッドを示しています。 メソッドごとに返される、サポートされるパラメーターと応答本体も異なります。

環境 API アクションのサポート詳細
action v1 API 関連する v2 API
環境の作成 POST /v1/environments POST /v2/projects
環境のリスト GET /v1/environments GET /v2/projects
環境情報の取得 GET /v1/environments/{environment_id} GET /v2/projects/{project_id}
環境の更新 PUT /v1/environments/{environment_id} POST /v2/projects/{project_id}
v2 は、 PUT の代わりに POST を使用します。
環境を削除します DELETE /v1/environment/{environment_id} DELETE /v2/projects/{project_id}
複数のコレクションにわたるフィールドのリスト GET /v1/environments/{environment_id}/fields GET /v2/projects/{project_id}/fields

構成

v2 API には、構成専用のエンドポイントはありません。 代わりに、プロジェクト、コレクション、および照会の構成設定は、それらのオブジェクトの API で直接指定されます。 v1 で使用可能なすべての構成パラメーターが v2で使用できるわけではありません。

v1 構成 API では、構成オブジェクトの指定に使用される JSON オブジェクトに複数のパラメーターが含まれています。これらのパラメーターは、他の v2 エンドポイントとは異なる形式で使用できるか、 v2では使用できません。 以下の表で、 v2の関連パラメーターを見つける方法について説明します。

v1のように、 v2 の取り込みプロセス中に文書の変換をカスタマイズすることはできません。

構成設定の詳細
v1 構成パラメーター v2 API
"conversions.html": { ... } 使用不可
"conversions.image_text_recognition": { ... } API からは使用できません。 ただし、製品のユーザー・インターフェースからコレクションの光学式文字認識 (OCR) を有効にして、イメージからテキストを抽出することができます。 OCR には他にも利点があります。 例えば、文書内のページを処理できない場合、OCR はそのページを画像に変換してスキャンし、文書が正常にアップロードされたことを確認します。
"conversions.json_normalizations": { ... } Collections API に移動されました。
"conversions.pdf": { ... } 利用できません。 PDF 内のイメージからテキストを抽出するために特殊なパラメーターを使用した場合は、PDF を含むコレクションの製品ユーザー・インターフェースから光学式文字認識 (OCR) を使用可能にします。
"conversions.segment": { ... } プログラマチックには使用できません。 製品のユーザー・インターフェースから、 subtitle などの SDU 生成フィールドが出現するたびに文書を分割できます。
parent_idid、および total_segments の情報を持つ segment_metadata オブジェクトは、 v2では使用できません。 metadata.parent_document_id フィールドを使用して、多くの文書セグメントの共通の親を見つけることができます。
"conversions.word": { ... } 使用不可
"enrichments": { ... } /v2/projects/{project_id}/enrichments/v2/projects/{project_id}/collections/{collection_id}
エンリッチメント API を使用して、既存のエンリッチメントを探索します。 コレクション API を使用して、コレクション内のフィールドで有効になっているエンリッチメントを表示および変更します。
一部のエンリッチメントは、作成するプロジェクトのタイプに基づいて、デフォルトでサービスに適用されます。 詳しくは、 デフォルトのプロジェクト設定 を参照してください。
v2 で使用可能なエンティティー・エンリッチメントのバージョンには、 disambiguation フィールドは含まれていません。 v1 には、エンティティーの明確化情報とエンティティー・サブタイプ情報が含まれています。
以下のエンリッチメントは v2:
-カテゴリー
-概念
-感情
-関係
-セマンティック役割
-エンティティーのセンチメント
-キーワードのセンチメント
"normalizations": [ ... ] Collections API に移動されました。
"source": { ... } 利用できません。 ユーザー・インターフェースを介した外部データ・ソースへの接続を構成します。 詳しくは、 コレクションの作成 を参照してください。

コレクション

コレクション API のサポート詳細
action v1 API v2 API
コレクションの作成 POST /v1/environments/{environment_id}/collections POST /v2/projects/{project_id}/collections
サポートされるパラメーターと応答は、2 つのバージョンで異なります。 コレクション・ノート を参照してください。
コレクションのリスト GET /v1/environments/{environment_id}/collections GET /v2/projects/{project_id}/collections
v2では、各コレクションのコレクション ID と名前のみがリストに返されます。 各コレクションの詳細を返すには、 Get collection メソッドを使用する必要があります。
コレクションの詳細の取得 GET /v1/environments/{environment_id}/collections/{collection_id} GET /v2/projects/{project_id}/collections/{collection_id}
コレクション・ノート を参照してください。
コレクションの更新 PUT /v1/environments/{environment_id}/collections/{collection_id} POST /v2/projects/{project_id}/collections/{collection_id}
コレクションの削除 DELETE /v1/environments/{environment_id}/collections/{collection_id} DELETE /v2/projects/{project_id}/collections/{collection_id}
v2では、 status フィールドは応答で返されません。
リスト・コレクション・フィールド GET /v1/environments/{environment_id}/collections/{collection_id}/fields
v1 は、コレクションごとにフィールドをリストします。
GET /v2/projects/{project_id}/fields
v2 は、代わりにプロジェクトごとのフィールドをリストします。 collection_ids パラメーターを使用して単一のコレクション ID を渡すと、単一のコレクションからフィールドを取得できます。

コレクション API の注

以下の表に、 v1 コレクション API と v2 コレクション API の重要な相違点を示します。

コレクション API の注
方法 メモ
コレクションの作成 v2 応答には、 status フィールドと configuration_id フィールドは含まれません。 Get document details メソッドを使用して、特定のドキュメントの状況情報を取得できます。
オブジェクト disk_usagetraining_status、および crawl_status は、 v2の応答本体には存在しません。 現在、 document_counts オブジェクトは v2 の応答本体に存在しません。 トレーニング状況は、 Get project メソッド応答で返されます。 その他の情報は、 v2では使用できません。 v2では、オプションの enrichments オブジェクトを指定することで、コレクション内の文書に適用するエンリッチメントを定義できます。
コレクションの詳細の取得 v2 応答には、 status フィールドと configuration_id フィールドは含まれません。 Get document details メソッドを使用して、特定のドキュメントの状況情報を取得できます。
オブジェクト document_countsdisk_usagetraining_status、および crawl_status は、 v2の応答本体には存在しません。 トレーニング状況は、 Get project メソッド応答で返されます。 その他の情報は、 v2では使用できません。 例えば、コレクションの文書数を取得できず、 v2の外部データ・ソースに接続するコレクションのクロール状況を取得できません。 v2では、コレクションに適用されるエンリッチメントに関する情報を取得できます。
コレクションの更新 v2 は、 PUT の代わりに POST を使用します。 v2では、オプションの enrichments オブジェクトを指定することで、コレクション内の文書に適用されるエンリッチメントを更新できます。
v2 応答には、 status フィールドと configuration_id フィールドは含まれません。

照会の変更

v1 でトークン化をプログラマチックに構成するために使用可能であったメソッドは、 v2 API ではサポートされません。

照会変更 API のサポート詳細
v1 API v2 API
トークン化辞書 API 利用できません。
拡張 v1 API 拡張 v2 API
ストップワード v1 API ストップワード v2 API

文書

文書 API サポートの詳細
action v1 API v2 API
ドキュメントのリスト v1 API からは使用できません GET /v2/projects/{project_id}/collections/{collection_id}/documents
ドキュメントの作成 POST /v1/environments/{environment_id}/collections/{collection_id}/documents POST /v2/projects/{project_id}/collections/{collection_id}/documents
v1とは異なり、 v2 応答には通知オブジェクトは含まれません。 ただし、 v2の 「文書詳細の取得」 メソッドを使用すると、通知情報を取得できます。
文書の更新 POST /v1/environments/{environment_id}/collections /{collection_id}/documents/{document_id} POST /v2/projects/{project_id}/collections/{collection_id}/documents/{document_id}
分割された文書を更新すると、すべての文書セグメントが上書きされます。
文書詳細の取得 GET /v1/environments/{environment_id}/collections /{collection_id}/documents/{document_id} GET /v2/projects/{project_id}/collections/{collection_id}/documents/{document_id}
v2には、 statusDescription はありません。 v2 には、取り込み中に生成された子文書に関連付けられた通知に関する情報を持つ children オブジェクトがあります。
文書の削除 DELETE /v1/environments/{environment_id}/collections /{collection_id}/documents/{document_id} DELETE /v2/projects/{project_id}/collections/{collection_id}/documents/{document_id}
アップロードされた文書のセグメントを個別に削除することはできません。 セグメント結果の parent_document_id を含む DELETE 要求を使用して、すべてのセグメントを削除します。

v2 には、 v1では使用できない X-Watson-Discovery-Force という名前のカスタム・ヘッダーが導入されています。 多くのコレクションで共有されているデータに対して操作を実行する場合は、各コレクションで操作を実行することを示すためにヘッダーを含める必要があります。 ヘッダーを含めない場合は、 403 エラーが返されます。

コレクションに追加された JSON ファイルのフィールドは、 v1 と v2の間の取り込み時に異なる方法で変換されます。 JSON ファイルが v2 索引に保管される方法について詳しくは、 JSON ファイル を参照してください。

照会

文書 API サポートの詳細
action v1 API v2 API
コレクションの照会 GET 要求または POST 要求をサポートします。
GET または POST /v1/environments/{environment_id}/collections/{collection_id}/query
プロジェクトを照会します。 単一のコレクションを指定するには、 {collection_id} パラメーターを含めます。 POST 要求のみをサポートします。
POST /v2/projects/{project_id}/query
複数のコレクションを照会する GET または POST /v1/environments/{environment_id}/query POST /v2/projects/{project_id}/query
システム通知の照会 GET /v1/environments/{environment_id}/collections/{collection_id}/notices GET /v2/projects/{project_id}/collections/{collection_id}/notices
複数の収集システムの通知を照会する GET /v1/environments/{environment_id}/notices GET /v2/projects/{project_id}/notices
オートコンプリート候補の取得 /v1/environments/{environment_id}/collections/{collection_id}/autocompletion GET /v2/projects/{project_id}/autocompletion
クエリー・ノート を参照してください。

一部の照会結果構成は、作成するプロジェクトのタイプに基づいて、デフォルトでサービスに適用されます。 詳しくは、 デフォルトのプロジェクト設定 を参照してください。

照会メモ

  • v2 照会は、プロジェクト内のすべてのコレクションの結果を返します。 プロジェクト内の特定のコレクションのみを使用するように照会を制限するには、 collection_ids 照会パラメーターを使用します。 1 つの v2 照会要求で、異なるプロジェクトに追加された複数のコレクションを照会することはできません。

  • v2 の結果には confidence フィールドが含まれますが、 score フィールドは含まれません。

    v1のスコア情報は信頼性スコアに置き換えられましたが、後方互換性のためにスコアが保持されました。 v2では、信頼性フィールドのみが返されます。

  • v2を使用して照会を送信するには、(GET 呼び出しの代わりに) POST 呼び出しを使用します。

  • v1 照会は、多くのパラメーターを受け入れます。 「照会パラメーターの比較」 表は、 v1 のパラメーターを v2 のパラメーターにマップします。

    照会パラメーターの比較
    v1 パラメーター v2 パラメーター メモ
    該当なし collection_ids このパラメーターは、コレクション ID を指定するために v2 で使用します。
    フィルター フィルター 同じ式言語。
    照会 照会 同じ式言語。
    natural_language_query natural_language_query 注釈がありません。
    passages passages パッセージ形式が変更され、 v2で拡張されました。 passages:true パラメーターが passages.enable:true に変更されました。 countcharacters、および fields オプションに加えて、 per_document を指定することができます。これにより、文書の品質によって文書がランク付けされ、文書ごとの最高ランクのパッセージが返されます。 また、 find_answers を指定して、照会に対する簡潔な応答を含む、パッセージごとの応答オブジェクトを返すこともできます。
    集約 集約 同じ式言語。
    注釈がありません。
    offset offset 注釈がありません。
    return return 注釈がありません。
    ソート ソート 注釈がありません。
    ハイライト ハイライト passages.enabled および passages.per_documenttrue の場合、文書ごとに強調表示の代わりにパッセージが返されます。
    スペルの提案 スペルの提案 注釈がありません。
    deduplicate 該当なし v2 ではサポートされていません。
    similar similar v2でフォーマットが変更されました。 similar:true パラメーターが similar.enable:true に変更されました。 document_ids および fields パラメーターが、ストリング配列からストリング配列に変更されました。 enabled が true の場合、 document_ids パラメーターが必須になりました。
    バイアス 該当なし v2 ではサポートされていません。

トレーニング・データ

v1 トレーニング・データ API を使用して、以下の 2 つの関連オブジェクトを処理できます。

  • トレーニング済み照会
  • 照会のトレーニングに使用される例

これら 2 つのオブジェクトには、 v1に別個の API エンドポイントがあります。 v2では、各照会のトレーニングに使用される例が照会とともに提供され、トレーニング・データの処理に使用されるエンドポイントは 1 つのみです。

例えば、トレーニングされた照会とそのトレーニング例の文書を v2に追加するには、要求 POST /v2/projects/{project_id}/training_data/queries を使用し、1 回の呼び出しのペイロードで照会とすべての例を渡します。 同様に、 v2のトレーニング・セットで 1 つの例を更新する場合は、照会と変更した例を (他のすべての例とともに) v2 更新エンドポイントに渡す必要があります。 v1では、サンプル情報を更新するために、更新サンプル・エンドポイントを使用して 1 つの例のみを変更します。

v1 と v2 のもう 1 つの重要な違いは、 v1では、トレーニングされたモデルが特定のコレクションに関連付けられることです。 v2では、トレーニングされたモデルはプロジェクトに関連付けられます。 プロジェクト内の複数のコレクションからのデータを使用して、関連性モデルをトレーニングできます。 v2でトレーニング例を作成または更新する場合、API は文書が保管されているコレクションの collection_id を必要とします。

トレーニング・データ API のサポート詳細
action v1 API v2 API
トレーニング・データのリスト GET /v1/environments/{environment_id}/collections/{collection_id}/training_data GET /v2/projects/{project_id}/training_data /queries
トレーニングデータにクエリを追加する POST /v1/environments/{environment_id}/collections/{collection_id}/training_data POST /v2/projects/{project_id}/training_data /queries
すべてのトレーニング・データの削除 DELETE /v1/environments/{environment_id}/collections/{collection_id}/training_data DELETE /v2/projects/{project_id}/training_data /queries
クエリの詳細を取得する GET /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id} GET /v2/projects/{project_id}/training_data /queries/{query_id}
トレーニングデータクエリを削除する DELETE /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id} DELETE /v2/projects/{project_id}/training_data /queries/{query_id}
トレーニングデータクエリの例をリストアップ GET /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id}/examples GET /v2/projects/{project_id}/training_data /queries/{query_id}
これらの例は、照会で返されるリストに含まれています。
トレーニングデータクエリに例を追加 POST /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id}/examples POST /v2/projects/{project_id}/training_data /queries/{query_id}
v2 の 「トレーニング照会の作成 (Create training query)」 メソッドを使用し、照会の作成時にすべての例を渡します。 それ以外の場合は、更新 API を使用します。
トレーニングデータクエリの削除例 DELETE /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id}/examples/{example_id} POST /v2/projects/{project_id}/training_data/ queries/{query_id}
v2 training_data 更新方式を使用します。
ラベルまたは相互参照の変更 (例) PUT /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id}/examples/{example_id} POST /v2/projects/{project_id}/training_data/ queries/{query_id}
v2 training_data 更新方式を使用します。
トレーニングデータ例の詳細を取得する GET /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id}/examples/{example_id} 利用できません。 Read all examples 呼び出しを使用して、照会に関連付けられたすべての例を取得し、返されたリストで必要な例を見つけます。

ユーザー・データ

ユーザー・データ API は、 v2 と v1で同じです。

ユーザー・データ API のサポート詳細
action v1 API v2 API
削除 DELETE /v1/user_data DELETE /v2/user_data
v1に類似しています。 customer_id を使用して、その顧客 ID に関連付けられたデータを削除します。

イベントとフィードバック

v1 イベントおよびフィードバック API (/v1/events) は、 v2では使用できません。

資格情報

v1 資格情報 API (/v1/environments/{environment_id}/credentials) は、 v2では使用できません。 この機能は、 v2 製品のユーザー・インターフェースから使用できます。

状況コード

ほとんどすべての API メソッドで、 v2 要求に対して返される状況コードは、 v1 要求に対して返される状況コードとは異なります。