Conectar-se à Pesquisa de IA do Azure usando chaves
A Pesquisa de IA do Azure oferece autenticação baseada em chave para conexões no seu serviço de pesquisa. Uma chave de API é uma cadeia de caracteres exclusiva composta de 52 letras e números 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, referenciar a variável na solicitação. 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 substituí-lo pelo 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:
| 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 do Azure, são geradas quando o serviço é criado e podem ser regeneradas individualmente sob demanda. |
| Consulta | 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 do Azure.
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=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 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=2024-07-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.
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.
Em Configurações, selecione Chaves para exibir chaves de consulta e administrador.
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.
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.
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 do Azure 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.