Gerenciar seu serviço Azure AI Search com a CLI do Azure

  • Artigo

Você pode executar comandos e scripts da CLI do Azure no Windows, macOS, 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 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 de pesquisa az. Se você quiser usar um recurso de visualização, use a API REST de gerenciamento e uma versão da API de visualização.

Pré-requisitos

  • Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, consulte Guia de início rápido para Bash no Azure Cloud Shell.

  • Se preferir executar comandos de referência da CLI localmente, instale a CLI do Azure. Se estiver a utilizar o Windows ou macOS, considere executar a CLI do Azure num contentor Docker. Para obter mais informações, consulte Como executar a CLI do Azure em um contêiner do Docker.

    • Se estiver a utilizar uma instalação local, inicie sessão no CLI do Azure ao utilizar o comando az login. Para concluir o processo de autenticação, siga os passos apresentados no seu terminal. Para outras opções de entrada, consulte Entrar com a CLI do Azure.

    • Quando solicitado, instale a extensão da CLI do Azure na primeira utilização. Para obter mais informações sobre as extensões, veja Utilizar extensões com o CLI do Azure.

    • Execute o comando az version para localizar a versão e as bibliotecas dependentes instaladas. Para atualizar para a versão mais recente, execute o comando az upgrade.

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 de Gerenciamento de Pesquisa.

Listar serviços em uma assinatura

Os comandos a seguir são de az resource, 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.

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

Na lista de serviços, retorne informações sobre um recurso específico.

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

Listar todos os comandos az search

Você pode visualizar informações sobre os subgrupos e comandos disponíveis na pesquisa az de dentro da CLI. Em alternativa, pode rever a documentação.

Para exibir os subgrupos disponíveis no az search, execute o seguinte comando.

az search --help

A resposta deve ser semelhante à 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"

Dentro de cada subgrupo, vários comandos estão disponíveis. Você pode ver os comandos disponíveis para o service subgrupo executando a seguinte linha.

az search service --help

Você também pode ver 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 seu serviço de pesquisa, execute az search service show 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.

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

Criar ou eliminar um serviço

Para criar um novo 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 devem ser semelhantes aos seguintes resultados:

{
  "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, convém criar um serviço de pesquisa com um firewall IP configurado. Para fazer isso, passe os endereços IP públicos (v4) ou intervalos CIDR para o argumento, ip-rules conforme mostrado abaixo. As regras devem ser separadas por vírgula (,) ou 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, você precisa ativar a identidade gerenciada atribuída ao sistema. Isso é feito adicionando --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 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 a documentação sobre como criar 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.

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>

Finalmente, 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, 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 showpode , updatee delete a conexão.

Para recuperar uma conexão de ponto de extremidade privada e ver seu status, 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 exemplo a seguir define uma conexão de ponto de extremidade privada 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 rolar chaves de API de administrador, use az search admin-key renew. 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.

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 aos resultados a seguir. Ambas as chaves são devolvidas mesmo que você só mude uma de cada vez.

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

Criar ou excluir chaves de consulta

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

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

Dimensionar réplicas e partições

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

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éplicas e partições, você também pode atualizar ip-rules, public-accesse identity-type.

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.

Para criar o recurso de link privado compartilhado, use az search shared-private-link-resource create. Lembre-se de que alguma configuração pode ser necessária para a fonte de dados antes de executar este 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 compartilhado e exibir seu status, 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ê precisa aprovar a conexão com o seguinte comando antes que ele possa ser usado. A ID da conexão de ponto de extremidade privado deve ser recuperada do recurso filho. Neste caso, obtemos o ID de conexão do 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 compartilhado, consulte Fazendo 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.