Gérer votre service Recherche Azure AI avec les API REST

Article
09/27/2024

Dans cet article, vous découvrez comment créer et configurer un service Recherche Azure AI en utilisant les API REST de gestion. Seules les API REST de gestion garantissent un accès anticipé aux fonctionnalités d’évaluation.

L’API REST de gestion est disponible dans les versions stables et les préversions. Veillez à définir une préversion de l’API si vous accédez aux fonctionnalités en préversion.

Créer ou mettre à jour un service
Activer le contrôle d’accès en fonction du rôle Azure pour le plan de données
Appliquer une stratégie de clé gérée par le client
Désactiver le classeur sémantique
Désactiver les charges de travail qui envoient des données vers des ressources externes
Créer une clé de requête
Régénérer une clé d’administration
Répertorier les connexions de point de terminaison privé
Répertorier des opérations de recherche
Supprimer des services de recherche

Toutes les API REST de gestion ont des exemples. Si une tâche n’est pas couverte dans cet article, consultez la référence de l’API à la place.

Prérequis

Un abonnement Azure : créez-en un gratuitement.
Visual Studio Code avec un client REST.
L’interface Azure CLI utilisée pour obtenir un jeton d’accès. Vous devez être propriétaire ou Administrateur de votre abonnement Azure.

Obtention d’un jeton d’accès

Les appels d’API REST de gestion sont authentifiés avec Microsoft Entra ID. Vous devez fournir un jeton d’accès sur la requête, tout comme les autorisations de créer et configurer une ressource.

Vous pouvez utiliser l’interface Azure CLI ou Azure PowerShell pour créer un jeton d’accès.

Ouvrez un interpréteur de commandes pour Azure CLI.
Connectez-vous à votre abonnement Azure.
```
az login
```
Obtenez l’ID d’abonnement et l’ID de locataire. Si vous disposez de plusieurs locataires ou abonnements, assurez-vous d’utiliser celui qui convient.
```
az account show
```

Obtenez un jeton d’accès.

az account get-access-token --query accessToken --output tsv

Vous devez disposer d’un ID de locataire, d’un ID d’abonnement et d’un jeton du porteur. Vous allez coller ces valeurs dans le fichier .rest ou .http que vous créez à l’étape suivante.

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 .

Fournissez des variables pour les valeurs récupérées à l’étape précédente.

@tenantId = PASTE-YOUR-TENANT-ID-HERE
@subscriptionId = PASTE-YOUR-SUBSCRIPTION-ID-HERE
@token = PASTE-YOUR-TOKEN-HERE

Assurez-vous que la session est opérationnelle en répertoriant les services de recherche de votre abonnement.

 ### List search services
 GET https://management.azure.com/subscriptions/{{subscriptionId}}/providers/Microsoft.Search/searchServices?api-version=2023-11-01
      Content-type: application/json
      Authorization: Bearer {{token}}

Sélectionnez Envoyer une demande. Une réponse doit apparaître dans un volet adjacent. Si vous disposez de services de recherche existants, ceux-ci sont répertoriés. Sinon, la liste est vide, mais tant que le code HTTP est 200 OK, vous pouvez passer aux les étapes suivantes.

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Length: 22068
Content-Type: application/json; charset=utf-8
Expires: -1
x-ms-ratelimit-remaining-subscription-reads: 11999
x-ms-request-id: f47d3562-a409-49d2-b9cd-6a108e07304c
x-ms-correlation-request-id: f47d3562-a409-49d2-b9cd-6a108e07304c
x-ms-routing-request-id: WESTUS2:20240314T012052Z:f47d3562-a409-49d2-b9cd-6a108e07304c
Strict-Transport-Security: max-age=31536000; includeSubDomains
X-Content-Type-Options: nosniff
X-Cache: CONFIG_NOCACHE
X-MSEdge-Ref: Ref A: 12401F1160FE4A3A8BB54D99D1FDEE4E Ref B: CO6AA3150217011 Ref C: 2024-03-14T01:20:52Z
Date: Thu, 14 Mar 2024 01:20:52 GMT
Connection: close

{
  "value": [ . . . ]
}

Créer ou mettre à jour un service

Crée ou met à jour un service de recherche sous l’abonnement actuel. Cet exemple utilise des variables pour le nom et la région du service de recherche, qui n’ont pas encore été définis. Fournissez les noms directement ou ajoutez de nouvelles variables à la collection.

### Create a search service (provide an existing resource group)
@resource-group = my-rg
@search-service-name = my-search
PUT https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

    {
        "location": "North Central US",
        "sku": {
            "name": "basic"
        },
        "properties": {
            "replicaCount": 1,
            "partitionCount": 1,
            "hostingMode": "default"
        }
      }

Créer un service S3HD

Pour créer un service S3HD, utilisez une combinaison de propriétés sku et hostingMode. Définissez sku sur standard3 et « hostingMode » sur HighDensity.

@resource-group = my-rg
@search-service-name = my-search
PUT https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

    {
        "location": "{{region}}",
        "sku": {
          "name": "standard3"
        },
        "properties": {
          "replicaCount": 1,
          "partitionCount": 1,
          "hostingMode": "HighDensity"
        }
    }

Configurer l’accès en fonction du rôle pour le plan de données

S’applique à : Recherche dans l’index de données Contributeur, Lecteur de données d’index de recherche, Contributeur du Service de recherche

Dans cette étape, configurez votre service de recherche afin qu’il reconnaisse un en-tête d’autorisation sur les demandes de données qui fournissent un jeton d’accès OAuth2.

Pour utiliser le contrôle d’accès en fonction du rôle pour des opérations du plan de données, définissez authOptions sur aadOrApiKey et envoyez la requête.

Pour utiliser exclusivement le contrôle d’accès en fonction du rôle, désactivez l’authentification par clé API en envoyant une deuxième requête HTTP, avec cette fois le paramètre disableLocalAuth défini sur « true ».

PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

    {
        "properties": {
            "disableLocalAuth": false,
            "authOptions": {
                "aadOrApiKey": {
                    "aadAuthFailureMode": "http401WithBearerChallenge"
                }
            }
        }
    }

Appliquer une stratégie de clé gérée par le client

Si vous utilisez le chiffrement géré par le client, vous pouvez activer « encryptionWithCMK » avec « enforcement » défini sur « Enabled » si vous souhaitez que le service de recherche signale son état de conformité.

Quand vous activez cette stratégie, les appels REST qui créent des objets contenant des données sensibles, par exemple, la chaîne de connexion dans une source de données, échouent si aucune clé de chiffrement n’est fournie : "Error creating Data Source: "CannotCreateNonEncryptedResource: The creation of non-encrypted DataSources is not allowed when encryption policy is enforced."

PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
     
     {
        "properties": {
            "encryptionWithCmk": {
                "enforcement": "Enabled"
            }
        }
    }

Désactiver le classeur sémantique

Bien que le classeur sémantique ne soit pas activé par défaut, vous pouvez verrouiller la fonction au niveau du service pour être sûr qu’elle ne peut pas être utilisée.

### disable semantic ranker
PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
     
     {
        "properties": {
            "semanticSearch": "Disabled"
        }
    }

Désactiver les charges de travail qui envoient des données vers des ressources externes

La Recherche Azure AI écrit dans des sources de données externes pendant la mise à jour d’une base de connaissances, l’enregistrement d’un état de session de débogage ou la mise en cache d’enrichissements. L’exemple suivant désactive ces charges de travail au niveau du service.

### disable-external-access
PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
     
     {
        "properties": {
            "publicNetworkAccess": "Disabled"
        }
    }

Supprimer un service de recherche

### delete a search service
DELETE https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Répertorier les clés API administrateur

### List admin keys
POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/listAdminKeys?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Régénérer des clés API d’administration

Vous ne pouvez régénérer qu’une seule clé API d’Administrateur à la fois.

### Regnerate admin keys
POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/regenerateAdminKey/primary?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Créer des clés API de requête

### Create a query key
@query-key-name = myQueryKey
POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/createQueryKey/{name}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Répertorier les connexions au point de terminaison privé

### List private endpoint connections
GET https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/privateEndpointConnections?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Répertorier des opérations de recherche

### List search operations
GET https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups?api-version=2021-04-01 HTTP/1.1
  Content-type: application/json
  Authorization: Bearer {{token}}

Étapes suivantes

Une fois qu’un service de recherche est configuré, les étapes suivantes comprennent la création d’un index ou l’interrogation d’un index à l’aide du portail, des API REST ou un kit de développement logiciel (SDK) Azure.

Partage via