Documenten toevoegen, bijwerken of verwijderen (Azure AI Search REST API)
U kunt zoekdocumenten importeren in een opgegeven index met behulp van HTTP POST. Voor een grote update wordt batchverwerking (maximaal 1000 documenten per batch of ongeveer 16 MB per batch) aanbevolen en worden de indexeringsprestaties aanzienlijk verbeterd.
POST https://[service name].search.windows.net/indexes/[index name]/docs/index?api-version=[api-version]
Content-Type: application/json
api-key: [admin key]
Voor ondersteunde Azure-gegevensbronnen bieden indexeerfuncties een eenvoudiger alternatief voor het toevoegen en bijwerken van documenten. Zie Indexeerbewerkingen voor meer informatie.
URI-parameters
| Parameter | Beschrijving |
|---|---|
| servicenaam | Vereist. Stel deze in op de unieke, door de gebruiker gedefinieerde naam van uw zoekservice. |
| indexnaam | Vereist voor de URI, waarmee wordt opgegeven welke index moet worden geplaatst voor het posten van documenten. U kunt documenten slechts naar één index tegelijk posten. |
| api-versie | Vereist. De huidige stabiele versie is api-version=2020-06-30. Zie API-versies voor meer versies. |
Aanvraagheaders
In de volgende tabel worden de vereiste en optionele aanvraagheaders beschreven.
| Velden | Description |
|---|---|
| Content-Type | Vereist. Stel dit in op application/json |
| api-sleutel | Optioneel als u Azure-rollen gebruikt en er een bearer-token wordt opgegeven voor de aanvraag, anders is een sleutel vereist. Een API-sleutel is een unieke, door het systeem gegenereerde tekenreeks die de aanvraag verifieert bij uw zoekservice. Voor het uploaden van documenten is een beheer-API-sleutel vereist. Zie Verbinding maken met Azure AI Search met behulp van sleutelverificatie voor meer informatie. |
Aanvraagbody
De hoofdtekst van de aanvraag bevat een of meer documenten die moeten worden geïndexeerd. Documenten worden geïdentificeerd met een unieke hoofdlettergevoelige sleutel. Elk document is gekoppeld aan een actie: 'uploaden', 'verwijderen', 'samenvoegen' of 'mergeOrUpload'. Uploadaanvragen moeten de documentgegevens bevatten als een set sleutel-waardeparen.
{
"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)
...
},
...
]
}
| Eigenschap | Beschrijving |
|---|---|
| @search.action | Vereist. Geldige waarden zijn 'uploaden', 'verwijderen', 'samenvoegen' of 'mergeOrUpload'. Standaard ingesteld op 'uploaden'. U kunt acties combineren, één per document, in dezelfde batch.
'uploaden': een uploadactie is vergelijkbaar met een 'upsert' waarbij het document wordt ingevoegd als het nieuw en bijgewerkt/vervangen is als het bestaat. Alle velden worden vervangen in de updatecase. 'verwijderen': met Verwijderen wordt het opgegeven document uit de index verwijderd. Elk veld dat u opgeeft in een verwijderbewerking, behalve het sleutelveld, wordt genegeerd. Als u een afzonderlijk veld uit een document wilt verwijderen, gebruikt merge u in plaats daarvan en stelt u het veld expliciet in op null.
'mergeOrUpload': deze actie gedraagt zich als samenvoegen als een document met de opgegeven sleutel al in de index bestaat. Als het document niet bestaat, gedraagt het zich als uploaden met een nieuw document. 'samenvoegen': Met Samenvoegen wordt een bestaand document bijgewerkt met de opgegeven velden. Als het document niet bestaat, mislukt de samenvoeging. Alle velden die u in een samenvoeging opgeeft, vervangen de bestaande velden in het document, Dit geldt ook voor verzamelingen van primitieve en complexe typen. Als het document in primitieve verzamelingen een veld Tags bevat van het type Collection(Edm.String) met de waarde ["budget"] en u een samenvoeging uitvoert met de waarde ["economy", "pool"] voor Tag, is de uiteindelijke waarde van het veld Tags ["economy", "pool"]. Dit is niet ["budget", "economie", "pool"]. Als het document in complexe verzamelingen een complex verzamelingsveld bevat met de naam Ruimten met de waarde [{ "Type": "Budgetruimte", "BaseRate": 75,0 }], en u voert een samenvoeging uit met een waarde van [{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }], de uiteindelijke waarde van het veld Kamers wordt [{ "Type": "Standaardruimte" }, { "Type": "Budget Room", "BaseRate": 60,5 }]. Het is niet een van de volgende: [{ "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 }] (voeg elementen samen in volgorde en voeg vervolgens extra's toe) |
| key_field_name | Vereist. Een velddefinitie in de index die fungeert als de documentsleutel en alleen unieke waarden bevat. Documentsleutels mogen alleen letters, cijfers, streepjes ("-"), onderstrepingstekens ("_") en gelijktekens ("=") bevatten en zijn hoofdlettergevoelig. Zie Naamgevingsregels voor meer informatie. |
| field_name | Vereist. Naam-waardeparen, waarbij de naam van het veld overeenkomt met een veldnaam in de indexdefinitie. De waarde is door de gebruiker gedefinieerd, maar moet geldig zijn voor het veldtype. |
Notitie
Er zijn geen volgordegaranties voor welke actie in de aanvraagbody het eerst wordt uitgevoerd. Het wordt afgeraden om meerdere samenvoegacties te koppelen aan hetzelfde document in één aanvraagbody. Als er meerdere samenvoegacties vereist zijn voor hetzelfde document, voert u de samenvoeging aan de clientzijde uit voordat u het document in de zoekindex bijwerkt.
Antwoord
Statuscode: 200 wordt geretourneerd voor een geslaagd antwoord, wat betekent dat alle items duurzaam zijn opgeslagen en worden geïndexeerd. Indexering wordt uitgevoerd op de achtergrond en maakt nieuwe documenten beschikbaar (dus doorzoekbaar en doorzoekbaar) enkele seconden nadat de indexeringsbewerking is voltooid. De specifieke vertraging is afhankelijk van de belasting van de service.
Een geslaagde indexering wordt aangegeven door de statuseigenschap die wordt ingesteld op true voor alle items, evenals de eigenschap statusCode die is ingesteld op 201 (voor nieuw geüploade documenten) of 200 (voor samengevoegde of verwijderde documenten):
{
"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
}
]
}
Statuscode: 207 wordt geretourneerd wanneer ten minste één item niet is geïndexeerd. Items die niet zijn geïndexeerd, hebben het statusveld ingesteld op false. De eigenschappen errorMessage en statusCode geven de reden voor de indexeringsfout aan:
{
"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
}
]
}
De eigenschap errorMessage geeft indien mogelijk de reden voor de indexeringsfout aan.
In de volgende tabel worden de verschillende statuscodes per document uitgelegd die in het antwoord kunnen worden geretourneerd. Sommige statuscodes duiden op problemen met de aanvraag zelf, terwijl andere tijdelijke foutvoorwaarden aangeven. Het laatste moet u na een vertraging opnieuw proberen.
| Statuscode | Betekenis | Er kan een nieuwe poging worden gedaan | Notities |
|---|---|---|---|
| 200 | Document is gewijzigd of verwijderd. | n.v.t. | Verwijderingsbewerkingen zijn idempotent. Dat wil dat zelfs als er geen documentsleutel in de index bestaat, een verwijderingsbewerking met die sleutel resulteert in een 200-statuscode. |
| 201 | Het document is gemaakt. | n.v.t. | |
| 400 | Er is een fout opgetreden in het document waardoor het niet kon worden geïndexeerd. | No | Het foutbericht in het antwoord geeft aan wat er mis is met het document. |
| 404 | Het document kan niet worden samengevoegd omdat de opgegeven sleutel niet in de index bestaat. | No | Deze fout treedt niet op bij uploads omdat ze nieuwe documenten maken en niet voor verwijderingen omdat ze idempotent zijn. |
| 409 | Er is een versieconflict gedetecteerd bij een poging om een document te indexeren. | Yes | Dit kan voorkomen wanneer u hetzelfde document meer dan één keer achter elkaar probeert te indexeren. |
| 422 | De index is tijdelijk niet beschikbaar omdat deze is bijgewerkt met de vlag allowIndexDowntime ingesteld op waar. | Yes | |
| 503 | Uw zoekservice is tijdelijk niet beschikbaar, mogelijk vanwege een zware belasting. | Yes | In dit geval moet de code wachten voordat u het opnieuw probeert, anders riskeert u dat de service nog langer niet beschikbaar is. |
Notitie
Als uw clientcode vaak een 207-antwoord tegenkomt, is een mogelijke reden dat het systeem wordt belast. U kunt dit bevestigen door de statusCode eigenschap op 503 te controleren. Als dit het geval is, raden we u aan indexeringsaanvragen te beperken. Als het indexeringsverkeer anders niet afneemt, kan het systeem beginnen met het weigeren van alle aanvragen met 503-fouten.
Statuscode: 429 geeft aan dat u uw quotum voor het aantal documenten per index hebt overschreden. U moet een nieuwe index maken of upgraden voor hogere capaciteitslimieten.
Voorbeelden
Voorbeeld: twee volledig gedefinieerde documenten uploaden
{
"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"
}
]
}
Notitie
Wanneer u waarden met tijdzonegegevens uploadt DateTimeOffset naar uw index, normaliseert Azure AI Search deze waarden naar UTC. 2019-01-13T14:03:00-08:00 wordt bijvoorbeeld opgeslagen als 2019-01-13T22:03:00Z. Als u tijdzonegegevens wilt opslaan, moet u een extra kolom toevoegen aan uw index.