Partilhar via

Gerenciar seu serviço Azure AI Search usando 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:

Ocasionalmente, são feitas perguntas sobre tarefas que não estão na lista acima.

Não é possível alterar o nome ou a região de um serviço programaticamente ou no portal do Azure. Recursos dedicados são alocados quando um serviço é criado, portanto, alterar o hardware subjacente (local ou tipo de nó) requer um novo serviço.

Observação

As APIs REST de Gerenciamento de Pesquisa e o portal do Azure oferecem suporte à alteração de sua camada de preços. Atualmente, você só pode alternar entre as camadas Basic e Standard (S1, S2 e S3).

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 visualização de administração normalmente não estão disponíveis no módulo Az.Search. Se quiseres usar uma funcionalidade de pré-visualização, usa a API REST de gestão e uma versão prévia da API.

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 um principal 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. Caso não saiba quantos serviços de pesquisa foram já criados, estes comandos devolverão essas informações, evitando ter de ir ao portal do Azure.

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 de Az.Search ser importado e de saber o grupo de recursos que contém o serviço de pesquisa, execute Get-AzSearchService para retornar a definição do serviço, incluindo o nome, a região, a camada e 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 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

Pontos Finais Privados para a Pesquisa de IA do Azure permitem que um cliente numa rede virtual aceda com segurança aos dados num í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 da rede virtual para o 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 Criação de um ponto de extremidade privado do Azure AI Search.

O exemplo seguinte mostra como criar um serviço de pesquisa com um endpoint 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 Quickstart do Private Link.

Gerir conexões de pontos finais privados

Além de criar uma conexão de ponto de extremidade privada, você também pode Get, Set e Remove a conexão.

Get-AzSearchPrivateEndpointConnection é utilizado para recuperar uma ligação de ponto de extremidade privada e ver o seu estado.

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 alternar 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 uma de cada vez, especificada como a chave primary ou secondary. Para um serviço ininterrupto, lembre-se de atualizar todo o código de cliente para usar uma chave secundária ao substituir 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. A regeneração de todas as novas chaves não o bloqueia permanentemente do seu serviço e ainda pode aceder ao serviço através do portal do Azure. 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 ser usada pelo Azure AI Search. 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 de leitura a partir 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 o custo na 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 monitorização na página do portal Visão Geral tem painéis sobre latência das consultas, 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/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/demo-westus/providers/Microsoft.Search/searchServices/my-demo-searchapp

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 onde pode criar pontos finais privados de saída a partir do Azure AI Search 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 informações completas sobre a configuração de recursos de link privado compartilhado, consulte a documentação sobre estabelecer conexões de indexadores através de um ponto de extremidade privado.

Próximos passos

Crie um índice, consulte um índice usando o portal do Azure, APIs REST ou o SDK do .NET.

  • Last updated on