ドキュメントの追加、更新、または削除 (Azure AI Search REST API)
HTTP POST を使用して、指定したインデックスに 検索ドキュメントをインポート できます。 大規模な更新では、バッチ処理 (バッチあたり最大 1000 ドキュメント、またはバッチあたり約 16 MB) が推奨され、インデックス作成のパフォーマンスが大幅に向上します。
POST https://[service name].search.windows.net/indexes/[index name]/docs/index?api-version=[api-version]
Content-Type: application/json
api-key: [admin key]
サポートされている Azure データ ソースの場合、 インデクサー は、ドキュメントを追加および更新するためのより簡単な代替手段を提供します。 詳細については、インデクサーの操作に関するページを参照してください。
URI パラメーター
| パラメーター | 説明 |
|---|---|
| サービス名 | 必須。 これを検索サービスの一意のユーザー定義名に設定します。 |
| インデックス名 | ドキュメントを投稿するインデックスを指定する URI で必須。 一度に 1 つのインデックスに対してのみ、ドキュメントを POST できます。 |
| api-version | 必須。 現在の安定バージョンは です api-version=2020-06-30。 その他 のバージョンについては、「API のバージョン 」を参照してください。 |
要求ヘッダー
次の表では、必須と省略可能の要求ヘッダーについて説明します。
| フィールド | 説明 |
|---|---|
| Content-Type | 必須。 これを application/json |
| api-key | Azure ロールを使用していて、要求でベアラー トークンが提供されている場合は省略可能。それ以外の場合はキーが必要です。 api-key は、検索サービスに対する要求を認証する一意のシステム生成文字列です。 ドキュメントをアップロードするには、管理者 API キーが必要です。 詳細については、「 キー認証を使用して Azure AI Search に接続 する」を参照してください。 |
要求本文
要求の本文には、インデックスを作成する 1 つまたは複数のドキュメントが含まれます。 ドキュメントは、大文字と小文字を区別する一意のキーによって識別されます。 各ドキュメントは、アクション "upload"、"delete"、"merge"、または "mergeOrUpload" に関連付けられます。 アップロード要求には、キー/値ペアのセットとしてドキュメント データが含まれる必要があります。
{
"value": [
{
"@search.action": "upload (default) | merge | mergeOrUpload | delete",
"key_field_name": "unique_key_of_document", (key/value pair for key field from index schema)
"field_name": field_value (key/value pairs matching index schema)
...
},
...
]
}
| プロパティ | 説明 |
|---|---|
| @search.action | 必須。 有効な値は、"upload"、"delete"、"merge"、または "mergeOrUpload" です。 既定値は "upload" です。 同じバッチで、ドキュメントごとに 1 つずつアクションを組み合わせることができます。
"upload": アップロード アクションは、ドキュメントが新しい場合は挿入され、存在する場合は更新/置換される 'upsert' に似ています。 更新ケースでは、すべてのフィールドが置き換えられます。 "delete": 削除すると、指定したドキュメントがインデックスから削除されます。 キー フィールド以外の削除操作で指定したフィールドは無視されます。 ドキュメントから個々のフィールドを削除する場合は、代わりに を使用 merge し、フィールドを 明示的に に null設定します。
"mergeOrUpload": 指定したキーを持つドキュメントがインデックスに既に存在する場合、このアクションは merge と同様に動作します。 ドキュメントが存在しない場合は、新しいドキュメントでのアップロードと同様に動作します。 "merge": Merge は、指定されたフィールドを持つ既存のドキュメントを更新します。 ドキュメントが存在しない場合、マージは失敗します。 マージで指定したすべてのフィールドは、ドキュメント内の既存のフィールドを置き換えます。 これは、プリミティブ型と複合型のコレクションにも適用されます。 プリミティブ コレクションで、値が ["budget"] の Collection(Edm.String) 型の Tags フィールドがドキュメントに含まれており、Tag に ["economy"、"pool"] の値を持つマージを実行すると、Tags フィールドの最終的な値は ["economy","pool"] になります。 ["budget", "economy", "pool"] にはなりません。 複合コレクションでは、ドキュメントに Rooms という名前の複合コレクション フィールドが含まれている場合、値は [{ "Type": "Budget Room", "BaseRate": 75.0 }]、値 [{ "Type": "Standard Room" }、{ "Type": "Budget Room"、"BaseRate": 60.5 }] の値でマージを実行すると、Rooms フィールドの最終的な値は [{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }] になります。 [{ "Type": "Budget Room", "BaseRate": 75.0 }, { "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }] (append elements) [{ "Type": "Standard Room", "BaseRate": 75.0 }, { "Type": "Budget Room", "BaseRate": 60.5 }] (要素を順番にマージしてから追加) |
| key_field_name | 必須。 ドキュメント キーとして機能し、一意の値のみを含むインデックス内のフィールド定義。 ドキュメント キーには、文字、数字、ダッシュ ()、アンダースコア ("-")、等号 ("_""=") のみを含めることができます。大文字と小文字は区別されます。 詳細については、「 名前付け規則」を参照してください。 |
| field_name | 必須。 名前と値のペア。フィールドの名前は、インデックス定義のフィールド名に対応します。 値はユーザー定義ですが、フィールド型に対して有効である必要があります。 |
注意
要求本文で最初に実行されるアクションの順序付けの保証はありません。 1 つの要求本文で同じドキュメントに複数の "マージ" アクションを関連付けすることはお勧めしません。 同じドキュメントに複数の "マージ" アクションが必要な場合は、検索インデックス内のドキュメントを更新する前に、マージ クライアント側を実行します。
Response
状態コード: 正常な応答のために 200 が返されます。つまり、すべての項目が永続的に格納され、インデックスの作成が開始されます。 インデックス作成はバックグラウンドで実行され、インデックス作成操作が完了してから数秒後に新しいドキュメントを使用できるようになります (つまり、クエリ可能で検索可能)。 特定の遅延は、サービスの負荷によって異なります。
インデックス作成が成功すると、すべてのアイテムに対して status プロパティが true に設定され、statusCode プロパティが 201 (新しくアップロードされたドキュメントの場合) または 200 (マージまたは削除されたドキュメントの場合) に設定されます。
{
"value": [
{
"key": "unique_key_of_new_document",
"status": true,
"errorMessage": null,
"statusCode": 201
},
{
"key": "unique_key_of_merged_document",
"status": true,
"errorMessage": null,
"statusCode": 200
},
{
"key": "unique_key_of_deleted_document",
"status": true,
"errorMessage": null,
"statusCode": 200
}
]
}
状態コード: 少なくとも 1 つの項目のインデックスが正常に作成されなかった場合、207 が返されます。 インデックスが作成されていないアイテムには、状態フィールドが false に設定されています。 errorMessage プロパティと statusCode プロパティは、インデックス作成エラーの理由を示します。
{
"value": [
{
"key": "unique_key_of_document_1",
"status": false,
"errorMessage": "The search service is too busy to process this document. Please try again later.",
"statusCode": 503
},
{
"key": "unique_key_of_document_2",
"status": false,
"errorMessage": "Document not found.",
"statusCode": 404
},
{
"key": "unique_key_of_document_3",
"status": false,
"errorMessage": "Index is temporarily unavailable because it was updated with the 'allowIndexDowntime' flag set to 'true'. Please try again later.",
"statusCode": 422
}
]
}
errorMessage プロパティは、可能であればインデックス作成エラーの理由を示します。
次の表では、応答で返すことができるさまざまなドキュメントごとの 状態コード について説明します。 一部の状態コードは要求自体の問題を示し、他の状態は一時的なエラー状態を示します。 後者の場合は、待機してから再試行する必要があります。
| status code | 意味 | 再試行可能 | Notes |
|---|---|---|---|
| 200 | ドキュメントは正常に変更または削除されました。 | 該当なし | 削除操作はべき等です。 つまり、ドキュメント キーがインデックスに存在しない場合でも、そのキーを使用して削除操作を試みると、状態コードは 200 になります。 |
| 201 | ドキュメントは正常に作成されました。 | 該当なし | |
| 400 | ドキュメントにエラーがあり、インデックスを作成できませんでした。 | いいえ | 応答のエラー メッセージは、ドキュメントの問題を示しています。 |
| 404 | 指定されたキーがインデックスに存在しないため、ドキュメントをマージできませんでした。 | いいえ | このエラーは、新しいドキュメントを作成するためアップロードには発生しません。また、削除は べき等であるため、発生しません。 |
| 409 | ドキュメントのインデックスを作成しようとしたときにバージョンの競合が検出されました。 | Yes | これは、同じドキュメントに対して同時に複数回インデックスを作成しようとしたときに発生することがあります。 |
| 422 | インデックスは、allowIndexDowntime フラグを true に設定して更新されたため、一時的に使用できない状態です。 | Yes | |
| 503 | 検索サービスは一時的に使用できない状態です。負荷が高いことが原因として考えられます。 | Yes | この場合は、待機してから再試行する必要があります。そうしないと、サービスを使用できない状態が長引く場合があります。 |
注意
クライアント コードで 207 応答が頻繁に検出される場合、理由の 1 つとしてシステムが高負荷の状態にあることが考えられます。 これは、 statusCode プロパティが 503 になっているかどうかをチェックすることで確認できます。 高い負荷状態にある場合は、インデックス作成の要求を調整することをお勧めします。 調整しないでインデックス作成トラフィックが減らない場合、システムは 503 エラーですべての要求を拒否し始めることがあります。
状態コード: 429 は、インデックスあたりのドキュメント数に対するクォータを超過したことを示します。 新しいインデックスを作成するか、またはさらに高い処理能力の限界にアップグレードする必要があります。
例
例: 2 つの完全に定義されたドキュメントをアップロードする
{
"value": [
{
"@search.action": "upload",
"HotelId": "1",
"HotelName": "Secret Point Motel",
"Description": "The hotel is ideally located on the main commercial artery of the city in the heart of New York.",
"Category": "Boutique",
"Tags": [ "pool", "air conditioning", "concierge" ],
"ParkingIncluded": false,
"LastRenovationDate": "1970-01-18T00:00:00Z",
"Rating": 3.60,
"Address": {
"StreetAddress": "677 5th Ave",
"City": "New York",
"StateProvince": "NY",
"PostalCode": "10022",
"Country": "USA"
},
"Location": {
"type": "Point",
"coordinates": [ -73.975403, 40.760586 ]
},
"Rooms": [
{
"Description": "Budget Room, 1 Queen Bed (Cityside)",
"Description_fr": "Chambre Économique, 1 grand lit (côté ville)",
"Type": "Budget Room",
"BaseRate": 96.99,
"BedOptions": "1 Queen Bed",
"SleepsCount": 2,
"SmokingAllowed": true,
"Tags": [ "vcr/dvd" ]
},
{
"Description": "Budget Room, 1 King Bed (Mountain View)",
"Description_fr": "Chambre Économique, 1 très grand lit (Mountain View)",
"Type": "Budget Room",
"BaseRate": 80.99,
"BedOptions": "1 King Bed",
"SleepsCount": 2,
"SmokingAllowed": true,
"Tags": [ "vcr/dvd", "jacuzzi tub" ]
}
]
},
{
"@search.action": "upload",
"HotelId": "2",
"HotelName": "Twin Dome Motel",
"Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts.",
"Description_fr": "L'hôtel est situé dans une place du XIXe siècle, qui a été agrandie et rénovée aux plus hautes normes architecturales pour créer un hôtel moderne, fonctionnel et de première classe dans lequel l'art et les éléments historiques uniques coexistent avec le confort le plus moderne.",
"Category": "Boutique",
"Tags": [ "pool", "free wifi", "concierge" ],
"ParkingIncluded": false,
"LastRenovationDate": "1979-02-18T00:00:00Z",
"Rating": 3.60,
"Address": {
"StreetAddress": "140 University Town Center Dr",
"City": "Sarasota",
"StateProvince": "FL",
"PostalCode": "34243",
"Country": "USA"
},
"Location": {
"type": "Point",
"coordinates": [ -82.452843, 27.384417 ]
},
"Rooms": [
{
"Description": "Suite, 2 Double Beds (Mountain View)",
"Description_fr": "Suite, 2 lits doubles (vue sur la montagne)",
"Type": "Suite",
"BaseRate": 250.99,
"BedOptions": "2 Double Beds",
"SleepsCount": 2,
"SmokingAllowed": false,
"Tags": [ "Room Tags" ]
}
]
},
{
"@search.action": "merge",
"HotelId": "3",
"Rating": 2.39,
"Description": "Surprisingly expensive",
"LastRenovationDate": null
},
{
"@search.action": "delete",
"hotelId": "4"
}
]
}
注意
タイム ゾーン情報を含む値をインデックスにアップロード DateTimeOffset すると、Azure AI Search によってこれらの値が UTC に正規化されます。 たとえば、2019-01-13T14:03:00-08:00 は 2019-01-13T22:03:00Z として格納されます。 タイム ゾーン情報を格納する必要がある場合は、インデックスに列を追加する必要があります。