API バージョンの比較
ほとんどの API メソッドで、要求パラメーターと応答本体は v1 と v2で異なります。 v1 API でサポートされるアクションを実行するために使用できる、同等または代替の v2 メソッドについて説明します。
比較情報は、 v1 API (バージョン 2019-04-30) の最新バージョンを使用していることを前提とし、それを v2 API (バージョン 2020-08-30) の最新バージョンと比較します。
環境
v2には、 環境 の概念はありません。 サイズや索引容量などのデプロイメントの詳細は、サービス・プラン・タイプに基づいて管理されます。 v2では、コレクションはプロジェクトに編成されます。 さまざまなタイプのプロジェクトを作成して、プロジェクトに追加するコレクションにデフォルトの構成設定を適用できます。
v2 には、 v1 環境メソッドと同等のメソッドはありません。 ただし、以下の表は、対応する v1 メソッドと類似した機能を提供する v2 メソッドを示しています。 メソッドごとに返される、サポートされるパラメーターと応答本体も異なります。
| 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_id、 id、および 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 の注
以下の表に、 v1 コレクション API と v2 コレクション API の重要な相違点を示します。
| 方法 | メモ |
|---|---|
| コレクションの作成 | v2 応答には、 status フィールドと configuration_id フィールドは含まれません。 Get document details メソッドを使用して、特定のドキュメントの状況情報を取得できます。オブジェクト disk_usage、 training_status、および
crawl_status は、 v2の応答本体には存在しません。 現在、 document_counts オブジェクトは v2 の応答本体に存在しません。 トレーニング状況は、 Get project メソッド応答で返されます。 その他の情報は、
v2では使用できません。 v2では、オプションの enrichments オブジェクトを指定することで、コレクション内の文書に適用するエンリッチメントを定義できます。 |
| コレクションの詳細の取得 | v2 応答には、 status フィールドと configuration_id フィールドは含まれません。 Get document details メソッドを使用して、特定のドキュメントの状況情報を取得できます。オブジェクト document_counts、 disk_usage、
training_status、および crawl_status は、 v2の応答本体には存在しません。 トレーニング状況は、 Get project メソッド応答で返されます。 その他の情報は、 v2では使用できません。 例えば、コレクションの文書数を取得できず、 v2の外部データ・ソースに接続するコレクションのクロール状況を取得できません。 v2では、コレクションに適用されるエンリッチメントに関する情報を取得できます。 |
| コレクションの更新 | v2 は、 PUT の代わりに POST を使用します。 v2では、オプションの enrichments オブジェクトを指定することで、コレクション内の文書に適用されるエンリッチメントを更新できます。v2 応答には、 status フィールドと configuration_id フィールドは含まれません。 |
照会の変更
v1 でトークン化をプログラマチックに構成するために使用可能であったメソッドは、 v2 API ではサポートされません。
| v1 API | v2 API |
|---|---|
| トークン化辞書 API | 利用できません。 |
| 拡張 v1 API | 拡張 v2 API |
| ストップワード v1 API | ストップワード v2 API |
文書
v2 には、 v1では使用できない X-Watson-Discovery-Force という名前のカスタム・ヘッダーが導入されています。 多くのコレクションで共有されているデータに対して操作を実行する場合は、各コレクションで操作を実行することを示すためにヘッダーを含める必要があります。 ヘッダーを含めない場合は、 403 エラーが返されます。
コレクションに追加された JSON ファイルのフィールドは、 v1 と v2の間の取り込み時に異なる方法で変換されます。 JSON ファイルが v2 索引に保管される方法について詳しくは、 JSON ファイル を参照してください。
照会
| 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に変更されました。count、characters、およびfieldsオプションに加えて、per_documentを指定することができます。これにより、文書の品質によって文書がランク付けされ、文書ごとの最高ランクのパッセージが返されます。 また、find_answersを指定して、照会に対する簡潔な応答を含む、パッセージごとの応答オブジェクトを返すこともできます。集約 集約 同じ式言語。 数 数 注釈がありません。 offset offset 注釈がありません。 return return 注釈がありません。 ソート ソート 注釈がありません。 ハイライト ハイライト passages.enabledおよびpassages.per_documentがtrueの場合、文書ごとに強調表示の代わりにパッセージが返されます。スペルの提案 スペルの提案 注釈がありません。 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 は、 v2 と v1で同じです。
| action | v1 API | v2 API |
|---|---|---|
| 削除 | DELETE /v1/user_data |
DELETE /v2/user_datav1に類似しています。 customer_id を使用して、その顧客 ID に関連付けられたデータを削除します。 |
イベントとフィードバック
v1 イベントおよびフィードバック API (/v1/events) は、 v2では使用できません。
資格情報
v1 資格情報 API (/v1/environments/{environment_id}/credentials) は、 v2では使用できません。 この機能は、 v2 製品のユーザー・インターフェースから使用できます。
状況コード
ほとんどすべての API メソッドで、 v2 要求に対して返される状況コードは、 v1 要求に対して返される状況コードとは異なります。