Hinzufügen, Aktualisieren oder Löschen von Dokumenten (Azure AI Search-REST-API)
Sie können Suchdokumente mithilfe von HTTP POST in einen angegebenen Index importieren. Für ein großes Update wird die Batchverarbeitung (bis zu 1.000 Dokumente pro Batch oder ca. 16 MB pro Batch) empfohlen und verbessert die Indizierungsleistung erheblich.
POST https://[service name].search.windows.net/indexes/[index name]/docs/index?api-version=[api-version]
Content-Type: application/json
api-key: [admin key]
Für unterstützte Azure-Datenquellen bieten Indexer eine einfachere Alternative zum Hinzufügen und Aktualisieren von Dokumenten. Weitere Informationen finden Sie unter Indexer operations (Indexer-Vorgänge).
URI-Parameter
| Parameter | BESCHREIBUNG |
|---|---|
| Dienstname | Erforderlich. Legen Sie dies auf den eindeutigen, benutzerdefinierten Namen Ihres Suchdiensts fest. |
| Indexname | Erforderlich für den URI, um anzugeben, welcher Index dokumente geposten werden soll. Sie können Dokumente jeweils nur in einem Index bereitstellen. |
| api-version | Erforderlich. Die aktuelle stabile Version ist api-version=2020-06-30. Weitere Versionen finden Sie unter API-Versionen . |
Anforderungsheader
Die folgende Tabelle beschreibt die erforderlichen und optionalen Anforderungsheader.
| Felder | BESCHREIBUNG |
|---|---|
| Content-Type | Erforderlich. Auf application/json |
| api-key | Optional, wenn Sie Azure-Rollen verwenden und ein Bearertoken für die Anforderung bereitgestellt wird, andernfalls ist ein Schlüssel erforderlich. Ein API-Schlüssel ist eine eindeutige, vom System generierte Zeichenfolge, die die Anforderung bei Ihrem Suchdienst authentifiziert. Für das Hochladen von Dokumenten ist ein Administrator-API-Schlüssel erforderlich. Weitere Informationen finden Sie unter Herstellen einer Verbindung mit Azure AI Search mithilfe der Schlüsselauthentifizierung . |
Anforderungstext
Der Anforderungstext enthält ein oder mehrere zu indizierende Dokumente. Dokumente werden durch einen eindeutigen Schlüssel identifiziert, bei dem die Groß-/Kleinschreibung beachtet wird. Jedem Dokument ist eine Aktion zugeordnet: "upload", "delete", "merge" oder "mergeOrUpload". Anforderungen zum Hochladen müssen die Dokumentdaten als einen Satz mit Schlüssel-Wert-Paare enthalten.
{
"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)
...
},
...
]
}
| Eigenschaft | BESCHREIBUNG |
|---|---|
| @search.action | Erforderlich. Gültige Werte sind "upload", "delete", "merge" oder "mergeOrUpload". Standardmäßig wird "upload" festgelegt. Sie können Aktionen, eine pro Dokument, im selben Batch kombinieren.
"Hochladen": Eine Uploadaktion ähnelt einem "Upsert", bei dem das Dokument eingefügt wird, wenn es neu ist und aktualisiert/ersetzt wird, wenn es vorhanden ist. Alle Felder werden im Updatefall ersetzt. "delete": Delete entfernt das angegebene Dokument aus dem Index. Alle Felder, die Sie in einem Löschvorgang angeben, mit Ausnahme des Schlüsselfelds, werden ignoriert. Wenn Sie ein einzelnes Feld aus einem Dokument entfernen möchten, verwenden Sie merge stattdessen, und legen Sie das Feld explizit auf fest null.
"mergeOrUpload": Diese Aktion verhält sich wie merge, wenn ein Dokument mit dem angegebenen Schlüssel bereits im Index vorhanden ist. Wenn das Dokument nicht vorhanden ist, verhält es sich wie das Hochladen mit einem neuen Dokument. "merge": Merge aktualisiert ein vorhandenes Dokument mit den angegebenen Feldern. Wenn das Dokument nicht vorhanden ist, schlägt die Zusammenführung fehl. Jedes Feld, das Sie in einer Zusammenführung angeben, ersetzt das vorhandene Feld im Dokument. Dies gilt auch für Sammlungen von primitiven und komplexen Typen. Wenn das Dokument in primitiven Sammlungen ein Feld Tags des Typs Collection(Edm.String) mit dem Wert ["budget"] enthält und Sie eine Zusammenführung mit dem Wert ["economy", "pool"] für Tag ausführen, lautet der endgültige Wert des Felds Tags ["economy", "pool"]. Er entspricht nicht ["budget", "economy", "pool"]. Wenn das Dokument in komplexen Sammlungen ein komplexes Sammlungsfeld mit dem Namen Räume mit dem Wert [{ "Type": "Budget Room" enthält, "BaseRate": 75.0 }], und Sie führen eine Zusammenführung mit dem Wert [{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }], aus, und Sie führen eine Zusammenführung mit dem Wert [{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }]. Es wird keines der folgenden sein: [{ "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 }] (Elemente in der Reihenfolge zusammenführen, dann alle Extras anfügen) |
| key_field_name | Erforderlich. Eine Felddefinition im Index, die als Dokumentschlüssel dient und nur eindeutige Werte enthält. Dokumentschlüssel dürfen nur Buchstaben, Zahlen, Bindestriche (), Unterstriche ("-""_") und Gleichheitszeichen ("=") enthalten und beachten die Groß-/Kleinschreibung. Weitere Informationen finden Sie unter Benennungsregeln. |
| field_name | Erforderlich. Name-Wert-Paare, bei denen der Name des Felds einem Feldnamen in der Indexdefinition entspricht. Der Wert ist benutzerdefinierter Wert, muss aber für den Feldtyp gültig sein. |
Hinweis
Es gibt keine Bestellgarantien, für die die Aktion im Anforderungstext zuerst ausgeführt wird. Es wird nicht empfohlen, mehrere Zusammenführungsaktionen demselben Dokument in einem einzelnen Anforderungstext zuzuordnen. Wenn für dasselbe Dokument mehrere Mergeaktionen erforderlich sind, führen Sie die clientseitige Zusammenführung durch, bevor Sie das Dokument im Suchindex aktualisieren.
Antwort
Statuscode: 200 wird für eine erfolgreiche Antwort zurückgegeben, was bedeutet, dass alle Elemente dauerhaft gespeichert wurden und beginnen, indiziert zu werden. Die Indizierung wird im Hintergrund ausgeführt und stellt einige Sekunden nach Abschluss des Indizierungsvorgangs neue Dokumente (d. h. abfrage- und durchsuchbar) zur Verfügung. Die spezifische Verzögerung hängt von der Auslastung des Diensts ab.
Eine erfolgreiche Indizierung wird durch die status-Eigenschaft angezeigt, die für alle Elemente auf true festgelegt wird, sowie durch die statusCode-Eigenschaft, die entweder auf 201 (für neu hochgeladene Dokumente) oder 200 (für zusammengeführte oder gelöschte Dokumente) festgelegt wird:
{
"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
}
]
}
Statuscode: 207 wird zurückgegeben, wenn mindestens ein Element nicht erfolgreich indiziert wurde. Für Elemente, die nicht indiziert wurden, ist das feld status auf false festgelegt. Die Eigenschaften errorMessage und statusCode geben den Grund für den Indizierungsfehler an:
{
"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
}
]
}
Die errorMessage-Eigenschaft gibt den Grund für den Indizierungsfehler an, wenn möglich.
In der folgenden Tabelle werden die verschiedenen status Codes pro Dokument erläutert, die in der Antwort zurückgegeben werden können. Einige status-Codes weisen auf Probleme mit der Anforderung selbst hin, während andere auf temporäre Fehlerbedingungen hinweisen. Das Letztere sollten Sie nach einer Verzögerung erneut versuchen.
| Statuscode | Bedeutung | Wiederholbar | Hinweise |
|---|---|---|---|
| 200 | Dokument wurde erfolgreich geändert oder gelöscht. | – | Löschvorgänge sind idempotent. Das heißt, selbst wenn im Index kein Dokumentschlüssel vorhanden ist, führt der Versuch eines Löschvorgangs mit diesem Schlüssel zu einem 200 status Code. |
| 201 | Dokument wurde erfolgreich erstellt. | – | |
| 400 | Das Dokument enthielt einen Fehler, der die Indizierung verhindert hat. | No | Die Fehlermeldung in der Antwort gibt an, was mit dem Dokument falsch ist. |
| 404 | Das Dokument konnte nicht zusammengeführt werden, da der angegebene Schlüssel nicht im Index vorhanden ist. | No | Dieser Fehler tritt bei Uploads nicht auf, da sie neue Dokumente erstellen, und er tritt nicht für Löschvorgänge auf, da sie idempotent sind. |
| 409 | Ein Versionskonflikt wurde erkannt, als Sie versuchten, ein Dokument zu indizieren. | Yes | Dies kann vorkommen, wenn Sie versuchen, mehr als einmal gleichzeitig das gleiche Dokument zu indizieren. |
| 422 | Der Index ist vorübergehend nicht verfügbar, da er aktualisiert wurde, als das Flag „allowIndexDowntime“ auf „true“ gesetzt war. | Yes | |
| 503 | Ihr Suchdienst ist vorübergehend nicht verfügbar, möglicherweise aufgrund starker Auslastung. | Yes | Der Code sollte in diesem Fall vor Wiederholungsversuchen warten, oder es besteht das Risiko, dass die Nichtverfügbarkeit des Diensts verlängert wird. |
Hinweis
Wenn für Ihren Clientcode häufig die Antwort "207" auftritt, ist ein möglicher Grund, dass das System ausgelastet ist. Sie können zur Bestätigung die Eigenschaft statusCode auf „503“ überprüfen. Wenn dies der Fall ist, wird empfohlen, die Indizierungsanforderungen zu drosseln. Nimmt der Indizierdatenverkehr nicht ab, kann dies dazu führen, dass alle Anforderungen mit dem Fehler "503" abgelehnt werden.
Der Statuscode "429" gibt an, dass Sie Ihr Kontingent hinsichtlich der Anzahl der Dokumente pro Index überschritten haben. Erstellen Sie in diesem Fall entweder einen neuen Index oder aktualisieren Sie auf höhere Kapazitätsgrenzen.
Beispiele
Beispiel: Hochladen von zwei vollständig definierten Dokumenten
{
"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"
}
]
}
Hinweis
Wenn Sie Werte mit Zeitzoneninformationen in Ihren Index hochladen DateTimeOffset , normalisiert Azure AI Search diese Werte auf UTC. Beispielsweise wird 2019-01-13T14:03:00-08:00 als 2019-01-13T22:03:00Z gespeichert. Wenn Sie Zeitzoneninformationen speichern müssen, müssen Sie Dem Index eine zusätzliche Spalte hinzufügen.