Gerencie o serviço Pesquisa de IA do Azure com o PowerShell
É possível executar cmdlets e scripts do PowerShell no Windows, no Linux ou no Azure Cloud Shell para criar e configurar a Pesquisa de IA do Azure.
Use o módulo Az.Search para realizar as seguintes tarefas:
- Listar serviços de pesquisa em uma assinatura
- Retornar informações do serviço
- Criar ou excluir um serviço
- Criar um serviço com um ponto de extremidade privado
- Regenerar chaves de API de administrador
- Criar ou excluir chaves de API de consulta
- Escalar ou reduzir verticalmente com réplicas e partições
- Criar um recurso de link privado compartilhado
Às vezes, surgem dúvidas sobre as tarefas que não estão na lista acima.
Não é possível alterar um nome de servidor, região ou camada de forma programática ou no portal. Os recursos dedicados são alocados quando um serviço é criado. Assim, a alteração do hardware subjacente (localização ou tipo de nó) exige 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 é executada por meio da API REST do serviço Pesquisa ou do 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 clientes para criar e carregar índices em um novo serviço.
As versões prévias de recursos de administração normalmente não estão disponíveis no módulo Az.Search. Se você quiser usar uma versão prévia do recurso, use a API REST de Gerenciamento e uma versão da API de versão prévia.
O módulo Az.Search estende o Azure PowerShell com paridade total para as versões estáveis das APIs REST do Gerenciamento de Pesquisa.
Verificar versões e carregar módulos
Os exemplos deste artigo são interativos e exigem obter permissões elevadas. O PowerShell local e o Azure PowerShell (o módulo Az) são necessários.
Verificar versão do PowerShell
Instale a versão mais recente do PowerShell se não a tiver.
$PSVersionTable.PSVersion
Carregar o Azure PowerShell
Se não tiver certeza se o módulo Az está instalado, execute o comando a seguir como uma etapa de verificação.
Get-InstalledModule -Name Az
Alguns sistemas não recarregam os módulos automaticamente. Caso receba um erro no comando anterior, tente carregar o módulo. Se isso não der certo, volte para as instruções de instalação do Azure PowerShell da instalação para ver se você pulou uma etapa.
Import-Module -Name Az
Conectar-se ao Azure com um token de logon de navegador
É possível usar credenciais de entrada do portal para se conectar a uma assinatura no PowerShell. Como alternativa, é possível executar uma autenticação de modo não interativo com uma entidade de serviço.
Connect-AzAccount
Caso tenha várias assinaturas do Azure, defina uma assinatura do Azure. Para ver uma lista de suas assinaturas atuais, execute este comando.
Get-AzSubscription | sort SubscriptionName | Select SubscriptionName
Para especificar a assinatura, execute o comando a seguir. 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 do Az.Resources, eles retornam informações sobre recursos e serviços existentes que já foram provisionados em sua assinatura. Se você não souber quantos serviços de pesquisa já foram criados, os comandos retornarão essas informações, sem a necessidade de acessar o portal.
O primeiro comando retorna todos os serviços de pesquisa.
Get-AzResource -ResourceType Microsoft.Search/searchServices | ft
Ele retornará informações da lista de serviços sobre um recurso específico.
Get-AzResource -ResourceName <service-name>
Os resultados devem ser semelhantes à saída 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
Importe Az.Search.
Os comandos do Az.Search só ficarão disponíveis quando você carregar o módulo.
Install-Module -Name Az.Search -Scope CurrentUser
Listar todos os comandos Az.Search
Como etapa de verificação, retorne uma lista de comandos fornecidos pelo módulo.
Get-Command -Module Az.Search
Os resultados devem ser semelhantes à saída 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
Caso tenha uma versão anterior 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
Após importar o módulo Az.Search e identificar o grupo de recursos que contém o serviço Pesquisa, execute Get-AzSearchService para retornar a definição de serviço, incluindo: o nome, a região, a camada, bem como as 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 à saída 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 excluir um serviço
O New-AzSearchService é usado para criar um serviço 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 à saída 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ê precisará 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, o ideal será criar um serviço de pesquisa com um firewall de IP configurado. Nesse caso, primeiro defina as Regras de IP e as envie ao parâmetro IPRuleList, conforme 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, será preciso ativar a identidade gerenciada atribuída pelo sistema. Isso é feito pela adição de -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, é usada uma combinação de -Sku e -HostingMode. Defina -Sku para 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 da Pesquisa de IA do Azure permitem que um cliente em uma rede virtual acesse dados com segurança em um índice de pesquisa por um Link Privado. O ponto de extremidade privado usa um endereço IP do espaço de endereço da rede virtual para o serviço de pesquisa. O tráfego de rede entre o cliente e o serviço de pesquisa atravessa a rede virtual e o link privado na rede de backbone da Microsoft, eliminando a exposição na Internet pública. Para obter mais informações, confira Como criar um ponto de extremidade privado para a Pesquisa de IA do Azure.
O exemplo a seguir mostra como criar um serviço de pesquisa com um ponto de extremidade privado.
Primeiro, implante um serviço Pesquisa usando 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
Depois, crie uma rede virtual, uma conexão de rede privada e um 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
Por fim, 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, confira este Início Rápido do Link Privado.
Gerenciar conexões de ponto de extremidade privado
Além de criar uma conexão de ponto de extremidade privado, você também pode executar Get, Set e Remove na conexão.
O Get-AzSearchPrivateEndpointConnection é usado para recuperar uma conexão de ponto de extremidade privado e conferir o respectivo status.
Get-AzSearchPrivateEndpointConnection -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name>
O Set-AzSearchPrivateEndpointConnection é usado para atualizar a conexão. O seguinte exemplo define uma conexão de ponto de extremidade privado como rejeitada:
Set-AzSearchPrivateEndpointConnection -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <pe-connection-name> -Status Rejected -Description "Rejected"
O Remove-AzSearchPrivateEndpointConnection é usado para excluir a conexão do ponto de extremidade privado.
Remove-AzSearchPrivateEndpointConnection -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <pe-connection-name>
Regenerar chaves de administrador
O New-AzSearchAdminKey é usado para reverter as Chaves de API de administração. Duas chaves de administração são criadas com cada serviço para o acesso autenticado. As chaves são necessárias em cada solicitação. As duas chaves de administração são funcionalmente equivalentes, permitindo 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 uma de cada vez, especificado como a chave primary ou secondary. Para o serviço ininterrupto, lembre-se de atualizar todo o código do cliente para que ele use uma chave secundária ao sobrepor a chave primária. Evite alterar as chaves enquanto as operações estiverem em trânsito.
Como você deve esperar, se você regenerar as chaves sem atualizar o código do cliente, as solicitações que usam a chave antiga falharão. A regeneração de todas as novas chaves não bloqueia você permanentemente do serviço. Você ainda poderá acessá-lo por meio do portal. Depois de regenerar as chaves primárias e secundárias, você poderá 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 uso da Pesquisa de IA do Azure. Da mesma forma, não há nenhum nome definido pelo usuário para as chaves de API de administrador. As referências à chave são cadeias de caracteres fixas: primary ou secondary.
New-AzSearchAdminKey -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -KeyKind Primary
Os resultados devem ser semelhantes à saída a seguir. As duas chaves são retornadas, mesmo que você altere apenas uma por vez.
Primary Secondary
------- ---------
<alphanumeric-guid> <alphanumeric-guid>
Criar ou excluir chaves de consulta
O New-AzSearchQueryKey é usado para criar chaves de API de consulta para permitir acesso somente leitura de aplicativos cliente a um índice da Pesquisa de IA do Azure. As chaves de consulta são usadas para autenticação em um índice específico para recuperar os resultados da pesquisa. Elas não permitem o acesso somente leitura a outros itens no serviço, como um índice, uma fonte de dados ou um indexador.
Não é possível fornecer uma chave para uso pela Pesquisa de IA do Azure. 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>
Escalar réplicas e partições
O Set-AzSearchService é usado para aumentar ou diminuir réplicas e partições a fim de reajustar recursos faturáveis em seu serviço. O aumento de réplicas ou de partições adiciona custos à sua fatura, que tem custos fixos e variáveis. Se você tiver uma necessidade temporária de mais capacidade de processamento, aumente as réplicas e as partições para lidar com a carga de trabalho. A área de monitoramento na página Visão geral do portal tem blocos de latência de consulta, consultas por segundo e limitação, indicando se a capacidade atual é adequada.
Pode levar algum tempo para adicionar ou remover a alocação de recursos. Os ajustes na capacidade ocorrem em segundo plano, permitindo a continuação das cargas de trabalho existentes. A capacidade adicional é usada para as solicitações de entrada assim que ela fica pronta, sem a necessidade de configuração extra.
A remoção da capacidade pode causar interrupções. Recomendamos interromper todos os trabalhos de indexação e do indexador antes de reduzir a capacidade a fim de evitar a remoção de solicitações. Se isso não for viável, considere a possibilidade de reduzir a capacidade de modo incremental, uma réplica e uma partição de cada vez, até que os novos níveis de destino sejam atingidos.
Depois que você enviar o comando, não será possível terminá-lo no meio do processo. Você precisará aguardar até que o comando seja concluído para revisar as contagens.
Set-AzSearchService -ResourceGroupName <search-service-resource-group-name> -Name <search-service-name> -PartitionCount 6 -ReplicaCount 6
Os resultados devem ser semelhantes à saída a seguir.
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
Criar um recurso de link privado compartilhado
Os pontos de extremidade privados de recursos protegidos que são criados por meio das APIs da Pesquisa de IA do Azure são chamados de recursos de link privado compartilhados. Isso 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 na Pesquisa de IA do Azure e a fonte de dados estiver em uma rede privada, crie uma conexão de ponto de extremidade privado de saída para acessar os dados.
Encontre aqui 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, junto com os valores de ID de grupo relacionados.
O New-AzSearchSharedPrivateLinkResource é usado para criar um recurso compartilhado de link privado. Tenha em mente que algumas configurações podem ser necessárias para a fonte de dados antes da execução desse 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"
O Get-AzSearchSharedPrivateLinkResource permite recuperar recursos compartilhados de link privado e exibir o respectivo status.
Get-AzSearchSharedPrivateLinkResource -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <spl-name>
Você precisará aprovar a conexão com o comando a seguir para que ela possa ser usada.
Approve-AzPrivateEndpointConnection `
-Name <spl-name> `
-ServiceName <search-service-name> `
-ResourceGroupName <search-service-resource-group-name> `
-Description = "Approved"
O Remove-AzSearchSharedPrivateLinkResource é usado para excluir o recurso compartilhado de link privado.
$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 compartilhados, confira a documentação sobre como fazer conexões do indexador por meio de um ponto de extremidade privado.
Próximas etapas
Crie um índice e consulte um índice usando o portal, as APIs REST ou o SDK do .NET.