Referência da API REST do Pesquisa de IA do Azure
O Pesquisa de IA do Azure (anteriormente conhecido como Azure Cognitive Search) é um serviço de pesquisa em nuvem totalmente gerenciado que fornece recuperação de informações sobre conteúdo de propriedade do usuário.
As APIs REST do plano de dados são usadas para indexação e fluxos de trabalho de consulta e estão documentadas nesta seção.
As operações do painel de controle são acessadas por meio de uma API REST de Gerenciamento separada.
Documentos da API com controle de versão
Os documentos da API REST agora têm controle de versão. Quando você abre uma página de referência de API, um seletor de versão aparece acima do sumário. Verifique se a referência de API é da pasta Plano de Dados de Referência>.
Principais conceitos
O Pesquisa de IA do Azure tem os conceitos de serviços de pesquisa, índices, documentos, indexadores, fontes de dados, conjuntos de habilidades e mapas de sinônimos.
- Um serviço de pesquisa hospeda índices, indexadores, fontes de dados, conjuntos de habilidades e mapas de sinônimos como objetos de nível superior.
- Um índice de pesquisa fornece armazenamento persistente de documentos de pesquisa. Pesquisa documentos são seus dados, articulados como uma coleção de campos, carregados de fontes externas e enviados por push para um índice para torná-los pesquisáveis.
- Um indexador de pesquisa adiciona automação, leitura de dados em formatos nativos e serialização em JSON.
- Um indexador tem uma fonte de dados e aponta para um índice.
- Um indexador também pode ter um conjunto de habilidades que adiciona enriquecimento de IA e vetorização integrada ao pipeline de indexação. Os conjuntos de habilidades são sempre anexados a um indexador. Eles invocam o aprendizado de máquina para extrair ou dividir texto, vetorizar conteúdo, inferir recursos ou adicionar estrutura ao conteúdo para que ele possa ser indexado por um serviço de pesquisa.
Ao todo, você pode criar os seguintes objetos em um serviço de pesquisa:
| Objetos | Descrição |
|---|---|
| Fontes de dados | Uma conexão de fonte de dados usada por um indexador para recuperar e atualizar documentos para indexação. As fontes de dados têm um type. Você pode usar as conexões fornecidas pela Microsoft para o Azure ou conectores de terceiros por meio de parceiros. Confira Galeria de fontes de dados para obter a lista completa. |
| Documentos | Conceitualmente, um documento é uma entidade em seu índice. Mapeando esse conceito para equivalentes de banco de dados mais familiares: um índice de pesquisa equivale a uma tabela e os documentos são aproximadamente equivalentes a linhas em uma tabela. Os documentos existem apenas em um índice e são recuperados somente por meio de consultas direcionadas à coleção de documentos (/docs) de um índice. Todas as operações executadas na coleção, como carregar, mesclar, excluir ou consultar documentos, ocorrem no contexto de um único índice, portanto, as operações de documento de formato de URL sempre incluirão /indexes/[index name]/docs para um determinado nome de índice. |
| Índices | Um índice é armazenado em seu serviço de pesquisa e preenchido com documentos JSON indexados e com tokens para recuperação de informações. A coleção de campos de um índice define a estrutura do documento de pesquisa. Os campos têm um nome, tipos de dados e atributos que determinam como eles são usados. Por exemplo, searchable os campos são usados na pesquisa de texto completo e, portanto, são tokenizados durante a indexação. Um índice também define outros constructos, como perfis de pontuação para ajuste de relevância, sugestores, configurações semânticas e analisadores personalizados. |
| Indexadores | Os indexadores fornecem automação de indexação. Um indexador se conecta a uma fonte de dados, lê os dados e os passa para um mecanismo de pesquisa para indexação em um índice de pesquisa de destino. Os indexadores leem de uma fonte externa usando informações de conexão em uma fonte de dados e serializam os dados de entrada em documentos de pesquisa JSON. Além de uma fonte de dados, um indexador também requer um índice. O índice especifica os campos e atributos dos documentos de pesquisa. |
| Conjuntos de habilidades | Um conjunto de habilidades adiciona etapas de processamento externo à execução do indexador e geralmente é usado para adicionar modelos de IA ou aprendizado profundo para analisar ou transformar conteúdo para torná-lo pesquisável em um índice. O conteúdo de um conjunto de habilidades é uma ou mais habilidades, que podem ser habilidades internas criadas pela Microsoft, habilidades personalizadas ou uma combinação de ambas. Existem habilidades internas para análise de imagem, incluindo OCR e processamento de linguagem natural. Outros exemplos de habilidades internas incluem reconhecimento de entidade, extração de frases-chave, agrupamento de texto em páginas lógicas, entre outros. Um conjunto de habilidades é um objeto autônomo de alto nível que existe em um nível equivalente a índices, indexadores e fontes de dados, mas está operacional somente no processamento do indexador. Como um objeto de alto nível, você pode criar um conjunto de habilidades uma vez e, em seguida, referenciá-lo em vários indexadores. |
| Mapas de sinônimos | Um mapa de sinônimos é um objeto de nível de serviço que contém sinônimos definidos pelo usuário. Esse objeto é mantido independentemente dos índices de pesquisa. Depois de carregado, você pode apontar qualquer campo pesquisável para o mapa de sinônimos (um por campo). |
Permissões e controle de acesso
Você pode usar a autenticação baseada em chave ou baseada em função por meio de Microsoft Entra ID.
A autenticação baseada em chave depende das chaves de API geradas para o serviço de pesquisa. Ter uma chave válida estabelece a relação de confiança, para cada solicitação, entre o aplicativo que envia a solicitação e o serviço que lida com ela. Você pode usar uma chave de API Administração para operações de leitura/gravação ou uma chave de API de Consulta para acesso de leitura à coleção de documentos de um índice de pesquisa.
Microsoft Entra ID autenticação e controle de acesso baseado em função exigem que você tenha um locatário estabelecido em Microsoft Entra ID, com entidades de segurança e atribuições de função. Os membros das funções a seguir têm acesso ao plano de dados. Você poderá criar funções personalizadas se as funções internas forem insuficientes.
Função Access Colaborador do Serviço de Pesquisa Acesso a objetos, mas sem acesso ao conteúdo do índice. Essa função não pode consultar um índice de pesquisa ou adicionar, remover ou atualizar documentos em um índice de pesquisa. Essa função é para administradores que precisam gerenciar objetos, mas sem a capacidade de exibir ou acessar dados de objeto. Colaborador do Índice de Dados do Pesquisa Acesso de leitura/gravação ao conteúdo do índice. Essa função é para desenvolvedores ou proprietários de índice que precisam importar, atualizar ou consultar a coleção de documentos de um índice. Leitor de Índice de Dados do Pesquisa Acesso de leitura ao conteúdo do índice. Essa função é para os usuários que executam consultas em um índice.
Ao usar funções na conexão, seu aplicativo cliente apresenta um token de portador no cabeçalho de autorização. Consulte Autorizar o acesso a um aplicativo de pesquisa usando Microsoft Entra ID para obter ajuda com a configuração.
Você pode desabilitar a autenticação baseada em chave ou a autenticação baseada em função. Se você desabilitar a autenticação baseada em função, algumas funções internas ainda terão acesso. Confira autenticação Microsoft Entra ID e controle de acesso baseado em função para Pesquisa de IA do Azure para obter detalhes.
Chamando as APIs
As APIs documentadas nesta seção fornecem acesso a operações em dados de pesquisa, como criação e população de índice, carregamento de documentos e consultas. Ao chamar APIs, tenha em mente os seguintes pontos:
As solicitações devem ser emitidas por HTTPS (na porta padrão 443).
Os URIs de solicitação devem incluir a api-version. O valor deve ser definido como uma versão com suporte, formatada conforme mostrado neste exemplo:
GET https://[search service name].search.windows.net/indexes?api-version=2020-06-30Os cabeçalhos de solicitação devem incluir uma chave de api ou um token de portador para conexões autenticadas. Opcionalmente, você pode definir o cabeçalho Aceitar HTTP. Se o cabeçalho do tipo de conteúdo não estiver definido, o padrão será considerado
application/json.