Compartilhar via

Referência da API REST do Azure AI Search

O Azure AI Search (anteriormente conhecido como Azure Cognitive Search) é um serviço de pesquisa de 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 plano de controle para administração de serviço são abordadas em uma API REST de Gerenciamento de Pesquisa separada.

Documentos de API com versão

Um seletor de versão aparece acima do sumário quando você seleciona um artigo de referência de API. Verifique se a API é da pasta Plano de Dados de Referência>.

Captura de tela do seletor de versão.

Principais conceitos

O Azure AI Search 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 índice, 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. Os documentos de pesquisa 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 agrupar texto, vetorizar conteúdo, inferir recursos ou adicionar estrutura ao conteúdo para melhor indexação 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 parceiros. Consulte a 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 apenas 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, de modo que as operações de documento de formato de URL sempre incluem /indexes/[index name]/docs um determinado nome de índice.
Índices Um índice é armazenado em seu serviço de pesquisa e preenchido com documentos JSON indexados e tokenizados 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 o uso. Por exemplo, searchable os campos são usados na pesquisa de texto completo e, portanto, 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 é usado para aplicar modelos de IA ou aprendizado profundo para analisar ou transformar conteúdo para melhorar a pesquisa 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 apenas 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 com base em função por meio da ID do Microsoft Entra.

  • A autenticação baseada em chave depende de chaves de API geradas para o serviço de pesquisa. Ter uma chave válida estabelece a confiança, por solicitação, entre o aplicativo que envia a solicitação e o serviço que a manipula. Você pode usar uma chave de API de Administrador 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.

  • A autenticação do Microsoft Entra ID e o controle de acesso baseado em função exigem que você tenha um locatário estabelecido na ID do Microsoft Entra, 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.

Quando você usa 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 a ID do Microsoft Entra para obter ajuda para configurar isso.

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, ela só se aplicará às operações do plano de dados. Operações de plano de controle, como administração de serviço, sempre usam a autenticação baseada em função. Consulte a autenticação do Microsoft Entra ID e o controle de acesso baseado em função para a 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 de índice e população, upload 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 versão da API. 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=2024-07-01

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

Consulte também