Gérer votre service Recherche Azure AI à l’aide d’API REST

Découvrez comment créer et configurer un service Recherche Azure AI à l’aide des API REST Management. Seules les API REST de gestion sont garanties pour fournir un accès anticipé aux fonctionnalités en préversion.

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

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

Conditions préalables

• Un compte Azure avec un abonnement actif. Créez gratuitement un compte.

• Visual Studio Code avec un client REST.

• Azure CLI pour obtenir un jeton d’accès, comme décrit dans les étapes suivantes. Vous devez être propriétaire ou administrateur dans votre abonnement Azure.

  Les appels d’API REST de gestion sont authentifiés via Microsoft Entra ID. Vous devez fournir un jeton d’accès sur la demande et les autorisations pour créer et configurer une ressource. Outre le Azure CLI, vous pouvez utiliser Azure PowerShell pour créer un jeton d’accès.

  1. Ouvrez un interpréteur de commandes pour Azure CLI.

  2. Connectez-vous à votre abonnement Azure. Si vous avez plusieurs locataires ou abonnements, veillez à en sélectionner un.

     az login
     

  3. Obtenez l’ID de locataire et l’ID d’abonnement.

     az account show
     

  4. 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 d'accès. Vous allez coller ces valeurs dans le fichier .rest ou le fichier .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 décrites dans cet article.

1. Démarrez Visual Studio Code et sélectionnez la vignette Extensions.

2. Recherchez le client REST et sélectionnez Installer.

   

3. Ouvrez ou créez un nouveau fichier nommé avec une extension .rest ou .http.

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

   @tenant-id = PUT-YOUR-TENANT-ID-HERE
   @subscription-id = PUT-YOUR-SUBSCRIPTION-ID-HERE
   @token = PUT-YOUR-TOKEN-HERE
   

5. Vérifiez que la session est opérationnelle en répertoriant les services de recherche dans votre abonnement.

    ### List search services
    GET https://management.azure.com/subscriptions/{{subscription-id}}/providers/Microsoft.Search/searchServices?api-version=2025-05-01  HTTP/1.1
         Content-type: application/json
         Authorization: Bearer {{token}}
   

6. Sélectionnez Envoyer une demande. Une réponse doit apparaître dans un volet adjacent. Si vous avez des services de recherche existants, ils sont répertoriés. Sinon, la liste est vide, mais tant que le code HTTP est 200 OK, vous êtes prêt pour 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éfinies. Fournissez les noms directement ou ajoutez de nouvelles variables à la collection.

### Create a search service (provide an existing resource group)
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

PUT https://management.azure.com/subscriptions/{{subscription-id}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-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"
        }
      }

Mettre à niveau un service

Certaines fonctionnalités Recherche Azure AI sont uniquement disponibles pour les nouveaux services. Pour éviter la recréation du service et intégrer ces fonctionnalités à un service existant, vous pouvez peut-être mettre à niveau votre service.

### Upgrade a search service
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

POST https://management.azure.com/subscriptions/{{subscription-id}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/upgrade?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Modifier les niveaux tarifaires

Si vous avez besoin de plus ou moins de capacité, vous pouvez basculer vers un autre niveau tarifaire. Actuellement, vous pouvez uniquement basculer entre les niveaux De base et Standard (S1, S2 et S3). Utilisez la sku propriété pour spécifier le nouveau niveau.

### Change pricing tiers
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

PATCH https://management.azure.com/subscriptions/{{subscription-id}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

    {
        "sku": {
            "name": "standard2"
        }
    }

Créer un service S3HD

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

### Create an S3HD service
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

PUT https://management.azure.com/subscriptions/{{subscription-id}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-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 à : Contributeur de données d’index de recherche, Lecteur de données d’index de recherche, Contributeur du service de recherche

Configurez votre service de recherche pour reconnaître 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 les opérations de plan de données, définissez authOptions à aadOrApiKey puis envoyez la requête.

Pour utiliser exclusivement le contrôle d’accès en fonction du rôle, désactivez l’authentification par clé d’API en suivant une deuxième requête, cette fois en configurant la valeur disableLocalAuth sur true.

### Configure role-based access
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

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

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

Configurer l’informatique confidentielle

L’informatique confidentielle est un type de calcul facultatif pour la protection des données en cours d’utilisation. Une fois configuré, votre service de recherche est déployé sur des machines virtuelles confidentielles (DCasv5 ou DCesv5) au lieu de machines virtuelles standard. Ce type de calcul entraîne également une surcharge de 10 % pour les niveaux facturables. Pour plus d’informations, consultez la page de tarification.

Pour une utilisation quotidienne, l’informatique confidentielle n’est pas nécessaire. Nous recommandons uniquement ce type de calcul pour des exigences réglementaires, de conformité ou de sécurité strictes. Pour plus d’informations, consultez les cas d’usage de l’informatique confidentielle.

Le type de calcul est fixe pour la durée de vie de votre service de recherche. Pour configurer définitivement l’informatique confidentielle, définissez la propriété computeType sur confidential sur un nouveau service.

### Configure confidential computing
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE
PUT https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
    Content-type: application/json
    Authorization: Bearer {{token}}
    {
        "location": "{{region}}",
        "sku": {
            "name": "basic"
        },
        "properties": {
            "computeType": "confidential"
        }
    }

Appliquer une politique de clé gérée par le client

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

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

### Enforce a customer-managed key policy
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

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

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

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

### Disable external access
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

PATCH https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
     
     {
        "properties": {
            "publicNetworkAccess": "Disabled"
        }
    }

Supprimer un service de recherche

### Delete a search service
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

DELETE https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Répertorier les clés d’API d’administration

### List admin keys
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

POST https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/listAdminKeys?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

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

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

### Regnerate admin keys
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

POST https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/regenerateAdminKey/primary?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

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

### Create a query key
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE
@query-key = PUT-YOUR-QUERY-KEY-NAME-HERE

POST https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/createQueryKey/{query-key}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Répertorier les connexions de point de terminaison privé

### List private endpoint connections
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

GET https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/privateEndpointConnections?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Répertorier les opérations de recherche

### List search operations
GET https://management.azure.com/subscriptions/{{subscription-id}}/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 incluent création d’un index ou querying un index à l’aide du portail Azure, des API REST ou d’un Kit de développement logiciel (SDK) Azure.

• Créer un index Recherche Azure AI dans le portail Azure
• Configurer un indexeur pour charger des données à partir d’autres services
• Interroger un index de Recherche Azure AI à l’aide de l’Explorateur de recherche dans le portail Microsoft Azure
• Comment utiliser la recherche Azure AI dans .NET