Partage via

Effectuer une mise à niveau vers la version 11 du SDK .NET Recherche Azure AI

  • Article

Si votre solution de recherche repose sur le kit de développement logiciel (SDK) Azure pour .NET, cet article vous aide à migrer votre code des versions antérieures de Microsoft.Azure.Search à la version 11, la nouvelle bibliothèque de client Azure.Search.Documents. La version 11 est une bibliothèque de client entièrement repensée, publiée par l’équipe de développement de kits de développement logiciel (SDK) d’Azure (les versions précédentes ont été produites par l’équipe de développement de Recherche Azure AI).

Toutes les fonctionnalités de la version 10 sont implémentées dans la version 11. Les principales différences sont les suivantes :

  • Un seul package (Azure.Search.Documents) au lieu de quatre
  • Trois clients au lieu de deux : SearchClient, SearchIndexClient, SearchIndexerClient
  • Des différences d’affectation de noms dans une plage d’API et de petites différences structurelles qui simplifient certaines tâches

Le journal des modifications de la bibliothèque de client comporte une liste détaillée des mises à jour. Vous pouvez consulter une version résumée dans cet article.

Tous les extraits et exemples de code C# de la documentation relative au produit Recherche Azure AI ont été révisés pour tenir compte de l’utilisation de la nouvelle bibliothèque de client Azure.Search.Documents.

Pourquoi procéder à une mise à niveau ?

Synthèse des avantages de la mise à niveau :

  • Les nouvelles fonctionnalités sont ajoutées à Azure.Search.Documents uniquement. La version précédente, Microsoft.Azure.Search, est désormais hors service. Les mises à jour des bibliothèques dépréciées se limitent uniquement aux résolutions des bogues de haute priorité.

  • Cohérence avec les autres bibliothèques de clients Azure. Azure.Search.Documents accepte une dépendance sur Azure.Core et System.Text.Json. Il suit les approches conventionnelles pour les tâches courantes, par exemple les autorisations et les connexions des clients.

Microsoft.Azure.Search est officiellement retiré. Si vous utilisez une ancienne version, nous vous recommandons d’effectuer une mise à niveau vers la version supérieure suivante, en répétant le processus en succession jusqu’à atteindre la version 11 et Azure.Search.Documents. Une stratégie de mise à niveau incrémentielle facilite la recherche et la résolution des problèmes de blocage. Consultez la documentation de version précédente pour obtenir des conseils.

Comparaison des packages

La version 11 regroupe et simplifie la gestion des packages pour en réduire le nombre à gérer.

Version 10 et versions antérieures Version 11
Microsoft.Azure.Search
Microsoft.Azure.Search.Service
Microsoft.Azure.Search.Data
Microsoft.Azure.Search.Common		 Package Azure.Search.Documents

Comparaison des clients

Le cas échéant, le tableau suivant mappe les bibliothèques de client entre les deux versions.

Opérations du client Microsoft.Azure.Search (v10) Azure.Search.Documents (v11)
Cible la collection de documents d’un index (requêtes et importation de données) SearchIndexClient SearchClient
Cible les objets liés aux index (index, analyseurs, mappages de synonymes) SearchServiceClient SearchIndexClient
Cible les objets liés aux indexeurs (indexeurs, sources de données, ensembles de compétences) SearchServiceClient SearchIndexerClient (nouveau)

Attention

Notez que SearchIndexClient existe dans les deux versions, mais qu’il cible des opérations distinctes. Dans la version 10, SearchIndexClient crée des index et d’autres objets. Dans la version 11, SearchIndexClient fonctionne avec les index existants, en ciblant la collection de documents à l’aide des API de requête et d’ingestion des données. Pour éviter toute confusion lors de la mise à jour du code, gardez à l’esprit l’ordre dans lequel les références de client sont mises à jour. Le fait de suivre l’ordre des étapes de mise à niveau devrait aider à atténuer les éventuels problèmes de remplacement de chaînes.

Affectation de noms et autres différences d’API

Outre les différences de clients (notées précédemment et donc omises ici), plusieurs autres API ont été renommées et, dans certains cas, redéfinies. Les différences de nom de classe sont résumées dans les sections suivants. Cette liste n'est pas exhaustive mais elle regroupe les changements d'API par tâche, ce qui peut être utile pour les révisions sur des blocs de code spécifiques. Pour obtenir la liste détaillée des mises à jour des API, consultez le journal des modifications pour Azure.Search.Documents sur GitHub.

Authentification et chiffrement

Version 10 Équivalent dans la version 11
SearchCredentials AzureKeyCredential
EncryptionKey (non documenté dans la référence API. La prise en charge de cette API est passée en disponibilité générale dans la version 10, mais elle n’était disponible que dans la préversion du kit SDK) SearchResourceEncryptionKey

Index, analyseurs et mappages de synonymes

Version 10 Équivalent dans la version 11
Index SearchIndex
Champ SearchField
DataType SearchFieldDataType
ItemError SearchIndexerError
Analyseur LexicalAnalyzer (ainsi que AnalyzerName vers LexicalAnalyzerName)
AnalyzeRequest AnalyzeTextOptions
StandardAnalyzer LuceneStandardAnalyzer
StandardTokenizer LuceneStandardTokenizer (ainsi que StandardTokenizerV2 vers LuceneStandardTokenizerV2)
TokenInfo AnalyzedTokenInfo
Générateur de jetons LexicalTokenizer (ainsi que TokenizerName vers LexicalTokenizerName)
SynonymMap.Format Aucune. Supprimez les références à Format.

Les définitions de champ sont rationalisées : SearchableField, SimpleField et ComplexField sont de nouvelles API permettant de créer des définitions de champ.

Indexeurs, sources de données et ensembles de compétences

Version 10 Équivalent dans la version 11
Indexeur SearchIndexer
Source de données SearchIndexerDataSourceConnection
Compétence SearchIndexerSkill
Ensemble de compétences SearchIndexerSkillset
DataSourceType SearchIndexerDataSourceType

Importation des données

Version 10 Équivalent dans la version 11
IndexAction IndexDocumentsAction
IndexBatch IndexDocumentsBatch
IndexBatchException.FindFailedActionsToRetry() SearchIndexingBufferedSender

Requêtes et réponses

Version 10 Équivalent dans la version 11
DocumentsOperationsExtensions.SearchAsync SearchClient.SearchAsync
DocumentSearchResult SearchResult ou SearchResults, selon que le résultat est un document unique ou plusieurs documents.
DocumentSuggestResult SuggestResults
SearchParameters SearchOptions
SuggestParameters SuggestOptions
SearchParameters.Filter SearchFilter (nouvelle classe pour la construction d’expressions de filtre OData)

Sérialisation JSON

Par défaut, le Kit de développement logiciel (SDK) Azure utilise System.Text.Json pour la sérialisation JSON, en se basant sur les capacités de ces API pour gérer les transformations de texte précédemment implémentées par le biais d’une classe SerializePropertyNamesAsCamelCaseAttribute native, qui n’a pas d’équivalent dans la nouvelle bibliothèque.

Pour sérialiser les noms de propriété en camelCase, vous pouvez utiliser l’attribut JsonPropertyNameAttribute (semblable à cet exemple).

Vous pouvez également définir une stratégie JsonNamingPolicy fournie dans JsonSerializerOptions. L’exemple de code System.Text.Json suivant, extrait du fichier Lisez-moi Microsoft.Azure.Core.Spatial, montre l’utilisation de camelCase sans avoir à attribuer une valeur à chaque propriété :

// Get the Azure AI Search service endpoint and read-only API key.
Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
AzureKeyCredential credential = new AzureKeyCredential(Environment.GetEnvironmentVariable("SEARCH_API_KEY"));

// Create serializer options with our converter to deserialize geographic points.
JsonSerializerOptions serializerOptions = new JsonSerializerOptions
{
    Converters =
    {
        new MicrosoftSpatialGeoJsonConverter()
    },
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase
};

SearchClientOptions clientOptions = new SearchClientOptions
{
    Serializer = new JsonObjectSerializer(serializerOptions)
};

SearchClient client = new SearchClient(endpoint, "mountains", credential, clientOptions);
Response<SearchResults<Mountain>> results = client.Search<Mountain>("Rainier");

Si vous utilisez Newtonsoft.Json pour la sérialisation JSON, vous pouvez intégrer des stratégies de dénomination globale à l'aide d'attributs similaires, ou en utilisant les propriétés de JsonSerializerSettings. Pour obtenir un exemple équivalent au précédent, consultez l’exemple de désérialisation des documents dans le fichier Lisez-moi de Newtonsoft.Json.

Dans la version 11

Chaque version d’une bibliothèque de client Recherche Azure AI cible une version correspondante de l’API REST. L’API REST est considérée comme fondamentale pour le service, avec des Kits de développement logiciel (SDK) individuels encapsulant une version de l’API REST. En tant que développeur .NET, il peut être utile de passer en revue la documentation de l’API REST, qui est plus détaillée, pour obtenir une couverture plus précise d’objets ou d’opérations spécifiques. La version 11 cible la spécification du service de recherche 2020-06-30.

La version 11.0 prend entièrement en charge les opérations et objets suivants :

  • Création et gestion d’index
  • Création et gestion de mappage de synonymes
  • Création et gestion d’indexeurs
  • Création et gestion de sources de données d’indexeur
  • Création et gestion d’ensembles de compétences
  • Tous les types de requête et toutes les syntaxes

Ajouts à la version 11.1 (détails du journal des modifications) :

Ajouts à la version 11.2 (détails du journal des modifications) :

Ajouts à la version 11.3 (détails du journal des modifications) :

Avant la mise à niveau

  • Les guides de démarrage rapide, les tutoriels et les exemples C# ont été mis à jour pour tenir compte de l’utilisation du package Azure.Search.Documents. Nous vous recommandons de passer en revue les exemples et procédures pas à pas pour en savoir plus sur les nouvelles API avant de vous lancer dans un exercice de migration.

  • Le Guide pratique pour utiliser Azure.Search.Documents présente les API les plus couramment utilisées. Même les utilisateurs avertis du service Recherche Azure AI peuvent être amenés à consulter cette introduction à la nouvelle bibliothèque en prévision de la migration.

Procédure de mise à niveau

Les étapes suivantes vous permettent de commencer une migration de code en parcourant la première série de tâches requises, notamment en ce qui concerne les références de client.

  1. Installez le package Azure.Search.Documents en cliquant avec le bouton droit sur les références de votre projet et en sélectionnant « Gérer les packages NuGet… » dans Visual Studio.

  2. Remplacez les directives d’utilisation pour Microsoft.Azure.Search par ce qui suit à l’aide des instructions :

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

  3. Pour les classes qui requièrent la sérialisation JSON, remplacez using Newtonsoft.Json par using System.Text.Json.Serialization.

  4. Révisez le code d’authentification du client. Dans les versions précédentes, vous deviez utiliser les propriétés sur l’objet client pour définir la clé API (par exemple, la propriété SearchServiceClient.Credentials). Dans la version actuelle, utilisez la classe AzureKeyCredential pour transmettre la clé en tant qu’informations d’identification. Ainsi, si nécessaire, vous pouvez mettre à jour la clé API, sans créer de nouveaux objets clients.

    Les propriétés du client ont été rationalisées pour Endpoint, ServiceNameet IndexName (le cas échéant). L’exemple suivant utilise la classe URI du système pour fournir le point de terminaison et la classe Environnement pour lire la valeur de clé :

    Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
AzureKeyCredential credential = new AzureKeyCredential(
   Environment.GetEnvironmentVariable("SEARCH_API_KEY"));
SearchIndexClient indexClient = new SearchIndexClient(endpoint, credential);

  5. Ajoutez de nouvelles références de client pour les objets liés à l’indexeur. Si vous utilisez des indexeurs, des sources de données ou des ensembles de compétences, changez les références client en SearchIndexerClient. Ce client est nouveau dans la version 11 et n’a pas d’antécédent.

  6. Révisez les collections et les listes. Dans le nouveau Kit de développement logiciel (SDK), toutes les listes sont en lecture seule afin d’éviter les problèmes en aval si la liste contient des valeurs NULL. La modification du code consiste à ajouter des éléments à une liste. Par exemple, au lieu d’assigner des chaînes à une propriété Select, vous devez les ajouter comme suit :

    var options = new SearchOptions
 {
    SearchMode = SearchMode.All,
    IncludeTotalCount = true
 };

 // Select fields to return in results.
 options.Select.Add("HotelName");
 options.Select.Add("Description");
 options.Select.Add("Tags");
 options.Select.Add("Rooms");
 options.Select.Add("Rating");
 options.Select.Add("LastRenovationDate");

    Select, Facets, SearchFields, SourceFields, ScoringParameters et OrderBy sont toutes des listes qui doivent maintenant être reconstruites.

  7. Mettez à jour les références de client pour les requêtes et l’importation de données. Les instances de SearchIndexClient doivent être remplacées par SearchClient. Pour éviter toute confusion dans les noms, veillez à intercepter toutes les instances avant de passer à l’étape suivante.

  8. Mettez à jour les références de client pour les objets index, mappage de synonymes et analyseur. Les instances de SearchServiceClient doivent être remplacées par SearchIndexClient.

  9. Pour le reste de votre code, mettez à jour les classes, les méthodes et les propriétés pour utiliser les API de la nouvelle bibliothèque. La section relative aux différences d’affectation de noms est un point de départ, mais vous pouvez également consulter le journal des modifications.

    Si vous avez des difficultés à trouver des API équivalentes, nous vous suggérons de signaler le problème sur https://github.com/MicrosoftDocs/azure-docs/issues afin que nous puissions améliorer la documentation ou examiner le problème.

  10. Recréez la solution. Après avoir corrigé les erreurs de build ou les avertissements, vous pouvez apporter des modifications supplémentaires à votre application pour bénéficier des nouvelles fonctionnalités.

Dernières modifications

Compte tenu des modifications radicales apportées aux bibliothèques et aux API, une mise à niveau vers la version 11 n’est pas anodine et constitue un changement cassant dans la mesure où votre code ne sera plus rétrocompatible avec la version 10 et les versions antérieures. Pour une analyse approfondie des différences, consultez le journal des modifications pour Azure.Search.Documents.

En termes de mises à jour de version de service, lorsque les modifications de code de la version 11 sont liées à la fonctionnalité existante (et pas simplement à la refactorisation des API), vous noterez les modifications de comportement suivantes :

  • L’algorithme de classement BM25 remplace l’algorithme de classement précédent par une technologie plus récente. Les nouveaux services utilisent cet algorithme automatiquement. Pour les services existants, vous devez définir des paramètres pour utiliser le nouvel algorithme.

  • Les résultats ordonnés pour les valeurs Null ont été modifiés dans cette version ; les valeurs Null apparaissent en premier si le tri est asc et en dernier si le tri est desc. Si vous avez écrit du code pour gérer la manière dont les valeurs Null sont triées, vous devez revoir et éventuellement supprimer ce code s’il n’est plus nécessaire.

En raison de ces changements de comportement, il est probable qu’il existe de légères variations dans les résultats classés.

Étapes suivantes