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

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.

Observação

Uma nota rápida sobre como a terminologia "chave" é usada no Azure AI Search. Uma "chave de API", que é descrita neste artigo, refere-se a um GUID usado para autenticar uma solicitação. Um termo separado, "chave de documento", refere-se a uma cadeia de caracteres exclusiva em seu conteúdo indexado que é usada para identificar exclusivamente 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 1 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.

1 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 nas solicitações de plano de dados (conteúdo), por exemplo, criação ou acesso a 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 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 API são especificadas em solicitações de cliente a um serviço de pesquisa. Passar uma chave de API válida na solicitação é considerado uma prova de que a solicitação é de um cliente autorizado. Se você estiver criando, modificando ou excluindo objetos, precisará de uma chave de API de administrador. Caso contrário, as chaves de consulta normalmente são distribuídas para aplicativos cliente que emitem consultas.

Você pode especificar chaves de API em um cabeçalho de solicitação para chamadas à API REST ou no código que chama as bibliotecas de cliente azure.search.documents nos SDKs do Azure. Se você estiver usando o portal do Azure para executar tarefas, sua atribuição de função determinará o nível de acesso.

As práticas recomendadas para usar chaves codificadas em arquivos de origem incluem:

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

Como as chaves de API são usadas no portal do Azure:

  • A autenticação de chave é interna. Por padrão, o portal tenta primeiro as chaves de API. No entanto, se você desabilitar chaves de API e configurar atribuições de função, o portal usará atribuições de função.

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:

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.

  1. Entre no portal do Azure e localize o serviço de pesquisa.

  2. Em Configurações, selecione Chaves para exibir chaves de consulta e administrador.

Screenshot of a portal page showing API keys.

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.

  1. Entre no portal do Azure e localize o serviço de pesquisa.

  2. Em Configurações, selecione Chaves para exibir chaves de API.

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

    Screenshot of the query key management options.

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.

  1. Em Configurações, selecione Chavese copie a chave secundária.

  2. Para todos os aplicativos, atualize as configurações de chave de API para usar a chave secundária.

  3. Regenere a chave primária.

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

Observe que 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 da fonte de dados) podem ser criptografados por CMK.

  1. Navegue até a folha de serviço de pesquisa no Portal do Azure.

  2. No painel de navegação à esquerda, selecione Controle de acesso (IAM) e, em seguida, selecione a guia Atribuições de função.

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

  4. Por precaução, verifique também a guia Administradores Clássicos para determinar se os administradores e coadministradores têm acesso.

Confira também