Tutoriel : Indexer des données Azure SQL à l’aide du SDK .NET

Découvrez comment configurer un indexeur pour extraire des données pouvant faire l’objet d’une recherche à partir d’Azure SQL Database et l’envoyer à un index de recherche dans Recherche IA Azure.

Dans ce tutoriel, vous utilisez C# et le Kit de développement logiciel (SDK) Azure pour .NET pour :

Prérequis

• Un compte Azure avec un abonnement actif. Créez un compte gratuitement.
• Azure SQL Database à l’aide de l’authentification SQL Server.
• Recherche Azure AI. Créez un service ou recherchez un service existant dans votre abonnement actuel.
• Visual Studio.

Télécharger les fichiers

Le code source pour ce tutoriel se trouve dans le dossier DotNetHowToIndexer du dépôt GitHub Azure-Samples/search-dotnet-getting-started.

Créer des services

Ce tutoriel utilise Recherche Azure AI pour l’indexation et les requêtes et Azure SQL Database en tant que source de données externe. Si possible, créez les deux services dans la même région et le même groupe de ressources pour des raisons de proximité et de facilité de gestion. En pratique, Azure SQL Database peut se trouver dans n’importe quelle région.

Démarrer avec Azure SQL Database

Ce tutoriel fournit le fichier hotels.sql dans l’exemple de téléchargement pour remplir la base de données. Azure AI Search consomme des ensembles de lignes aplatis, comme ceux générés à partir d’une vue ou d’une requête. Le fichier SQL de l’exemple de solution crée et remplit une table unique.

Si vous disposez d’une ressource Azure SQL Database existante, vous pouvez ajouter la table des hôtels à celle-ci à partir de l’étape Ouvrir la requête .

1. Créez une instance Azure SQL Database. La configuration du serveur pour la base de données est importante :

   • Choisissez l’option d’authentification SQL Server qui vous invite à spécifier un nom d’utilisateur et un mot de passe. Vous en avez besoin pour la chaîne de connexion ADO.NET utilisée par l’indexeur.

   • Choisissez une connexion publique, ce qui facilite la réalisation de ce didacticiel. Public n’est pas recommandé pour la production et nous vous recommandons de supprimer cette ressource à la fin du didacticiel.

   

2. Dans le portail Azure, accédez à la nouvelle ressource.

3. Ajoutez une règle de pare-feu qui autorise l’accès à partir de votre client. Vous pouvez exécuter ipconfig à partir d’une invite de commandes pour obtenir votre adresse IP.

4. Utilisez l’Éditeur de requêtes pour charger les exemples de données. Dans le volet de navigation, sélectionnez l’éditeur de requête (préversion) et entrez le nom d’utilisateur et le mot de passe de l’administrateur du serveur.

   Si vous recevez une erreur d’accès refusé, copiez l’adresse IP du client à partir du message d’erreur, ouvrez la page de sécurité réseau du serveur et ajoutez une règle de trafic entrant qui autorise l’accès à partir de votre client.

5. Dans l’Éditeur de requête, sélectionnez Ouvrir la requête et accédez à l’emplacement du fichier hotels.sql sur votre ordinateur local.

6. Sélectionnez le fichier, puis le bouton Ouvrir. Le script doit ressembler à la capture d’écran suivante :

   

7. Sélectionnez Exécuter pour exécuter la requête. Dans le volet Résultats , vous devez voir un message de requête réussi pour trois lignes.

8. Pour renvoyer un ensemble de lignes de cette table, vous pouvez exécuter la requête suivante comme étape de vérification :

   SELECT * FROM Hotels
   

9. Copiez la chaîne de connexion ADO.NET pour la base de données. Sous Paramètres>, copiez la chaîne de connexion ADO.NET, qui doit être similaire à l’exemple suivant :

   Server=tcp:<YOUR-DATABASE-NAME>.database.windows.net,1433;Initial Catalog=hotels-db;Persist Security Info=False;User ID=<YOUR-USER-NAME>;Password=<YOUR-PASSWORD>;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;
   

Vous aurez besoin de cette chaîne de connexion pour configurer votre environnement à l’étape suivante.

Recherche Azure AI

Le composant suivant est la Recherche Azure AI, que vous pouvez créer dans le portail Azure. Vous pouvez utiliser le niveau Gratuit pour suivre ce tutoriel.

Obtenir une clé d’administration et une URL pour Recherche Azure AI

Les appels d’API nécessitent l’URL du service et une clé d’accès. Comme la création d’un service de recherche utilise les deux, si vous avez ajouté la Recherche Azure AI à votre abonnement, suivez ces étapes pour obtenir les informations nécessaires :

1. Connectez-vous au portail Azure. Dans la page Vue d’ensemble de votre service, copiez l’URL du point de terminaison. Voici un exemple de point de terminaison : https://mydemo.search.windows.net.

2. Sur Paramètres>Clés, obtenez une clé d’administration donnant des droits complets sur le service. Il existe deux clés d’administration interchangeables, fournies pour assurer la continuité de l’activité au cas où vous deviez en remplacer une. Vous pouvez utiliser une clé sur les requêtes pour ajouter, modifier ou supprimer des objets.

   

Configurer votre environnement

1. Démarrez Visual Studio et ouvrez le fichier DotNetHowToIndexers.sln.

2. Dans l’Explorateur de solutions, ouvrez appsettings.json pour fournir les informations de connexion.

3. Pour SearchServiceEndPoint, si l’URL complète de la page Vue d’ensemble de votre service est https://my-demo-service.search.windows.net, fournissez l’URL entière.

4. Pour AzureSqlConnectionString, le format de chaîne est similaire à "Server=tcp:<your-database-name>.database.windows.net,1433;Initial Catalog=hotels-db;Persist Security Info=False;User ID=<your-user-name>;Password=<your-password>;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;".

   {
     "SearchServiceEndPoint": "<placeholder-search-full-url>",
     "SearchServiceAdminApiKey": "<placeholder-admin-key-for-search-service>",
     "AzureSqlConnectionString": "<placeholder-ADO.NET-connection-string",
   }
   

5. Remplacez le mot de passe utilisateur dans la chaîne de connexion SQL par un mot de passe valide. Alors que la base de données et les noms d’utilisateur sont copiés, vous devez entrer le mot de passe manuellement.

Créer le pipeline

Les indexeurs nécessitent un objet de source de données et un index. Le code qui convient se trouve dans deux fichiers :

• hotel.cs contient un schéma qui définit l’index
• Program.cs contient des fonctions permettant de créer et de gérer des structures dans votre service

Dans Hotel.cs

Le schéma d’index définit la collection de champs, y compris les attributs spécifiant les opérations autorisées, telles qu’un champ pouvant faire l’objet d’une recherche en texte intégral, filtrable ou triable, comme indiqué dans la définition de champ suivante pour HotelName. Un SearchableField est, par définition, pouvant faire l’objet d’une recherche en texte intégral. D’autres attributs sont explicitement attribués.

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

Un schéma peut également inclure d’autres éléments, tels que des profils de scoring pour stimuler un score de recherche et des analyseurs personnalisés. Toutefois, pour ce didacticiel, le schéma est partiellement défini, composé uniquement de champs trouvés dans les exemples de jeux de données.

Dans Program.cs

Le programme principal inclut une logique pour la création d’un client d’indexeur, d’un index, d’une source de données et d’un indexeur. Le code recherche et supprime les ressources existantes du même nom, en supposant que vous pouvez exécuter ce programme plusieurs fois.

L’objet source de données est configuré avec des paramètres propres aux ressources Azure SQL Database, notamment l’indexation partielle ou incrémentielle, pour utiliser les fonctionnalités intégrées de détection des modifications d’Azure SQL. La base de données source des hôtels de démonstration dans Azure SQL a une colonne « suppression réversible » nommée IsDeleted. Quand cette colonne est définie sur true dans la base de données, l’indexeur supprime le document correspondant dans l’index de Recherche Azure AI.

Console.WriteLine("Creating data source...");

var dataSource =
      new SearchIndexerDataSourceConnection(
         "hotels-sql-ds",
         SearchIndexerDataSourceType.AzureSql,
         configuration["AzureSQLConnectionString"],
         new SearchIndexerDataContainer("hotels"));

indexerClient.CreateOrUpdateDataSourceConnection(dataSource);

Un objet indexeur est indépendant de la plateforme, où la configuration, la planification et l’appel sont identiques, quelle que soit la source. Cet exemple d’indexeur inclut une planification et une option de réinitialisation qui efface l’historique de l’indexeur. Il appelle également une méthode pour créer et exécuter immédiatement l’indexeur. Pour créer ou mettre à jour un indexeur, utilisez CreateOrUpdateIndexerAsync.

Console.WriteLine("Creating Azure SQL indexer...");

var schedule = new IndexingSchedule(TimeSpan.FromDays(1))
{
      StartTime = DateTimeOffset.Now
};

var parameters = new IndexingParameters()
{
      BatchSize = 100,
      MaxFailedItems = 0,
      MaxFailedItemsPerBatch = 0
};

// Indexer declarations require a data source and search index.
// Common optional properties include a schedule, parameters, and field mappings
// The field mappings below are redundant due to how the Hotel class is defined, but 
// we included them anyway to show the syntax 
var indexer = new SearchIndexer("hotels-sql-idxr", dataSource.Name, searchIndex.Name)
{
      Description = "Data indexer",
      Schedule = schedule,
      Parameters = parameters,
      FieldMappings =
      {
         new FieldMapping("_id") {TargetFieldName = "HotelId"},
         new FieldMapping("Amenities") {TargetFieldName = "Tags"}
      }
};

await indexerClient.CreateOrUpdateIndexerAsync(indexer);

Les exécutions de l’indexeur sont généralement planifiées, mais pendant le développement, vous pouvez exécuter immédiatement l’indexeur à l’aide de RunIndexerAsync.

Console.WriteLine("Running Azure SQL indexer...");

try
{
      await indexerClient.RunIndexerAsync(indexer.Name);
}
catch (RequestFailedException ex) when (ex.Status == 429)
{
      Console.WriteLine("Failed to run indexer: {0}", ex.Message);
}

Générez la solution.

Sélectionnez F5 pour générer et exécuter la solution. Le programme s’exécute en mode débogage. Une fenêtre de console signale l’état de chaque opération.

Votre code s’exécute localement dans Visual Studio en se connectant à votre service de recherche sur Azure qui, à son tour, se connecte à Azure SQL Database et récupère le jeu de données. Étant donné le grand nombre d’opérations, il existe plusieurs points de défaillance potentiels. Si une erreur survient, commencez par vérifier les conditions suivantes :

• Les informations de connexion au service de recherche que vous fournissez sont l’URL complète. Si vous avez entré uniquement le nom du service, les opérations s’arrêtent lors de la création de l’index, avec un échec de connexion.

• Informations de connexion à la base de données dans appsettings.json. Il doit s’agir de la chaîne de connexion ADO.NET obtenue à partir du portail Azure et modifiée pour inclure un nom d’utilisateur et un mot de passe valides pour votre base de données. Le compte d’utilisateur doit avoir l’autorisation de récupérer des données. L’accès entrant via le pare-feu doit être autorisé pour l’adresse IP de votre client local.

• Limites des ressources. N’oubliez pas que le niveau Gratuit est limité à trois index, indexeurs et sources de données. Un service ayant atteint la limite maximale ne peut pas créer de nouveaux objets.

Rechercher

Utilisez le portail Azure pour vérifier la création d’objets, puis utilisez l’Explorateur de recherche pour interroger l’index.

1. Connectez-vous au portail Azure et accédez à votre service de recherche. Dans le volet gauche, ouvrez chaque page pour vérifier que les objets sont créés. Les index, les indexeurs et les sources de données doivent avoir respectivement hotels-sql-idx, hotels-sql-indexer et hotels-sql-ds.

2. Sous l’onglet Index , sélectionnez l’index hotels-sql-idx . Dans la page hotels, le premier onglet est celui de l’Explorateur de recherche.

3. Sélectionnez Rechercher pour émettre une requête vide.

   Les trois entrées de votre index sont renvoyées en tant que documents JSON. L’explorateur de recherche renvoie des documents au format JSON afin que vous puissiez afficher l’ensemble de la structure.

   

4. Basculez vers la vue JSON pour pouvoir entrer des paramètres de requête.

   {
        "search": "river",
        "count": true
   }
   

   Cette requête appelle la recherche en texte intégral sur le terme river. Le résultat inclut le nombre de documents qui correspondent. Le renvoi du nombre de documents correspondants est utile dans les scénarios de test où vous avez un index volumineux avec des milliers ou des millions de documents. Dans ce cas, un seul document correspond à la requête.

5. Entrez des paramètres qui limitent les résultats de recherche aux champs d’intérêt.

   {
        "search": "river",
        "select": "hotelId, hotelName, baseRate, description",
        "count": true
   }
   

   La réponse à la requête se réduit aux champs sélectionnés, ce qui entraîne une sortie plus concise.

Réinitialiser et réexécuter

Dans les premières étapes expérimentales de développement, l’approche la plus pratique pour les itérations de conception consiste à supprimer les objets d’Azure AI Search et à autoriser votre code à les reconstruire. Les noms des ressources sont uniques. La suppression d’un objet vous permet de le recréer en utilisant le même nom.

L’exemple de code pour ce tutoriel recherche les objets existants et les supprime pour vous permettre de réexécuter votre code.

Vous pouvez également utiliser le Portail Azure pour supprimer les index, les indexeurs et les sources de données.

Nettoyer les ressources

Lorsque vous travaillez dans votre propre abonnement, il est judicieux à la fin d’un projet de supprimer les ressources dont vous n’avez plus besoin. Les ressources laissées actives peuvent vous coûter de l’argent. Vous pouvez supprimer les ressources individuellement, ou supprimer le groupe de ressources pour supprimer l’ensemble des ressources.

Vous pouvez rechercher et gérer des ressources dans le portail Azure, en utilisant le lien Toutes les ressources ou Groupes de ressources dans le volet de navigation de gauche.

Étapes suivantes

Maintenant que vous connaissez les principes de base de l’indexation SQL Database, examinez plus en plus la configuration de l’indexeur :