Aggiungere, aggiornare o eliminare documenti (API REST di Ricerca di intelligenza artificiale di Azure)
È possibile importare documenti di ricerca in un indice specificato usando HTTP POST. Per un aggiornamento di grandi dimensioni, l'invio in batch (fino a 1000 documenti per batch o circa 16 MB per batch) è consigliato e migliorerà significativamente le prestazioni di indicizzazione.
POST https://[service name].search.windows.net/indexes/[index name]/docs/index?api-version=[api-version]
Content-Type: application/json
api-key: [admin key]
Per le origini dati di Azure supportate, gli indicizzatori offrono un'alternativa più semplice per l'aggiunta e l'aggiornamento di documenti. Per altre informazioni, vedere Indexer operations (Operazioni dell'indicizzatore).
Parametri dell'URI
| Parametro | Descrizione |
|---|---|
| nome servizio | Obbligatorio. Impostarlo sul nome univoco definito dall'utente del servizio di ricerca. |
| nome indice | Obbligatorio nell'URI, specificando l'indice da inserire nei documenti. Questa operazione può essere eseguita su un solo indice alla volta. |
| api-version | Obbligatorio. La versione stabile corrente è api-version=2020-06-30. Per altre versioni, vedere Versioni API . |
Intestazioni richiesta
La tabella seguente descrive le intestazioni della richiesta obbligatorie e facoltative.
| Campi | Descrizione |
|---|---|
| Content-Type | Obbligatorio. Impostare il valore su application/json |
| api-key | Facoltativo se si usano i ruoli di Azure e viene fornito un token di connessione nella richiesta, in caso contrario è necessaria una chiave. Una chiave API è una stringa univoca generata dal sistema che autentica la richiesta al servizio di ricerca. Il caricamento di documenti richiede una chiave API amministratore. Per informazioni dettagliate, vedere Connettersi a Ricerca intelligenza artificiale di Azure usando l'autenticazione della chiave . |
Corpo della richiesta
Il corpo della richiesta contiene uno o più documenti da indicizzare. I documenti vengono identificati da una chiave con distinzione tra maiuscole e minuscole univoche. Ogni documento è associato a un'azione: "upload", "delete", "merge" o "mergeOrUpload". Le richieste di caricamento devono includere i dati del documento sotto forma di coppie chiave/valore.
{
"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)
...
},
...
]
}
| Proprietà | Descrizione |
|---|---|
| @search.action | Obbligatorio. I valori validi sono "upload", "delete", "merge" o "mergeOrUpload". Il valore predefinito è "upload". È possibile combinare azioni, una per ogni documento, nello stesso batch. "upload": un'azione di caricamento è simile a un 'upsert' in cui il documento verrà inserito se è nuovo e aggiornato/sostituito se esiste. Tutti i campi vengono sostituiti nel caso di aggiornamento. "delete": elimina rimuove il documento specificato dall'indice. Qualsiasi campo specificato in un'operazione di eliminazione, diverso dal campo chiave, verrà ignorato. Se si desidera rimuovere un singolo campo da un documento, usare merge invece e impostare il campo in modo esplicito su null. "mergeOrUpload": questa azione si comporta come l'unione se un documento con la chiave specificata esiste già nell'indice. Se il documento non esiste, si comporta come il caricamento con un nuovo documento. "merge": unisci aggiorna un documento esistente con i campi specificati. Se il documento non esiste, l'unione ha esito negativo. I campi specificati in un'azione di unione sostituiscono i campi esistenti nel documento. Questo vale anche per le raccolte di tipi primitivi e complessi. Nelle raccolte primitive, se il documento contiene un campo Tags di tipo Collection(Edm.String) con un valore ["budget"], e si esegue un merge con un valore ["economy", "pool"] per Tag, il valore finale del campo Tags sarà ["economy", "pool"]. Non sarà ["budget", "economy", "pool"]. Nelle raccolte complesse, se il documento contiene un campo di raccolta complesso denominato Rooms con valore [{ "Type": "Budget Room", "BaseRate": 75.0 }], e si esegue un merge con un valore di [{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }], il valore finale del campo Rooms sarà [{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }]. Non sarà uno dei seguenti: [{ "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 }] (unire gli elementi in ordine, quindi accodare eventuali extra) |
| key_field_name | Obbligatorio. Definizione di campo nell'indice che funge da chiave del documento e contiene solo valori univoci. Le chiavi del documento possono contenere solo lettere, numeri, trattini ("-"), caratteri di sottolineatura ("_") e segni di uguale maiuscole e minuscole ("="). Per altre informazioni, vedere Regole di denominazione. |
| field_name | Obbligatorio. Coppie nome-valore, in cui il nome del campo corrisponde a un nome di campo nella definizione dell'indice. Il valore è definito dall'utente, ma deve essere valido per il tipo di campo. |
Nota
Non esistono garanzie di ordinamento per le quali viene eseguita prima l'azione nel corpo della richiesta. Non è consigliabile avere più azioni di "merge" associate allo stesso documento in un singolo corpo della richiesta. Se sono necessarie più azioni di "merge" per lo stesso documento, eseguire l'unione sul lato client prima di aggiornare il documento nell'indice di ricerca.
Risposta
Codice di stato: 200 viene restituito per una risposta corretta, vale a dire che tutti gli elementi sono stati archiviati in modo permanente e inizieranno a essere indicizzati. L'indicizzazione viene eseguita in background e rende disponibili nuovi documenti ( ovvero ricercabili e ricercabili) pochi secondi dopo il completamento dell'operazione di indicizzazione. Il ritardo specifico dipende dal carico del servizio.
L'indicizzazione riuscita è indicata dalla proprietà status impostata su true per tutti gli elementi, nonché la proprietà statusCode impostata su 201 (per i documenti appena caricati) o 200 (per i documenti uniti o eliminati):
{
"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
}
]
}
Codice di stato: 207 viene restituito quando almeno un elemento non è stato indicizzato correttamente. Gli elementi che non sono stati indicizzati hanno il campo di stato impostato su false. Le proprietà errorMessage e statusCode indicano il motivo dell'errore di indicizzazione:
{
"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
}
]
}
La proprietà errorMessage indica il motivo dell'errore di indicizzazione, se possibile.
La tabella seguente illustra i vari codici di stato per documento che possono essere restituiti nella risposta. Alcuni codici di stato indicano problemi con la richiesta stessa, mentre altri indicano condizioni di errore temporanee. Per queste ultime è necessario riprovare dopo un breve intervallo di tempo.
| Codice stato | Significato | Non irreversibile | Note |
|---|---|---|---|
| 200 | Il documento è stato modificato o eliminato correttamente. | n/d | Le operazioni di eliminazione sono idempotenti. Ovvero, anche se non esiste una chiave del documento nell'indice, il tentativo di un'operazione di eliminazione con tale chiave genera un codice di stato 200. |
| 201 | Il documento è stato creato correttamente. | n/d | |
| 400 | Si è verificato un errore nel documento che ne ha impedito l'indicizzazione. | No | Il messaggio di errore nella risposta indica l'errore del documento. |
| 404 | Impossibile unire il documento perché la chiave specificata non esiste nell'indice. | No | Questo errore non si verifica per i caricamenti perché creano nuovi documenti e non si verifica per le eliminazioni perché sono idempotenti. |
| 409 | È stato rilevato un conflitto di versione nel tentativo di indicizzare un documento. | Sì | Ciò può verificarsi quando si prova a indicizzare lo stesso documento più di una volta contemporaneamente. |
| 422 | L'indice è temporaneamente non disponibile perché è stato aggiornato con il flag 'allowIndexDowntime' impostato su 'true'. | Sì | |
| 503 | Il servizio di ricerca è temporaneamente non disponibile, probabilmente a causa di un sovraccarico. | Sì | In questo caso, il codice deve attendere prima di riprovare o si rischia di prolungare la non disponibilità del servizio. |
Nota
Se il codice del client riceve spesso una risposta 207, potrebbe ad esempio dipendere da un carico eccessivo del sistema. Per una conferma verificare se la proprietà statusCode contiene 503. Se si verifica questo problema, è consigliabile limitare le richieste di indicizzazione. Se non si riduce il traffico di indicizzazione, è possibile che il sistema inizi a rifiutare tutte le richieste con errori 503.
Il codice di stato 429 indica che è stata superata la quota del numero di documenti per indice. È necessario creare un nuovo indice o effettuare l'aggiornamento per ottenere limiti di capacità più elevati.
Esempio
Esempio: Caricare due documenti completamente definiti
{
"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"
}
]
}
Nota
Quando si caricano DateTimeOffset valori con informazioni sul fuso orario nell'indice, Ricerca intelligenza artificiale di Azure normalizza questi valori in UTC. Ad esempio, 2019-01-13T14:03:00-08:00 verranno archiviati come 2019-01-13T22:03:00Z. Se è necessario archiviare le informazioni sul fuso orario, sarà necessario aggiungere una colonna aggiuntiva all'indice.