Hinzufügen, Aktualisieren oder Löschen von Dokumenten (Vorschau-REST-API)
gilt für: 2023-07-01-Preview. Diese Version wird nicht mehr unterstützt. Upgrade sofort auf eine neuere Version.
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 in einen angegebenen Index übertragen. Bei einer großen Aktualisierung verbessert das Batching (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. Dokumente können jeweils nur in einem Index gepostt werden. |
| API-Version | Weitere Versionen finden Sie unter API-Versionen. |
Anforderungsheader
In der folgenden Tabelle werden die erforderlichen und optionalen Anforderungsheader beschrieben.
| Felder | Beschreibung |
|---|---|
| Inhaltstyp | Erforderlich. Legen Sie diesen Wert auf application/json |
| API-Schlüssel | 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 an Ihren 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 Textkörper der Anforderung enthält ein oder mehrere Dokumente, die indiziert werden sollen. Dokumente werden durch einen Schlüssel mit Groß-/Kleinschreibung eindeutig identifiziert. Jedes Dokument ist einer Aktion zugeordnet: "hochladen", "löschen", "zusammenführen" oder "mergeOrUpload". Uploadanforderungen müssen die Dokumentdaten als Gruppe von Schlüssel-Wert-Paaren enthalten.
Vektorfelder sind vom Typ Collection(Edm.Single). Vektordaten bestehen aus einem Array mit Gleitkommazahlen mit einfacher Genauigkeit.
Vektorfelder können Tausende von Einbettungen enthalten, je nach Komplexität, Länge oder Typ des ursprünglichen Inhalts. Azure AI Search konvertiert keine Inhalte 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 ]
...
},
...
]
}
| Eigentum | 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 können nur Buchstaben, Zahlen, Gedankenstriche ("-"), Unterstriche ("_") und Gleichheitszeichen ("=") enthalten und Groß-/Kleinschreibung beachten. |
| field_name | Erforderlich. Name-Wert-Paare, wobei 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 dass die Indizierung begonnen hat. Die Indizierung wird im Hintergrund ausgeführt und stellt neue Dokumente (d. h. abfragefähig und durchsuchbar) ein paar Sekunden nach Abschluss des Indizierungsvorgangs zur Verfügung.
Die erfolgreiche Indizierung wird angezeigt, wenn die Statuseigenschaft 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
Zur Lesbarkeit zeigt das folgende Beispiel eine Teilmenge von Dokumenten und Einbettungen. Der Textkörper 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"
}
. . .
]
}
Anmerkung
Wenn Sie DateTimeOffset Werte mit Zeitzoneninformationen in Ihren Index hochladen, normalisiert Azure AI 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, fügen Sie ihrem Index eine zusätzliche Spalte hinzu.