Gerenciar seu serviço Azure AI Search com o PowerShell
Você pode executar cmdlets e scripts do PowerShell no Windows, Linux ou no Azure Cloud Shell para criar e configurar o Azure AI Search.
Use o módulo Az.Search para executar as seguintes tarefas:
- Listar serviços de pesquisa em uma assinatura
- Informações sobre o serviço de devolução
- Criar ou excluir um serviço
- Criar um serviço com um ponto de extremidade privado
- Regenerar chaves de API de administração
- Criar ou excluir chaves de api de consulta
- Aumente ou diminua a escala com réplicas e partições
- Criar um recurso de link privado compartilhado
Ocasionalmente, são feitas perguntas sobre tarefas que não estão na lista acima.
Não é possível alterar um nome de servidor, região ou camada programaticamente ou no portal. Os recursos dedicados são alocados quando um serviço é criado. Como tal, alterar o hardware subjacente (local ou tipo de nó) requer um novo serviço.
Não é possível usar ferramentas ou APIs para transferir conteúdo, como um índice, de um serviço para outro. Dentro de um serviço, a criação programática de conteúdo é feita por meio da API REST do Serviço de Pesquisa ou de um SDK, como o SDK do Azure para .NET. Embora não haja comandos dedicados para a migração de conteúdo, você pode escrever um script que chame a API REST ou uma biblioteca de cliente para criar e carregar índices em um novo serviço.
Os recursos de administração de visualização normalmente não estão disponíveis no módulo Az.Search . Se você quiser usar um recurso de visualização, use a API REST de gerenciamento e uma versão da API de visualização.
O módulo Az.Search estende o Azure PowerShell com paridade total para as versões estáveis das APIs REST de Gerenciamento de Pesquisa.
Verificar versões e carregar módulos
Os exemplos neste artigo são interativos e exigem permissões elevadas. O PowerShell local e o Azure PowerShell (o módulo Az ) são necessários.
Verificação de versão do PowerShell
Instale a versão mais recente do PowerShell se não a tiver.
$PSVersionTable.PSVersion
Carregar o Azure PowerShell
Se você não tiver certeza se o Az está instalado, execute o seguinte comando como uma etapa de verificação.
Get-InstalledModule -Name Az
Alguns sistemas não carregam módulos automaticamente. Se você tiver um erro no comando anterior, tente carregar o módulo e, se isso falhar, volte para as instruções de instalação do Azure PowerShell de instalação para ver se você perdeu uma etapa.
Import-Module -Name Az
Conectar-se ao Azure com um token de entrada do navegador
Você pode usar suas credenciais de entrada no portal para se conectar a uma assinatura no PowerShell. Como alternativa, você pode autenticar de forma não interativa com uma entidade de serviço.
Connect-AzAccount
Se você tiver várias assinaturas do Azure, defina sua assinatura do Azure. Para ver uma lista das suas subscrições atuais, execute este comando.
Get-AzSubscription | sort SubscriptionName | Select SubscriptionName
Para especificar a assinatura, execute o seguinte comando. No exemplo a seguir, o nome da assinatura é ContosoSubscription.
Select-AzSubscription -SubscriptionName ContosoSubscription
Listar serviços em uma assinatura
Os comandos a seguir são de Az.Resources, retornando informações sobre recursos e serviços existentes já provisionados em sua assinatura. Se não souber quantos serviços de pesquisa já foram criados, estes comandos devolvem essa informação, poupando-lhe uma viagem ao portal.
O primeiro comando retorna todos os serviços de pesquisa.
Get-AzResource -ResourceType Microsoft.Search/searchServices | ft
Na lista de serviços, retorne informações sobre um recurso específico.
Get-AzResource -ResourceName <service-name>
Os resultados devem ser semelhantes aos resultados a seguir.
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
Importação Az.Search
Os comandos do Az.Search não estarão disponíveis até que você carregue o módulo.
Install-Module -Name Az.Search -Scope CurrentUser
Listar todos os Az.Search comandos
Como etapa de verificação, retorne uma lista de comandos fornecidos no módulo.
Get-Command -Module Az.Search
Os resultados devem ser semelhantes aos resultados a seguir.
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
Se você tiver uma versão mais antiga do pacote, atualize o módulo para obter a funcionalidade mais recente.
Update-Module -Name Az.Search
Obter informações do serviço de pesquisa
Depois que Az.Search for importado e você souber o grupo de recursos que contém seu serviço de pesquisa, execute Get-AzSearchService para retornar a definição de serviço, incluindo nome, região, camada e contagens de réplica e partição. Para este comando, forneça o grupo de recursos que contém o serviço de pesquisa.
Get-AzSearchService -ResourceGroupName <resource-group-name>
Os resultados devem ser semelhantes aos resultados a seguir.
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
Criar ou eliminar um serviço
New-AzSearchService é usado para criar um novo serviço de pesquisa.
New-AzSearchService -ResourceGroupName <resource-group-name> -Name <search-service-name> -Sku "Standard" -Location "West US" -PartitionCount 3 -ReplicaCount 3 -HostingMode Default
Os resultados devem ser semelhantes aos resultados a seguir.
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 é usado para excluir um serviço e seus dados.
Remove-AzSearchService -ResourceGroupName <resource-group-name> -Name <search-service-name>
Você será solicitado a confirmar a ação.
Confirm
Are you sure you want to remove Search Service 'pstestazuresearch01'?
[Y] Yes [N] No [S] Suspend [?] Help (default is "Y"): y
Criar um serviço com regras de IP
Dependendo dos seus requisitos de segurança, convém criar um serviço de pesquisa com um firewall IP configurado. Para fazer isso, primeiro defina as regras de IP e, em seguida, passe-as para o IPRuleList parâmetro como mostrado abaixo.
$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
Criar um serviço com uma identidade gerenciada atribuída ao sistema
Em alguns casos, como ao usar a identidade gerenciada para se conectar a uma fonte de dados, você precisa ativar a identidade gerenciada atribuída ao sistema. Isso é feito adicionando -IdentityType SystemAssigned ao comando.
New-AzSearchService -ResourceGroupName <resource-group-name> `
-Name <search-service-name> `
-Sku Standard `
-Location "West US" `
-PartitionCount 3 -ReplicaCount 3 `
-HostingMode Default `
-IdentityType SystemAssigned
Criar um serviço S3HD
Para criar um serviço S3HD , uma combinação de -Sku e -HostingMode é usada. Defina -Sku como Standard3 e -HostingMode para HighDensity.
New-AzSearchService -ResourceGroupName <resource-group-name> `
-Name <search-service-name> `
-Sku Standard3 `
-Location "West US" `
-PartitionCount 1 -ReplicaCount 3 `
-HostingMode HighDensity
Criar um serviço com um ponto de extremidade privado
Os Pontos de Extremidade Privados para a Pesquisa de IA do Azure permitem que um cliente em uma rede virtual acesse com segurança os dados em um índice de pesquisa por meio de um Link Privado. O ponto de extremidade privado usa um endereço IP do espaço de endereço de rede virtual para seu serviço de pesquisa. O tráfego de rede entre o cliente e o serviço de pesquisa atravessa a rede virtual e um link privado na rede de backbone da Microsoft, eliminando a exposição da Internet pública. Para obter mais informações, consulte Criando um ponto de extremidade privado para o Azure AI Search.
O exemplo a seguir mostra como criar um serviço de pesquisa com um ponto de extremidade privado.
Primeiro, implante um serviço de pesquisa com PublicNetworkAccess definido como 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
Em seguida, crie uma rede virtual, uma conexão de rede privada e o ponto de extremidade privado.
# 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
Finalmente, crie uma zona DNS privada.
## 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
Para obter mais informações sobre como criar pontos de extremidade privados no PowerShell, consulte este Guia de início rápido de link privado.
Gerir ligações de pontos finais privados
Além de criar uma conexão de ponto de extremidade privada, você também Getpode , Sete Remove a conexão.
Get-AzSearchPrivateEndpointConnection é usado para recuperar uma conexão de ponto de extremidade privada e ver seu status.
Get-AzSearchPrivateEndpointConnection -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name>
Set-AzSearchPrivateEndpointConnection é usado para atualizar a conexão. O exemplo a seguir define uma conexão de ponto de extremidade privada como rejeitada:
Set-AzSearchPrivateEndpointConnection -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <pe-connection-name> -Status Rejected -Description "Rejected"
Remove-AzSearchPrivateEndpointConnection é usado para excluir a conexão de ponto de extremidade privado.
Remove-AzSearchPrivateEndpointConnection -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <pe-connection-name>
Regenerar chaves de administrador
New-AzSearchAdminKey é usado para rolar chaves de API de administração. Duas chaves de administrador são criadas com cada serviço para acesso autenticado. As chaves são necessárias em todos os pedidos. Ambas as chaves de administração são funcionalmente equivalentes, concedendo acesso total de gravação a um serviço de pesquisa com a capacidade de recuperar qualquer informação ou criar e excluir qualquer objeto. Existem duas chaves para que você possa usar uma enquanto substitui a outra.
Você só pode regenerar um de cada vez, especificado como a primary chave ou secondary . Para um serviço ininterrupto, lembre-se de atualizar todo o código do cliente para usar uma chave secundária ao rolar a chave primária. Evite trocar as chaves durante o voo.
Como seria de esperar, se regenerar chaves sem atualizar o código do cliente, os pedidos que utilizam a chave antiga falharão. Regenerar todas as novas chaves não o bloqueia permanentemente do seu serviço, e você ainda pode acessar o serviço através do portal. Depois de regenerar as chaves primária e secundária, você pode atualizar o código do cliente para usar as novas chaves e as operações serão retomadas de acordo.
Os valores para as chaves de API são gerados pelo serviço. Não é possível fornecer uma chave personalizada para o Azure AI Search usar. Da mesma forma, não há um nome definido pelo usuário para chaves de API de administrador. As referências à chave são cadeias de caracteres fixas, ou primarysecondary.
New-AzSearchAdminKey -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -KeyKind Primary
Os resultados devem ser semelhantes aos resultados a seguir. Ambas as chaves são devolvidas mesmo que você só mude uma de cada vez.
Primary Secondary
------- ---------
<alphanumeric-guid> <alphanumeric-guid>
Criar ou excluir chaves de consulta
New-AzSearchQueryKey é usado para criar chaves de API de consulta para acesso somente leitura de aplicativos cliente a um índice do Azure AI Search. As chaves de consulta são usadas para autenticar em um índice específico para recuperar resultados de pesquisa. As chaves de consulta não concedem acesso somente leitura a outros itens no serviço, como um índice, fonte de dados ou indexador.
Você não pode fornecer uma chave para o Azure AI Search usar. As chaves de API são geradas pelo serviço.
New-AzSearchQueryKey -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <query-key-name>
Dimensionar réplicas e partições
Set-AzSearchService é usado para aumentar ou diminuir réplicas e partições para reajustar recursos faturáveis dentro do seu serviço. Aumentar as réplicas ou partições aumenta a sua fatura, que tem encargos fixos e variáveis. Se você tiver uma necessidade temporária de mais poder de processamento, poderá aumentar as réplicas e partições para lidar com a carga de trabalho. A área de monitoramento na página do portal Visão geral tem blocos sobre latência de consulta, consultas por segundo e limitação, indicando se a capacidade atual é adequada.
Pode demorar algum tempo a adicionar ou remover recursos. Os ajustes na capacidade ocorrem em segundo plano, permitindo que as cargas de trabalho existentes continuem. A capacidade extra é usada para solicitações recebidas assim que estiver pronta, sem necessidade de configuração extra.
A remoção de capacidade pode causar interrupções. Recomenda-se interromper todos os trabalhos de indexação e indexador antes de reduzir a capacidade para evitar solicitações descartadas. Se isso não for viável, você pode considerar reduzir a capacidade incrementalmente, uma réplica e partição de cada vez, até que seus novos níveis de destino sejam atingidos.
Depois de enviar o comando, não há como encerrá-lo no meio do caminho. Você tem que esperar até que o comando seja concluído antes de revisar as contagens.
Set-AzSearchService -ResourceGroupName <search-service-resource-group-name> -Name <search-service-name> -PartitionCount 6 -ReplicaCount 6
Os resultados devem ser semelhantes aos resultados a seguir.
ResourceGroupName : demo-westus
Name : my-demo-searchapp
Location : West US
Sku : Standard
ReplicaCount : 6
PartitionCount : 6
HostingMode : Default
Id : /subscriptions/65a1016d-0f67-45d2-b838-b8f373d6d52e/resourceGroups/demo-westus/providers/Microsoft.Search/searchServices/my-demo-searchapp
Criar um recurso de link privado compartilhado
Os pontos de extremidade privados de recursos protegidos criados por meio das APIs de Pesquisa do Azure AI são chamados de recursos de link privado compartilhado. Isso ocorre porque você está "compartilhando" o acesso a um recurso, como uma conta de armazenamento que foi integrada ao serviço de Link Privado do Azure.
Se você estiver usando um indexador para indexar dados no Azure AI Search e sua fonte de dados estiver em uma rede privada, poderá criar uma conexão de ponto de extremidade privada de saída para acessar os dados.
Uma lista completa dos Recursos do Azure para os quais você pode criar pontos de extremidade privados de saída da Pesquisa de IA do Azure pode ser encontrada aqui, juntamente com os valores de ID de Grupo relacionados.
New-AzSearchSharedPrivateLinkResource é usado para criar o recurso de link privado compartilhado. Lembre-se de que alguma configuração pode ser necessária para a fonte de dados antes de executar este comando.
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 permite que você recupere os recursos de link privado compartilhado e visualize seu status.
Get-AzSearchSharedPrivateLinkResource -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <spl-name>
Você precisa aprovar a conexão com o seguinte comando antes que ele possa ser usado.
Approve-AzPrivateEndpointConnection `
-Name <spl-name> `
-ServiceName <search-service-name> `
-ResourceGroupName <search-service-resource-group-name> `
-Description = "Approved"
Remove-AzSearchSharedPrivateLinkResource é usado para excluir o recurso de link privado compartilhado.
$job = Remove-AzSearchSharedPrivateLinkResource -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <spl-name> -Force -AsJob
$job | Get-Job
Para obter detalhes completos sobre como configurar recursos de link privado compartilhado, consulte a documentação sobre como fazer conexões de indexador por meio de um ponto de extremidade privado.
Próximos passos
Crie um índice, consulte um índice usando o portal, APIs REST ou o SDK do .NET.