Gérer votre service de recherche Azure AI avec Azure CLI

  • Article

Vous pouvez exécuter des scripts et des commandes Azure CLI sur Windows, macOS, Linux ou dans Azure Cloud Shell pour créer et configurer la recherche Azure AI.

Utilisez le module az search pour effectuer les tâches suivantes :

Parfois, des questions sont posées sur des tâches qui ne figurent pas dans la liste ci-dessus.

Vous ne pouvez pas modifier un nom de serveur, une région ou un niveau par programmation ou dans le portail. Des ressources dédiées sont allouées lorsqu’un service est créé. Ainsi, toute modification du matériel sous-jacent (emplacement ou type de nœud) nécessite un nouveau service.

Vous ne pouvez pas utiliser d’outils ou d’API pour transférer du contenu, tel qu’un index, d’un service à un autre. Au sein d’un service, la création par programme du contenu s’effectue par le biais de l’API REST du service de recherche ou un Kit de développement logiciel (SDK) tel que le SDK Azure pour .NET. Bien qu’il n’existe aucune commande dédiée pour la migration de contenu, vous pouvez écrire un script qui appelle l’API REST ou une bibliothèque cliente pour créer et charger des index sur un nouveau service.

Les fonctionnalités d’administration en préversion ne sont généralement pas disponibles dans le module az search. Si vous souhaitez utiliser une fonctionnalité en préversion, utilisez l’API REST de gestion et une version préliminaire de l’API.

Prérequis

Les versions d’Azure CLI sont répertoriées sur GitHub.

Le module az search étend le Azure CLI avec une parité complète aux versions stables des API REST Search Management.

Répertorier les services dans un abonnement

Les commandes suivantes proviennent d’az resources et renvoient des informations sur les ressources et services existants déjà approvisionnés dans votre abonnement. Si vous ne savez pas combien de services de recherche sont déjà créés, ces commandes vous en informent et vous évitent d'accéder au portail.

La première commande renvoie tous les services de recherche.

az resource list --resource-type Microsoft.Search/searchServices --output table

Dans la liste des services, elle permet d'obtenir des informations sur une ressource spécifique.

az resource list --name <search-service-name>

Répertorier toutes les commandes az search

Vous pouvez afficher des informations sur les sous-groupes et les commandes disponibles dans az search à partir de l’interface CLI. Vous pouvez également consulter la documentation.

Pour afficher les sous-groupes disponibles dans az search, exécutez la commande suivante.

az search --help

La réponse doit être semblable à ma sortie suivante.

Group
    az search : Manage Azure Search services, admin keys and query keys.
        WARNING: This command group is in preview and under development. Reference and support
        levels: https://aka.ms/CLI_refstatus
Subgroups:
    admin-key                    : Manage Azure Search admin keys.
    private-endpoint-connection  : Manage Azure Search private endpoint connections.
    private-link-resource        : Manage Azure Search private link resources.
    query-key                    : Manage Azure Search query keys.
    service                      : Manage Azure Search services.
    shared-private-link-resource : Manage Azure Search shared private link resources.

For more specific examples, use: az find "az search"

Dans chaque sous-groupe, plusieurs commandes sont disponibles. Vous pouvez voir les commandes disponibles pour le sous-groupes service en exécutant la ligne suivante.

az search service --help

Vous pouvez également voir les arguments disponibles pour une commande particulière.

az search service create --help

Obtenir des informations sur le service de recherche

Si vous connaissez le groupe de ressources qui contient votre service de recherche, exécuter az search service show pour renvoyer la définition du service, avec le nom, la région, le niveau ainsi que le nombre de partitions et de réplicas. Pour cette commande, indiquez le groupe de ressources qui contient le service de recherche.

az search service show --name <service-name> --resource-group <search-service-resource-group-name>

Créer ou supprimer un service

Pour créer un service de recherche, utilisez la commande az search service create.

az search service create \
    --name <service-name> \
    --resource-group <search-service-resource-group-name> \
    --sku Standard \
    --partition-count 1 \
    --replica-count 1

Les résultats se présentent comme suit :

{
  "hostingMode": "default",
  "id": "/subscriptions/<alphanumeric-subscription-ID>/resourceGroups/demo-westus/providers/Microsoft.Search/searchServices/my-demo-searchapp",
  "identity": null,
  "location": "West US",
  "name": "my-demo-searchapp",
  "networkRuleSet": {
    "bypass": "None",
    "ipRules": []
  },
  "partitionCount": 1,
  "privateEndpointConnections": [],
  "provisioningState": "succeeded",
  "publicNetworkAccess": "Enabled",
  "replicaCount": 1,
  "resourceGroup": "demo-westus",
  "sharedPrivateLinkResources": [],
  "sku": {
    "name": "standard"
  },
  "status": "running",
  "statusDetails": "",
  "tags": null,
  "type": "Microsoft.Search/searchServices"
}

supprimer le service de recherche azure supprime le service et ses données.

az search service delete --name <service-name> \
                         --resource-group  <search-service-resource-group-name> \

Créer un service avec des règles IP

Selon vos exigences de sécurité, vous pouvez créer un service de recherche avec un pare-feu IP configuré. Pour ce faire, transmettez les adresses IP publiques (v4) ou les plages CIDR à l’argument ip-rules comme indiqué ci-dessous. Les règles doivent être séparées par une virgule (,) ou un point-virgule (;).

az search service create \
    --name <search-service-name> \
    --resource-group <search-service-resource-group-name> \
    --sku Standard \
    --partition-count 1 \
    --replica-count 1 \
    --ip-rules "55.5.63.73;52.228.215.197;101.37.221.205"

Créer un service avec une identité managée affectée par le système

Dans certains cas, par exemple, lorsque à l’aide d’une identité managée pour vous connecter à une source de données, vous devez activer identité managée affectée par le système. Pour ce faire, ajoutez --identity-type SystemAssigned à la commande.

az search service create \
    --name <search-service-name> \
    --resource-group <search-service-resource-group-name> \
    --sku Standard \
    --partition-count 1 \
    --replica-count 1 \
    --identity-type SystemAssigned

Créer un service avec un point de terminaison privé

Les points de terminaison privés pour la recherche Azure AI permettent à un client sur un réseau virtuel d’accéder en toute sécurité aux données d’un index de recherche grâce à une liaison privée. Ils utilisent une adresse IP de l’espace d’adressage du réseau virtuel pour votre service Search. Le trafic entre le client et le service Search traverse le réseau virtuel et une liaison privée sur le réseau principal de Microsoft, ce qui élimine l’exposition sur l’Internet public. Pour plus d’informations, reportez-vous à la documentation sur la création d’un point de terminaison privé pour azure AI Search.

L’exemple suivant montre comment créer un service de recherche avec un point de terminaison privé.

Tout d’abord, déployez un service de recherche avec PublicNetworkAccess défini sur Disabled.

az search service create \
    --name <search-service-name> \
    --resource-group <search-service-resource-group-name> \
    --sku Standard \
    --partition-count 1 \
    --replica-count 1 \
    --public-access Disabled

Ensuite, créez un réseau virtuel et le point de terminaison privé.

# Create the virtual network
az network vnet create \
    --resource-group <vnet-resource-group-name> \
    --location "West US" \
    --name <virtual-network-name> \
    --address-prefixes 10.1.0.0/16 \
    --subnet-name <subnet-name> \
    --subnet-prefixes 10.1.0.0/24

# Update the subnet to disable private endpoint network policies
az network vnet subnet update \
    --name <subnet-name> \
    --resource-group <vnet-resource-group-name> \
    --vnet-name <virtual-network-name> \
    --disable-private-endpoint-network-policies true

# Get the id of the search service
id=$(az search service show \
    --resource-group <search-service-resource-group-name> \
    --name <search-service-name> \
    --query [id] \
    --output tsv)

# Create the private endpoint
az network private-endpoint create \
    --name <private-endpoint-name> \
    --resource-group <private-endpoint-resource-group-name> \
    --vnet-name <virtual-network-name> \
    --subnet <subnet-name> \
    --private-connection-resource-id $id \
    --group-id searchService \
    --connection-name <private-link-connection-name>

Enfin, créez une zone DNS privée.

## Create private DNS zone
az network private-dns zone create \
    --resource-group <private-dns-resource-group-name> \
    --name "privatelink.search.windows.net"

## Create DNS network link
az network private-dns link vnet create \
    --resource-group <private-dns-resource-group-name> \
    --zone-name "privatelink.search.windows.net" \
    --name "myLink" \
    --virtual-network <virtual-network-name> \
    --registration-enabled false

## Create DNS zone group
az network private-endpoint dns-zone-group create \
   --resource-group <private-endpoint-resource-group-name>\
   --endpoint-name <private-endpoint-name> \
   --name "myZoneGroup" \
   --private-dns-zone "privatelink.search.windows.net" \
   --zone-name "searchServiceZone"

Pour plus d’informations sur la création de points de terminaison privés dans Azure CLI, consultez ce guide de démarrage rapide liaison privée.

Gérer les connexions de point de terminaison privé

Vous pouvez créer une connexion de point de terminaison privé, mais également récupérer (show), définir (update) et supprimer (delete) cette connexion.

Pour récupérer une connexion de point de terminaison privé et afficher son état, utilisez la commande az search private-endpoint-connection show.

az search private-endpoint-connection show \
    --name <pe-connection-name> \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name>

Pour mettre à jour la connexion, utilisez la commande az search private-endpoint-connection update. L’exemple suivant montre comment rejeter une connexion de point de terminaison privé :

az search private-endpoint-connection update \
    --name <pe-connection-name> \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name> 
    --status Rejected \
    --description "Rejected" \
    --actions-required "Please fix XYZ"

Pour supprimer la connexion au point de terminaison privé, utilisez la commande az search private-endpoint-connection delet.

az search private-endpoint-connection delete \
    --name <pe-connection-name> \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name>

Régénération des clés d’administration

Pour remplacer les clés de l’API Administrateur, utilisez la commande az search admin-key renew. Deux clés d'administration sont créées avec chaque service à des fins d'accès authentifié. Ces clés sont nécessaires pour chaque requête. Les deux clés d’administration fonctionnement de la même manière, et accorde au service de recherche un accès total en écriture, avec possibilité de récupérer des informations ou de créer et de supprimer des objets. Deux clés sont disponibles pour vous permettre d'en utiliser une lorsque vous remplacez l'autre.

Vous ne pouvez régénérer qu'une clé à la fois, spécifiée en tant que clé primary ou secondary. Pour ne pas interrompre le service, pensez à mettre à jour la totalité du code client de manière à utiliser une clé secondaire lors de la substitution de la clé primaire. Évitez tout changement de clés lorsque des opérations sont en cours.

En effet, si vous régénérez les clés sans mettre à jour le code client, les requêtes utilisant l'ancienne clé n'aboutiront pas. La régénération de toutes les nouvelles clés ne vous verrouille pas définitivement hors de votre service, et vous pouvez toujours accéder au service via le portail. Une fois les clés primaire et secondaire régénérées, vous pouvez mettre à jour le code client pour utiliser les nouvelles clés, après quoi les opérations reprennent.

Les valeurs correspondant aux clés API sont générées par le service. Vous ne pouvez pas fournir de clé personnalisée pour Azure AI Search à utiliser. De même, il n’existe aucun nom défini par l’utilisateur pour les clés API d’administration. Les références à la clé correspondent à des chaînes fixes, primary ou secondary.

az search admin-key renew \
    --resource-group <search-service-resource-group-name> \
    --service-name <search-service-name> \
    --key-kind primary

Les résultats se présentent comme suit. Les deux clés sont renvoyées, même si vous n'en modifiez qu'une.

{
  "primaryKey": <alphanumeric-guid>,
  "secondaryKey": <alphanumeric-guid>  
}

Créer ou supprimer des clés de requête

Pour créer des clés API de requête à des fins d’accès en lecture seule à partir d’applications clientes vers un index de recherche Azure AI, utilisez la commande créer une clé de requête de recherche azure. Les clés de requête sont utilisées pour s’authentifier auprès d’un index spécifique pour récupérer les résultats de la recherche. Les clés de requête n’accordent pas d’accès en lecture seule à d’autres éléments du service, tels qu’un index, une source de données ou un indexeur.

Vous ne pouvez pas fournir de clé pour Azure AI Search à utiliser. Les clés API sont générées par le service.

az search query-key create \
    --name myQueryKey \
    --resource-group <search-service-resource-group-name> \
    --service-name <search-service-name>

Mettre à l'échelle des réplicas et des partitions

Pour augmenter ou diminuer les réplicas et les partitions, utilisez la commande az search service update. Augmenter les réplicas ou les partitions se répercute sur votre facture, qui présente des frais fixes et variables. Si vous avez besoin d’une puissance de traitement supplémentaire, vous pouvez augmenter les réplicas et les partitions pour gérer la charge de travail. La zone de surveillance de la page Vue d’ensemble du portail présente des vignettes sur la latence de requête, les requêtes par seconde et les limitations, indiquant si la capacité actuelle est suffisante.

L'ajout ou la suppression de ressources peut prendre un certain temps. Des ajustements de la capacité interviennent en arrière-plan, ce qui permet la poursuite des charges de travail existantes. Une capacité supplémentaire est utilisée pour les requêtes entrantes dès qu’elle est prête, sans configuration supplémentaire requise.

La suppression de la capacité peut entraîner des perturbations. Il est recommandé d'arrêter tous les travaux d'indexation avant de réduire la capacité pour éviter la suppression de requêtes. Si ce n’est pas possible, essayez de réduire la capacité de façon incrémentielle, un seul réplica et une seule partition à la fois, jusqu'à ce que vos nouveaux niveaux cibles soient atteints.

Une fois que vous avez envoyé la commande, il n’existe aucun moyen de l’arrêter à mi-chemin. Vous devez attendre la fin de la commande avant de réviser les nombres.

az search service update \
    --name <search-service-name> \
    --resource-group <search-service-resource-group-name> \
    --partition-count 6 \
    --replica-count 6

Outre la mise à jour des nombres de réplicas et de partitions, vous pouvez également mettre à jour ip-rules, public-access et identity-type.

Les points de terminaison privés des ressources sécurisées créées par les API de recherche Azure AI sont appelés ressources de liaison privée partagées. Cela est dû au fait que vous partagez l’accès à une ressource, tel qu’un compte de stockage intégré au service Azure Private Link.

Si vous utilisez un indexeur pour indexer des données dans la recherche Azure AI et que votre source de données se trouve sur un réseau privé, vous pouvez créer une connexion de point de terminaison privé sortante pour atteindre les données.

Si vous souhaitez obtenir la liste complète des ressources Azure pour lesquelles il est possible de créer des points de terminaison privés sortants à partir de la recherche Azure AI, ainsi que les valeurs d’ID de groupe associées, cliquez ici.

Pour créer la ressource de liaison privée partagée, utilisez la commande az search shared-private-link-resource create. N’oubliez pas que certaines configurations peuvent être requises pour la source de données avant d’exécuter cette commande.

az search shared-private-link-resource create \
    --name <spl-name> \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name> \
    --group-id blob \
    --resource-id "/subscriptions/<alphanumeric-subscription-ID>/resourceGroups/<resource-group-name>/providers/Microsoft.Storage/storageAccounts/myBlobStorage"  \
    --request-message "Please approve"

Pour récupérer les ressources de liaison privée partagée et afficher leur état, utilisez la commande az search shared-private-link-resource list.

az search shared-private-link-resource list \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name>

Vous devez approuver la connexion avec la commande suivante pour pouvoir être utilisée. L’ID de la connexion de point de terminaison privé doit être récupéré à partir de la ressource enfant. Dans ce cas, nous obtenons l’ID de connexion à partir de la commande az storage.

id = (az storage account show -n myBlobStorage --query "privateEndpointConnections[0].id")

az network private-endpoint-connection approve --id $id

Pour supprimer la ressource de liaison privée partagée, utilisez la commande az search shared-private-link-resource delete.

az search shared-private-link-resource delete \
    --name <spl-name> \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name>

Pour plus d’informations sur la configuration des ressources de liaison privée partagée, consultez établir des connexions d’indexeur via un point de terminaison privé.

Étapes suivantes

Génération d'un index, interrogation d'un index à l’aide du portail, des API REST ou du kit de développement logiciel (SDK) .NET.