API を使用したドキュメントの一括プッシュ - OpenSearch

OpenSearch LLM-Based Conversational Search Edition では、API を使用してドキュメントを一括でプッシュできます。

前提条件

API 呼び出しを認証するための API キーを取得してください。詳細については、「API キーの管理」をご参照ください。
すべての API 呼び出しに必要なサービスエンドポイントを取得してください。詳細については、「サービスエンドポイントの取得」をご参照ください。

リクエストの詳細

リクエストメソッド	リクエストプロトコル	リクエストデータ形式
POST	HTTP	JSON

リクエスト URL

{host}/v3/openapi/apps/[app_group_identity]/actions/knowledge-bulk

{host}：サービスエンドポイント。パブリックネットワークまたは VPC 経由で API を呼び出すことができます。詳細については、「サービスエンドポイントの取得」をご参照ください。
{app_group_identity}：アプリケーションの名前。名前を確認するには、OpenSearch LLM-Based Conversational Search Edition コンソールにサインインし、**[インスタンス管理]** ページでインスタンスを見つけてください。

リクエストパラメーター

ヘッダーパラメーター

パラメーター	タイプ	必須	説明	例
Content-Type	string	はい	リクエストボディの形式。`application/json` を指定する必要があります。	application/json
Authorization	string	はい	リクエスト認証用の API キー。値の前に `Bearer` を付加する必要があります。	Bearer OS-d1**2a

ボディパラメーター

パラメーター	タイプ	必須	説明	例
cmd	string	はい	ドキュメントに対して実行するアクション。	ADD/DELETE
fields	map	はい	キーと値のマップ形式のドキュメントフィールド。
fields.id	string	はい	ドキュメントのプライマリキー。	13579
fields.title	string	いいえ	ドキュメントのタイトル。	Something interesting
fields.url	string	いいえ	ドキュメントの URL。	https://www.aliyun.com
fields.content	string	はい	ドキュメントのコンテンツ。	No, is not.

リクエスト例

1. メインテーブルへのドキュメントのアップロード

['{
    "cmd": "ADD",
    "fields": {
      "id": "13579",
      "title": "Something interesting",
      "url": "https://www.aliyun.com",
      "content": "No, is not."
      }
}']

非構造化ドキュメント (PDF、DOC、TXT、HTML) のアップロード

['{
    "cmd" : "URL/BASE64",
    "fields": {
      "id": "ドキュメント ID (オプション)",
      "type": "ファイルタイプ、例：pdf、doc、txt、html",
      "title": "ファイル名 (オプション)",
      "content": "URL または Base64 エンコードされたデータ",
      "url": "リンク (オプション)"
    }
 }']

説明

cmd に URL を指定して非構造化ドキュメントをアップロードする場合、content フィールドに指定する URL は、ossClient.generatePresignedUrl メソッドで生成された OSS オブジェクトの署名付き URL のみサポートします。

2. カスタムテーブルへのドキュメントのアップロード

['{
    "cmd" : "ADD",
    "fields": {					# データオブジェクト。テーブルスキーマに基づいてフィールドを定義します。
      "key1": "value1",
      "key2": "value2",
      "key3": "value3"
    },
    "table_name": "custom_table_name"	# テーブル名。空の場合、操作はメインテーブルで実行されます。
  }']

3. ドキュメントの削除

['{
    "cmd" : "DELETE",
    "fields": {
      "id": "13579333"
    }
}']

cmd：必須。ドキュメントに対して実行するアクションを指定します。ネットワークと処理の効率を向上させるため、1 つのリクエストで複数の操作をバッチ処理することを推奨します。ADD は新しいドキュメントを作成するか、同じプライマリキーを持つ既存のドキュメントを上書きします。DELETE はドキュメントを削除します。指定されたドキュメントが存在しない場合でも、操作は成功したと見なされます。
fields：必須。ドキュメントのフィールドです。プライマリキーは常に必須です。DELETE アクションでは、ドキュメントのプライマリキーのみが必要です。
注意：複数のドキュメントに対するバッチ操作をサポートするには、リクエストボディを JSON 配列にする必要があります。

レスポンスパラメーター

パラメーター	タイプ	説明
errors	list	エラーのリスト。
status	string	実行ステータス。`OK` は成功を示し、`FAIL` は失敗を示します。リクエストが失敗した場合は、返されたエラーコードを使用してトラブルシューティングを行ってください。
request_id	string	リクエストの ID。
result	boolean	実行が成功した場合は `true` を返します。失敗した場合、このパラメーターは省略されます。
total	int	リクエスト内のドキュメントの総数。
success	int	正常にアップロードされたドキュメントの数。
failure	int	アップロードに失敗したドキュメントの数。
failed_ids	array	アップロードに失敗したドキュメントの ID。

レスポンス例

{
  "request_id" : "abc123-ABC",
  "result" : {
    "total": 100,
    "success": 50,
    "failure": 50,
    "failed_ids": [
      "id1",
      "id2",
      "id3",
      "..."
    ]
  },
  "errors" : [
    {
      "code" : "エラーが発生した場合のエラーコード。",
      "message" : "エラーが発生した場合のエラーメッセージ。"
    }
  ]
}

注意事項

API または SDK を使用してデータをプッシュする場合、フィールド名は大文字と小文字を区別しません。
API または SDK を使用したデータプッシュには、頻度とサイズの制限があります。アップロードサイズの制限は変更できません。制限はアプリケーションによって異なります。詳細については、「制限事項」をご参照ください。
データ損失を防ぐため、各アップロード後にレスポンスを確認し、特定のエラーコード (特に 3007) で失敗したリクエストをリトライしてください。データ処理は非同期です。OK のレスポンスは、システムがデータを正常に受信したことのみを示します。データ処理エラーはコンソールに表示されます。定期的にエラーメッセージを確認してください。
POST リクエストボディは、エンコーディング前に 2 MB を超えることはできません。サーバーはこの制限を超えるリクエストを拒否します。
POST 操作のリクエストボディに中国語文字が含まれている場合は、UTF-8 でエンコードする必要があります。同様に、Content-MD5 ヘッダーの値は、UTF-8 でエンコードされたデータから計算する必要があります。そうしないと、プッシュ操作は失敗します。
API コールがエラーコード 4016 を返した場合、RAM ユーザーの権限が不十分です。 RAM ユーザーに [AliyunOpenSearchFullAccess] 権限を付与してください。詳細については、「RAM ユーザーに権限を付与する」をご参照ください。