Conectar-se ao Azure AI Search usando chaves

Artigo
10/30/2024

O Azure AI Search oferece autenticação baseada em chave para conexões com seu serviço de pesquisa. Uma chave de API é uma cadeia de caracteres exclusiva composta por 52 números e letras gerados aleatoriamente. No código-fonte, você pode especificá-lo como uma variável de ambiente ou como uma configuração de aplicativo em seu projeto e, em seguida, fazer referência à variável na solicitação. Uma solicitação feita a um ponto de extremidade do serviço de pesquisa será aceita se a solicitação e a chave da API forem válidas.

A autenticação baseada em chave é o padrão.

Você pode substituí-lo por acesso baseado em função, o que elimina a necessidade de chaves codificadas em sua base de código.

Tipos de chaves de API

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

Type	Nível de permissão	Máximo	Como foi criado
Administrador	Acesso total (leitura-gravação) para todas as operações de conteúdo	^{2 1}	Duas chaves de administrador, referidas como chaves primária e secundária no portal do Azure, são geradas quando o serviço é criado e podem ser regeneradas individualmente sob demanda.
Query	Acesso somente leitura, com escopo para a coleção de documentos de um índice de pesquisa	50	Uma chave de consulta é gerada com o serviço. Mais pode ser criado sob demanda por um administrador de serviço de pesquisa.

1 Ter duas permite que você role uma tecla enquanto usa a segunda chave para acesso contínuo ao serviço.

Visualmente, não há distinção entre uma chave de administrador ou uma chave de consulta. Ambas as teclas são cadeias de caracteres compostas por 52 caracteres alfanuméricos gerados aleatoriamente. Se você perder o controle de que tipo de chave é especificado em seu aplicativo, você pode verificar os valores de chave no portal do Azure.

Usar chaves de API em conexões

As chaves de API são usadas para solicitações de plano de dados (conteúdo), como criar ou acessar um índice ou qualquer outra solicitação representada nas APIs REST de pesquisa. Após a criação do serviço, uma chave de API é o único mecanismo de autenticação para operações de plano de dados, mas você pode substituir ou complementar a autenticação de chave com funções do Azure se não puder usar chaves codificadas em seu código.

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

As chaves de consulta são normalmente distribuídas para aplicativos cliente 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. Não é possível passar chaves de administrador no URI ou no corpo da solicitação. As chaves de administrador são usadas para a operação create-read-update-delete e em solicitações emitidas para o próprio serviço de pesquisa, como LIST Indexes ou GET Service Statistics.

Aqui está um exemplo de uso da chave de API de administrador em uma solicitação de criação de índice:

### Create an index
POST {{baseUrl}}/indexes?api-version=2024-07-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 destinadas à index/docs coleção: Pesquisar Documentos, Preenchimento Automático, Sugerir ou GET Document.

Aqui está um exemplo de uso da 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=2024-07-01&api-key={{queryApiKey}}

Nota

É considerado uma prática de segurança ruim passar dados confidenciais, como um api-key URI de solicitação. Por esse motivo, o Azure AI Search só aceita uma chave de consulta como uma api-key na cadeia de caracteres de consulta. Como regra geral, recomendamos passar o cabeçalho api-key como uma solicitação.

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

Defina 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 da chave de API para várias operações pode ser encontrado em Guia de início rápido: criar um índice de Pesquisa de IA do Azure no PowerShell usando APIs REST.

Permissões para exibir ou gerenciar chaves de API

As permissões para visualizar 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 chaves:

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

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

Leitor
Contribuidor de dados do índice de pesquisa
Leitor de dados de índice de pesquisa

Localizar chaves existentes

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

Entre no portal do Azure e encontre seu serviço de pesquisa.
Em Configurações, selecione Chaves para exibir as chaves de administração e de consulta.

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

Retornar chaves de administração:

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 admin e de 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 Administração ou Listar Chaves de Consulta na API REST de Gerenciamento para retornar chaves de API.

Você deve ter uma atribuição de função válida para retornar ou atualizar chaves de API. Consulte Gerenciar seu serviço Azure AI Search com APIs REST para obter orientação sobre como atender aos requisitos de função usando as 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

Criar 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 as operações que usam uma chave de consulta. Qualquer operação somente leitura que retorne dados do sistema ou definições de objeto, como uma definição de índice ou status do indexador, requer uma chave de administrador.

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 administrador para qualquer consulta originada de um aplicativo cliente.

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

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. Consulte Gerenciar seu serviço Azure AI Search com APIs REST para obter orientação sobre como atender aos requisitos de função usando as 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 continuidade de negócios.

Em Configurações, selecione Teclas e 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 ambas as chaves ao mesmo tempo, todas as solicitações de cliente usando essas chaves falharão com HTTP 403 Proibido. No entanto, o conteúdo não é excluído e você não é bloqueado permanentemente.

Você ainda pode acessar o serviço por meio do portal do Azure ou programaticamente. As funções de gerenciamento são operacionais por meio de um ID de assinatura e 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 de criar novas chaves via portal ou camada de gerenciamento, o acesso é restaurado ao seu conteúdo (índices, indexadores, fontes de dados, mapas de sinônimos) depois de fornecer essas chaves nas solicitações.

Chaves de API seguras

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

Não é possível usar a 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 de fonte de dados) podem ser criptografados por CMK.

Navegue até a página do serviço de pesquisa no portal do Azure.
No painel de navegação esquerdo, 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 no seu serviço de pesquisa.
Como precaução, verifique também a guia Administradores clássicos para determinar se os administradores e coadministradores têm acesso.

Melhores práticas

Use chaves de API apenas 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 seu serviço de pesquisa.
Sempre verifique o código, os exemplos e o material de treinamento antes de publicar para garantir que você não deixou chaves de API válidas para trás.
Para cargas de trabalho de produção, alterne para Microsoft Entra ID e acesso baseado em função. Ou, se você quiser continuar usando chaves de API, certifique-se de sempre monitorar quem tem acesso às suas chaves de API e regenerar chaves de API em uma cadência regular.

Partilhar via