Caricare dati in Ricerca di Azure tramite l'API RESTUpload data to Azure Search using the REST API

Questo articolo illustra come usare l' API REST di Ricerca di Azure per importare dati in un indice di Ricerca di Azure.This article will show you how to use the Azure Search REST API to import data into an Azure Search index.

Prima di iniziare questa procedura dettagliata, è necessario avere creato un indice di Ricerca di Azure.Before beginning this walkthrough, you should already have created an Azure Search index.

Per effettuare il push dei documenti nell'indice con l'API REST, inviare una richiesta HTTP POST all'endpoint dell'URL dell'indice.In order to push documents into your index using the REST API, you will issue an HTTP POST request to your index's URL endpoint. Il corpo della richiesta HTTP è un oggetto JSON che contiene i documenti da aggiungere, modificare o eliminare.The body of the HTTP request body is a JSON object containing the documents to be added, modified, or deleted.

Identificare la chiave API amministratore del servizio Ricerca di AzureIdentify your Azure Search service's admin api-key

Quando si inviano richieste HTTP al servizio tramite l'API REST, ogni richiesta API deve includere la chiave API generata per il servizio di ricerca di cui è stato effettuato il provisioning.When issuing HTTP requests against your service using the REST API, each API request must include the api-key that was generated for the Search service you provisioned. La presenza di una chiave valida stabilisce una relazione di trust, in base alle singole richieste, tra l'applicazione che invia la richiesta e il servizio che la gestisce.Having a valid key establishes trust, on a per request basis, between the application sending the request and the service that handles it.

  1. Per trovare le chiavi API del servizio, è possibile accedere al portale di AzureTo find your service's api-keys, you can sign in to the Azure portal
  2. Passare al pannello del servizio Ricerca di Azure.Go to your Azure Search service's blade
  3. Fare clic sull'icona "Chiavi".Click on the "Keys" icon

Il servizio avrà chiavi amministratore e chiavi di query.Your service will have admin keys and query keys.

  • Le chiavi amministratore primarie e secondarie concedono diritti completi a tutte le operazioni, inclusa la possibilità di gestire il servizio, creare ed eliminare indici, indicizzatori e origini dati.Your primary and secondary admin keys grant full rights to all operations, including the ability to manage the service, create and delete indexes, indexers, and data sources. Sono disponibili due chiavi, quindi è possibile continuare a usare la chiave secondaria se si decide di rigenerare la chiave primaria e viceversa.There are two keys so that you can continue to use the secondary key if you decide to regenerate the primary key, and vice-versa.
  • Le chiavi di query concedono l'accesso in sola lettura agli indici e ai documenti e vengono in genere distribuite alle applicazioni client che inviano richieste di ricerca.Your query keys grant read-only access to indexes and documents, and are typically distributed to client applications that issue search requests.

Per l'importazione di dati in un indice è possibile usare la chiave amministratore primaria o secondaria.For the purposes of importing data into an index, you can use either your primary or secondary admin key.

Decidere quale azione di indicizzazione usareDecide which indexing action to use

Quando si usa l'API REST, si inviano richieste HTTP POST con corpi delle richieste JSON all'URL dell'endpoint dell'indice di Ricerca di Azure.When using the REST API, you will issue HTTP POST requests with JSON request bodies to your Azure Search index's endpoint URL. L'oggetto JSON nel corpo della richiesta HTTP contiene una matrice JSON denominata "value" che include oggetti JSON che rappresentano i documenti da aggiungere all'indice, aggiornare o eliminare.The JSON object in your HTTP request body will contain a single JSON array named "value" containing JSON objects representing documents you would like to add to your index, update, or delete.

Ogni oggetto JSON nella matrice "value" rappresenta un documento da indicizzare.Each JSON object in the "value" array represents a document to be indexed. Ognuno di questi oggetti contiene la chiave del documento e specifica l'azione di indicizzazione desiderata, ovvero caricamento, unione, eliminazione e così via.Each of these objects contains the document's key and specifies the desired indexing action (upload, merge, delete, etc). A seconda delle azioni scelte tra le seguenti, per ogni documento devono essere inclusi solo campi specifici:Depending on which of the below actions you choose, only certain fields must be included for each document:

@search.action DescrizioneDescription Campi necessari per ogni documentoNecessary fields for each document NoteNotes
upload L'azione upload è simile a "upsert", in cui il documento viene inserito se è nuovo e aggiornato o sostituito se esiste già.An upload action is similar to an "upsert" where the document will be inserted if it is new and updated/replaced if it exists. chiave, oltre a tutti gli altri campi da definirekey, plus any other fields you wish to define Quando si aggiorna o si sostituisce un documento esistente, qualsiasi campo non specificato nella richiesta avrà il campo impostato su null.When updating/replacing an existing document, any field that is not specified in the request will have its field set to null. Ciò si verifica anche quando il campo è stato precedentemente impostato su un valore diverso da null.This occurs even when the field was previously set to a non-null value.
merge Aggiorna un documento esistente con i campi specificati.Updates an existing document with the specified fields. Se il documento non esiste nell'indice, l'unione non riuscirà.If the document does not exist in the index, the merge will fail. chiave, oltre a tutti gli altri campi da definirekey, plus any other fields you wish to define I campi specificati in un'azione di unione sostituiscono i campi esistenti nel documento.Any field you specify in a merge will replace the existing field in the document. Sono inclusi anche i campi di tipo Collection(Edm.String).This includes fields of type Collection(Edm.String). Ad esempio, se il documento contiene un campo tags con valore ["budget"] e si esegue un'unione con valore ["economy", "pool"] per tags, il valore finale del campo tags sarà ["economy", "pool"]For example, if the document contains a field tags with value ["budget"] and you execute a merge with value ["economy", "pool"] for tags, the final value of the tags field will be ["economy", "pool"]. e non ["budget", "economy", "pool"].It will not be ["budget", "economy", "pool"].
mergeOrUpload Questa azione si comporta come merge se nell'indice esiste già un documento con la chiave specificata.This action behaves like merge if a document with the given key already exists in the index. Se il documento non esiste, si comporta come upload con un nuovo documento.If the document does not exist, it behaves like upload with a new document. chiave, oltre a tutti gli altri campi da definirekey, plus any other fields you wish to define -
delete Rimuove il documento specificato dall'indice.Removes the specified document from the index. solo campo chiavekey only Tutti i campi diversi dal campo chiave specificati verranno ignorati.Any fields you specify other than the key field will be ignored. Se si vuole rimuovere un singolo campo da un documento, usare invece merge e impostare il campo su Null in modo esplicito.If you want to remove an individual field from a document, use merge instead and simply set the field explicitly to null.

Creare la richiesta HTTP e il corpo della richiestaConstruct your HTTP request and request body

Ora che sono stati raccolti i valori dei campi necessari per le operazioni sull'indice, si è pronti per creare la richiesta HTTP effettiva e il corpo della richiesta JSON per importare i dati.Now that you have gathered the necessary field values for your index actions, you are ready to construct the actual HTTP request and JSON request body to import your data.

Richiesta e intestazioni della richiestaRequest and Request Headers

Nell'URL è necessario fornire il nome del servizio, il nome dell'indice, in questo caso "hotels", nonché la versione corretta dell'API. Al momento della pubblicazione di questo documento la versione dell'API corrente è 2016-09-01.In the URL, you will need to provide your service name, index name ("hotels" in this case), as well as the proper API version (the current API version is 2016-09-01 at the time of publishing this document). È necessario definire le intestazioni della richiesta Content-Type e api-key.You will need to define the Content-Type and api-key request headers. Nel secondo caso, usare una delle chiavi amministratore del servizio.For the latter, use one of your service's admin keys.

POST https://[search service].search.windows.net/indexes/hotels/docs/index?api-version=2016-09-01
Content-Type: application/json
api-key: [admin key]

Request BodyRequest Body

{
    "value": [
        {
            "@search.action": "upload",
            "hotelId": "1",
            "baseRate": 199.0,
            "description": "Best hotel in town",
            "description_fr": "Meilleur hôtel en ville",
            "hotelName": "Fancy Stay",
            "category": "Luxury",
            "tags": ["pool", "view", "wifi", "concierge"],
            "parkingIncluded": false,
            "smokingAllowed": false,
            "lastRenovationDate": "2010-06-27T00:00:00Z",
            "rating": 5,
            "location": { "type": "Point", "coordinates": [-122.131577, 47.678581] }
        },
        {
            "@search.action": "upload",
            "hotelId": "2",
            "baseRate": 79.99,
            "description": "Cheapest hotel in town",
            "description_fr": "Hôtel le moins cher en ville",
            "hotelName": "Roach Motel",
            "category": "Budget",
            "tags": ["motel", "budget"],
            "parkingIncluded": true,
            "smokingAllowed": true,
            "lastRenovationDate": "1982-04-28T00:00:00Z",
            "rating": 1,
            "location": { "type": "Point", "coordinates": [-122.131577, 49.678581] }
        },
        {
            "@search.action": "mergeOrUpload",
            "hotelId": "3",
            "baseRate": 129.99,
            "description": "Close to town hall and the river"
        },
        {
            "@search.action": "delete",
            "hotelId": "6"
        }
    ]
}

In questo caso, si useranno upload, mergeOrUpload e delete come azioni di ricerca.In this case, we are using upload, mergeOrUpload, and delete as our search actions.

Si supponga che l'indice "hotels" di esempio sia già popolato con alcuni documenti.Assume that this example "hotels" index is already populated with a number of documents. Si noti che non è stato necessario specificare tutti i possibili campi dei documenti quando si usa mergeOrUpload e come viene specificata solo la chiave del documento (hotelId) quando si usa delete.Note how we did not have to specify all the possible document fields when using mergeOrUpload and how we only specified the document key (hotelId) when using delete.

Si noti anche che è possibile includere solo fino a 1000 documenti, o 16 MB, in una singola richiesta di indicizzazione.Also, note that you can only include up to 1000 documents (or 16 MB) in a single indexing request.

Informazioni sul codice di risposta HTTPUnderstand your HTTP response code

200200

Dopo l'invio di una richiesta di indicizzazione riuscita, si riceverà una risposta HTTP con codice di stato 200 OK.After submitting a successful indexing request you will receive an HTTP response with status code of 200 OK. Il corpo JSON della risposta HTTP sarà il seguente:The JSON body of the HTTP response will be as follows:

{
    "value": [
        {
            "key": "unique_key_of_document",
            "status": true,
            "errorMessage": null
        },
        ...
    ]
}

207207

Quando almeno un elemento non è stato indicizzato correttamente, viene restituito il codice di stato 207 .A status code of 207 will be returned when at least one item was not successfully indexed. Il corpo JSON della risposta HTTP contiene informazioni sui documenti la cui richiesta di indicizzazione non è riuscita.The JSON body of the HTTP response will contain information about the unsuccessful document(s).

{
    "value": [
        {
            "key": "unique_key_of_document",
            "status": false,
            "errorMessage": "The search service is too busy to process this document. Please try again later."
        },
        ...
    ]
}

Nota

Spesso questo significa che il carico sul servizio di ricerca sta per raggiungere un punto in cui le richieste di indicizzazione inizieranno a restituire risposte 503.This often means that the load on your search service is reaching a point where indexing requests will begin to return 503 responses. In questo caso, è consigliabile interrompere l'invio del codice client e attendere prima di riprovare.In this case, we highly recommend that your client code back off and wait before retrying. Il sistema avrà così tempo per recuperare, aumentando le probabilità che le future richieste siano soddisfatte.This will give the system some time to recover, increasing the chances that future requests will succeed. La ripetizione rapida delle richieste prolungherà semplicemente il tempo necessario per risolvere la situazione.Rapidly retrying your requests will only prolong the situation.

429429

Il codice di stato 429 viene restituito quando è stata superata la quota del numero di documenti per indice.A status code of 429 will be returned when you have exceeded your quota on the number of documents per index.

503503

Il codice di stato 503 viene restituito se nessuno degli elementi nella richiesta è stato indicizzato.A status code of 503 will be returned if none of the items in the request were successfully indexed. Questo errore indica che il sistema è sovraccarico e non può elaborare la richiesta in questo momento.This error means that the system is under heavy load and your request can't be processed at this time.

Nota

In questo caso, è consigliabile interrompere l'invio del codice client e attendere prima di riprovare.In this case, we highly recommend that your client code back off and wait before retrying. Il sistema avrà così tempo per recuperare, aumentando le probabilità che le future richieste siano soddisfatte.This will give the system some time to recover, increasing the chances that future requests will succeed. La ripetizione rapida delle richieste prolungherà semplicemente il tempo necessario per risolvere la situazione.Rapidly retrying your requests will only prolong the situation.

Per altre informazioni su azioni sui documenti e risposte di esito positivo/errore, vedere Aggiungere, aggiornare o eliminare documenti.For more information on document actions and success/error responses, please see Add, Update, or Delete Documents. Per altre informazioni su altri codici di stato HTTP che possono essere restituiti in caso di errore, vedere Codici di stato HTTP (Ricerca di Azure).For more information on other HTTP status codes that could be returned in case of failure, see HTTP status codes (Azure Search).

Passaggi successiviNext steps

Dopo il popolamento dell'indice di Ricerca di Azure, si potrà iniziare a eseguire una query per la ricerca di documenti.After populating your Azure Search index, you will be ready to start issuing queries to search for documents. Per informazioni dettagliate, vedere Eseguire query su un indice di Ricerca di Azure .See Query Your Azure Search Index for details.