Conectar-se ao Azure AI Search usando a autenticação de chave

Artigo
04/28/2024

O Azure AI Search oferece autenticação baseada em chave que você pode usar nas conexões com seu serviço de pesquisa. Uma chave de API é uma cadeia de caracteres exclusiva composta de 52 letras e números gerados aleatoriamente. Uma solicitação feita a um ponto de extremidade de serviço de pesquisa será aceita se a solicitação e a chave de API forem válidas.

A autenticação baseada em chave é a padrão. Você pode desativá-la se optar pela autenticação baseada em função.

Observação

Uma observação rápida sobre a terminologia de chave. Uma Chave de API é um GUID usado para autenticação. Um termo separado, chave de documento, é uma cadeia de caracteres exclusiva em seu conteúdo indexado que identifica exclusivamente os documentos em um índice de pesquisa.

Tipos de chaves de API

Há dois tipos de chaves usadas para autenticar uma solicitação:

Tipo	Nível de permissão	Máximo	Como foi criada
Admin	Acesso completo (leitura/gravação) para todas as operações de conteúdo	2 ¹	Duas chaves de API de administrador, chamadas de chaves primária e secundária no portal, são geradas quando o serviço é criado e podem ser regeneradas individualmente sob demanda.
Query	Acesso somente leitura, com a coleção de documentos de um índice de pesquisa como escopo	50	Uma chave de consulta é gerada com o serviço. Outras podem ser criadas sob demanda por um administrador do serviço de pesquisa.

¹ Ter duas permite que você substitua uma chave enquanto usa a segunda chave de acesso contínuo para o serviço.

Visualmente, não há nenhuma distinção entre as chaves de administrador ou de consulta. As duas chaves são cadeias de caracteres compostas de 52 caracteres alfanuméricos gerados aleatoriamente. Se você perder o controle de qual tipo de chave está especificado em seu aplicativo, poderá verificar os valores de chave no portal.

Usar chaves de API em conexões

As chaves de API são usadas para solicitações de planos de dados (conteúdo), como a criação ou o acesso a um índice ou qualquer outra solicitação representada nas APIs REST da Pesquisa. Após a criação do serviço, uma chave de API é o único mecanismo de autenticação nas operações de plano de dados, mas você pode substituir ou complementar a autenticação de chave por funções do Azure se não puder inserir chaves no código.

As chaves de administrador são usadas para criar, modificar ou excluir objetos. As chaves de administração também são usadas para OBTER definições de objetos e informações do sistema.

As chaves de consulta são normalmente distribuídas aos aplicativos clientes que emitem consultas.

Como as chaves de API são usadas em chamadas REST:

Defina uma chave de administrador no cabeçalho da solicitação. Você não pode passar chaves de administrador no URI ou no corpo da solicitação. As chaves de administração são usadas para a operação de criação, leitura, atualização e exclusão e em solicitações emitidas para o próprio serviço de pesquisa, como LISTAGEM de Índices ou OBTER Estatísticas do Serviço.

Veja a seguir um exemplo de uso da chave da API de administrador em uma solicitação de criação de índice:

### Create an index
POST {{baseUrl}}/indexes?api-version=2023-11-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{adminApiKey}}

    {
        "name": "my-new-index",  
        "fields": [
            {"name": "docId", "type": "Edm.String", "key": true, "filterable": true},
            {"name": "Name", "type": "Edm.String", "searchable": true }
         ]
   }

Defina uma chave de consulta em um cabeçalho de solicitação para POST ou no URI para GET. As chaves de consulta são usadas para operações que têm como alvo a coleção index/docs: Pesquisar Documentos, Autocompletar, Sugerir ou OBTER Documento.

Veja um exemplo de uso de chave de API de consulta em uma solicitação de Pesquisa de Documentos (GET):

### Query an index
GET /indexes/my-new-index/docs?search=*&api-version=2023-11-01&api-key={{queryApiKey}}

Observação

Passar dados confidenciais, como um api-key, no URI de solicitação, é considerado uma prática de segurança inadequada. Por esse motivo, o Azure AI Search aceita apenas uma chave de consulta como api-key na cadeia de caracteres de consulta. Em vez disso, recomendamos passar a api-key como um cabeçalho de solicitação.

Como as chaves de API são usadas no PowerShell:

Defina as chaves de API no cabeçalho da solicitação usando a seguinte sintaxe:

$headers = @{
'api-key' = '<YOUR-ADMIN-OR-QUERY-API-KEY>'
'Content-Type' = 'application/json' 
'Accept' = 'application/json' }

Um exemplo de script mostrando o uso de chave de API para várias operações pode ser encontrado no Início Rápido: Criar um índice do Azure AI Search no PowerShell usando APIs REST.

Permissões para exibir ou gerenciar chaves de API

As permissões para exibir e gerenciar chaves de API são transmitidas por meio de atribuições de função. Os membros das seguintes funções podem exibir e regenerar as chaves:

Proprietário
Colaborador
Colaborador do Serviço de Pesquisa
Administrador e Coadministrador (clássico)

As seguintes funções não têm acesso a chaves de API:

Leitor
Colaborador de dados de índice de pesquisa
Leitor de dados de índice de pesquisa

Localizar chaves existentes

Você pode exibir e gerenciar as chaves de API no portal do Azure ou por meio do PowerShell, da CLI do Azure ou da API REST.

Entre no portal do Azure e localize o serviço de pesquisa.
Em Configurações, selecione Chaves para exibir chaves de consulta e administrador.

Instalar o módulo Az.Search:
```
Install-Module Az.Search
```

Retornar chaves de administrador:

Get-AzSearchAdminKeyPair -ResourceGroupName <resource-group-name> -ServiceName <search-service-name>

Retornar chaves de consulta:

Get-AzSearchQueryKey -ResourceGroupName <resource-group-name> -ServiceName <search-service-name>

Use os seguintes comandos para retornar chaves de API de administrador e consulta, respectivamente:

az search admin-key show --resource-group <myresourcegroup> --service-name <myservice>

az search query-key list --resource-group <myresourcegroup> --service-name <myservice>

Use Listar Chaves de Administrador ou Listar Chaves de Consulta na API REST de Gerenciamento para retornar chaves de API.

Você precisa ter uma atribuição de função válida para retornar ou atualizar chaves de API. Confira Gerenciar o serviço do Azure AI Search com APIs REST para obter diretrizes sobre como atender aos requisitos de função no uso das APIs REST.

POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers//Microsoft.Search/searchServices/{{search-service-name}}/listAdminKeys?api-version=2023-11-01

Excluir chaves de consulta

As chaves de consulta são usadas para acesso somente leitura a documentos dentro de um índice para operações direcionadas a uma coleção de documentos. Consultas de pesquisa, filtro e sugestão são todas operações que usam uma chave de consulta. Qualquer operação somente leitura que retorna dados do sistema ou definições de objeto, como uma definição de índice ou um status de indexador, requer uma chave de administração.

Restringir o acesso e as operações em aplicativos cliente é essencial para proteger os ativos de pesquisa em seu serviço. Sempre use uma chave de consulta em vez de uma chave de administração para qualquer consulta proveniente de um aplicativo cliente.

Entre no portal do Azure e localize o serviço de pesquisa.
Em Configurações, selecione Chaves para exibir chaves de API.
Em Gerenciar chaves de consulta, use a chave de consulta já gerada para seu serviço ou crie outras chaves de consulta. A chave de consulta padrão não é nomeada, mas outras chaves de consulta geradas podem ser nomeadas para gerenciamento.

Use Criar Chaves de Consulta na API REST de Gerenciamento.

Você deve ter uma atribuição de função válida para criar ou gerenciar chaves de API. Confira Gerenciar o serviço do Azure AI Search com APIs REST para obter diretrizes sobre como atender aos requisitos de função no uso das APIs REST.

POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Search/searchServices/{searchServiceName}/createQueryKey/{name}?api-version=2023-11-01

Regenerar chaves de administrador

Duas chaves de administrador são criadas para cada serviço, para que você possa girar uma chave primária enquanto usa a chave secundária para manter a continuidade dos negócios.

Em Configurações, selecione Chavese copie a chave secundária.
Para todos os aplicativos, atualize as configurações de chave de API para usar a chave secundária.
Regenere a chave primária.
Atualize todos os aplicativos para usar a nova chave primária.

Se você regenerar inadvertidamente as duas chaves ao mesmo tempo, todas as solicitações de cliente que usam essas chaves falharão com HTTP 403 Proibido. No entanto, o conteúdo não será excluído e você não será bloqueado permanentemente.

Você ainda pode acessar o serviço por meio do Portal ou programaticamente. As funções de gerenciamento são operacionais por meio de uma ID de assinatura, não de uma chave de API de serviço e, portanto, ainda estão disponíveis, mesmo que suas chaves de API não estejam.

Depois da criação de chaves por meio do portal ou da camada de gerenciamento, o acesso ao conteúdo (índices, indexadores, fontes de dados, mapas de sinônimos) é restaurado quando você fornece essas chaves nas solicitações.

Proteger chaves de API

Use atribuições de função para restringir o acesso a chaves de API.

Não é possível usar criptografia de chave gerenciada pelo cliente para criptografar chaves de API. Somente dados confidenciais dentro do próprio serviço de pesquisa (por exemplo, conteúdo de índice ou cadeias de conexão em definições de objeto da fonte de dados) podem ser criptografados por CMK.

Navegue até a folha de serviço de pesquisa no Portal do Azure.
No painel de navegação à esquerda, selecione Controle de acesso (IAM) e, em seguida, selecione a guia Atribuições de função.
No filtro Função, selecione as funções que têm permissão para exibir ou gerenciar chaves (Proprietário, Colaborador, Colaborador do Serviço de Pesquisa). As entidades de segurança resultantes atribuídas a essas funções têm permissões de chave em seu serviço de pesquisa.
Por precaução, verifique também a guia Administradores Clássicos para determinar se os administradores e coadministradores têm acesso.

Práticas recomendadas

Use apenas chaves de API se a divulgação de dados não for um risco (por exemplo, ao usar dados de exemplo) e se você estiver operando atrás de um firewall. A exposição de chaves de API é um risco para os dados e para o uso não autorizado do serviço de pesquisa.
Sempre verifique o código, os exemplos e o material de treinamento antes da publicação para garantir que você não deixou chaves de API válidas para trás.
Para cargas de trabalho de produção, alterne para o Microsoft Entra ID e o acesso baseado em função. Ou, se você quiser continuar usando chaves de API, monitore sempre quem tem acesso às suas chaves de API e regenere as chaves de API regularmente.