Eseguire query su un indice di Ricerca di Azure con l'API RESTQuery your Azure Search index using the REST API

Questo articolo illustra come eseguire query in un indice con l'API REST di Ricerca di Azure.This article shows you how to query an index using the Azure Search REST API.

Prima di iniziare questa procedura dettagliata, è necessario avere creato un indice di Ricerca di Azure e averlo popolato con dati.Before beginning this walkthrough, you should already have created an Azure Search index and populated it with data. Per informazioni generali, vedere Funzionamento della ricerca full-text in Ricerca di Azure.For background information, see How full text search works in Azure Search.

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

Un componente chiave di ogni operazione di ricerca con l'API REST di Ricerca di Azure è la chiave API generata per il servizio di cui è stato effettuato il provisioning.A key component of every search operation against the Azure Search REST API is the api-key that was generated for the 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 the "Keys" icon

Il servizio ha chiavi amministratore e chiavi di query.Your service has 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.

Ai fini di una query su un indice, è possibile usare una delle chiavi di query.For the purposes of querying an index, you can use one of your query keys. Si possono anche usare le chiavi amministratore per le query, ma è necessario usare una chiave di query nel codice dell'applicazione, perché questo approccio è più coerente con il principio del privilegio minimo.Your admin keys can also be used for queries, but you should use a query key in your application code as this better follows the Principle of least privilege.

Formulare la queryFormulate your query

Esistono due modi per eseguire una ricerca nell'indice usando l'API REST.There are two ways to search your index using the REST API. Uno consiste nell'inviare una richiesta HTTP POST in cui i parametri di query vengono definiti in un oggetto JSON nel corpo della richiesta.One way is to issue an HTTP POST request where your query parameters are defined in a JSON object in the request body. L'altro consiste nell'inviare una richiesta HTTP GET in cui i parametri di query vengono definiti nell'URL della richiesta.The other way is to issue an HTTP GET request where your query parameters are defined within the request URL. POST ha limiti più ridotti per quanto riguarda le dimensioni dei parametri di query rispetto a GET.POST has more relaxed limits on the size of query parameters than GET. Per questo motivo, è consigliabile usare POST, a meno di non avere circostanze particolari in cui l'uso di GET potrebbe essere più conveniente.For this reason, we recommend using POST unless you have special circumstances where using GET would be more convenient.

Sia per POST che per GET è necessario fornire il nome del servizio, il nome dell'indice e la versione dell'API corretta nell'URL della richiesta. Al momento della pubblicazione di questo documento la versione dell'API corrente è 2016-09-01.For both POST and GET, you need to provide your service name, index name, and the proper API version (the current API version is 2016-09-01 at the time of publishing this document) in the request URL. Per GET i parametri di query devono essere forniti nella stringa di query alla fine dell'URL.For GET, the query string at the end of the URL is where you provide the query parameters. Per il formato dell'URL, vedere di seguito:See below for the URL format:

https://[service name].search.windows.net/indexes/[index name]/docs?[query string]&api-version=2016-09-01

Il formato per POST è lo stesso, ma con solo la versione dell'API nei parametri della stringa di query.The format for POST is the same, but with only api-version in the query string parameters.

Query di esempioExample Queries

Ecco alcuni esempi di query su un indice denominato "hotels".Here are a few example queries on an index named "hotels". Queste query vengono visualizzate in formato GET e POST.These queries are shown in both GET and POST format.

Eseguire una ricerca del termine "budget" nell'intero indice e restituire solo il campo hotelName:Search the entire index for the term 'budget' and return only the hotelName field:

GET https://[service name].search.windows.net/indexes/hotels/docs?search=budget&$select=hotelName&api-version=2016-09-01

POST https://[service name].search.windows.net/indexes/hotels/docs/search?api-version=2016-09-01
{
    "search": "budget",
    "select": "hotelName"
}

Applicare un filtro all'indice per trovare gli hotel con un prezzo inferiore a 150 dollari a notte e restituire hotelId e description:Apply a filter to the index to find hotels cheaper than $150 per night, and return the hotelId and description:

GET https://[service name].search.windows.net/indexes/hotels/docs?search=*&$filter=baseRate lt 150&$select=hotelId,description&api-version=2016-09-01

POST https://[service name].search.windows.net/indexes/hotels/docs/search?api-version=2016-09-01
{
    "search": "*",
    "filter": "baseRate lt 150",
    "select": "hotelId,description"
}

Eseguire una ricerca nell'intero indice, ordinata per campo specifico (lastRenovationDate) in ordine decrescente, acquisire i primi due risultati e mostrare solo hotelName e lastRenovationDate:Search the entire index, order by a specific field (lastRenovationDate) in descending order, take the top two results, and show only hotelName and lastRenovationDate:

GET https://[service name].search.windows.net/indexes/hotels/docs?search=*&$top=2&$orderby=lastRenovationDate desc&$select=hotelName,lastRenovationDate&api-version=2016-09-01

POST https://[service name].search.windows.net/indexes/hotels/docs/search?api-version=2016-09-01
{
    "search": "*",
    "orderby": "lastRenovationDate desc",
    "select": "hotelName,lastRenovationDate",
    "top": 2
}

Inviare la richiesta HTTPSubmit your HTTP request

Dopo aver formulato la query come parte dell'URL della richiesta HTTP (per GET) o del corpo (per POST), è possibile definire le intestazioni delle richieste e inviare la query.Now that you have formulated your query as part of your HTTP request URL (for GET) or body (for POST), you can define your request headers and submit your query.

Richiesta e intestazioni della richiestaRequest and Request Headers

È necessario definire due intestazioni della richiesta per GET o tre per POST:You must define two request headers for GET, or three for POST:

  1. L'intestazione api-key deve essere impostata sulla chiave di query trovata nel passaggio I precedente.The api-key header must be set to the query key you found in step I above. È anche possibile usare una chiave amministratore come intestazione api-key, ma è consigliabile usare una chiave di query perché concederà esclusivamente l'accesso in sola lettura a indici e documenti.You can also use an admin key as the api-key header, but it is recommended that you use a query key as it exclusively grants read-only access to indexes and documents.
  2. L'intestazione Accept deve essere impostata su application/json.The Accept header must be set to application/json.
  3. Solo per POST l'intestazione Content-Type deve essere impostata anche su application/json.For POST only, the Content-Type header should also be set to application/json.

Vedere di seguito per una richiesta HTTP GET per la ricerca nell'indice "hotels" con l'API REST di Ricerca di Azure, usando una query semplice che consente di cercare il termine "motel":See below for an HTTP GET request to search the "hotels" index using the Azure Search REST API, using a simple query that searches for the term "motel":

GET https://[service name].search.windows.net/indexes/hotels/docs?search=motel&api-version=2016-09-01
Accept: application/json
api-key: [query key]

Di seguito è riportata la stessa query di esempio, questa volta usando HTTP POST:Here is the same example query, this time using HTTP POST:

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

{
    "search": "motel"
}

Una richiesta di query riuscita restituirà un codice di stato 200 OK e i risultati della ricerca saranno restituiti in formato JSON nel corpo della risposta.A successful query request will result in a Status Code of 200 OK and the search results are returned as JSON in the response body. Ecco i risultati per la query precedente, supponendo che l'indice "hotels" sia popolato con i dati di esempio in Importazione di dati in Ricerca di Azure tramite l'API REST. Si noti che JSON è stato formattato per maggiore chiarezza.Here is what the results for the above query look like, assuming the "hotels" index is populated with the sample data in Data Import in Azure Search using the REST API (note that the JSON has been formatted for clarity).

{
    "value": [
        {
            "@search.score": 0.59600675,
            "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],
                "crs": {
                    "type":"name",
                    "properties": {
                        "name": "EPSG:4326"
                    }
                }
            }
        }
    ]
}

Per altre informazioni, vedere la sezione "Risposta" di Eseguire ricerche nei documenti.To learn more, please visit the "Response" section of Search 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).