Aggiungere, aggiornare o eliminare documenti (API REST di anteprima)
si applica a: 2023-07-01-Preview. Questa versione non è più supportata. Aggiornare immediatamente a una versione più recente.
Importante
2023-07-01-Preview aggiunge:
- Supporto per i campi vettoriali in un documento.
È possibile eseguire il push di documenti contenenti campi vettoriali 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) migliora le prestazioni di indicizzazione.
POST https://[service name].search.windows.net/indexes/[index name]/docs/index?api-version=2023-07-01-Preview
Content-Type: application/json
api-key: [admin key]
Parametri URI
| Parametro | Descrizione |
|---|---|
| nome del servizio | Obbligatorio. Impostare questo valore sul nome univoco definito dall'utente del servizio di ricerca. |
| nome indice | Obbligatorio. Impostare questo valore sul nome dell'indice che riceve i documenti. È possibile inserire documenti in un solo indice alla volta. |
| api-version | Per altre versioni, vedere versioni dell'API. |
Intestazioni della richiesta
Nella tabella seguente vengono descritte le intestazioni di richiesta obbligatorie e facoltative.
| Campi | Descrizione |
|---|---|
| Tipo di contenuto | Obbligatorio. Impostare questo valore su application/json |
| api-key | Facoltativo se si usano 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 di 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 in modo univoco tramite una chiave con distinzione tra maiuscole e minuscole. Ogni documento è associato a un'azione: "upload", "delete", "merge" o "mergeOrUpload". Le richieste di caricamento devono includere i dati del documento come set di coppie chiave/valore.
I campi vettoriali sono di tipo Collection(Edm.Single). I dati vettoriali sono costituiti da una matrice di numeri a virgola mobile a precisione singola.
I campi vettoriali possono contenere migliaia di incorporamenti, a seconda della complessità, della lunghezza o del tipo di contenuto originale. Ricerca di intelligenza artificiale di Azure non converte il contenuto in incorporamenti. I documenti di cui si esegue il push in un indice devono contenere incorporamenti generati in precedenza.
{
"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),
"vector_field_name": [ array of single-precision floating point numbers ]
...
},
...
]
}
| Proprietà | Descrizione |
|---|---|
| @search.action | Obbligatorio. I valori validi sono "upload", "delete", "merge" o "mergeOrUpload". Il valore predefinito è "upload". |
| 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 ("=") e fanno distinzione tra maiuscole e minuscole. |
| field_name | Obbligatorio. Coppie nome-valore, dove 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. |
Risposta
Codice di stato: 200 viene restituito per una risposta con esito positivo, vale a dire che tutti gli elementi sono stati archiviati in modo permanente e che l'indicizzazione è iniziata. L'indicizzazione viene eseguita in background e rende disponibili nuovi documenti( ovvero queryable e ricercabili) pochi secondi dopo il completamento dell'operazione di indicizzazione.
L'indicizzazione riuscita viene indicata quando la proprietà status è impostata su true per tutti gli elementi. La proprietà statusCode deve essere 201 (per i documenti appena caricati) o 200 (per documenti uniti o eliminati).
Esempi
esempio : Caricare due documenti con contenuto di testo e vettore
Per la leggibilità, nell'esempio seguente viene illustrato un subset di documenti e incorporamenti. Il corpo della richiesta Carica documenti è costituito da 108 documenti, ognuno con un set completo di incorporamenti per "titleVector" e "contentVector".
POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/index?api-version={{api-version}}
Content-Type: application/json
api-key: {{admin-api-key}}
{
"value": [
{
"id": "1",
"title": "Azure App Service",
"content": "Azure App Service is a fully managed platform for building, deploying, and scaling web apps. You can host web apps, mobile app backends, and RESTful APIs. It supports a variety of programming languages and frameworks, such as .NET, Java, Node.js, Python, and PHP. The service offers built-in auto-scaling and load balancing capabilities. It also provides integration with other Azure services, such as Azure DevOps, GitHub, and Bitbucket.",
"category": "Web",
"titleVector": [
-0.02250031754374504,
. . .
],
"contentVector": [
-0.024740582332015038,
. . .
],
"@search.action": "upload"
},
{
"id": "2",
"title": "Azure Functions",
"content": "Azure Functions is a serverless compute service that enables you to run code on-demand without having to manage infrastructure. It allows you to build and deploy event-driven applications that automatically scale with your workload. Functions support various languages, including C#, F#, Node.js, Python, and Java. It offers a variety of triggers and bindings to integrate with other Azure services and external services. You only pay for the compute time you consume.",
"category": "Compute",
"titleVector": [
-0.020159931853413582,
. . .
],
"contentVector": [
-0.02780858241021633,,
. . .
],
"@search.action": "upload"
}
. . .
]
}
Nota
Quando si caricano valori DateTimeOffset con informazioni sul fuso orario nell'indice, Ricerca di intelligenza artificiale di Azure normalizza questi valori in formato UTC. Ad esempio, 2019-01-13T14:03:00-08:00 verrà archiviato come 2019-01-13T22:03:00Z. Se è necessario archiviare le informazioni sul fuso orario, aggiungere una colonna aggiuntiva all'indice.