Gérer votre service Azure AI Recherche avec PowerShell
Vous pouvez exécuter des scripts et des cmdlets PowerShell sur Windows, Linux ou dans Azure Cloud Shell pour créer et configurer Azure AI Recherche.
Utilisez le module Az.Search pour effectuer les tâches suivantes :
- Lister les services de recherche dans un abonnement
- Retourner les informations sur les services
- Créer ou supprimer un service
- Créer un service avec un point de terminaison privé
- Régénérer des clés API d’administration
- Créer ou supprimer des clés API de requête
- Effectuer un scale-up ou un scale-down avec les réplicas et les partitions
- Créer une ressource de liaison privée partagée
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.
Le module Az.Search étend Azure PowerShell avec une parité complète aux versions stables des API REST Search Management.
Vérifier les versions et charger des modules
Les exemples de cet article sont interactifs et requièrent des autorisations élevées. PowerShell local et le Azure PowerShell (le module Az) sont requis.
Vérification de la version de PowerShell
Installez la dernière version de PowerShell si vous ne l’avez pas.
$PSVersionTable.PSVersion
Charger Azure PowerShell
Si vous ne savez pas si Az est installé, exécutez la commande suivante pour le vérifier.
Get-InstalledModule -Name Az
Certains systèmes ne chargent pas automatiquement les modules. Si vous avez obtenu une erreur sur la commande précédente, essayez de charger le module et, en cas d’échec, revenez à l’installation instructions d’installation d’Azure PowerShell pour voir si vous avez manqué une étape.
Import-Module -Name Az
Se connecter à Azure avec un jeton de connexion de navigateur
Vous pouvez utiliser vos informations d’identification de connexion au portail pour vous connecter à un abonnement dans PowerShell. Vous pouvez également vous authentifier de manière non interactive avec un principal de service.
Connect-AzAccount
Si vous disposez de plusieurs abonnements Azure, définissez votre abonnement Azure à utiliser. Pour afficher une liste de vos abonnements en cours, exécutez la commande suivante.
Get-AzSubscription | sort SubscriptionName | Select SubscriptionName
Pour spécifier l’abonnement, exécutez la commande suivante. Dans l’exemple suivant, le nom de l’abonnement est ContosoSubscription.
Select-AzSubscription -SubscriptionName ContosoSubscription
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.
Get-AzResource -ResourceType Microsoft.Search/searchServices | ft
Dans la liste des services, elle permet d'obtenir des informations sur une ressource spécifique.
Get-AzResource -ResourceName <service-name>
Les résultats se présentent comme suit.
Name : my-demo-searchapp
ResourceGroupName : demo-westus
ResourceType : Microsoft.Search/searchServices
Location : westus
ResourceId : /subscriptions/<alphanumeric-subscription-ID>/resourceGroups/demo-westus/providers/Microsoft.Search/searchServices/my-demo-searchapp
Importez Az.Search
Les commandes de Az.Search ne sont pas disponibles tant que vous n’avez pas chargé le module.
Install-Module -Name Az.Search -Scope CurrentUser
Répertorier toutes les commandes Az.Search
En guise de vérification, renvoyez une liste de commandes fournies dans le module.
Get-Command -Module Az.Search
Les résultats se présentent comme suit.
CommandType Name Version Source
----------- ---- ------- ------
Cmdlet Get-AzSearchAdminKeyPair 0.10.0 Az.Search
Cmdlet Get-AzSearchPrivateEndpointConnection 0.10.0 Az.Search
Cmdlet Get-AzSearchPrivateLinkResource 0.10.0 Az.Search
Cmdlet Get-AzSearchQueryKey 0.10.0 Az.Search
Cmdlet Get-AzSearchService 0.10.0 Az.Search
Cmdlet Get-AzSearchSharedPrivateLinkResource 0.10.0 Az.Search
Cmdlet New-AzSearchAdminKey 0.10.0 Az.Search
Cmdlet New-AzSearchQueryKey 0.10.0 Az.Search
Cmdlet New-AzSearchService 0.10.0 Az.Search
Cmdlet New-AzSearchSharedPrivateLinkResource 0.10.0 Az.Search
Cmdlet Remove-AzSearchPrivateEndpointConnection 0.10.0 Az.Search
Cmdlet Remove-AzSearchQueryKey 0.10.0 Az.Search
Cmdlet Remove-AzSearchService 0.10.0 Az.Search
Cmdlet Remove-AzSearchSharedPrivateLinkResource 0.10.0 Az.Search
Cmdlet Set-AzSearchPrivateEndpointConnection 0.10.0 Az.Search
Cmdlet Set-AzSearchService 0.10.0 Az.Search
Cmdlet Set-AzSearchSharedPrivateLinkResource 0.10.0 Az.Search
Si vous disposez d’une version antérieure du package, mettez à jour le module pour obtenir les fonctionnalités les plus récentes.
Update-Module -Name Az.Search
Obtenir des informations sur le service de recherche
Après avoir importé Az.Search et déterminé le groupe de ressources contenant votre service de recherche, exécutez Get-AzSearchService pour renvoyer la définition de service, notamment le nom, la région, le niveau, ainsi que le nombre de réplicas et de partitions. Pour cette commande, indiquez le groupe de ressources qui contient le service de recherche.
Get-AzSearchService -ResourceGroupName <resource-group-name>
Les résultats se présentent comme suit.
Name : my-demo-searchapp
ResourceGroupName : demo-westus
ResourceType : Microsoft.Search/searchServices
Location : West US
Sku : Standard
ReplicaCount : 1
PartitionCount : 1
HostingMode : Default
ResourceId : /subscriptions/<alphanumeric-subscription-ID>/resourceGroups/demo-westus/providers/Microsoft.Search/searchServices/my-demo-searchapp
Créer ou supprimer un service
New-AzSearchService permet de créer un service de recherche.
New-AzSearchService -ResourceGroupName <resource-group-name> -Name <search-service-name> -Sku "Standard" -Location "West US" -PartitionCount 3 -ReplicaCount 3 -HostingMode Default
Les résultats se présentent comme suit.
ResourceGroupName : demo-westus
Name : my-demo-searchapp
Id : /subscriptions/<alphanumeric-subscription-ID>/demo-westus/providers/Microsoft.Search/searchServices/my-demo-searchapp
Location : West US
Sku : Standard
ReplicaCount : 3
PartitionCount : 3
HostingMode : Default
Tags
Remove-AzSearchService permet de supprimer un service et ses données.
Remove-AzSearchService -ResourceGroupName <resource-group-name> -Name <search-service-name>
Vous êtes invité à confirmer l’action.
Confirm
Are you sure you want to remove Search Service 'pstestazuresearch01'?
[Y] Yes [N] No [S] Suspend [?] Help (default is "Y"): y
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, commencez par définir les règles IP, puis passez-les au paramètre IPRuleList comme indiqué ci-dessous.
$ipRules = @([pscustomobject]@{Value="55.5.63.73"},
[pscustomobject]@{Value="52.228.215.197"},
[pscustomobject]@{Value="101.37.221.205"})
New-AzSearchService -ResourceGroupName <resource-group-name> `
-Name <search-service-name> `
-Sku Standard `
-Location "West US" `
-PartitionCount 3 -ReplicaCount 3 `
-HostingMode Default `
-IPRuleList $ipRules
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 -IdentityType SystemAssigned à la commande.
New-AzSearchService -ResourceGroupName <resource-group-name> `
-Name <search-service-name> `
-Sku Standard `
-Location "West US" `
-PartitionCount 3 -ReplicaCount 3 `
-HostingMode Default `
-IdentityType SystemAssigned
Créer un service S3HD
Pour créer un service S3HD, une combinaison de -Sku et de -HostingMode est utilisée. Définissez -Sku sur Standard3 et -HostingMode sur HighDensity.
New-AzSearchService -ResourceGroupName <resource-group-name> `
-Name <search-service-name> `
-Sku Standard3 `
-Location "West US" `
-PartitionCount 1 -ReplicaCount 3 `
-HostingMode HighDensity
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, consultez 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.
$searchService = New-AzSearchService `
-ResourceGroupName <search-service-resource-group-name> `
-Name <search-service-name> `
-Sku Standard `
-Location "West US" `
-PartitionCount 1 -ReplicaCount 1 `
-HostingMode Default `
-PublicNetworkAccess Disabled
Ensuite, créez un réseau virtuel, une connexion réseau privée et le point de terminaison privé.
# Create the subnet
$subnetConfig = New-AzVirtualNetworkSubnetConfig `
-Name <subnet-name> `
-AddressPrefix 10.1.0.0/24 `
-PrivateEndpointNetworkPolicies Disabled
# Create the virtual network
$virtualNetwork = New-AzVirtualNetwork `
-ResourceGroupName <vm-resource-group-name> `
-Location "West US" `
-Name <virtual-network-name> `
-AddressPrefix 10.1.0.0/16 `
-Subnet $subnetConfig
# Create the private network connection
$privateLinkConnection = New-AzPrivateLinkServiceConnection `
-Name <private-link-name> `
-PrivateLinkServiceId $searchService.Id `
-GroupId searchService
# Create the private endpoint
$privateEndpoint = New-AzPrivateEndpoint `
-Name <private-endpoint-name> `
-ResourceGroupName <private-endpoint-resource-group-name> `
-Location "West US" `
-Subnet $virtualNetwork.subnets[0] `
-PrivateLinkServiceConnection $privateLinkConnection
Enfin, créez une zone DNS privée.
## Create private dns zone
$zone = New-AzPrivateDnsZone `
-ResourceGroupName <private-dns-resource-group-name> `
-Name "privatelink.search.windows.net"
## Create dns network link
$link = New-AzPrivateDnsVirtualNetworkLink `
-ResourceGroupName <private-dns-link-resource-group-name> `
-ZoneName "privatelink.search.windows.net" `
-Name "myLink" `
-VirtualNetworkId $virtualNetwork.Id
## Create DNS configuration
$config = New-AzPrivateDnsZoneConfig `
-Name "privatelink.search.windows.net" `
-PrivateDnsZoneId $zone.ResourceId
## Create DNS zone group
New-AzPrivateDnsZoneGroup `
-ResourceGroupName <private-dns-zone-resource-group-name> `
-PrivateEndpointName <private-endpoint-name> `
-Name 'myZoneGroup' `
-PrivateDnsZoneConfig $config
Pour plus d’informations sur la création de points de terminaison privés dans PowerShell, consultez ce démarrage rapide Private Link.
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 (Get), définir (Set) et supprimer (Remove) cette connexion.
Get-AzSearchPrivateEndpointConnection est utilisé pour récupérer une connexion de point de terminaison privé et pour voir son état.
Get-AzSearchPrivateEndpointConnection -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name>
Set-AzSearchPrivateEndpointConnection est utilisé pour mettre à jour la connexion. L’exemple suivant montre comment rejeter une connexion de point de terminaison privé :
Set-AzSearchPrivateEndpointConnection -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <pe-connection-name> -Status Rejected -Description "Rejected"
Remove-AzSearchPrivateEndpointConnection est utilisé pour supprimer la connexion de point de terminaison privé.
Remove-AzSearchPrivateEndpointConnection -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <pe-connection-name>
Régénération des clés d’administration
New- AzSearchAdminKey permet de substituer les clés API d'administration. 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.
New-AzSearchAdminKey -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -KeyKind 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.
Primary Secondary
------- ---------
<alphanumeric-guid> <alphanumeric-guid>
Créer ou supprimer des clés de requête
New-AzSearchQueryKey permet de créer des clés API de requête pour un accès en lecture seule à partir d’applications clientes à un index Azure AI Recherche. 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.
New-AzSearchQueryKey -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <query-key-name>
Mettre à l'échelle des réplicas et des partitions
Set-AzSearchService permet d'augmenter ou de diminuer les réplicas et les partitions pour réajuster les ressources facturables de votre service. 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.
Set-AzSearchService -ResourceGroupName <search-service-resource-group-name> -Name <search-service-name> -PartitionCount 6 -ReplicaCount 6
Les résultats se présentent comme suit.
ResourceGroupName : demo-westus
Name : my-demo-searchapp
Location : West US
Sku : Standard
ReplicaCount : 6
PartitionCount : 6
HostingMode : Default
Id : /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/demo-westus/providers/Microsoft.Search/searchServices/my-demo-searchapp
Créer une ressource de liaison privée partagée
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 d’Azure AI Recherche, ainsi que les valeurs d’ID de groupe associées, cliquez ici.
New-AzSearchSharedPrivateLinkResource est utilisé pour créer la ressource de liaison privée partagée. N’oubliez pas que certaines configurations peuvent être requises pour la source de données avant d’exécuter cette commande.
New-AzSearchSharedPrivateLinkResource -ResourceGroupName <search-serviceresource-group-name> -ServiceName <search-service-name> -Name <spl-name> -PrivateLinkResourceId /subscriptions/<alphanumeric-subscription-ID>/resourceGroups/<storage-resource-group-name>/providers/Microsoft.Storage/storageAccounts/myBlobStorage -GroupId <group-id> -RequestMessage "Please approve"
Get-AzSearchSharedPrivateLinkResource vous permet de récupérer les ressources de liaisons privées partagées et d’afficher leur état.
Get-AzSearchSharedPrivateLinkResource -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <spl-name>
Vous devez approuver la connexion avec la commande suivante pour pouvoir être utilisée.
Approve-AzPrivateEndpointConnection `
-Name <spl-name> `
-ServiceName <search-service-name> `
-ResourceGroupName <search-service-resource-group-name> `
-Description = "Approved"
Remove-AzSearchSharedPrivateLinkResource est utilisé pour supprimer la ressource de liaison privée partagée.
$job = Remove-AzSearchSharedPrivateLinkResource -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <spl-name> -Force -AsJob
$job | Get-Job
Pour plus d’informations sur la configuration des ressources de liaisons privées partagées, consultez la documentation relative à la création de 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.