Creare un indice di Ricerca di Azure con .NET SDKCreate an Azure Search index using the .NET SDK

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

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.

Nota

Tutto il codice di esempio in questo articolo è scritto in C#.All sample code in this article is written in C#. Il codice sorgente completo è disponibile su GitHub.You can find the full source code on GitHub. Per una descrizione più dettagliata del codice di esempio, vedere le informazioni relative a Azure Search .NET SDK.You can also read about the Azure Search .NET SDK for a more detailed walk through of the sample code.

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 di Ricerca di Azure, è possibile inviare richieste rispetto all'endpoint di servizio usando .NET SDK.Now that you have provisioned an Azure Search service, you are almost ready to issue requests against your service endpoint using the .NET SDK. Innanzitutto, è necessario ottenere una delle chiavi API amministratore generate per il servizio di ricerca di cui è stato effettuato il provisioning.First, you will need to obtain one of the admin api-keys that was generated for the search service you provisioned. .NET SDK invierà questa chiave API a ogni richiesta del servizio.The .NET SDK will send this api-key on every request to your service. 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, accedere al portale di AzureTo find your service's api-keys, 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 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.

Creare un'istanza della classe SearchServiceClientCreate an instance of the SearchServiceClient class

Per iniziare a usare Azure Search .NET SDK, è necessario creare un'istanza della classe SearchServiceClient .To start using the Azure Search .NET SDK, you will need to create an instance of the SearchServiceClient class. Questa classe ha diversi costruttori.This class has several constructors. Il costruttore in uso accetta il nome del servizio di ricerca e un oggetto SearchCredentials come parametri.The one you want takes your search service name and a SearchCredentials object as parameters. SearchCredentials esegue il wrapping della chiave API.SearchCredentials wraps your api-key.

Il codice seguente crea un nuovo oggetto SearchServiceClient usando i valori del nome del servizio di ricerca e della chiave API archiviati nel file di configurazione dell'applicazione, appsettings.json nel caso dell'applicazione di esempio:The code below creates a new SearchServiceClient using values for the search service name and api-key that are stored in the application's config file (appsettings.json in the case of the sample application):

private static SearchServiceClient CreateSearchServiceClient(IConfigurationRoot configuration)
{
    string searchServiceName = configuration["SearchServiceName"];
    string adminApiKey = configuration["SearchServiceAdminApiKey"];

    SearchServiceClient serviceClient = new SearchServiceClient(searchServiceName, new SearchCredentials(adminApiKey));
    return serviceClient;
}

SearchServiceClient ha una proprietà Indexes.SearchServiceClient has an Indexes property. Questa proprietà fornisce tutti i metodi necessari per creare, elencare, aggiornare o eliminare gli indici di Ricerca di Azure.This property provides all the methods you need to create, list, update, or delete Azure Search indexes.

Nota

La classe SearchServiceClient gestisce le connessioni al servizio di ricerca.The SearchServiceClient class manages connections to your search service. Per evitare l'apertura di un numero eccessivo di connessioni, se possibile è consigliabile provare a condividere una singola istanza di SearchServiceClient nell'applicazione.In order to avoid opening too many connections, you should try to share a single instance of SearchServiceClient in your application if possible. I metodi per abilitare tale condivisione sono thread-safe.Its methods are thread-safe to enable such sharing.

Definire l'indice di ricerca di AzureDefine your Azure Search index

Una singola chiamata al metodo Indexes.Create consente di creare l'indice.A single call to the Indexes.Create method will create your index. Questo metodo accetta come parametro un oggetto Index che definisce l'indice di Ricerca di Azure.This method takes as a parameter an Index object that defines your Azure Search index. È necessario creare un oggetto Index e inizializzarlo come indicato di seguito:You need to create an Index object and initialize it as follows:

  1. Impostare la proprietà Name dell'oggetto Index sul nome dell'indice.Set the Name property of the Index object to the name of your index.
  2. Impostare la proprietà Fields dell'oggetto Index su un array di oggetti Field.Set the Fields property of the Index object to an array of Field objects. Il modo più semplice per creare gli oggetti Field consiste nel chiamare il metodo FieldBuilder.BuildForType passando una classe modello per il parametro di tipo.The easiest way to create the Field objects is by calling the FieldBuilder.BuildForType method, passing a model class for the type parameter. Una classe modello dispone di proprietà corrispondenti ai campi dell'indice.A model class has properties that map to the fields of your index. Questo consente di associare documenti dell'indice di ricerca a istanze della classe modello.This allows you to bind documents from your search index to instances of your model class.

Nota

Se non si prevede di usare una classe modello, è comunque possibile definire l'indice mediante la creazione diretta di oggetti Field.If you don't plan to use a model class, you can still define your index by creating Field objects directly. È possibile fornire il nome del campo al costruttore, insieme al tipo di dati (o all'analizzatore per i campi stringa).You can provide the name of the field to the constructor, along with the data type (or analyzer for string fields). È inoltre possibile impostare altre proprietà come IsSearchable, IsFilterable e così via.You can also set other properties like IsSearchable, IsFilterable, etc.

Quando si progetta l'indice è importante tenere in considerazione l'esperienza di ricerca dell'utente e le esigenze aziendali, perché a ogni campo devono essere assegnate le proprietà opportune.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 appropriate properties. Queste proprietà controllano le funzionalità di ricerca (filtro, facet, ordinamento, ricerca full-text e così via) che vengono applicate ai campi.These properties control which search features (filtering, faceting, sorting full-text search, etc.) apply to which fields. Per tutte le proprietà non esplicitamente impostate, la classe Field disabilita per impostazione predefinita la funzionalità di ricerca corrispondente, a meno che non venga abilitata specificamente.For any property you do not explicitly set, the Field class defaults to disabling the corresponding search feature unless you specifically enable it.

All'indice di esempio è stato assegnato il nome "hotels" e i campi sono stati definiti usando una classe modello.For our example, we've named our index "hotels" and defined our fields using a model class. Ogni proprietà della classe modello contiene attributi che determinano i comportamenti correlati alla ricerca del campo di indice corrispondente.Each property of the model class has attributes which determine the search-related behaviors of the corresponding index field. La classe modello viene definita come segue:The model class is defined as follows:

using System;
using Microsoft.Azure.Search;
using Microsoft.Azure.Search.Models;
using Microsoft.Spatial;
using Newtonsoft.Json;

// The SerializePropertyNamesAsCamelCase attribute is defined in the Azure Search .NET SDK.
// It ensures that Pascal-case property names in the model class are mapped to camel-case
// field names in the index.
[SerializePropertyNamesAsCamelCase]
public partial class Hotel
{
    [System.ComponentModel.DataAnnotations.Key]
    [IsFilterable]
    public string HotelId { get; set; }

    [IsFilterable, IsSortable, IsFacetable]
    public double? BaseRate { get; set; }

    [IsSearchable]
    public string Description { get; set; }

    [IsSearchable]
    [Analyzer(AnalyzerName.AsString.FrLucene)]
    [JsonProperty("description_fr")]
    public string DescriptionFr { get; set; }

    [IsSearchable, IsFilterable, IsSortable]
    public string HotelName { get; set; }

    [IsSearchable, IsFilterable, IsSortable, IsFacetable]
    public string Category { get; set; }

    [IsSearchable, IsFilterable, IsFacetable]
    public string[] Tags { get; set; }

    [IsFilterable, IsFacetable]
    public bool? ParkingIncluded { get; set; }

    [IsFilterable, IsFacetable]
    public bool? SmokingAllowed { get; set; }

    [IsFilterable, IsSortable, IsFacetable]
    public DateTimeOffset? LastRenovationDate { get; set; }

    [IsFilterable, IsSortable, IsFacetable]
    public int? Rating { get; set; }

    [IsFilterable, IsSortable]
    public GeographyPoint Location { get; set; }
}

Gli attributi per ogni proprietà sono stati scelti con attenzione in base al modo in cui si pensa che verranno usati nell'applicazione.We have carefully chosen the attributes for each property based on how we think they will be used in an application. Ad esempio, è probabile che gli utenti che cercano degli hotel siano interessati alle corrispondenze delle parole chiave nel campo description. Viene quindi abilitata la ricerca full-text per il campo mediante l'aggiunta dell'attributo IsSearchable alla proprietà Description.For example, it is likely that people searching for hotels will be interested in keyword matches on the description field, so we enable full-text search for that field by adding the IsSearchable attribute to the Description property.

Si noti che esattamente un campo di tipo string dell'indice deve essere il campo designato come key mediante l'aggiunta dell'attributo Key. Vedere HotelId nell'esempio precedente.Please note that exactly one field in your index of type string must be the designated as the key field by adding the Key attribute (see HotelId in the above example).

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.

Nota

Per impostazione predefinita, il nome di ogni proprietà della classe modello viene usato come nome del corrispondente campo dell'indice.By default, the name of each property in your model class is used as the name of the corresponding field in the index. Se si intendono mappare tutti i nomi di proprietà ai nomi di campo secondo la convenzione camel, contrassegnare la classe con l'attributo SerializePropertyNamesAsCamelCase.If you want to map all property names to camel-case field names, mark the class with the SerializePropertyNamesAsCamelCase attribute. Se si intende eseguire il mapping a un nome differente, è possibile usare l'attributo JsonProperty come la proprietà DescriptionFr precedente.If you want to map to a different name, you can use the JsonProperty attribute like the DescriptionFr property above. L'attributo JsonProperty ha la precedenza sull'attributo SerializePropertyNamesAsCamelCase.The JsonProperty attribute takes precedence over the SerializePropertyNamesAsCamelCase attribute.

Dopo aver definito una classe modello, è possibile creare una definizione di indice in modo molto semplice:Now that we've defined a model class, we can create an index definition very easily:

var definition = new Index()
{
    Name = "hotels",
    Fields = FieldBuilder.BuildForType<Hotel>()
};

Creare l'indiceCreate the index

Dopo aver creato un oggetto Index inizializzato, è possibile creare l'indice chiamando Indexes.Create sull'oggetto SearchServiceClient.Now that you have an initialized Index object, you can create the index simply by calling Indexes.Create on your SearchServiceClient object:

serviceClient.Indexes.Create(definition);

Se la richiesta è corretta, il metodo restituirà un valore regolare.For a successful request, the method will return normally. Se si verifica un problema con la richiesta, ad esempio un parametro non valido, il metodo genererà CloudException.If there is a problem with the request such as an invalid parameter, the method will throw CloudException.

Dopo avere usato un indice, se si vuole eliminarlo è sufficiente chiamare il metodo Indexes.Delete in SearchServiceClient.When you're done with an index and want to delete it, just call the Indexes.Delete method on your SearchServiceClient. Ad esempio, per eliminare l'indice "hotels":For example, this is how we would delete the "hotels" index:

serviceClient.Indexes.Delete("hotels");

Nota

Il codice di esempio riportato in questo articolo utilizza i metodi sincroni di .NET SDK di Ricerca di Azure per motivi di semplicità.The example code in this article uses the synchronous methods of the Azure Search .NET SDK for simplicity. È consigliabile utilizzare i metodi asincroni nelle proprie applicazioni per mantenerle scalabili e reattive.We recommend that you use the asynchronous methods in your own applications to keep them scalable and responsive. Ad esempio, negli esempi precedenti è possibile usare CreateAsync e DeleteAsync anziché Create e Delete.For example, in the examples above you could use CreateAsync and DeleteAsync instead of Create and Delete.

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.