bibliothèque de client Recherche cognitive Azure pour .NET - version 11.4.0

  • Article

La Recherche cognitive Azure est une solution cloud de recherche en tant que service qui offre aux développeurs des API et des outils permettant d’ajouter une expérience de recherche enrichie sur du contenu privé et hétérogène dans des applications web, mobiles et d’entreprise.

Le service Recherche cognitive Azure convient parfaitement aux scénarios d’application suivants :

  • Regroupez les types de contenu variés dans un seul index pouvant faire l’objet d’une recherche. Pour remplir un index, vous pouvez envoyer (push) des documents JSON qui contiennent votre contenu ou, si vos données sont déjà dans Azure, créer un indexeur pour extraire automatiquement les données.
  • Joignez des ensembles de compétences à un indexeur pour créer du contenu pouvant faire l’objet d’une recherche à partir d’images et de documents texte volumineux. Un ensemble de compétences tire parti de l’IA de Cognitive Services pour l’OCR intégrée, la reconnaissance d’entité, l’extraction d’expressions clés, la détection de langue, la traduction de texte et l’analyse des sentiments. Vous pouvez également ajouter des compétences personnalisées pour intégrer le traitement externe de votre contenu pendant l’ingestion des données.
  • Dans une application cliente de recherche, implémentez une logique de requête et des expériences utilisateur similaires aux moteurs de recherche web commerciaux.

Utilisez la bibliothèque cliente Azure.Search.Documents pour :

  • Envoyez des requêtes pour les formulaires de requête simples et avancés qui incluent la recherche approximative, la recherche par caractères génériques et les expressions régulières.
  • Implémentez des requêtes filtrées pour la navigation à facettes, la recherche géospatiale ou pour affiner les résultats en fonction de critères de filtre.
  • Créer et gérer des index de recherche.
  • Charger et mettre à jour des documents dans l’index de recherche.
  • Créez et gérez des indexeurs qui extrayent des données d’Azure dans un index.
  • Créez et gérez des ensembles de compétences qui ajoutent l’enrichissement par IA à l’ingestion des données.
  • Créez et gérez des analyseurs pour l’analyse de texte avancée ou le contenu multilingue.
  • Optimisez les résultats via des profils de scoring pour prendre en compte la logique métier ou l’actualisation.

| Code sourcePackage (NuGet) | Documentation de référence sur les | API Documentation | sur l’API REST | Documentation produitÉchantillons

Prise en main

Installer le package

Installez la bibliothèque de client Recherche cognitive Azure pour .NET avec NuGet :

dotnet add package Azure.Search.Documents

Prérequis

Vous avez besoin d’un abonnement Azure et d’un service de recherche pour utiliser ce package.

Pour créer un service de recherche, vous pouvez utiliser le Portail Azure, Azure PowerShell ou Azure CLI. Voici un exemple d’utilisation d’Azure CLI pour créer un instance gratuit pour la prise en main :

az search service create --name <mysearch> --resource-group <mysearch-rg> --sku free --location westus

Pour plus d’informations sur les options disponibles, consultez Choix d’un niveau tarifaire .

Authentifier le client

Toutes les demandes adressées à votre service de recherche ont besoin d’une clé API générée spécialement pour votre service. La clé API est le seul mécanisme d’authentification de l’accès à votre point de terminaison de service de recherche. Vous pouvez obtenir votre clé API à partir du Portail Azure ou via Azure CLI :

az search admin-key show --service-name <mysearch> --resource-group <mysearch-rg>

Deux types de clés sont utilisés pour accéder à votre service de recherche : les clés d’administration(lecture-écriture) et les clés de requête(lecture seule). Il est essentiel de restreindre l'accès et les opérations dans les applications clientes afin de protéger les ressources de recherche de votre service. Utilisez toujours une clé de requête plutôt qu'une clé d'administration pour toutes les requêtes provenant d'une application cliente.

Remarque : l’exemple d’extrait de code Azure CLI ci-dessus récupère une clé d’administration afin de faciliter l’exploration des API, mais elle doit être gérée avec soin.

Nous pouvons utiliser la clé API pour créer un nouveau SearchClient.

string indexName = "nycjobs";

// Get the service endpoint and API key from the environment
Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
string key = Environment.GetEnvironmentVariable("SEARCH_API_KEY");

// Create a client
AzureKeyCredential credential = new AzureKeyCredential(key);
SearchClient client = new SearchClient(endpoint, indexName, credential);

ASP.NET Core

Pour injecter SearchClient en tant que dépendance dans une application ASP.NET Core, installez d’abord le package Microsoft.Extensions.Azure. Inscrivez ensuite le client dans la Startup.ConfigureServices méthode :

public void ConfigureServices(IServiceCollection services)
{
    services.AddAzureClients(builder =>
    {
        builder.AddSearchClient(Configuration.GetSection("SearchClient"));
    });
  
    services.AddControllers();
}

Pour utiliser le code précédent, ajoutez ceci à votre configuration :

{
    "SearchClient": {
      "endpoint": "https://<resource-name>.search.windows.net",
      "indexname": "nycjobs"
    }
}

Vous devez également fournir votre clé de ressource pour authentifier le client, mais vous ne devez pas placer ces informations dans la configuration. Au lieu de cela, lors du développement, utilisez User-Secrets. Ajoutez la ligne suivante à secrets.json :

{
    "SearchClient": {
      "credential": { "key": "<you resource key>" }
    }
}

Lors de l’exécution en production, il est préférable d’utiliser des variables d’environnement :

SEARCH__CREDENTIAL__KEY="..."

Vous pouvez également utiliser d’autres moyens sécurisés de stockage des secrets, comme Azure Key Vault.

Pour plus d’informations sur l’injection de dépendances dans ASP.NET Core applications, consultez Injection de dépendances avec le Kit de développement logiciel (SDK) Azure pour .NET.

Concepts clés

Un service Recherche cognitive Azure contient un ou plusieurs index qui fournissent un stockage persistant des données pouvant faire l’objet d’une recherche sous forme de documents JSON. (Si vous débutez dans la recherche, vous pouvez faire une analogie très approximative entre les index et les tables de base de données.) La bibliothèque cliente Azure.Search.Documents expose des opérations sur ces ressources via trois types de clients main.

La Azure.Search.Documents bibliothèque cliente (v11) est une toute nouvelle offre pour les développeurs .NET qui souhaitent utiliser la technologie de recherche dans leurs applications. Il existe une bibliothèque cliente Microsoft.Azure.Search plus ancienne et complète (v10) avec de nombreuses API similaires. Veillez donc à éviter toute confusion lors de l’exploration des ressources en ligne. Une bonne règle générale consiste à case activée pour l’espace de noms using Azure.Search.Documents; lorsque vous nous recherchez.

Sécurité des threads

Nous garantissons que toutes les méthodes de instance client sont thread-safe et indépendantes les unes des autres (instructions). Cela garantit que la recommandation de réutilisation des instances clientes est toujours sécurisée, même entre les threads.

Concepts supplémentaires

Options | du client Accès à la réponse | Opérations | de longue duréeGestion des défaillances | Diagnostics | Moqueur | Durée de vie du client

Exemples

Les exemples suivants utilisent tous un jeu de données Hotel simple que vous pouvez importer dans votre propre index à partir du Portail Azure. Ce ne sont que quelques-unes des bases - s’il vous plaît case activée nos exemples pour bien plus.

Authentification avancée

Interrogation

Commençons par importer nos espaces de noms.

using Azure;
using Azure.Search.Documents;
using Azure.Search.Documents.Indexes;

Nous allons ensuite créer un SearchClient pour accéder à notre index de recherche d’hôtels.

// Get the service endpoint and API key from the environment
Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
string key = Environment.GetEnvironmentVariable("SEARCH_API_KEY");
string indexName = "hotels";

// Create a client
AzureKeyCredential credential = new AzureKeyCredential(key);
SearchClient client = new SearchClient(endpoint, indexName, credential);

Il existe deux façons d’interagir avec les données retournées par une requête de recherche. Explorons-les à la recherche d’un hôtel de « luxe ».

Utiliser des types C# pour les résultats de la recherche

Nous pouvons décorer nos propres types C# avec les attributs de System.Text.Json:

public class Hotel
{
    [JsonPropertyName("HotelId")]
    [SimpleField(IsKey = true, IsFilterable = true, IsSortable = true)]
    public string Id { get; set; }

    [JsonPropertyName("HotelName")]
    [SearchableField(IsFilterable = true, IsSortable = true)]
    public string Name { get; set; }
}

Ensuite, nous les utilisons comme paramètre de type lors de l’interrogation pour retourner des résultats de recherche fortement typés :

SearchResults<Hotel> response = client.Search<Hotel>("luxury");
foreach (SearchResult<Hotel> result in response.GetResults())
{
    Hotel doc = result.Document;
    Console.WriteLine($"{doc.Id}: {doc.Name}");
}

Si vous utilisez un index de recherche et que vous connaissez le schéma, il est recommandé de créer des types C#.

Utiliser SearchDocument comme un dictionnaire pour les résultats de la recherche

Si vous n’avez pas votre propre type pour les résultats de recherche, SearchDocument peut être utilisé à la place. Ici, nous effectuons la recherche, énumérons les résultats et extrayons les données à l’aide SearchDocumentde l’indexeur de dictionnaire.

SearchResults<SearchDocument> response = client.Search<SearchDocument>("luxury");
foreach (SearchResult<SearchDocument> result in response.GetResults())
{
    SearchDocument doc = result.Document;
    string id = (string)doc["HotelId"];
    string name = (string)doc["HotelName"];
    Console.WriteLine("{id}: {name}");
}

SearchOptions

fournissent SearchOptions un contrôle puissant sur le comportement de nos requêtes. Nous allons rechercher les 5 meilleurs hôtels de luxe avec une bonne note.

int stars = 4;
SearchOptions options = new SearchOptions
{
    // Filter to only Rating greater than or equal our preference
    Filter = SearchFilter.Create($"Rating ge {stars}"),
    Size = 5, // Take only 5 results
    OrderBy = { "Rating desc" } // Sort by Rating from high to low
};
SearchResults<Hotel> response = client.Search<Hotel>("luxury", options);
// ...

Création d'un index

Vous pouvez utiliser pour SearchIndexClient créer un index de recherche. Les champs peuvent être définis à partir d’une classe de modèle à l’aide de FieldBuilder. Les index peuvent également définir des suggesteurs, des analyseurs lexicales et bien plus encore :

Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
string key = Environment.GetEnvironmentVariable("SEARCH_API_KEY");

// Create a service client
AzureKeyCredential credential = new AzureKeyCredential(key);
SearchIndexClient client = new SearchIndexClient(endpoint, credential);

// Create the index using FieldBuilder.
SearchIndex index = new SearchIndex("hotels")
{
    Fields = new FieldBuilder().Build(typeof(Hotel)),
    Suggesters =
    {
        // Suggest query terms from the hotelName field.
        new SearchSuggester("sg", "hotelName")
    }
};

client.CreateIndex(index);

Dans les scénarios où le modèle n’est pas connu ou ne peut pas être modifié, vous pouvez également créer des champs explicitement à l’aide SimpleFielddes classes pratiques , SearchableFieldou ComplexField :

// Create the index using field definitions.
SearchIndex index = new SearchIndex("hotels")
{
    Fields =
    {
        new SimpleField("hotelId", SearchFieldDataType.String) { IsKey = true, IsFilterable = true, IsSortable = true },
        new SearchableField("hotelName") { IsFilterable = true, IsSortable = true },
        new SearchableField("description") { AnalyzerName = LexicalAnalyzerName.EnLucene },
        new SearchableField("tags", collection: true) { IsFilterable = true, IsFacetable = true },
        new ComplexField("address")
        {
            Fields =
            {
                new SearchableField("streetAddress"),
                new SearchableField("city") { IsFilterable = true, IsSortable = true, IsFacetable = true },
                new SearchableField("stateProvince") { IsFilterable = true, IsSortable = true, IsFacetable = true },
                new SearchableField("country") { IsFilterable = true, IsSortable = true, IsFacetable = true },
                new SearchableField("postalCode") { IsFilterable = true, IsSortable = true, IsFacetable = true }
            }
        }
    },
    Suggesters =
    {
        // Suggest query terms from the hotelName field.
        new SearchSuggester("sg", "hotelName")
    }
};

client.CreateIndex(index);

Ajout de documents à votre index

Vous pouvez Upload, Merge, MergeOrUploadet Delete plusieurs documents à partir d’un index dans une seule requête par lot. Il existe quelques règles particulières à connaître pour la fusion .

IndexDocumentsBatch<Hotel> batch = IndexDocumentsBatch.Create(
    IndexDocumentsAction.Upload(new Hotel { Id = "783", Name = "Upload Inn" }),
    IndexDocumentsAction.Merge(new Hotel { Id = "12", Name = "Renovated Ranch" }));

IndexDocumentsOptions options = new IndexDocumentsOptions { ThrowOnAnyError = true };
client.IndexDocuments(batch, options);

La demande réussit même si l’une des actions individuelles échoue et retourne un IndexDocumentsResult pour inspection. Il existe également une ThrowOnAnyError option si vous vous souciez uniquement de la réussite ou de l’échec de l’ensemble du lot.

Récupération d’un document spécifique à partir de votre index

En plus d’interroger des documents à l’aide de mots clés et de filtres facultatifs, vous pouvez récupérer un document spécifique à partir de votre index si vous connaissez déjà la clé. Vous pouvez obtenir la clé à partir d’une requête, par exemple, et vouloir afficher plus d’informations à son sujet ou naviguer vers ce document.

Hotel doc = client.GetDocument<Hotel>("1");
Console.WriteLine($"{doc.Id}: {doc.Name}");

API asynchrones

Jusqu’à présent, tous les exemples utilisent des API synchrones, mais nous fournissons également une prise en charge complète des API asynchrones. En règle générale, vous ajoutez simplement un Async suffixe au nom de la méthode et await à celui-ci.

SearchResults<Hotel> response = await client.SearchAsync<Hotel>("luxury");
await foreach (SearchResult<Hotel> result in response.GetResultsAsync())
{
    Hotel doc = result.Document;
    Console.WriteLine($"{doc.Id}: {doc.Name}");
}

S’authentifier dans un cloud national

Pour vous authentifier dans un cloud national, vous devez effectuer les ajouts suivants à votre configuration client :

  • Définir dans AuthorityHost les options d’informations d’identification ou via la variable d’environnement AZURE_AUTHORITY_HOST
  • Définir le Audience dans SearchClientOptions
// Create a SearchClient that will authenticate through AAD in the China national cloud
string indexName = "nycjobs";
Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
SearchClient client = new SearchClient(endpoint, indexName,
    new DefaultAzureCredential(
        new DefaultAzureCredentialOptions()
        {
            AuthorityHost = AzureAuthorityHosts.AzureChina
        }),
    new SearchClientOptions()
    {
        Audience = SearchAudience.AzureChina
    });

Dépannage

Toute opération Azure.Search.Documents qui échoue lève un avec des RequestFailedException codes utilesStatus. La plupart de ces erreurs peuvent être récupérées.

try
{
    return client.GetDocument<Hotel>("12345");
}
catch (RequestFailedException ex) when (ex.Status == 404)
{
    Console.WriteLine("We couldn't find the hotel you are looking for!");
    Console.WriteLine("Please try selecting another.");
    return null;
}

Vous pouvez également activer la journalisation de la console facilement si vous souhaitez approfondir les requêtes que vous formulez sur le service.

Consultez notre guide de résolution des problèmes pour plus d’informations sur la façon de diagnostiquer différents scénarios d’échec.

Étapes suivantes

Contribution

Consultez nos CONTRIBUTING.md de recherche pour plus d’informations sur la création, le test et la contribution à cette bibliothèque.

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, visitez cla.microsoft.com.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.

Impressions