Eseguire query su un indice di Ricerca di Azure con .NET SDKQuery your Azure Search index using the .NET SDK

Questo articolo illustra come eseguire query su un indice con Azure Search .NET SDK.This article will show you how to query an index using the Azure Search .NET SDK.

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.

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 di query del servizio Ricerca di AzureIdentify your Azure Search service's query api-key

Dopo avere creato un indice di Ricerca di Azure, si è quasi pronti per eseguire query con .NET SDK.Now that you have created an Azure Search index, you are almost ready to issue queries using the .NET SDK. Prima di tutto è necessario ottenere una delle chiavi API di query generate per il servizio di ricerca di cui è stato effettuato il provisioning.First, you will need to obtain one of the query api-keys that was generated for the search service you provisioned. .NET SDK invierà questa chiave API a ogni richiesta al 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, è 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.

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.

Creare un'istanza della classe SearchIndexClientCreate an instance of the SearchIndexClient class

Per eseguire query con Azure Search .NET SDK, è necessario creare un'istanza della classe SearchIndexClient .To issue queries with the Azure Search .NET SDK, you will need to create an instance of the SearchIndexClient class. Questa classe ha diversi costruttori.This class has several constructors. Quello appropriato accetta il nome del servizio di ricerca, il nome dell'indice e un oggetto SearchCredentials come parametri.The one you want takes your search service name, index 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 SearchIndexClient per l'indice "hotels" creato in Creare un indice di Ricerca di Azure con .NET SDK, usando i valori archiviati nel file di configurazione dell'applicazione, appsettings.json nel caso dell'applicazione di esempio, per il nome del servizio di ricerca e la chiave API:The code below creates a new SearchIndexClient for the "hotels" index (created in Create an Azure Search index using the .NET SDK) 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 SearchIndexClient CreateSearchIndexClient(IConfigurationRoot configuration)
{
    string searchServiceName = configuration["SearchServiceName"];
    string queryApiKey = configuration["SearchServiceQueryApiKey"];

    SearchIndexClient indexClient = new SearchIndexClient(searchServiceName, "hotels", new SearchCredentials(queryApiKey));
    return indexClient;
}

SearchIndexClient include una proprietà Documents.SearchIndexClient has a Documents property. Questa proprietà fornisce tutti i metodi necessari per eseguire query sugli indici di Ricerca di Azure.This property provides all the methods you need to query Azure Search indexes.

Eseguire query sull'indiceQuery your index

Per eseguire una ricerca con .NET SDK è sufficiente chiamare il metodo Documents.Search sull'oggetto SearchIndexClient.Searching with the .NET SDK is as simple as calling the Documents.Search method on your SearchIndexClient. Questo metodo accetta alcuni parametri, incluso il testo di ricerca, nonché un oggetto SearchParameters che può essere usato per perfezionare ulteriormente la query.This method takes a few parameters, including the search text, along with a SearchParameters object that can be used to further refine the query.

Tipi di queryTypes of Queries

I due tipi di query principali che si useranno sono search e filter.The two main query types you will use are search and filter. Una query search esegue la ricerca di uno o più termini in tutti i campi ricercabile nell'indice.A search query searches for one or more terms in all searchable fields in your index. Una query filter valuta un'espressione booleana su tutti i campi filtrabili di un indice.A filter query evaluates a boolean expression over all filterable fields in an index.

Ricerche e filtri vengono eseguiti usando il metodo Documents.Search .Both searches and filters are performed using the Documents.Search method. Una query di ricerca può essere passata nel parametro searchText, mentre un'espressione di filtro può essere passata nella proprietà Filter della classe SearchParameters.A search query can be passed in the searchText parameter, while a filter expression can be passed in the Filter property of the SearchParameters class. Per filtrare senza eseguire ricerche, passare semplicemente "*" per il parametro searchText.To filter without searching, just pass "*" for the searchText parameter. Per eseguire una ricerca senza filtrare, lasciare la proprietà Filter non impostata oppure non passare un'istanza di SearchParameters.To search without filtering, just leave the Filter property unset, or do not pass in a SearchParameters instance at all.

Query di esempioExample Queries

Il codice di esempio seguente mostra alcuni modi per eseguire una query sull'indice "hotels" definito in Creare un indice di Ricerca di Azure con .NET SDK.The following sample code shows a few different ways to query the "hotels" index defined in Create an Azure Search index using the .NET SDK. Si noti che i documenti restituiti con i risultati della ricerca sono istanze della classe Hotel , che è stata definita in Importazione di dati in Ricerca di Azure tramite .NET SDK.Note that the documents returned with the search results are instances of the Hotel class, which was defined in Data Import in Azure Search using the .NET SDK. Il codice di esempio usa un metodo WriteDocuments per restituire i risultati di ricerca nella console.The sample code makes use of a WriteDocuments method to output the search results to the console. Questo metodo è descritto nella sezione successiva.This method is described in the next section.

SearchParameters parameters;
DocumentSearchResult<Hotel> results;

Console.WriteLine("Search the entire index for the term 'budget' and return only the hotelName field:\n");

parameters =
    new SearchParameters()
    {
        Select = new[] { "hotelName" }
    };

results = indexClient.Documents.Search<Hotel>("budget", parameters);

WriteDocuments(results);

Console.Write("Apply a filter to the index to find hotels cheaper than $150 per night, ");
Console.WriteLine("and return the hotelId and description:\n");

parameters =
    new SearchParameters()
    {
        Filter = "baseRate lt 150",
        Select = new[] { "hotelId", "description" }
    };

results = indexClient.Documents.Search<Hotel>("*", parameters);

WriteDocuments(results);

Console.Write("Search the entire index, order by a specific field (lastRenovationDate) ");
Console.Write("in descending order, take the top two results, and show only hotelName and ");
Console.WriteLine("lastRenovationDate:\n");

parameters =
    new SearchParameters()
    {
        OrderBy = new[] { "lastRenovationDate desc" },
        Select = new[] { "hotelName", "lastRenovationDate" },
        Top = 2
    };

results = indexClient.Documents.Search<Hotel>("*", parameters);

WriteDocuments(results);

Console.WriteLine("Search the entire index for the term 'motel':\n");

parameters = new SearchParameters();
results = indexClient.Documents.Search<Hotel>("motel", parameters);

WriteDocuments(results);

Gestire i risultati della ricercaHandle search results

Il metodo Documents.Search restituisce un oggetto DocumentSearchResult che contiene i risultati della query.The Documents.Search method returns a DocumentSearchResult object that contains the results of the query. Nell'esempio nella sezione precedente viene usato un metodo denominato WriteDocuments per restituire i risultati di ricerca nella console:The example in the previous section used a method called WriteDocuments to output the search results to the console:

private static void WriteDocuments(DocumentSearchResult<Hotel> searchResults)
{
    foreach (SearchResult<Hotel> result in searchResults.Results)
    {
        Console.WriteLine(result.Document);
    }

    Console.WriteLine();
}

Ecco i risultati per le query nella sezione precedente, supponendo che l'indice "hotels" sia popolato con i dati di esempio in Importazione di dati in Ricerca di Azure tramite .NET SDK:Here is what the results look like for the queries in the previous section, assuming the "hotels" index is populated with the sample data in Data Import in Azure Search using the .NET SDK:

Search the entire index for the term 'budget' and return only the hotelName field:

Name: Roach Motel

Apply a filter to the index to find hotels cheaper than $150 per night, and return the hotelId and description:

ID: 2   Description: Cheapest hotel in town
ID: 3   Description: Close to town hall and the river

Search the entire index, order by a specific field (lastRenovationDate) in descending order, take the top two results, and show only hotelName and lastRenovationDate:

Name: Fancy Stay        Last renovated on: 6/27/2010 12:00:00 AM +00:00
Name: Roach Motel       Last renovated on: 4/28/1982 12:00:00 AM +00:00

Search the entire index for the term 'motel':

ID: 2   Base rate: 79.99        Description: Cheapest hotel in town     Description (French): Hôtel le moins cher en ville      Name: Roach Motel       Category: Budget        Tags: [motel, budget]   Parking included: yes   Smoking allowed: yes    Last renovated on: 4/28/1982 12:00:00 AM +00:00 Rating: 1/5     Location: Latitude 49.678581, longitude -122.131577

Il codice di esempio precedente usa la console per restituire i risultati della ricerca.The sample code above uses the console to output search results. Analogamente, sarà necessario visualizzare i risultati della ricerca nella propria applicazione.You will likewise need to display search results in your own application. Per un esempio di rendering dei risultati di ricerca in un'applicazione Web basata su ASP.NET MVC, vedere questo esempio su GitHub .See this sample on GitHub for an example of how to render search results in an ASP.NET MVC-based web application.