Démarrage rapide : Créer un index de recherche dans PowerShell à l’aide des API REST

Article
10/31/2024

Dans ce guide de démarrage rapide Recherche Azure AI, découvrez comment créer, charger et interroger un index de recherche à l’aide de PowerShell et des API REST de Recherche Azure AI. Cet article explique comment exécuter des commandes PowerShell de manière interactive. Vous pouvez également télécharger et exécuter un script PowerShell qui effectue les mêmes opérations.

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

Prérequis

Les services et outils suivants sont indispensables dans ce guide de démarrage rapide :

PowerShell 7.3 ou version ultérieure avec Invoke-RestMethod pour les étapes séquentielles et interactives.
Créez un service Recherche Azure AI ou recherchez un service existant dans votre abonnement actuel. Vous pouvez utiliser un service gratuit pour ce guide de démarrage rapide.

Copier la clé et l’URL d’un service de recherche

Dans ce guide de démarrage rapide, les appels REST incluent l’URL du service et une clé d’accès sur chaque requête. Un service de recherche est créé avec les deux. Ainsi, si vous avez ajouté Recherche Azure AI à votre abonnement, effectuez ces étapes pour obtenir les informations nécessaires.

Connectez-vous au portail Azure. Dans la page Vue d’ensemble de votre service de recherche, obtenez l’URL. Voici un exemple de point de terminaison : https://mydemo.search.windows.net.
Sélectionnez Paramètres>Clés, puis obtenez une clé d’administration pour avoir des droits d’accès complets sur le service. Deux clés d’administration interchangeables sont fournies pour assurer la continuité de l’activité si vous devez en remplacer une. Vous pouvez utiliser la clé primaire ou secondaire sur les demandes d’ajout, de modification et de suppression d’objets.

Toutes les requêtes nécessitent une clé API sur chaque requête envoyée à votre service. L’utilisation d’une clé valide permet d’établir, en fonction de chaque requête, une relation de confiance entre l’application qui envoie la requête et le service qui en assure le traitement.

Se connecter à Recherche cognitive Azure AI

Dans PowerShell, créez un objet $headers pour stocker le type de contenu et la clé API. Remplacez la clé API d’administration (YOUR-ADMIN-API-KEY) par une clé valide pour votre service de recherche. Vous définissez cet en-tête une seule fois pour toute la durée de la session, mais vous devez l’ajouter à chaque requête.
```
$headers = @{
'api-key' = '<YOUR-ADMIN-API-KEY>'
'Content-Type' = 'application/json' 
'Accept' = 'application/json' }
```
Créez un objet $url qui spécifie la collection d’index du service. Remplacez le nom du service (YOUR-SEARCH-SERVICE-NAME) par un service de recherche valide.
```
$url = "https://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net/indexes?api-version=2024-07-01&`$select=name"
```
Exécutez Invoke-RestMethod pour envoyer une requête GET au service et vérifier la connexion. Ajoutez ConvertTo-Json afin d’afficher les réponses renvoyées par le service.
```
Invoke-RestMethod -Uri $url -Headers $headers | ConvertTo-Json
```
Si le service est vide et ne contient aucun index, les résultats se présenteront comme suit. Sinon, vous voyez une représentation JSON des définitions d’index.
```
{
    "@odata.context":  "https://mydemo.search.windows.net/$metadata#indexes",
    "value":  [

            ]
}
```

Création d'un index

Sauf si vous utilisez le portail, le service doit contenir un index pour vous permettre de charger des données. Cette étape définit l’index et l’envoie (push) au service. L’API REST Create Index est utilisée pour cette étape.

Un index doit contenir un nom et une collection de champs. La collection de champs définit la structure d'un document. Chaque champ a un nom, un type et des attributs qui déterminent la façon dont il est utilisé (par exemple, s’il permet d’effectuer une recherche en texte intégral, et s’il est filtrable ou récupérable dans les résultats de la recherche). Dans un index, l’un des champs de type Edm.String doit être désigné comme clé pour l’identité du document.

Cet index se nomme hotels-quickstart, et il contient les définitions de champs que vous voyez dans le code suivant. Il s’agit d’un sous-ensemble d’un index Hotels plus grand utilisé dans d’autres articles de procédures. Par souci de concision, les définitions de champs sont découpées dans ce guide de démarrage rapide.

Collez cet exemple dans PowerShell pour créer un objet $body qui contient le schéma d’index.

$body = @"
{
    "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}
        ]
     }
  ]
}
"@

Définissez l’URI vers la collection d’index de votre service et l’index hotels-quickstart.

$url = "https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart?api-version=2024-07-01"

Exécutez la commande avec $url, $headers et $body pour créer l’index sur le service.

Invoke-RestMethod -Uri $url -Headers $headers -Method Put -Body $body | ConvertTo-Json

Les résultats doivent ressembler à cet exemple, qui affiche uniquement les deux premiers champs par souci de concision :

{
    "@odata.context":  "https://mydemo.search.windows.net/$metadata#indexes/$entity",
    "@odata.etag":  "\"0x8D6EDE28CFEABDA\"",
    "name":  "hotels-quickstart",
    "defaultScoringProfile":  null,
    "fields":  [
                {
                    "name":  "HotelId",
                    "type":  "Edm.String",
                    "searchable":  true,
                    "filterable":  true,
                    "retrievable":  true,
                    "sortable":  true,
                    "facetable":  true,
                    "key":  true,
                    "indexAnalyzer":  null,
                    "searchAnalyzer":  null,
                    "analyzer":  null,
                    "synonymMaps":  ""
                },
                {
                    "name":  "HotelName",
                    "type":  "Edm.String",
                    "searchable":  true,
                    "filterable":  false,
                    "retrievable":  true,
                    "sortable":  true,
                    "facetable":  false,
                    "key":  false,
                    "indexAnalyzer":  null,
                    "searchAnalyzer":  null,
                    "analyzer":  null,
                    "synonymMaps":  ""
                },
                . . .
    ]
}

Conseil

À des fins de vérification, vous pouvez également consulter la liste des index dans le portail.

Charger des documents

Pour envoyer (push) des documents, utilisez une requête HTTP POST au point de terminaison de l’URL de votre index. L’API REST pour cette tâche est Index Documents.

Collez cet exemple dans PowerShell pour créer un objet $body qui contient les documents que vous souhaitez charger.

Cette requête comprend deux enregistrements intégraux et un enregistrement partiel. L’enregistrement partiel indique que vous pouvez charger des documents incomplets. Le paramètre @search.action spécifie la manière dont l’indexation est effectuée. Les valeurs valides sont upload, merge, mergeOrUpload et delete. Le comportement mergeOrUpload crée un nouveau document pour hotelId = 3 ou met à jour le contenu s’il existe déjà.

$body = @"
{
    "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"
        }
    }
]
}
"@

Définissez le point de terminaison vers la collection de documents hotels-quickstart et incluez l’opération d’index (indexes/hotels-quickstart/docs/index).
```
$url = "https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs/index?api-version=2024-07-01"
```

Exécutez la commande avec $url, $headers et $body pour charger des documents dans l’index hotels-quickstart.

Invoke-RestMethod -Uri $url -Headers $headers -Method Post -Body $body | ConvertTo-Json

Les résultats doivent ressembler à l’exemple suivant. Vous devez voir un code d’état de 201.

{
    "@odata.context":  "https://mydemo.search.windows.net/indexes(\u0027hotels-quickstart\u0027)/$metadata#Collection(Microsoft.Azure.Search.V2019_05_06.IndexResult)",
    "value":  [
                {
                    "key":  "1",
                    "status":  true,
                    "errorMessage":  null,
                    "statusCode":  201
                },
                {
                    "key":  "2",
                    "status":  true,
                    "errorMessage":  null,
                    "statusCode":  201
                },
                {
                    "key":  "3",
                    "status":  true,
                    "errorMessage":  null,
                    "statusCode":  201
                },
                {
                    "key":  "4",
                    "status":  true,
                    "errorMessage":  null,
                    "statusCode":  201
                }
            ]
}

Rechercher dans un index

Cette étape explique comment interroger un index à l’aide de l’API Rechercher des documents.

Veillez à utiliser des guillemets simples pour la recherche $urls. Les chaînes de requêtes contiennent des caractères $, et vous n’êtes pas tenu de les placer en échappement si l’intégralité de la chaîne est placée entre guillemets simples.

Définissez le point de terminaison vers la collection de documents hotels-quickstart et ajoutez un paramètre search à transmettre dans une chaîne de requête.

Cette chaîne exécute une recherche vide (search=*) retournant une liste non classée (score de la recherche = 1.0) de documents arbitraires. Par défaut, Recherche Azure AI renvoie 50 correspondances à la fois. Telle qu’elle est structurée, cette requête renvoie la structure et les valeurs d’un document entier. Ajoutez $count=true pour obtenir le nombre de tous les documents dans les résultats.
```
$url = 'https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs?api-version=2024-07-01&search=*&$count=true'
```

Exécutez la commande pour envoyer $url au service.

Invoke-RestMethod -Uri $url -Headers $headers | ConvertTo-Json

Les résultats se présentent comme suit :

{
"@odata.context":  "https://mydemo.search.windows.net/indexes(\u0027hotels-quickstart\u0027)/$metadata#docs(*)",
"@odata.count":  4,
"value":  [
              {
                  "@search.score":  0.1547872,
                  "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.6,
                  "Address":  "@{StreetAddress=140 University Town Center Dr; City=Sarasota; StateProvince=FL; PostalCode=34243; Country=USA}"
              },
              {
                  "@search.score":  0.009068266,
                  "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\u0027s restaurant services.",
                  "Category":  "Resort and Spa",
                  "Tags":  "air conditioning bar continental breakfast",
                  "ParkingIncluded":  true,
                  "LastRenovationDate":  "2015-09-20T00:00:00Z",
                  "Rating":  4.8,
                  "Address":  "@{StreetAddress=3393 Peachtree Rd; City=Atlanta; StateProvince=GA; PostalCode=30326; Country=USA}"
              },
            . . .
    ]
}

Essayez quelques autres exemples de requête pour avoir un aperçu de la syntaxe. Vous pouvez effectuer une recherche de chaîne, textualiser les requêtes $filter, limiter le jeu de résultats, restreindre la recherche à des champs spécifiques, etc.

# Query example 1
# Search the entire index for the terms 'restaurant' and 'wifi'
# Return only the HotelName, Description, and Tags fields
$url = 'https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs?api-version=2024-07-01&search=restaurant wifi&$count=true&$select=HotelName,Description,Tags'

# Query example 2 
# Apply a filter to the index to find hotels rated 4 or higher
# Returns the HotelName and Rating. Two documents match.
$url = 'https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs?api-version=2024-07-01&search=*&$filter=Rating gt 4&$select=HotelName,Rating'

# Query example 3
# Take the top two results, and show only HotelName and Category in the results
$url = 'https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs?api-version=2024-07-01&search=boutique&$top=2&$select=HotelName,Category'

# Query example 4
# Sort by a specific field (Address/City) in ascending order

$url = 'https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs?api-version=2024-07-01&search=pool&$orderby=Address/City asc&$select=HotelName, Address/City, Tags, Rating'

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 les ressources dans le portail à l’aide des liens Toutes les ressources ou Groupes de ressources situés dans le volet le plus à gauche.

Si vous utilisez un service gratuit, n'oubliez pas que vous êtes limité à trois index, indexeurs et sources de données. Vous pouvez supprimer des éléments un par un dans le portail pour ne pas dépasser la limite.

Étapes suivantes

Dans ce démarrage rapide, vous avez utilisé PowerShell pour parcourir le flux de travail de base permettant de créer et d'accéder à du contenu dans Recherche Azure AI. En prenant ces concepts en compte, nous vous recommandons de passer à des scénarios plus avancés, tels que l’indexation à partir de sources de données Azure :

Tutoriel REST : Indexer et rechercher des données semi-structurées (objets blob JSON) dans Recherche Azure AI

Partager via