Démarrage rapide : recherche de mots clés à l’aide de REST

Article
10/31/2024

Les API REST dans Recherche Azure AI fournissent un accès programmatique à toutes les fonctionnalités, y compris les fonctionnalités d’évaluation, et offrent un moyen simple d’apprendre à s’en servir. Dans ce guide de démarrage rapide, découvrez comment appeler les API REST de recherche pour créer, charger et interroger un index de recherche dans Recherche Azure AI.

Si vous n’avez pas d’abonnement Azure, créez un compte gratuit avant de commencer.

Prérequis

Visual Studio Code avec un client REST.
Recherche Azure AI. Créez ou recherchez une ressource Recherche Azure AI existante sous votre abonnement actuel. Vous pouvez utiliser un service gratuit pour ce guide de démarrage rapide.

Télécharger les fichiers

Téléchargez un exemple REST à partir de GitHub pour envoyer les requêtes dans ce démarrage rapide. Vous pouvez trouver des instructions sur Téléchargement de fichiers à partir de GitHub.

Vous pouvez également démarrer un nouveau fichier sur votre système local et créer des requêtes manuellement en tirant parti des instructions contenues dans cet article.

Obtenir un point de terminaison de service de recherche

Vous trouverez le point de terminaison du service de recherche dans le Portail Azure.

Connectez-vous au Portail Azure, puis trouvez votre service de recherche.
Dans la page d’accueil Vue d’ensemble, recherchez l’URL. Voici un exemple de point de terminaison : https://mydemo.search.windows.net.

Vous collez ce point de terminaison dans le fichier .rest ou .http lors d’une étape ultérieure.

Configurer l’accès

Les demandes effectuées au point de terminaison de recherche doivent être authentifiées et autorisées. Vous pouvez utiliser des clés d’API ou des rôles pour cette tâche. Les clés sont plus faciles à utiliser, mais les rôles sont plus sécurisés.

Pour une connexion basée sur des rôles, les instructions suivantes vous permettent de vous connecter à la Recherche Azure AI sous votre identité, et non sous l’identité d’une application cliente.

Option 1 : utiliser des clés

Sélectionnez Paramètres>Clés, puis copiez une clé d’administration. Les clés d’administration sont utilisées pour ajouter, modifier et supprimer des objets. Il existe deux clés d’administration interchangeables. Copiez l’une ou l’autre. Pour plus d’informations, consultez Se connecter à la Recherche Azure AI à l’aide de l’authentification de clé.

Vous collez cette clé dans le fichier .rest ou .http lors d’une étape ultérieure.

Option 2 : utiliser des rôles

Vérifiez que votre service de recherche est configuré pour l’accès en fonction du rôle. Vous devez avoir préconfiguré les attributions de rôles pour l’accès aux développeurs. Vos attributions de rôles doivent accorder l’autorisation de créer, charger et interroger un index de recherche.

Dans cette section, obtenez votre jeton d’identité personnel à l’aide d’Azure CLI, d’Azure PowerShell ou du Portail Azure.

Connectez-vous à Azure CLI.
```
az login
```

Obtenez votre jeton d’identité personnelle.

az account get-access-token --scope https://search.azure.com/.default

Vous collez votre jeton d’identité personnelle dans le fichier .rest ou .http lors d’une étape ultérieure.

Remarque

Cette section suppose que vous utilisez un client local qui se connecte à la Recherche Azure AI en votre nom. Une approche alternative consiste à obtenir un jeton pour l’application cliente, en supposant que votre application est enregistrée auprès de Microsoft Entra ID.

Configurer Visual Studio Code

Si vous n’êtes pas familiarisé avec le client REST pour Visual Studio Code, cette section inclut la configuration afin de pouvoir effectuer les tâches de ce guide de démarrage rapide.

Démarrez Visual Studio Code et sélectionnez la vignette Extensions .
Recherchez le client REST et sélectionnez Installer.
Ouvrez ou créez un fichier nommé avec une extension de fichier .rest ou .http.

Collez l’exemple suivant si vous utilisez des clés API. Remplacez les espaces réservés @baseUrl et @apiKey par les valeurs que vous avez copiées précédemment.

@baseUrl = PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE
@apiKey = PUT-YOUR-SEARCH-SERVICE-API-KEY-HERE

 ### List existing indexes by name
 GET  {{baseUrl}}/indexes?api-version=2024-07-01&$select=name  HTTP/1.1
   Content-Type: application/json
   api-key: {{apiKey}}

Ou collez cet exemple si vous utilisez des rôles. Remplacez les espaces réservés @baseUrl et @token par les valeurs que vous avez copiées précédemment.

@baseUrl = PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE
@token = PUT-YOUR-PERSONAL-IDENTITY-TOKEN-HERE

 ### List existing indexes by name
 GET  {{baseUrl}}/indexes?api-version=2024-07-01&$select=name  HTTP/1.1
   Content-Type: application/json
   Authorization: Bearer {{token}}

Sélectionnez Envoyer une demande. Une réponse doit apparaître dans un volet adjacent. Si vous avez des index existants, ceux-ci sont répertoriés. Sinon, la liste est vide. Si le code HTTP est 200 OK, vous êtes prêt pour les étapes suivantes.

Points essentiels :
- Les paramètres sont spécifiés en utilisant un préfixe @.
- ### désigne un appel REST. La ligne suivante contient la requête, qui doit inclure HTTP/1.1.
- Send request doit apparaître au-dessus de la demande.

Création d'un index

Ajoutez une deuxième requête à votre fichier .rest. Créer un index (REST) crée un index de recherche et configure des structures de données physiques sur votre service de recherche.

Collez l’exemple suivant pour créer l’index hotels-quickstart sur votre service de recherche.

### Create a new index
POST {{baseUrl}}/indexes?api-version=2024-07-01  HTTP/1.1
  Content-Type: application/json
  Authorization: Bearer {{token}}

    {
        "name": "hotels-quickstart",  
        "fields": [
            {"name": "HotelId", "type": "Edm.String", "key": true, "filterable": true},
            {"name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": true, "facetable": false},
            {"name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.lucene"},
            {"name": "Category", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
            {"name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "sortable": false, "facetable": true},
            {"name": "ParkingIncluded", "type": "Edm.Boolean", "filterable": true, "sortable": true, "facetable": true},
            {"name": "LastRenovationDate", "type": "Edm.DateTimeOffset", "filterable": true, "sortable": true, "facetable": true},
            {"name": "Rating", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true},
            {"name": "Address", "type": "Edm.ComplexType", 
                "fields": [
                {"name": "StreetAddress", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false, "searchable": true},
                {"name": "City", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
                {"name": "StateProvince", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
                {"name": "PostalCode", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
                {"name": "Country", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true}
                ]
            }
        ]
    }

Sélectionnez Envoyer une demande. Vous devez avoir une réponse HTTP/1.1 201 Created et le corps de la réponse doit inclure la représentation JSON du schéma d’index.

Si vous obtenez une erreur Header name must be a valid HTTP token ["{"], vérifiez qu’il existe une ligne vide entre api-key et le corps de la requête. Si vous obtenez HTTP 504, vérifiez que l’URL spécifie HTTPS. Si vous voyez HTTP 400 ou 404, contrôlez le corps de la demande pour vérifier l'absence d'erreurs de copier-coller. Une erreur HTTP 403 indique généralement un problème avec la clé API. Il s’agit d’un problème de syntaxe lié à la façon dont la clé API est spécifiée ou d’une clé non valide.

Vous avez maintenant plusieurs demandes dans votre fichier. Rappelez-vous que ### démarre une nouvelle requête et que chaque requête s’exécute indépendamment.

À propos de la définition de l’index

Dans le schéma d’index, la collection de champs définit la structure du document. Tous les documents que vous chargez doivent avoir ces champs. Vous devez attribuer chaque champ à un type de données Entity Data Model (EDM). Les champs de chaîne sont utilisés dans la recherche en texte intégral. Si vous souhaitez que les données numériques puissent faire l’objet d’une recherche, vérifiez que le type de données est Edm.String. D’autres types de données tels que Edm.Int32 sont filtrables, triables, à choix multiples et récupérables, mais ne peuvent pas faire l’objet d’une recherche en texte intégral.

Les attributs du champ déterminent l’action autorisée. Les API REST autorisent de nombreuses actions par défaut. Par exemple, toutes les chaînes peuvent faire l’objet de recherches et sont récupérables. Pour les API REST, il est possible que vous disposiez uniquement d’attributs si vous devez désactiver un comportement.

{
    "name": "hotels-quickstart",  
    "fields": [
        {"name": "HotelId", "type": "Edm.String", "key": true, "filterable": true},
        {"name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": true, "facetable": false},
        {"name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.lucene"},
        {"name": "Category", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
        {"name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "sortable": false, "facetable": true},
        {"name": "ParkingIncluded", "type": "Edm.Boolean", "filterable": true, "sortable": true, "facetable": true},
        {"name": "LastRenovationDate", "type": "Edm.DateTimeOffset", "filterable": true, "sortable": true, "facetable": true},
        {"name": "Rating", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true},
        {"name": "Address", "type": "Edm.ComplexType", 
        "fields": [
        {"name": "StreetAddress", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false, "searchable": true},
        {"name": "City", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
        {"name": "StateProvince", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
        {"name": "PostalCode", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
        {"name": "Country", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true}
        ]
     }
  ]
}

Charger des documents

La création et le chargement de l’index sont des étapes distinctes. Dans Recherche Azure AI, l’index contient toutes les données pouvant faire l’objet d’une recherche et les requêtes s’exécutent sur le service de recherche. Pour les appels REST, les données sont fournies sous forme de documents JSON. Utilisez Documents – API REST d’index pour cette tâche.

L’URL est étendue pour inclure les collections docs et l’opération index.

Collez l’exemple suivant pour charger des documents JSON dans l’index de recherche.

### Upload documents
POST {{baseUrl}}/indexes/hotels-quickstart/docs/index?api-version=2024-07-01  HTTP/1.1
  Content-Type: application/json
  Authorization: Bearer {{token}}

    {
        "value": [
        {
        "@search.action": "upload",
        "HotelId": "1",
        "HotelName": "Stay-Kay City Hotel",
        "Description": "The hotel is ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Time's Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.",
        "Category": "Boutique",
        "Tags": [ "pool", "air conditioning", "concierge" ],
        "ParkingIncluded": false,
        "LastRenovationDate": "1970-01-18T00:00:00Z",
        "Rating": 3.60,
        "Address": 
            {
            "StreetAddress": "677 5th Ave",
            "City": "New York",
            "StateProvince": "NY",
            "PostalCode": "10022",
            "Country": "USA"
            } 
        },
        {
        "@search.action": "upload",
        "HotelId": "2",
        "HotelName": "Old Century Hotel",
        "Description": "The hotel is situated in a  nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts.",
        "Category": "Boutique",
        "Tags": [ "pool", "free wifi", "concierge" ],
        "ParkingIncluded": false,
        "LastRenovationDate": "1979-02-18T00:00:00Z",
        "Rating": 3.60,
        "Address": 
            {
            "StreetAddress": "140 University Town Center Dr",
            "City": "Sarasota",
            "StateProvince": "FL",
            "PostalCode": "34243",
            "Country": "USA"
            } 
        },
        {
        "@search.action": "upload",
        "HotelId": "3",
        "HotelName": "Gastronomic Landscape Hotel",
        "Description": "The Hotel stands out for its gastronomic excellence under the management of William Dough, who advises on and oversees all of the Hotel’s restaurant services.",
        "Category": "Resort and Spa",
        "Tags": [ "air conditioning", "bar", "continental breakfast" ],
        "ParkingIncluded": true,
        "LastRenovationDate": "2015-09-20T00:00:00Z",
        "Rating": 4.80,
        "Address": 
            {
            "StreetAddress": "3393 Peachtree Rd",
            "City": "Atlanta",
            "StateProvince": "GA",
            "PostalCode": "30326",
            "Country": "USA"
            } 
        },
        {
        "@search.action": "upload",
        "HotelId": "4",
        "HotelName": "Sublime Palace Hotel",
        "Description": "Sublime Palace Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Palace is part of a lovingly restored 1800 palace.",
        "Category": "Boutique",
        "Tags": [ "concierge", "view", "24-hour front desk service" ],
        "ParkingIncluded": true,
        "LastRenovationDate": "1960-02-06T00:00:00Z",
        "Rating": 4.60,
        "Address": 
            {
            "StreetAddress": "7400 San Pedro Ave",
            "City": "San Antonio",
            "StateProvince": "TX",
            "PostalCode": "78216",
            "Country": "USA"
            }
        }
      ]
    }

Sélectionnez Envoyer une demande. Après quelques secondes, la réponse HTTP 201 apparaît dans le volet adjacent.

Si vous obtenez HTTP 207, cela signifie qu'au moins un document n'a pas pu être chargé. Si HTTP 404 s'affiche, vous avez une erreur de syntaxe dans l'en-tête ou le corps de la demande. Vérifiez que vous avez modifié le point de terminaison pour inclure /docs/index.

Exécuter des requêtes

Maintenant que des documents sont chargés, vous pouvez émettre des requêtes sur ceux-ci en tirant parti de Documents – Rechercher des publications (REST).

L’URI est étendue pour inclure une expression de requête spécifiée en utilisant l’opérateur /docs/search.

Collez l’exemple suivant pour interroger l’index de recherche. Sélectionnez ensuite Envoyer la requête. Une requête de recherche de texte inclut toujours un paramètre search. Cet exemple inclut un paramètre searchFields facultatif qui limite la recherche de texte à des champs spécifiques.

### Run a query
POST {{baseUrl}}/indexes/hotels-quickstart/docs/search?api-version=2024-07-01  HTTP/1.1
  Content-Type: application/json
  Authorization: Bearer {{token}}

  {
      "search": "lake view",
      "select": "HotelId, HotelName, Tags, Description",
      "searchFields": "Description, Tags",
      "count": true
  }

Passez en revue la réponse dans le volet adjacent. Vous devez avoir un décompte qui indique le nombre de correspondances trouvées dans l’index, un score de recherche indiquant la pertinence et les valeurs de chaque champ répertorié dans l’instruction select.

{
  "@odata.context": "https://my-demo.search.windows.net/indexes('hotels-quickstart')/$metadata#docs(*)",
  "@odata.count": 1,
  "value": [
    {
      "@search.score": 0.6189728,
      "HotelId": "4",
      "HotelName": "Sublime Palace Hotel",
      "Description": "Sublime Palace Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Palace is part of a lovingly restored 1800 palace.",
      "Tags": [
        "concierge",
        "view",
        "24-hour front desk service"
      ]
    }
  ]
}

Obtenez les propriétés de l’index

Vous pouvez également utiliser la commande Obtenir des statistiques pour interroger les nombres de documents et la taille de l’index.

Collez l’exemple suivant pour interroger l’index de recherche. Sélectionnez ensuite Envoyer la requête.

### Get index statistics
GET {{baseUrl}}/indexes/hotels-quickstart/stats?api-version=2024-07-01  HTTP/1.1
  Content-Type: application/json
  Authorization: Bearer {{token}}

Vérifiez la réponse. Cette opération est un moyen simple d’obtenir des détails sur le stockage d’index.

{
  "@odata.context": "https://my-demo.search.windows.net/$metadata#Microsoft.Azure.Search.V2023_11_01.IndexStatistics",
  "documentCount": 4,
  "storageSize": 34707,
  "vectorIndexSize": 0
}

Nettoyer les ressources

Lorsque vous travaillez dans votre propre abonnement, il est recommandé, à la fin de chaque projet, de déterminer si vous avez toujours besoin des ressources que vous avez créées. Les ressources laissées en cours d’exécution peuvent vous coûter de l’argent. Vous pouvez supprimer les ressources une par une ou supprimer le groupe de ressources.

Vous pouvez rechercher et gérer des ressources dans le portail en tirant parti des liens Toutes les ressources ou Groupes de ressources situés dans le volet le plus à gauche.

Vous pouvez également essayer cette commande DELETE :

### Delete an index
DELETE  {{baseUrl}}/indexes/hotels-quickstart?api-version=2024-07-01 HTTP/1.1
    Content-Type: application/json
    api-key: {{apiKey}}

Étape suivante

Maintenant que vous connaissez le client REST et que vous effectuez des appels REST à Recherche Azure AI, essayez un autre guide de démarrage rapide qui illustre la prise en charge des vecteurs.

Démarrage rapide : Recherche vectorielle à l’aide de REST

Partage via