Creare un indice di Ricerca di Azure con l'API RESTCreate an Azure Search index using the REST API

Questo articolo illustra il processo di creazione di un indice di Ricerca di Azure mediante l'API REST di Ricerca di Azure.This article will walk you through the process of creating an Azure Search index using the Azure Search REST API.

Prima di seguire le indicazioni di questa guida e creare un indice, è necessario creare un servizio Ricerca di Azure.Before following this guide and creating an index, you should have already created an Azure Search service.

Per creare un indice di Ricerca di Azure usando l'API REST, verrà inviata una singola richiesta HTTP POST all'endpoint dell'URL del servizio Ricerca di Azure.To create an Azure Search index using the REST API, you will issue a single HTTP POST request to your Azure Search service's URL endpoint. La definizione dell'indice verrà inclusa nel corpo della richiesta come contenuto JSON ben formato.Your index definition will be contained in the request body as well-formed JSON content.

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

Dopo avere effettuato il provisioning di un servizio Ricerca di Azure, è possibile inviare richieste HTTP rispetto all'endpoint dell'URL del servizio usando l'API REST.Now that you have provisioned an Azure Search service, you can issue HTTP requests against your service's URL endpoint using the REST API. Tutte le richieste API devono includere la chiave API generata per il servizio di ricerca di cui è stato effettuato il provisioning.All API requests 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, è necessario accedere al portale di AzureTo find your service's api-keys you must log into 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 la creazione di un indice è possibile usare la chiave primaria o secondaria.For the purposes of creating an index, you can use either your primary or secondary admin key.

Definire l'indice di Ricerca di Azure usando JSON ben formatoDefine your Azure Search index using well-formed JSON

Una singola richiesta HTTP POST al servizio creerà l'indice.A single HTTP POST request to your service will create your index. Il corpo della richiesta HTTP POST conterrà un singolo oggetto JSON che definisce l'indice di Ricerca di Azure.The body of your HTTP POST request will contain a single JSON object that defines your Azure Search index.

  1. La prima proprietà di questo oggetto JSON è il nome dell'indice.The first property of this JSON object is the name of your index.
  2. La seconda proprietà di questo oggetto JSON è una matrice JSON denominata fields che contiene un oggetto JSON separato per ogni campo dell'indice.The second property of this JSON object is a JSON array named fields that contains a separate JSON object for each field in your index. Ogni oggetto JSON contiene più coppie nome/valore per ogni attributo dei campi che include "name", "type" e così via.Each of these JSON objects contain multiple name/value pairs for each of the field attributes including "name," "type," etc.

È importante tenere in considerazione l'esperienza di ricerca dell'utente e le esigenze aziendali quando si progetta l'indice, perché a ogni campo devono essere assegnati gli attributi appropriati.It is important that you keep your search user experience and business needs in mind when designing your index as each field must be assigned the proper attributes. Questi attributi controllano le funzionalità di ricerca (filtro, facet, ordinamento, ricerca full-text e così via) che vengono applicate ai campi.These attributes control which search features (filtering, faceting, sorting full-text search, etc.) apply to which fields. Per eventuali attributi non specificati, per impostazione predefinita verrà abilitata la funzionalità di ricerca corrispondente, a meno che non si specifichi che deve essere disabilitata.For any attribute you do not specify, the default will be to enable the corresponding search feature unless you specifically disable it.

All'indice di esempio è stato assegnato il nome "hotels" e i campi sono stati definiti come segue:For our example, we've named our index "hotels" and defined our fields as follows:

{
    "name": "hotels",  
    "fields": [
        {"name": "hotelId", "type": "Edm.String", "key": true, "searchable": false, "sortable": false, "facetable": false},
        {"name": "baseRate", "type": "Edm.Double"},
        {"name": "description", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false},
        {"name": "description_fr", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.lucene"},
        {"name": "hotelName", "type": "Edm.String", "facetable": false},
        {"name": "category", "type": "Edm.String"},
        {"name": "tags", "type": "Collection(Edm.String)"},
        {"name": "parkingIncluded", "type": "Edm.Boolean", "sortable": false},
        {"name": "smokingAllowed", "type": "Edm.Boolean", "sortable": false},
        {"name": "lastRenovationDate", "type": "Edm.DateTimeOffset"},
        {"name": "rating", "type": "Edm.Int32"},
        {"name": "location", "type": "Edm.GeographyPoint"}
    ]
}

Gli attributi dell'indice per ogni campo sono stati scelti con attenzione in base al modo in cui si pensa che verranno usati nell'applicazione.We have carefully chosen the index attributes for each field based on how we think they will be used in an application. Ad esempio, hotelId è una chiave univoca che probabilmente le persone che cercano hotel non conosceranno, quindi si disabilita la ricerca full-text per quel campo impostando searchable su false, in modo da risparmiare spazio nell'indice.For example, hotelId is a unique key that people searching for hotels likely won't know, so we disable full-text search for that field by setting searchable to false, which saves space in the index.

Si noti che esattamente un campo di tipo Edm.String nell'indice deve essere il campo designato come 'key'.Please note that exactly one field in your index of type Edm.String must be the designated as the 'key' field.

La definizione di indice precedente usa un analizzatore della lingua per il campo description_fr perché quest'ultimo viene usato per archiviare testo in francese.The index definition above uses a language analyzer for the description_fr field because it is intended to store French text. Per altre informazioni sugli analizzatori di lingue, vedere l'articolo sul supporto per le lingue e il post di blog corrispondente.See the Language support topic as well as the corresponding blog post for more information about language analyzers.

Inviare la richiesta HTTPIssue the HTTP request

  1. Usando la definizione di indice come corpo della richiesta, inviare una richiesta HTTP POST all'URL dell'endpoint di servizio Ricerca di Azure.Using your index definition as the request body, issue an HTTP POST request to your Azure Search service endpoint URL. Assicurarsi di usare nell'URL il nome del servizio come nome host e specificare il valore api-version appropriato come parametro della stringa di query. La versione API corrente è 2016-09-01 al momento della pubblicazione di questo documento.In the URL, be sure to use your service name as the host name, and put the proper api-version as a query string parameter (the current API version is 2016-09-01 at the time of publishing this document).
  2. Nelle intestazioni della richiesta specificare Content-Type come application/json.In the request headers, specify the Content-Type as application/json. Sarà anche necessario specificare la chiave amministratore del servizio identificata nel Passaggio I nell'intestazione api-key .You will also need to provide your service's admin key that you identified in Step I in the api-key header.

È necessario fornire il nome servizio e la chiave API per inviare la richiesta seguente:You will have to provide your own service name and api key to issue the request below:

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

Per una richiesta riuscita, verrà visualizzato il codice di stato 201 (Creato).For a successful request, you should see status code 201 (Created). Per altre informazioni sulla creazione di un indice tramite l'API REST, vedere qui le informazioni di riferimento sulle API.For more information on creating an index via the REST API, please visit the API reference here. 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).

Dopo avere usato un indice, se si vuole eliminarlo è sufficiente inviare una richiesta HTTP DELETE.When you're done with an index and want to delete it, just issue an HTTP DELETE request. Ad esempio, per eliminare l'indice "hotels":For example, this is how we would delete the "hotels" index:

DELETE https://[service name].search.windows.net/indexes/hotels?api-version=2016-09-01
api-key: [api-key]

Passaggi successiviNext steps

Dopo avere creato un indice di Ricerca di Azure, sarà possibile caricare il contenuto nell'indice , in modo che si possa iniziare a eseguire ricerche nei dati.After creating an Azure Search index, you will be ready to upload your content into the index so you can start searching your data.