Přidání, aktualizace nebo odstranění dokumentů (rozhraní REST API služby Azure AI Search)
Dokumenty hledání můžete importovat do zadaného indexu pomocí protokolu HTTP POST. U velké aktualizace se doporučuje dávkování (až 1 000 dokumentů na dávku nebo přibližně 16 MB na dávku) a výrazně zlepší výkon indexování.
POST https://[service name].search.windows.net/indexes/[index name]/docs/index?api-version=[api-version]
Content-Type: application/json
api-key: [admin key]
Pro podporované zdroje dat Azure nabízejí indexery jednodušší alternativu pro přidávání a aktualizaci dokumentů. Další informace najdete v tématu Operace indexeru.
Parametry identifikátoru URI
| Parametr | Popis |
|---|---|
| název služby | Povinná hodnota. Nastavte ho na jedinečný, uživatelem definovaný název vaší vyhledávací služby. |
| název indexu | Vyžaduje se u identifikátoru URI a určuje index, který se má publikovat dokumenty. Dokumenty můžete publikovat jenom do jednoho indexu najednou. |
| verze-api | Povinná hodnota. Aktuální stabilní verze je api-version=2020-06-30. Další verze najdete v tématu Verze rozhraní API . |
Hlavičky požadavku
Následující tabulka popisuje požadovanou a volitelnou hlavičku požadavku.
| Pole | Description |
|---|---|
| Typ obsahu | Povinná hodnota. Nastavte tuto možnost na application/json |
| klíč rozhraní API | Volitelné, pokud používáte role Azure a v požadavku je k dispozici nosný token, jinak se vyžaduje klíč. Klíč api-key je jedinečný, systémem vygenerovaný řetězec, který ověřuje požadavek na vaši vyhledávací službu. Nahrávání dokumentů vyžaduje klíč rozhraní API správce. Podrobnosti najdete v tématu Připojení ke službě Azure AI Search pomocí ověřování pomocí klíče . |
Text požadavku
Text požadavku obsahuje jeden nebo více dokumentů, které se mají indexovat. Dokumenty jsou identifikovány jedinečným klíčem s rozlišováním velkých a malých písmen. Ke každému dokumentu je přidružená akce: "upload", "delete", "merge" nebo "mergeOrUpload". Žádosti o nahrání musí obsahovat data dokumentu jako sadu dvojic klíč/hodnota.
{
"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)
...
},
...
]
}
| Vlastnost | Popis |
|---|---|
| @search.action | Povinná hodnota. Platné hodnoty jsou "upload", "delete", "merge" nebo "mergeOrUpload". Výchozí nastavení je nahrát. V každé dávce můžete zkombinovat akce, které jsou po jednom dokumentu.
"nahrát": Akce odeslání se podobá příkazu upsert, do kterého se dokument vloží, pokud je nový, a pokud existuje, aktualizuje nebo nahradí. Všechna pole jsou v případě aktualizace nahrazena. "delete": Odstranění odebere zadaný dokument z indexu. Všechna pole, která zadáte v operaci odstranění, kromě pole s klíčem, budou ignorována. Pokud chcete z dokumentu odebrat jednotlivá pole, použijte merge místo toho a nastavte pole explicitně na null.
MergeOrUpload: Tato akce se chová jako sloučení, pokud už v indexu existuje dokument s daným klíčem. Pokud dokument neexistuje, chová se jako nahrání nového dokumentu. "merge": Sloučení aktualizuje existující dokument se zadanými poli. Pokud dokument neexistuje, sloučení se nezdaří. Každé pole zadané ve sloučení nahradí stávající pole v dokumentu. To platí také pro kolekce primitivních a složitých typů. Pokud v primitivních kolekcích dokument obsahuje pole Tags typu Collection(Edm.String) s hodnotou ["budget"] a provedete sloučení s hodnotou ["economy", "pool"] pro tag, bude konečná hodnota pole Tags ["economy", "pool"]. Nebude to ["rozpočet", "ekonomika", "fond"]. Pokud dokument ve složitých kolekcích obsahuje komplexní pole kolekce s názvem Místnosti s hodnotou [{ "Typ": "Rozpočtová místnost", "BaseRate": 75.0 }] a provedete sloučení s hodnotou [{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }], konečná hodnota pole Rooms bude [{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }]. Nebude to jeden z následujících: [{ "Type": "Budget Room", "BaseRate": 75.0 }, { "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }] (doplňovací prvky) [{ "Type": "Standard Room", "BaseRate": 75.0 }, { "Type": "Budget Room", "BaseRate": 60.5 }] (slučujte prvky v pořadí, pak připojte případné doplňky) |
| key_field_name | Povinná hodnota. Definice pole v indexu, která slouží jako klíč dokumentu a obsahuje pouze jedinečné hodnoty. Klávesy dokumentu můžou obsahovat jenom písmena, číslice, pomlčky ("-"), podtržítka ("_") a znaky rovná se ("=") a rozlišují se u nich velká a malá písmena. Další informace najdete v tématu Pravidla pojmenování. |
| field_name | Povinná hodnota. Páry název-hodnota, kde název pole odpovídá názvu pole v definici indexu. Hodnota je definovaná uživatelem, ale musí být platná pro typ pole. |
Poznámka
Neexistují žádné záruky pořadí, pro které se akce v textu požadavku provede jako první. Nedoporučuje se mít více akcí "sloučení" přidružených ke stejnému dokumentu v jednom textu požadavku. Pokud se pro stejný dokument vyžaduje více akcí sloučení, proveďte sloučení na straně klienta před aktualizací dokumentu v indexu vyhledávání.
Odpověď
Stavový kód: Pro úspěšnou odpověď se vrátí 200, což znamená, že všechny položky byly uloženy trvale a začnou se indexovat. Indexování běží na pozadí a několik sekund po dokončení operace indexování zpřístupňuje nové dokumenty (tj. dotazovatelné a prohledávatelné). Konkrétní zpoždění závisí na zatížení služby.
Úspěšné indexování je indikováno nastavením vlastnosti status na hodnotu true pro všechny položky a také nastavením vlastnosti statusCode na hodnotu 201 (pro nově nahrané dokumenty) nebo 200 (pro sloučené nebo odstraněné dokumenty):
{
"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
}
]
}
Stavový kód: 207 se vrátí, pokud alespoň jedna položka nebyla úspěšně indexována. Položky, které nebyly indexovány, mají pole stavu nastavené na false. Vlastnosti errorMessage a statusCode označují důvod chyby indexování:
{
"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
}
]
}
Vlastnost errorMessage označuje důvod chyby indexování, pokud je to možné.
Následující tabulka vysvětluje různé stavové kódy pro jednotlivé dokumenty, které mohou být vráceny v odpovědi. Některé stavové kódy značí problémy se samotným požadavkem, zatímco jiné dočasné chybové stavy. To druhé byste měli po prodlevě zkusit znovu.
| Stavový kód | Význam | Možnost opakovaného pokusu | Poznámky |
|---|---|---|---|
| 200 | Dokument se úspěšně upravil nebo odstranil. | Není k dispozici | Operace odstranění jsou idempotentní. To znamená, že i když klíč dokumentu v indexu neexistuje, výsledkem pokusu o operaci odstranění s tímto klíčem bude stavový kód 200. |
| 201 | Dokument byl úspěšně vytvořen. | Není k dispozici | |
| 400 | V dokumentu došlo k chybě, která znemožňovala jeho indexování. | No | Chybová zpráva v odpovědi indikuje, co je s dokumentem špatně. |
| 404 | Dokument nelze sloučit, protože daný klíč v indexu neexistuje. | No | K této chybě nedochází u nahrání, protože vytvářejí nové dokumenty, a nedochází k ní u odstranění, protože jsou idempotentní. |
| 409 | Při pokusu o indexování dokumentu se zjistil konflikt verzí. | Yes | K tomu může dojít v případě, že se pokoušíte indexovat stejný dokument vícekrát současně. |
| 422 | Index je dočasně nedostupný, protože se v něm aktualizoval příznak allowIndexDowntime nastavený na hodnotu true. | Yes | |
| 503 | Vaše vyhledávací služba je dočasně nedostupná, pravděpodobně kvůli velkému zatížení. | Yes | V takovém případě by váš kód měl před opakováním počkat, jinak riskujete prodloužení nedostupnosti služby. |
Poznámka
Pokud se váš klientský kód často setkává s odpovědí 207, je jedním z možných důvodů zatížení systému. Můžete to potvrdit tak, že zkontrolujete statusCode vlastnost pro 503. V takovém případě doporučujeme požadavky indexování na omezování. Pokud indexování provozu neustoupí, může systém začít odmítat všechny požadavky s chybami 503.
Stavový kód 429 označuje, že jste překročili kvótu počtu dokumentů na index. Musíte buď vytvořit nový index, nebo upgradovat kvůli vyšším limitům kapacity.
Příklady
Příklad: Nahrání dvou plně definovaných dokumentů
{
"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"
}
]
}
Poznámka
Když do indexu nahrajete DateTimeOffset hodnoty s informacemi o časovém pásmu, služba Azure AI Search tyto hodnoty normalizuje do formátu UTC. Například 2019-01-13T14:03:00-08:00 se uloží jako 2019-01-13T22:03:00Z. Pokud potřebujete uložit informace o časovém pásmu, budete muset do indexu přidat další sloupec.