Dodawanie, aktualizowanie lub usuwanie dokumentów (interfejs API REST w wersji zapoznawczej)
Dotyczy: 2023-07-01-Preview
Ważne
2023-07-01-Preview dodaje:
- Obsługa pól wektorowych w dokumencie.
Dokumenty zawierające pola wektorowe można wypchnąć do określonego indeksu przy użyciu protokołu HTTP POST. W przypadku dużej aktualizacji przetwarzanie wsadowe (do 1000 dokumentów na partię lub około 16 MB na partię) zwiększa wydajność indeksowania.
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]
Parametry identyfikatora URI
| Parametr | Opis |
|---|---|
| nazwa usługi | Wymagane. Ustaw tę wartość na unikatową, zdefiniowaną przez użytkownika nazwę usługi wyszukiwania. |
| nazwa indeksu | Wymagane. Ustaw tę wartość na nazwę indeksu odbierającego dokumenty. Jednocześnie można publikować tylko dokumenty w jednym indeksie. |
| api-version | Wymagane. Bieżąca wersja zapoznawcza to 2023-07-23-Preview. Zobacz Wersje interfejsu API , aby uzyskać więcej wersji. |
Nagłówki żądań
W poniższej tabeli opisano wymagane i opcjonalne nagłówki żądań.
| Pola | Opis |
|---|---|
| Content-Type | Wymagane. Ustaw tę wartość na application/json |
| api-key | Opcjonalnie, jeśli używasz ról platformy Azure , a token elementu nośnego jest dostarczany w żądaniu, w przeciwnym razie wymagany jest klucz. Api-key to unikatowy ciąg generowany przez system, który uwierzytelnia żądanie w usłudze wyszukiwania. Przekazywanie dokumentów wymaga klucza interfejsu API administratora. Aby uzyskać szczegółowe informacje, zobacz Nawiązywanie połączenia z usługą Azure AI Search przy użyciu uwierzytelniania klucza . |
Treść żądania
Treść żądania zawiera co najmniej jeden dokument do indeksowania. Dokumenty są jednoznacznie identyfikowane za pomocą klucza z uwzględnieniem wielkości liter. Każdy dokument jest skojarzony z akcją: "upload", "delete", "merge" lub "mergeOrUpload". Żądania przekazywania muszą zawierać dane dokumentu jako zestaw par klucz/wartość.
Pola wektorowe mają typ Collection(Edm.Single). Dane wektorowe składają się z tablicy liczb zmiennoprzecinkowych o pojedynczej precyzji.
Pola wektorowe mogą zawierać tysiące osadzania, w zależności od złożoności, długości lub typu oryginalnej zawartości. Usługa Azure AI Search nie konwertuje zawartości na osadzanie. Dokumenty wypychane do indeksu muszą zawierać wcześniej wygenerowane osadzanie.
{
"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 ]
...
},
...
]
}
| Właściwość | Opis |
|---|---|
| @search.action | Wymagane. Prawidłowe wartości to "upload", "delete", "merge" lub "mergeOrUpload". Wartość domyślna to "upload". |
| key_field_name | Wymagane. Definicja pola w indeksie, która służy jako klucz dokumentu i zawiera tylko unikatowe wartości. Klucze dokumentów mogą zawierać tylko litery, cyfry, kreski ("-"), podkreślenia ("_") i znaki równości ("=") i uwzględniać wielkość liter. |
| Field_name | Wymagane. Pary nazwa-wartość, gdzie nazwa pola odpowiada nazwie pola w definicji indeksu. Wartość jest zdefiniowana przez użytkownika, ale musi być prawidłowa dla typu pola. |
Reakcja
Kod stanu: 200 jest zwracany dla pomyślnej odpowiedzi, co oznacza, że wszystkie elementy zostały trwale przechowywane i że indeksowanie zostało rozpoczęte. Indeksowanie jest uruchamiane w tle i udostępnia nowe dokumenty (czyli możliwość wykonywania zapytań i przeszukiwania) kilka sekund po zakończeniu operacji indeksowania.
Pomyślne indeksowanie jest wskazywane, gdy właściwość stanu ustawiona na wartość true dla wszystkich elementów. Właściwość statusCode powinna mieć wartość 201 (dla nowo przekazanych dokumentów) lub 200 (dla scalonych lub usuniętych dokumentów).
Przykłady
Przykład: przekazywanie dwóch dokumentów przy użyciu zawartości tekstowej i wektorowej
W celu zapewnienia czytelności w poniższym przykładzie przedstawiono podzbiór dokumentów i osadzania. Treść żądania przekazywania dokumentów składa się z 108 dokumentów, z których każdy ma pełny zestaw osadzonych elementów "titleVector" i "contentVector".
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"
}
. . .
]
}
Uwaga
Podczas przekazywania DateTimeOffset wartości z informacjami o strefie czasowej do indeksu usługa Azure AI Search normalizuje te wartości do czasu UTC. Na przykład 2019-01-13T14:03:00-08:00 będzie przechowywany jako 2019-01-13T22:03:00Z. Jeśli musisz przechowywać informacje o strefie czasowej, dodaj dodatkową kolumnę do indeksu.