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 o 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 para administração de serviços são abordadas em uma API REST de Gerenciamento separada.

Documentos de API com versão

Os documentos da API REST agora estão com 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>.

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 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 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 como eles são usados. 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 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 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 baseada em função por meio de Microsoft Entra ID.

  • 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 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 não forem suficientes.

    Função Access
    Colaborador do Serviço de Pesquisa Acesso a objetos, mas sem acesso ao conteúdo de índice. Essa função cria um índice de pesquisa e outros objetos de nível superior, mas não pode consultar um índice de pesquisa ou adicionar, remover ou atualizar documentos em um índice de pesquisa. Essa função é para desenvolvedores que criam, atualizam e excluem definições de objeto. Também é para administradores que precisam gerenciar objetos, mas sem a capacidade de exibir ou acessar dados de objeto.
    Colaborador do Índice de Dados de 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 de 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 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. As operações do painel de controle, como administração de serviços, sempre usam a autenticação baseada em função. Consulte Microsoft Entra ID autenticação e 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 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 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=2023-11-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á application/jsonconsiderado .

Confira também