Dodawanie, aktualizowanie lub usuwanie dokumentów (interfejs API REST usługi Azure AI Search)
Dokumenty wyszukiwania można zaimportować do określonego indeksu przy użyciu protokołu HTTP POST. W przypadku dużej aktualizacji zaleca się przetwarzanie wsadowe (do 1000 dokumentów na partię lub około 16 MB na partię) i znacznie poprawi wydajność indeksowania.
POST https://[service name].search.windows.net/indexes/[index name]/docs/index?api-version=[api-version]
Content-Type: application/json
api-key: [admin key]
W przypadku obsługiwanych źródeł danych platformy Azure indeksatory oferują prostszą alternatywę dla dodawania i aktualizowania dokumentów. Aby uzyskać więcej informacji, zobacz Operacje indeksatora.
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 w identyfikatorze URI, określając indeks do publikowania dokumentów. Dokumenty można publikować tylko w jednym indeksie jednocześnie. |
| api-version | Wymagane. Bieżąca stabilna wersja to api-version=2020-06-30. 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 udostępniany w żądaniu, w przeciwnym razie wymagany jest klucz. Klucz api-key to unikatowy, generowany przez system ciąg, 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ą identyfikowane przez unikatowy klucz uwzględniający wielkość liter. Każdy dokument jest skojarzony z akcją: "upload", "delete", "merge" lub "mergeOrUpload". Żądania przekazywania muszą zawierać dane dokumentu jako zestaw par klucz/wartość.
{
"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)
...
},
...
]
}
| Właściwość | Opis |
|---|---|
| @search.action | Wymagane. Prawidłowe wartości to "upload", "delete", "merge" lub "mergeOrUpload". Wartość domyślna to "upload". Możesz połączyć akcje, jeden na dokument, w tej samej partii. "upload": Akcja przekazywania jest podobna do "upsert", w której dokument zostanie wstawiony, jeśli jest on nowy i zaktualizowany/zastąpiony, jeśli istnieje. Wszystkie pola są zastępowane w przypadku aktualizacji. "delete": Usunięcie usuwa określony dokument z indeksu. Każde pole określone w operacji usuwania, inne niż pole klucza, zostanie zignorowane. Jeśli chcesz usunąć pojedyncze pole z dokumentu, użyj merge zamiast tego i ustaw jawnie pole na null. "mergeOrUpload": ta akcja zachowuje się jak scalanie, jeśli dokument z danym kluczem już istnieje w indeksie. Jeśli dokument nie istnieje, zachowuje się jak przekazywanie przy użyciu nowego dokumentu. "merge": Scalaj aktualizuje istniejący dokument z określonymi polami. Jeśli dokument nie istnieje, scalanie zakończy się niepowodzeniem. Wszystkie pola, które określisz w żądaniu scalania, zastąpią istniejące pola w dokumencie. Dotyczy to również kolekcji typów pierwotnych i złożonych. W kolekcjach pierwotnych, jeśli dokument zawiera pole Tagi typu Collection(Edm.String) z wartością ["budget"], a scalanie z wartością ["economy", "pool"] dla tagu, ostateczną wartością pola Tagi będzie ["economy", "pool". Nie będzie to ["budżet", "gospodarka", "pula". W złożonych kolekcjach, jeśli dokument zawiera złożone pole kolekcji o nazwie Rooms o wartości [{ "Type": "Budget Room", "BaseRate": 75.0 }] i wykonujesz scalanie z wartością [{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }], ostateczną wartością pola Pokoje będzie [{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }]. Nie będzie to jeden z następujących elementów: [{ "Type": "Budget Room", "BaseRate": 75.0 }, { "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }] (dołączanie elementów) [{ "Type": "Standard Room", "BaseRate": 75.0 }, { "Type": "Budget Room", "BaseRate": 60.5 }] (scalanie elementów w kolejności, a następnie dołączanie wszelkich dodatków) |
| key_field_name | Wymagane. Definicja pola w indeksie, który 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. Aby uzyskać więcej informacji, zobacz Reguły nazewnictwa. |
| Field_name | Wymagane. Pary name-value, gdzie nazwa pola odpowiada nazwie pola w definicji indeksu. Wartość jest zdefiniowana przez użytkownika, ale musi być prawidłowa dla typu pola. |
Uwaga
Nie ma gwarancji kolejności, dla których akcja w treści żądania jest wykonywana najpierw. Nie zaleca się posiadania wielu akcji "scalania" skojarzonych z tym samym dokumentem w jednej treści żądania. Jeśli istnieje wiele akcji "scalania" wymaganych dla tego samego dokumentu, wykonaj scalanie po stronie klienta przed zaktualizowaniem dokumentu w indeksie wyszukiwania.
Reakcja
Kod stanu: 200 jest zwracany dla pomyślnej odpowiedzi, co oznacza, że wszystkie elementy zostały przechowywane trwale i zaczną być indeksowane. Indeksowanie jest uruchamiane w tle i udostępnia nowe dokumenty (czyli możliwe do wykonywania zapytań i przeszukiwania) kilka sekund po zakończeniu operacji indeksowania. Określone opóźnienie zależy od obciążenia usługi.
Pomyślne indeksowanie jest wskazywane przez właściwość statusu ustawioną na wartość true dla wszystkich elementów, a także właściwość statusCode ustawioną na wartość 201 (dla nowo przekazanych dokumentów) lub 200 (dla scalonych lub usuniętych dokumentów):
{
"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
}
]
}
Kod stanu: 207 jest zwracany, gdy co najmniej jeden element nie został pomyślnie indeksowany. Elementy, które nie zostały indeksowane, mają pole stanu ustawione na wartość false. Właściwości errorMessage i statusCode wskazują przyczynę błędu indeksowania:
{
"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
}
]
}
Właściwość errorMessage wskazuje przyczynę błędu indeksowania, jeśli jest to możliwe.
W poniższej tabeli opisano różne kody stanu poszczególnych dokumentów, które można zwrócić w odpowiedzi. Niektóre kody stanu wskazują problemy z samym żądaniem, a inne wskazują tymczasowe warunki błędu. Te ostatnie należy ponowić próbę po opóźnieniu.
| Kod stanu | Znaczenie | Z możliwością ponowienia próby | Uwagi |
|---|---|---|---|
| 200 | Dokument został pomyślnie zmodyfikowany lub usunięty. | n/d | Operacje usuwania są idempotentne. Oznacza to, że nawet jeśli klucz dokumentu nie istnieje w indeksie, próba usunięcia operacji z tym kluczem powoduje wyświetlenie kodu stanu 200. |
| 201 | Dokument został pomyślnie utworzony. | n/d | |
| 400 | Wystąpił błąd w dokumencie, który uniemożliwił indeksowanie. | Nie | Komunikat o błędzie w odpowiedzi wskazuje, co jest nie tak z dokumentem. |
| 404 | Nie można scalić dokumentu, ponieważ dany klucz nie istnieje w indeksie. | Nie | Ten błąd nie występuje w przypadku przekazywania, ponieważ tworzą nowe dokumenty i nie występują w przypadku usuwania, ponieważ są idempotentne. |
| 409 | Wykryto konflikt wersji podczas próby indeksowania dokumentu. | Tak | Taka sytuacja może wystąpić, gdy równocześnie próbujesz indeksować ten sam dokument więcej niż jeden raz. |
| 422 | Indeks jest tymczasowo niedostępny, ponieważ został on zaktualizowany przy użyciu flagi „allowIndexDowntime” ustawionej na wartość „true”. | Tak | |
| 503 | Usługa wyszukiwania jest tymczasowo niedostępna, prawdopodobnie ze względu na duże obciążenie. | Tak | W takim przypadku należy poczekać przed wykonaniem ponownej próby, aby nie ryzykować przedłużenia niedostępności usługi. |
Uwaga
Jeśli kod klienta często napotyka odpowiedź 207, jedną z możliwych przyczyn jest to, że system jest pod obciążeniem. Możesz to potwierdzić, sprawdzając statusCode właściwość 503. W takim przypadku zalecamy ograniczanie żądań indeksowania. W przeciwnym razie, jeśli indeksowanie ruchu nie ustąpi, system może rozpocząć odrzucanie wszystkich żądań z błędami 503.
Kod stanu: 429 wskazuje, że przekroczono limit przydziału dla liczby dokumentów na indeks. Należy utworzyć nowy indeks lub uaktualnić w celu uzyskania wyższych limitów pojemności.
Przykłady
Przykład: Przekazywanie dwóch w pełni zdefiniowanych dokumentów
{
"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"
}
]
}
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, musisz dodać dodatkową kolumnę do indeksu.