Hinzufügen, Aktualisieren oder Löschen von Dokumenten (Azure Cognitive Search REST-API)
Sie können Suchdokumente mithilfe von HTTP POST in einen angegebenen Index importieren. Für große Anzahl von Updates wird das Batching von Dokumenten (bis zu 1000 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, der angibt, welchen Index Dokumente posten sollen. 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 | Erforderlich. Eine eindeutige, systemgenerierte Zeichenfolge, die die Anforderung an Ihren Suchdienst authentifiziert. Das Hochladen von Dokumenten erfordert einen Administrator-API-Schlüssel. Sie können Schlüssel aus dem Azure-Portal abrufen. Weitere Informationen finden Sie unter Suchen vorhandener Schlüssel. |
Anforderungstext
Der Anforderungstext enthält ein oder mehrere zu indizierende Dokumente. Dokumente werden durch einen eindeutigen Groß-/Kleinschreibungsschlüssel identifiziert. Jedes Dokument ist einer 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". Standardeinstellung für "Upload". Sie können Aktionen, eine pro Dokument, in derselben Batch kombinieren. "upload": Eine Uploadaktion ähnelt einem "upsert", in 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. Jedes Feld, das Sie in einem Löschvorgang angeben, außer dem Schlüsselfeld, wird ignoriert. Wenn Sie ein einzelnes Feld aus einem Dokument entfernen möchten, verwenden merge Sie stattdessen das Feld, und legen Sie das Feld explizit auf null. "mergeOrUpload": Diese Aktion verhält sich wie zusammenführen, 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": Zusammenführen 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 Grundtypen und komplexen Typen. Wenn das Dokument ein Feld vom Typ "Tags" enthält(Edm.String) mit einem Wert von ["Budget"], und Sie führen einen Zusammenführen mit einem Wert von ["economy", "pool"] für Tag aus, wird der Endgültige Wert des Tags-Felds ["Economy", "pool"]. Er entspricht nicht ["budget", "economy", "pool"]. Wenn das Dokument in komplexen Sammlungen ein komplexes Auflistungsfeld mit dem Namen "Räume" mit einem Wert von [{ "Type": "Budget Room" enthält, "BaseRate": 75.0 }], und Sie führen einen Zusammenführen mit einem Wert von [{ "Type": "Standardroom" }, { "Type": "Budget Room", "BaseRate": 60.5 }], der endgültige Wert des Felds "Räume" lautet [{ "Type": "Standardroom" }, { "Type": "Budget Room", "BaseRate": 60.5 }]. Es ist keine der folgenden:[{ "Type": "Budget Room", "BaseRate": 75.0 }, { "Type": "Standardroom" }, { "Type": "Budget Room", "BaseRate": 60.5 }] (Anfügeelemente)[{ "Type": "Standardroom", "BaseRate": 75.0 }, { "Type": "Budget Room", "BaseRate": 60.5 }] (Zusammenführen von Elementen in der Reihenfolge, dann anfügen beliebige Extras) |
| key_field_name | Erforderlich. Eine Felddefinition im Index, die als Dokumentschlüssel dient und nur eindeutige Werte enthält. Dokumentschlüssel können nur Buchstaben, Zahlen, Striche (), Unterstriche () und Gleichheitszeichen"=" ("-""_") enthalten und groß- und kleinschreibungsempfindlich sein. Weitere Informationen finden Sie unter Benennungsregeln. |
| field_name | Erforderlich. Namenwertpaare, bei denen der Name des Felds einem Feldnamen in der Indexdefinition entspricht. Der Wert ist benutzerdefinierter Wert, muss jedoch für den Feldtyp gültig sein. |
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 neue Dokumente zur Verfügung (das heißt, abfragebar und durchsuchbar), einige Sekunden nach Abschluss des Indizierungsvorgangs. Die spezifische Verzögerung hängt vom Laden des Diensts ab.
Erfolgreiche Indizierung wird durch die Statuseigenschaft angegeben, die für alle Elemente auf true festgelegt wird, sowie 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. Elemente, die nicht indiziert wurden, haben das Statusfeld auf "false" festgelegt. Die Eigenschaften "errorMessage" und "statusCode" geben den Grund für den Indexfehler 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 zeigt ggf. den Grund für den Indizierungsfehler an.
In der folgenden Tabelle werden die verschiedenen Statuscodes pro Dokument erläutert, die in der Antwort zurückgegeben werden können. Einige Statuscodes geben Probleme mit der Anforderung selbst an, während andere temporäre Fehlerbedingungen angeben. 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. Also auch wenn ein Dokumentschlüssel im Index nicht vorhanden ist, führt der Versuch, einen Löschvorgang mit diesem Schlüssel auszuführen, zum Statuscode „200“. |
| 201 | Dokument wurde erfolgreich erstellt. | – | |
| 400 | Das Dokument enthielt einen Fehler, der die Indizierung verhindert hat. | Nein | Die Fehlermeldung in der Antwort weist darauf hin, was mit dem Dokument falsch ist. |
| 404 | Das Dokument konnte nicht zusammengeführt werden, weil der angegebene Schlüssel nicht im Index vorhanden ist. | Nein | Dieser Fehler tritt nicht für Uploads auf, da sie neue Dokumente erstellen, und nicht für Löschungen, da sie idempotent sind. |
| 409 | Ein Versionskonflikt wurde erkannt, als Sie versuchten, ein Dokument zu indizieren. | Ja | 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. | Ja | |
| 503 | Ihr Suchdienst ist vorübergehend nicht verfügbar, möglicherweise aufgrund starker Auslastung. | Ja | 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 zwei vollständig definierte Dokumente
{
"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 hochladenDateTimeOffset, normalisiert Azure Cognitive Search diese Werte in 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 Ihrem Index eine zusätzliche Spalte hinzufügen.