Lägga till, uppdatera eller ta bort dokument (REST API för Azure AI Search)
Du kan importera sökdokument till ett angivet index med hjälp av HTTP POST. För en stor uppdatering rekommenderas batchbearbetning (upp till 1 000 dokument per batch eller cirka 16 MB per batch) och förbättrar indexeringsprestanda avsevärt.
POST https://[service name].search.windows.net/indexes/[index name]/docs/index?api-version=[api-version]
Content-Type: application/json
api-key: [admin key]
För Azure-datakällor som stöds erbjuder indexerare ett enklare alternativ för att lägga till och uppdatera dokument. Mer information finns i Indexer operations (Indexeringsåtgärder).
URI-parametrar
| Parameter | Beskrivning |
|---|---|
| tjänstnamn | Krävs. Ange det unika, användardefinierade namnet på söktjänsten. |
| indexnamn | Krävs för URI:n och anger vilket index som ska posta dokument. Du kan bara publicera dokument till ett index i taget. |
| api-version | Krävs. Den aktuella stabila versionen är api-version=2020-06-30. Fler versioner finns i API-versioner . |
Rubriker för begäran
I följande tabell beskrivs de obligatoriska och valfria begärandehuvudena.
| Fält | Description |
|---|---|
| Content-Type | Krävs. Ange detta till application/json |
| api-key | Valfritt om du använder Azure-roller och en ägartoken anges i begäran, annars krävs en nyckel. En API-nyckel är en unik, systemgenererad sträng som autentiserar begäran till söktjänsten. För att ladda upp dokument krävs en API-administratörsnyckel. Mer information finns i Ansluta till Azure AI Search med nyckelautentisering . |
Begärandetext
Brödtexten i begäran innehåller ett eller flera dokument som ska indexeras. Dokument identifieras med en unik skiftlägeskänslig nyckel. Varje dokument är associerat med en åtgärd: "upload", "delete", "merge" eller "mergeOrUpload". Uppladdningsbegäranden måste innehålla dokumentdata som en uppsättning nyckel/värde-par.
{
"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)
...
},
...
]
}
| Egenskap | Beskrivning |
|---|---|
| @search.action | Krävs. Giltiga värden är "upload", "delete", "merge" eller "mergeOrUpload". Standardvärdet är "upload". Du kan kombinera åtgärder, en per dokument, i samma batch.
"upload": En uppladdningsåtgärd liknar en "upsert" där dokumentet infogas om det är nytt och uppdateras/ersätts om det finns. Alla fält ersätts i uppdateringsfallet. "delete": Ta bort tar bort det angivna dokumentet från indexet. Alla fält som du anger i en borttagningsåtgärd, förutom nyckelfältet, ignoreras. Om du vill ta bort ett enskilt fält från ett dokument använder du merge i stället och anger fältet explicit till null.
"mergeOrUpload": Den här åtgärden fungerar som sammanslagning om ett dokument med den angivna nyckeln redan finns i indexet. Om dokumentet inte finns fungerar det som att ladda upp med ett nytt dokument. "merge": Sammanfoga uppdaterar ett befintligt dokument med de angivna fälten. Om dokumentet inte finns misslyckas kopplingen. Alla fält som du anger i en sammanfogning ersätter det befintliga fältet i dokumentet. Detta gäller även för samlingar av primitiva och komplexa typer. Om dokumentet i primitiva samlingar innehåller fältet Taggar av typen Collection(Edm.String) med värdet ["budget"], och du kör en sammanslagning med värdet ["economy", "pool"] för Tagg, blir det slutliga värdet för fältet Taggar ["ekonomi", "pool"]. Det kommer inte att vara ["budget", "ekonomi", "pool"]. I komplexa samlingar, om dokumentet innehåller ett komplext samlingsfält med namnet Rooms med värdet [{ "Type": "Budget Room", "BaseRate": 75.0 }], och du kör en sammanslagning med värdet [{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }], det slutliga värdet för fältet Rum är [{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }]. Det kommer inte att vara något av följande: [{ "Type": "Budget Room", "BaseRate": 75.0 }, { "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }] (tilläggselement) [{ "Type": "Standard Room", "BaseRate": 75.0 }, { "Type": "Budget Room", "BaseRate": 60.5 }] (sammanfoga element i ordning och lägg sedan till eventuella extrafunktioner) |
| key_field_name | Krävs. En fältdefinition i indexet som fungerar som dokumentnyckel och som endast innehåller unika värden. Dokumentnycklar får bara innehålla bokstäver, siffror, bindestreck ("-"), understreck ("_") och likhetstecken ("=") och är skiftlägeskänsliga. Mer information finns i Namngivningsregler. |
| field_name | Krävs. Namn/värde-par, där namnet på fältet motsvarar ett fältnamn i indexdefinitionen. Värdet är användardefinierat men måste vara giltigt för fälttypen. |
Anteckning
Det finns inga ordningsgarantier för vilken åtgärd i begärandetexten som körs först. Vi rekommenderar inte att flera "sammanslagningsåtgärder" är associerade med samma dokument i en enda begärandetext. Om det krävs flera "sammanslagningsåtgärder" för samma dokument utför du den sammanfogande klientsidan innan du uppdaterar dokumentet i sökindexet.
Svarsåtgärder
Statuskod: 200 returneras för ett lyckat svar, vilket innebär att alla objekt har lagrats varaktigt och börjar indexeras. Indexeringen körs i bakgrunden och gör nya dokument tillgängliga (dvs. frågebara och sökbara) några sekunder efter att indexeringsåtgärden har slutförts. Den specifika fördröjningen beror på belastningen på tjänsten.
Lyckad indexering anges av statusegenskapen som anges till true för alla objekt, samt egenskapen statusCode som anges till antingen 201 (för nyligen uppladdade dokument) eller 200 (för sammanfogade eller borttagna dokument):
{
"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
}
]
}
Statuskod: 207 returneras när minst ett objekt inte har indexerats. Objekt som inte har indexerats har statusfältet inställt på falskt. Egenskaperna errorMessage och statusCode anger orsaken till indexeringsfelet:
{
"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
}
]
}
Egenskapen errorMessage anger orsaken till indexeringsfelet om det är möjligt.
I följande tabell förklaras de olika statuskoder per dokument som kan returneras i svaret. Vissa statuskoder indikerar problem med själva begäran, medan andra anger tillfälliga feltillstånd. Det senare bör du försöka igen efter en fördröjning.
| Statuskod | Innebörd | Återförsökbar | Kommentarer |
|---|---|---|---|
| 200 | Dokumentet har ändrats eller tagits bort. | saknas | Borttagningsåtgärder är idempotenta. Det innebär att även om det inte finns någon dokumentnyckel i indexet resulterar ett borttagningsförsök med den nyckeln i en statuskod på 200. |
| 201 | Dokumentet har skapats. | saknas | |
| 400 | Det uppstod ett fel i dokumentet som hindrade det från att indexeras. | No | Felmeddelandet i svaret anger vad som är fel med dokumentet. |
| 404 | Det gick inte att sammanfoga dokumentet eftersom den angivna nyckeln inte finns i indexet. | No | Det här felet uppstår inte för uppladdningar eftersom de skapar nya dokument och det uppstår inte för borttagningar eftersom de är idempotenter. |
| 409 | En versionskonflikt upptäcktes när ett dokument skulle indexeras. | Yes | Detta kan inträffa när du försöker indexera samma dokument mer än en gång samtidigt. |
| 422 | Indexet är tillfälligt otillgängligt eftersom det uppdaterades med flaggan ”allowIndexDowntime” inställd på ”true”. | Yes | |
| 503 | Söktjänsten är inte tillgänglig för tillfället, möjligen på grund av hög belastning. | Yes | I detta fall bör koden vänta innan ett nytt försök görs så att tjänsten inte är otillgänglig längre än nödvändigt. |
Anteckning
Om klientkoden ofta stöter på ett 207-svar är en möjlig orsak att systemet är under belastning. Du kan bekräfta detta genom att statusCode kontrollera egenskapen för 503. I så fall rekommenderar vi att du begränsar indexeringsbegäranden. Om indexeringstrafiken inte avtar kan systemet annars börja avvisa alla begäranden med 503-fel.
Statuskod: 429 anger att du har överskridit din kvot för antalet dokument per index. Du måste antingen skapa ett nytt index eller uppgradera för högre kapacitetsgränser.
Exempel
Exempel: Ladda upp två fullständigt definierade 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"
}
]
}
Anteckning
När du laddar upp DateTimeOffset värden med tidszonsinformation till ditt index normaliserar Azure AI Search dessa värden till UTC. Till exempel lagras 2019-01-13T14:03:00-08:00 som 2019-01-13T22:03:00Z. Om du behöver lagra tidszonsinformation måste du lägga till en extra kolumn i indexet.