Lire en anglais

Partager via


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 :

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 de manière programmatique ou dans le Portail Azure. 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 Azure.

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 exclut pas définitivement de votre service, vous pouvez quand même accéder au service via le Portail Azure. 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

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érez un index, interrogez un index en tirant parti du Portail Azure, des API REST ou du Kit de développement logiciel (SDK) .NET.