Dokumentumok hozzáadása, frissítése vagy törlése (Azure AI Search REST API)
A keresési dokumentumokat a HTTP POST használatával importálhatja egy adott indexbe. Nagy frissítés esetén a kötegelés (kötegenként legfeljebb 1000 dokumentum, kötegenként körülbelül 16 MB) ajánlott, és jelentősen javítja az indexelési teljesítményt.
POST https://[service name].search.windows.net/indexes/[index name]/docs/index?api-version=[api-version]
Content-Type: application/json
api-key: [admin key]
A támogatott Azure-adatforrások esetében az indexelők egyszerűbb alternatívát kínálnak a dokumentumok hozzáadására és frissítésére. További információkért lásd: Indexelőműveletek.
URI-paraméterek
| Paraméter | Leírás |
|---|---|
| szolgáltatásnév | Kötelező. Állítsa be ezt a keresési szolgáltatás egyedi, felhasználó által megadott nevére. |
| index neve | Az URI-n kötelező megadni, hogy melyik indexet szeretné közzétenni a dokumentumokban. A dokumentumokat egyszerre csak egy indexbe lehet közzétenni. |
| api-verzió | Kötelező. A jelenlegi stabil verzió a következő api-version=2020-06-30: . További verziókért lásd: API-verziók . |
Kérelemfejlécek
Az alábbi táblázat a szükséges és nem kötelező kérelemfejléceket ismerteti.
| Mezők | Description |
|---|---|
| Content-Type | Kötelező. Állítsa ezt a következőre: application/json |
| api-key | Nem kötelező , ha Azure-szerepköröket használ, és egy tulajdonosi jogkivonatot ad meg a kéréshez, ellenkező esetben kulcsra van szükség. Az API-kulcs egy egyedi, rendszer által létrehozott sztring, amely hitelesíti a keresési szolgáltatásnak küldött kérést. A dokumentumok feltöltéséhez rendszergazdai API-kulcs szükséges. A részletekért lásd: Csatlakozás az Azure AI Searchhöz kulcshitelesítés használatával . |
Kérelem törzse
A kérelem törzse egy vagy több indexelendő dokumentumot tartalmaz. A dokumentumokat egy egyedi, kis- és nagybetűkre érzékeny kulcs azonosítja. Minden dokumentum egy művelethez van társítva: "upload", "delete", "merge", vagy "mergeOrUpload". A feltöltési kérelmeknek tartalmazniuk kell a dokumentumadatokat kulcs/érték párok halmazaként.
{
"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)
...
},
...
]
}
| Tulajdonság | Leírás |
|---|---|
| @search.action | Kötelező. Az érvényes értékek a következők: "upload", "delete", "merge", vagy "mergeOrUpload". Alapértelmezés szerint a "upload" (feltöltés) értékre van kapcsolva. A műveleteket dokumentumonként egy kötegben kombinálhatja.
"upload": A feltöltési művelet hasonló az "upsert" művelethez, ahol a dokumentum be lesz szúrva, ha új, és frissítve/lecserélve, ha létezik. A frissítési esetben az összes mező lecserélődik. "delete": A törlés eltávolítja a megadott dokumentumot az indexből. A rendszer figyelmen kívül hagyja a törlési műveletben megadott mezőket, kivéve a kulcsmezőt. Ha el szeretne távolítani egy egyéni mezőt egy dokumentumból, használja inkább a parancsot merge , és állítsa a mezőt explicit módon értékre null.
"mergeOrUpload": Ez a művelet úgy viselkedik, mint az egyesítés, ha az adott kulccsal rendelkező dokumentum már létezik az indexben. Ha a dokumentum nem létezik, úgy viselkedik, mint egy új dokumentum feltöltése. "merge": Egy meglévő dokumentum egyesítése a megadott mezőkkel. Ha a dokumentum nem létezik, az egyesítés sikertelen lesz. A rendszer az egyesítési művelet során megadott mezőkre cseréli a dokumentum meglévő mezőit. Ez a primitív és összetett típusok gyűjteményére is vonatkozik. A primitív gyűjteményekben, ha a dokumentum egy Collection(Edm.String) típusú, ["budget" ] értékű Címkék mezőt tartalmaz, és egy ["economy", "pool" ] értékkel rendelkező egyesítést hajt végre a Tag esetében, a Címkék mező végső értéke ["economy", "pool"]. Ez nem lesz ["költségvetés", "gazdaság", "készlet"]. Összetett gyűjteményekben, ha a dokumentum tartalmaz egy Konferencia nevű összetett gyűjteménymezőt[{ "Type": "Budget Room" értékkel, "BaseRate": 75.0 }], és végrehajt egy egyesítést [{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }], a Szobák mező végső értéke [{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }]. A következő egyik sem lesz: [{ "Type": "Budget Room", "BaseRate": 75.0 }, { "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }] (append elements) [{ "Type": "Standard Room", "BaseRate": 75.0 }, { "Type": "Budget Room", "BaseRate": 60.5 }] (az elemeket sorrendben egyesítse, majd fűzze hozzá az esetleges extrákat) |
| key_field_name | Kötelező. Egy meződefiníció az indexben, amely dokumentumkulcsként szolgál, és csak egyedi értékeket tartalmaz. A dokumentumkulcsok csak betűket, számokat, kötőjeleket ("-"), aláhúzásjeleket ("_") és egyenlőségjeleket ("=") tartalmazhatnak, és megkülönböztetik a kis- és nagybetűket. További információ: Elnevezési szabályok. |
| field_name | Kötelező. Név-érték párok, amelyekben a mező neve egy mezőnévnek felel meg az indexdefinícióban. Az érték felhasználó által definiált, de a mezőtípusra érvényesnek kell lennie. |
Megjegyzés
Nincsenek olyan megrendelési garanciák, amelyek esetében a kérelemtörzsben végrehajtott művelet először végrehajtásra kerül. Nem ajánlott több "egyesítési" műveletet társítani ugyanahhoz a dokumentumhoz egyetlen kérelemtörzsben. Ha több "egyesítési" műveletre van szükség ugyanahhoz a dokumentumhoz, hajtsa végre az egyesítést az ügyféloldalon, mielőtt frissíti a dokumentumot a keresési indexben.
Reagálás
Állapotkód: A rendszer 200 értéket ad vissza a sikeres válaszhoz, ami azt jelenti, hogy az összes elem tartósan lett tárolva, és indexelésbe kezd. Az indexelés a háttérben fut, és néhány másodperccel az indexelési művelet befejezése után elérhetővé teszi az új dokumentumokat (azaz lekérdezhető és kereshető). Az adott késés a szolgáltatás terhelésétől függ.
A sikeres indexelést az állapottulajdonság jelzi, amely az összes elem esetében igaz értékre van állítva, valamint a statusCode tulajdonság értéke 201 (újonnan feltöltött dokumentumok esetén) vagy 200 (egyesített vagy törölt dokumentumok esetén):
{
"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
}
]
}
Állapotkód: A rendszer 207-et ad vissza, ha legalább egy elem indexelése sikertelen volt. Az indexeletlen elemek állapotmezője false (hamis) értékre van állítva. Az errorMessage és statusCode tulajdonságok jelzik az indexelési hiba okát:
{
"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
}
]
}
Az errorMessage tulajdonság jelzi az indexelési hiba okát, ha lehetséges.
Az alábbi táblázat a válaszban visszaadható dokumentumonkénti állapotkódokat ismerteti. Egyes állapotkódok maguk a kéréssel kapcsolatos problémákat jeleznek, míg mások ideiglenes hibafeltételeket jeleznek. Az utóbbit késlekedés után újra kell próbálkoznia.
| Állapotkód | Értelmezés | Újrapróbálható | Jegyzetek |
|---|---|---|---|
| 200 | A dokumentum módosítása vagy törlése sikeresen megtörtént. | n.a. | A törlési műveletek idempotensek. Vagyis még ha nem is létezik dokumentumkulcs az indexben, a törlési művelet megkísérlése ezzel a kulccsal 200 állapotkódot eredményez. |
| 201 | A dokumentum létrehozása sikerült. | n.a. | |
| 400 | Hiba történt a dokumentumban, amely megakadályozta az indexelést. | No | A válaszban szereplő hibaüzenet jelzi, hogy mi a probléma a dokumentummal. |
| 404 | A dokumentum nem egyesíthető, mert a megadott kulcs nem létezik az indexben. | No | Ez a hiba nem fordul elő a feltöltések esetében, mivel új dokumentumokat hoznak létre, és a törléskor nem fordul elő, mert idempotensek. |
| 409 | A rendszer verzióütközést észlelt egy dokumentum indexelésének megkísérlésekor. | Yes | Ez akkor fordulhat elő, ha ugyanazt a dokumentumot egy időben többször próbálja indexelni. |
| 422 | Az index átmenetileg nem érhető el, mert „true” (igaz) értékű allowIndexDowntime jelölővel lett frissítve. | Yes | |
| 503 | A keresési szolgáltatás átmenetileg nem érhető el, valószínűleg nagy terhelés miatt. | Yes | Ebben az esetben a kódnak várnia kell az újrapróbálkozás előtt, különben fennáll a veszélye, hogy a szolgáltatás továbbra sem lesz elérhető. |
Megjegyzés
Ha az ügyfélkód gyakran találkozik egy 207-ben megadott válaszsal, az egyik lehetséges ok az, hogy a rendszer terhelés alatt áll. Ezt az 503 tulajdonság ellenőrzésével statusCode ellenőrizheti. Ha ez a helyzet, javasoljuk, hogy szabályozza az indexelési kérelmeket. Ellenkező esetben, ha a forgalom indexelése nem csökken, a rendszer 503 hibával elkezdheti elutasítani az összes kérést.
Állapotkód: A 429 azt jelzi, hogy túllépte a kvótát az indexenkénti dokumentumok száma alapján. Létre kell hoznia egy új indexet, vagy frissítenie kell a magasabb kapacitáskorlátok érdekében.
Példák
Példa: Két teljesen definiált dokumentum feltöltése
{
"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"
}
]
}
Megjegyzés
Amikor időzóna-adatokat tartalmazó értékeket tölt fel DateTimeOffset az indexbe, az Azure AI Search normalizálja ezeket az értékeket UTC értékre. A 2019-01-13T14:03:00-08:00 például 2019-01-13T22:03:00Z néven lesz tárolva. Ha időzóna-adatokat kell tárolnia, egy további oszlopot kell hozzáadnia az indexhez.