Informations de référence sur l’API REST Azure AI Recherche

  • Article

Azure AI Recherche (anciennement appelé Recherche cognitive Azure) est un service de recherche cloud entièrement managé qui fournit une récupération d’informations sur du contenu appartenant à l’utilisateur.

Les API REST de plan de données sont utilisées pour les workflows d’indexation et de requête, et elles sont documentées dans cette section.

Les opérations de plan de contrôle sont accessibles via une API REST de gestion distincte.

Documentation sur l’API versionnée

Les documents sur l’API REST sont désormais versionnés. Lorsque vous ouvrez une page de référence d’API, un sélecteur de version s’affiche au-dessus de la table des matières. Vérifiez que la référence d’API provient du dossier Plan de données de référence>.

Capture d’écran du sélecteur de version.

Concepts clés

Azure AI Recherche présente les concepts des services de recherche, des index, desdocuments, des indexeurs, des sources de données, des ensembles de compétences et des mappages de synonymes.

  • Un service de recherche héberge des index, des indexeurs, des sources de données, des ensembles de compétences et des mappages de synonymes en tant qu’objets de niveau supérieur.
  • Un index de recherche fournit un stockage persistant des documents de recherche. Recherche documents sont vos données, articulées sous la forme d’une collection de champs, chargées à partir de sources externes et envoyées à un index pour les rendre accessibles aux recherches.
  • Un indexeur de recherche ajoute l’automatisation, la lecture des données dans des formats natifs et leur sérialisation dans JSON.
  • Un indexeur a une source de données et pointe vers un index.
  • Un indexeur peut également avoir un ensemble de compétences qui ajoute l’enrichissement par IA et la vectorisation intégrée au pipeline d’indexation. Les ensembles de compétences sont toujours attachés à un indexeur. Ils appellent le Machine Learning pour extraire ou segmenter du texte, vectoriser du contenu, déduire des fonctionnalités ou ajouter une structure au contenu afin qu’il puisse être indexé par un service de recherche.

Dans l’ensemble, vous pouvez créer les objets suivants sur un service de recherche :

Objets Description
Sources de données Connexion de source de données utilisée par un indexeur pour récupérer et actualiser des documents à des fins d’indexation. Les sources de données ont un type. Vous pouvez utiliser les connexions fournies par Microsoft pour Azure ou des connecteurs tiers via des partenaires. Pour obtenir la liste complète, consultez Galerie de sources de données.
Documents Conceptuellement, un document est une entité dans votre index. Mappage de ce concept à des équivalents de base de données plus familiers : un index de recherche équivaut à une table et les documents sont à peu près équivalents aux lignes d’une table. Les documents existent uniquement dans un index et sont récupérés uniquement par le biais de requêtes qui ciblent la collection de documents (/docs) d’un index. Toutes les opérations effectuées sur la collection, telles que le chargement, la fusion, la suppression ou l’interrogation de documents, ont lieu dans le contexte d’un index unique, de sorte que les opérations de document au format URL incluent /indexes/[index name]/docs toujours pour un nom d’index donné.
Index Un index est stocké sur votre service de recherche et rempli avec des documents JSON indexés et tokenisés pour la récupération des informations. La collection fields d’un index définit la structure du document de recherche. Les champs ont un nom, des types de données et des attributs qui déterminent comment ils sont utilisés. Par exemple, searchable les champs sont utilisés dans la recherche en texte intégral et sont donc tokenisés pendant l’indexation. Un index définit également d’autres constructions, telles que les profils de scoring pour le réglage de la pertinence, les suggesteurs, les configurations sémantiques et les analyseurs personnalisés.
Indexeurs Les indexeurs fournissent une automatisation de l’indexation. Un indexeur se connecte à une source de données, lit les données et les transmet à un moteur de recherche pour l’indexation dans un index de recherche cible. Les indexeurs lisent à partir d’une source externe à l’aide des informations de connexion dans une source de données et sérialisent les données entrantes dans des documents de recherche JSON. En plus d’une source de données, un indexeur nécessite également un index. L’index spécifie les champs et les attributs des documents de recherche.
Ensemble de compétences Un ensemble de compétences ajoute des étapes de traitement externe à l’exécution de l’indexeur et est généralement utilisé pour ajouter des modèles IA ou Deep Learning pour analyser ou transformer du contenu afin de le rendre accessible à la recherche dans un index. Le contenu d’un ensemble de compétences est une ou plusieurs compétences, qui peuvent être des compétences intégrées créées par Microsoft, des compétences personnalisées ou une combinaison des deux. Il existe des compétences intégrées pour l’analyse d’images, y compris l’OCR et le traitement en langage naturel. D’autres exemples de compétences intégrées incluent la reconnaissance d’entités, l’extraction de phrases clés, la segmentation de texte en pages logiques, entre autres. Un ensemble de compétences est un objet autonome de haut niveau qui existe à un niveau équivalent aux index, indexeurs et sources de données, mais il est opérationnel uniquement dans le traitement de l’indexeur. En tant qu’objet de haut niveau, vous pouvez concevoir un ensemble de compétences une seule fois, puis le référencer dans plusieurs indexeurs.
Mappages de synonymes Une carte de synonymes est un objet de niveau de service qui contient des synonymes définis par l’utilisateur. Cet objet est conservé indépendamment des index de recherche. Une fois chargé, vous pouvez pointer n’importe quel champ pouvant faire l’objet d’une recherche vers la carte de synonymes (un par champ).

Autorisations et contrôle d’accès

Vous pouvez utiliser l’authentification basée sur les clés ou basée sur les rôles via Microsoft Entra ID.

  • L’authentification par clé s’appuie sur des clés API générées pour le service de recherche. L’utilisation d’une clé valide permet d’établir, en fonction de chaque demande, une relation de confiance entre l’application qui envoie la demande et le service qui en assure le traitement. Vous pouvez utiliser une clé API Administration pour les opérations de lecture-écriture ou une clé API de requête pour l’accès en lecture à la collection de documents d’un index de recherche.

  • Microsoft Entra ID l’authentification et le contrôle d’accès en fonction du rôle nécessitent que vous disposiez d’un locataire établi dans Microsoft Entra ID, avec des principaux de sécurité et des attributions de rôles. Les membres des rôles suivants ont un accès au plan de données. Vous pouvez créer des rôles personnalisés si les rôles intégrés sont insuffisants.

    Rôle Access
    Contributeur du service de recherche Accès aux objets, mais aucun accès au contenu d’index. Ce rôle ne peut pas interroger un index de recherche ni ajouter, supprimer ou mettre à jour des documents dans un index de recherche. Ce rôle est destiné aux administrateurs qui ont besoin de gérer des objets, mais sans la possibilité d’afficher ou d’accéder aux données d’objet.
    Contributeur d’index de données Recherche Accès en lecture-écriture au contenu d’index. Ce rôle est destiné aux développeurs ou aux propriétaires d’index qui ont besoin d’importer, d’actualiser ou d’interroger la collection de documents d’un index.
    Lecteur d’index de données Recherche Accès en lecture au contenu de l’index. Ce rôle est destiné aux applications et utilisateurs qui exécutent des requêtes.

Lorsque vous utilisez des rôles sur la connexion, votre application cliente présente un jeton de porteur dans l’en-tête d’autorisation. Pour obtenir de l’aide sur la configuration, consultez Autoriser l’accès à une application de recherche à l’aide de Microsoft Entra ID.

Vous pouvez désactiver l’authentification basée sur les clés ou l’authentification basée sur les rôles. Si vous désactivez l’authentification basée sur les rôles, certains rôles intégrés auront toujours accès. Pour plus d’informations, consultez Authentification Microsoft Entra ID et contrôle d’accès en fonction du rôle pour Azure AI Recherche.

Appel des API

Les API documentées dans cette section donnent accès aux opérations sur les données de recherche, telles que la création et le remplissage d'index, le téléchargement de documents et les requêtes. Lorsque vous appelez des API, gardez à l’esprit les points suivants :

  • Les demandes doivent être émises via HTTPS (sur le port par défaut 443).

  • Les URI de requête doivent inclure la version de l’API. La valeur doit être définie sur une version prise en charge, mise en forme comme indiqué dans cet exemple : GET https://[search service name].search.windows.net/indexes?api-version=2020-06-30

  • Les en-têtes de requête doivent inclure une clé API ou un jeton du porteur pour les connexions authentifiées. Si vous le souhaitez, vous pouvez définir l’en-tête Accepter HTTP. Si l’en-tête du type de contenu n’est pas défini, la valeur par défaut est supposée être application/json.

Voir aussi