Hinzufügen, Aktualisieren oder Löschen von Dokumenten (Vorschau-REST-API)
Gilt für: 2023-07-01-Preview
Wichtig
2023-07-01-Preview fügt Folgendes hinzu:
- Unterstützung für Vektorfelder in einem Dokument.
Sie können Dokumente, die Vektorfelder enthalten, mithilfe von HTTP POST per Push in einen angegebenen Index übertragen. Bei einem großen Update verbessert die Batchverarbeitung (bis zu 1000 Dokumente pro Batch oder etwa 16 MB pro Batch) die Indizierungsleistung.
POST https://[service name].search.windows.net/indexes/[index name]/docs/index?api-version=2023-07-01-Preview
Content-Type: application/json
api-key: [admin key]
URI-Parameter
| Parameter | BESCHREIBUNG |
|---|---|
| Dienstname | Erforderlich. Legen Sie diesen Wert auf den eindeutigen, benutzerdefinierten Namen Ihres Suchdiensts fest. |
| Indexname | Erforderlich. Legen Sie diesen Wert auf den Namen des Indexes fest, der die Dokumente empfängt. Sie können Dokumente jeweils nur in einem Index bereitstellen. |
| api-version | Erforderlich. Die aktuelle Vorschauversion ist 2023-07-23-Preview. Weitere Versionen finden Sie unter API-Versionen . |
Anforderungsheader
Die folgende Tabelle beschreibt die erforderlichen und optionalen Anforderungsheader.
| Felder | BESCHREIBUNG |
|---|---|
| Content-Type | Erforderlich. Legen Sie diesen Wert auf fest. application/json |
| api-key | Optional, wenn Sie Azure-Rollen verwenden und in der Anforderung ein Bearertoken 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 eindeutig durch einen Schlüssel identifiziert, bei dem die Groß-/Kleinschreibung beachtet wird. 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.
Vektorfelder sind vom Typ Collection(Edm.Single). Vektordaten bestehen aus einem Array von Gleitkommazahlen mit einfacher Genauigkeit.
Vektorfelder können je nach Komplexität, Länge oder Typ des ursprünglichen Inhalts Tausende von Einbettungen enthalten. Azure KI Search konvertiert Inhalte nicht in Einbettungen. Die Dokumente, die Sie in einen Index übertragen, müssen Einbettungen enthalten, die Sie zuvor generiert haben.
{
"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),
"vector_field_name": [ array of single-precision floating point numbers ]
...
},
...
]
}
| Eigenschaft | BESCHREIBUNG |
|---|---|
| @search.action | Erforderlich. Gültige Werte sind "upload", "delete", "merge" oder "mergeOrUpload". Der Standardwert ist "upload". |
| 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. |
| field_name | Erforderlich. Name-Wert-Paare, wobei der Name des Felds einem Feldnamen in der Indexdefinition entspricht. Der Wert ist benutzerdefinierter Wert, muss aber 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 die Indizierung begonnen hat. Die Indizierung wird im Hintergrund ausgeführt und stellt einige Sekunden nach Abschluss des Indizierungsvorgangs neue Dokumente zur Verfügung (d. h. abfragbar und durchsuchbar).
Die erfolgreiche Indizierung wird angezeigt, wenn die eigenschaft status für alle Elemente auf true festgelegt ist. Die statusCode-Eigenschaft sollte entweder 201 (für neu hochgeladene Dokumente) oder 200 (für zusammengeführte oder gelöschte Dokumente) sein.
Beispiele
Beispiel: Hochladen von zwei Dokumenten mit Text- und Vektorinhalt
Aus Gründen der Lesbarkeit zeigt das folgende Beispiel eine Teilmenge von Dokumenten und Einbettungen. Der Text der Anforderung „Dokumente hochladen“ besteht aus 108 Dokumenten, die jeweils einen vollständigen Satz von Einbettungen für „titleVector“ und „contentVector“ enthalten.
POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/index?api-version={{api-version}}
Content-Type: application/json
api-key: {{admin-api-key}}
{
"value": [
{
"id": "1",
"title": "Azure App Service",
"content": "Azure App Service is a fully managed platform for building, deploying, and scaling web apps. You can host web apps, mobile app backends, and RESTful APIs. It supports a variety of programming languages and frameworks, such as .NET, Java, Node.js, Python, and PHP. The service offers built-in auto-scaling and load balancing capabilities. It also provides integration with other Azure services, such as Azure DevOps, GitHub, and Bitbucket.",
"category": "Web",
"titleVector": [
-0.02250031754374504,
. . .
],
"contentVector": [
-0.024740582332015038,
. . .
],
"@search.action": "upload"
},
{
"id": "2",
"title": "Azure Functions",
"content": "Azure Functions is a serverless compute service that enables you to run code on-demand without having to manage infrastructure. It allows you to build and deploy event-driven applications that automatically scale with your workload. Functions support various languages, including C#, F#, Node.js, Python, and Java. It offers a variety of triggers and bindings to integrate with other Azure services and external services. You only pay for the compute time you consume.",
"category": "Compute",
"titleVector": [
-0.020159931853413582,
. . .
],
"contentVector": [
-0.02780858241021633,,
. . .
],
"@search.action": "upload"
}
. . .
]
}
Hinweis
Wenn Sie Werte mit Zeitzoneninformationen in Ihren Index hochladen DateTimeOffset , normalisiert Azure KI 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, fügen Sie dem Index eine zusätzliche Spalte hinzu.