Gerenciar o serviço Pesquisa de IA do Azure com a CLI do Azure

  • Artigo

Execute comandos e scripts da CLI do Azure no Windows, no macOS, no Linux ou no Azure Cloud Shell para criar e configurar a Pesquisa de IA do Azure.

Use o módulo az search para executar as seguintes tarefas:

À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.

Os recursos de administração de versão prévia 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.

Pré-requisitos

As versões da CLI do Azure estão listadas no GitHub.

O módulo az search estende a CLI do Azure com paridade total para as versões estáveis das APIs REST do Gerenciamento de Pesquisa.

Listar serviços em uma assinatura

Os comandos a seguir são do az resource, retornando informações sobre recursos e serviços existentes já provisionados na 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.

az resource list --resource-type Microsoft.Search/searchServices --output table

Ele retornará informações da lista de serviços sobre um recurso específico.

az resource list --name <search-service-name>

Listar todos os comandos do az search

Veja informações sobre os subgrupos e os comandos disponíveis no az search por meio da CLI. Como alternativa, examine a documentação.

Para ver os subgrupos disponíveis no az search, execute o comando a seguir.

az search --help

A resposta será parecida com a saída a seguir.

Group
    az search : Manage Azure Search services, admin keys and query keys.
        WARNING: This command group is in preview and under development. Reference and support
        levels: https://aka.ms/CLI_refstatus
Subgroups:
    admin-key                    : Manage Azure Search admin keys.
    private-endpoint-connection  : Manage Azure Search private endpoint connections.
    private-link-resource        : Manage Azure Search private link resources.
    query-key                    : Manage Azure Search query keys.
    service                      : Manage Azure Search services.
    shared-private-link-resource : Manage Azure Search shared private link resources.

For more specific examples, use: az find "az search"

Em cada subgrupo, vários comandos estão disponíveis. Veja os comandos disponíveis para o subgrupo service executando a linha a seguir.

az search service --help

Veja também os argumentos disponíveis para um comando específico.

az search service create --help

Obter informações do serviço de pesquisa

Se você souber o grupo de recursos que contém o serviço de pesquisa, execute az search service show para retornar a definição de serviço, incluindo o nome, a região, a camada e as contagens de réplicas e partições. Para este comando, forneça o grupo de recursos que contém o serviço de pesquisa.

az search service show --name <service-name> --resource-group <search-service-resource-group-name>

Criar ou excluir um serviço

Para criar um serviço de pesquisa, use o comando az search service create.

az search service create \
    --name <service-name> \
    --resource-group <search-service-resource-group-name> \
    --sku Standard \
    --partition-count 1 \
    --replica-count 1

Os resultados serão parecidos com a seguinte saída:

{
  "hostingMode": "default",
  "id": "/subscriptions/<alphanumeric-subscription-ID>/resourceGroups/demo-westus/providers/Microsoft.Search/searchServices/my-demo-searchapp",
  "identity": null,
  "location": "West US",
  "name": "my-demo-searchapp",
  "networkRuleSet": {
    "bypass": "None",
    "ipRules": []
  },
  "partitionCount": 1,
  "privateEndpointConnections": [],
  "provisioningState": "succeeded",
  "publicNetworkAccess": "Enabled",
  "replicaCount": 1,
  "resourceGroup": "demo-westus",
  "sharedPrivateLinkResources": [],
  "sku": {
    "name": "standard"
  },
  "status": "running",
  "statusDetails": "",
  "tags": null,
  "type": "Microsoft.Search/searchServices"
}

az search service delete remove o serviço e seus dados.

az search service delete --name <service-name> \
                         --resource-group  <search-service-resource-group-name> \

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. Para fazer isso, transmita os endereços IP públicos (v4) ou os intervalos CIDR para o argumento ip-rules, conforme mostrado abaixo. As regras devem ser separadas por uma vírgula (,) ou um ponto e vírgula (;).

az search service create \
    --name <search-service-name> \
    --resource-group <search-service-resource-group-name> \
    --sku Standard \
    --partition-count 1 \
    --replica-count 1 \
    --ip-rules "55.5.63.73;52.228.215.197;101.37.221.205"

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 --identity-type SystemAssigned ao comando.

az search service create \
    --name <search-service-name> \
    --resource-group <search-service-resource-group-name> \
    --sku Standard \
    --partition-count 1 \
    --replica-count 1 \
    --identity-type SystemAssigned

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 a documentação sobre 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.

az search service create \
    --name <search-service-name> \
    --resource-group <search-service-resource-group-name> \
    --sku Standard \
    --partition-count 1 \
    --replica-count 1 \
    --public-access Disabled

Em seguida, crie uma rede virtual e o ponto de extremidade privado.

# Create the virtual network
az network vnet create \
    --resource-group <vnet-resource-group-name> \
    --location "West US" \
    --name <virtual-network-name> \
    --address-prefixes 10.1.0.0/16 \
    --subnet-name <subnet-name> \
    --subnet-prefixes 10.1.0.0/24

# Update the subnet to disable private endpoint network policies
az network vnet subnet update \
    --name <subnet-name> \
    --resource-group <vnet-resource-group-name> \
    --vnet-name <virtual-network-name> \
    --disable-private-endpoint-network-policies true

# Get the id of the search service
id=$(az search service show \
    --resource-group <search-service-resource-group-name> \
    --name <search-service-name> \
    --query [id] \
    --output tsv)

# Create the private endpoint
az network private-endpoint create \
    --name <private-endpoint-name> \
    --resource-group <private-endpoint-resource-group-name> \
    --vnet-name <virtual-network-name> \
    --subnet <subnet-name> \
    --private-connection-resource-id $id \
    --group-id searchService \
    --connection-name <private-link-connection-name>

Por fim, crie uma zona DNS privada.

## Create private DNS zone
az network private-dns zone create \
    --resource-group <private-dns-resource-group-name> \
    --name "privatelink.search.windows.net"

## Create DNS network link
az network private-dns link vnet create \
    --resource-group <private-dns-resource-group-name> \
    --zone-name "privatelink.search.windows.net" \
    --name "myLink" \
    --virtual-network <virtual-network-name> \
    --registration-enabled false

## Create DNS zone group
az network private-endpoint dns-zone-group create \
   --resource-group <private-endpoint-resource-group-name>\
   --endpoint-name <private-endpoint-name> \
   --name "myZoneGroup" \
   --private-dns-zone "privatelink.search.windows.net" \
   --zone-name "searchServiceZone"

Para obter mais informações sobre como criar pontos de extremidade privados na CLI do Azure, confira este Guia de 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 show, update e delete na conexão.

Para recuperar uma conexão de ponto de extremidade privado e ver o status dele, use az search private-endpoint-connection show.

az search private-endpoint-connection show \
    --name <pe-connection-name> \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name>

Para atualizar a conexão, use az search private-endpoint-connection update. O seguinte exemplo define uma conexão de ponto de extremidade privado como rejeitada:

az search private-endpoint-connection update \
    --name <pe-connection-name> \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name> 
    --status Rejected \
    --description "Rejected" \
    --actions-required "Please fix XYZ"

Para excluir a conexão de ponto de extremidade privado, use az search private-endpoint-connection delete.

az search private-endpoint-connection delete \
    --name <pe-connection-name> \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name>

Regenerar chaves de administrador

Para sobrepor as chaves de API de administração, use az search admin-key renew. 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.

az search admin-key renew \
    --resource-group <search-service-resource-group-name> \
    --service-name <search-service-name> \
    --key-kind primary

Os resultados devem ser semelhantes à saída a seguir. As duas chaves são retornadas, mesmo que você altere apenas uma por vez.

{
  "primaryKey": <alphanumeric-guid>,
  "secondaryKey": <alphanumeric-guid>  
}

Criar ou excluir chaves de consulta

Para criar chaves de API de consulta para acesso somente leitura em aplicativos cliente a um índice da a Pesquisa de IA do Azure, use az search query-key create. 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.

az search query-key create \
    --name myQueryKey \
    --resource-group <search-service-resource-group-name> \
    --service-name <search-service-name>

Escalar réplicas e partições

Para aumentar ou diminuir réplicas e partições, use az search service update. 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.

az search service update \
    --name <search-service-name> \
    --resource-group <search-service-resource-group-name> \
    --partition-count 6 \
    --replica-count 6

Além de atualizar as contagens de réplica e de partição, atualize ip-rules, public-access e identity-type.

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.

Para criar o recurso de link privado compartilhado, use az search shared-private-link-resource create. Tenha em mente que algumas configurações podem ser necessárias para a fonte de dados antes da execução desse comando.

az search shared-private-link-resource create \
    --name <spl-name> \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name> \
    --group-id blob \
    --resource-id "/subscriptions/<alphanumeric-subscription-ID>/resourceGroups/<resource-group-name>/providers/Microsoft.Storage/storageAccounts/myBlobStorage"  \
    --request-message "Please approve"

Para recuperar os recursos de link privado compartilhados e ver o status deles, use az search shared-private-link-resource list.

az search shared-private-link-resource list \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name>

Você precisará aprovar a conexão com o comando a seguir para que ela possa ser usada. A ID da conexão de ponto de extremidade privado deve ser recuperada do recurso filho. Nesse caso, obtemos a ID de conexão com az storage.

id = (az storage account show -n myBlobStorage --query "privateEndpointConnections[0].id")

az network private-endpoint-connection approve --id $id

Para excluir o recurso de link privado compartilhado, use az search shared-private-link-resource delete.

az search shared-private-link-resource delete \
    --name <spl-name> \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name>

Para obter mais informações sobre como configurar recursos de link privado compartilhados, consulte como fazer conexões de 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.