Referência da API REST do Azure AI Search
Azure AI Search (anteriormente conhecido como Azure Cognitive Search) é um serviço de pesquisa na 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 consulta de fluxos de trabalho e estão documentadas nesta seção.
As operações do plano de controle para administração de serviços são cobertas em uma API REST de gerenciamento de separada.
Documentos de API versionados
Os documentos da API REST agora estão versionados. Quando você abre uma página de referência de API, um seletor de versão aparece acima do índice. Verifique se a referência da API é da pasta
Conceitos-chave
O Azure AI Search tem os conceitos de serviços de pesquisa, índices, documentos, indexadores, fontes de dados, conjuntos de habilidadese 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. Documentos de pesquisa são seus dados, articulados como uma coleção de campos, carregados de fontes externas e enviados para um índice para torná-los pesquisáveis.
- Um indexador de pesquisa adiciona automação, lendo dados em formatos nativos e serializando-os 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 de enriquecimento de IA e de vetorização integrada ao pipeline de indexação. Os conjuntos de habilidades estão sempre ligados a um indexador. Eles invocam o aprendizado de máquina para extrair ou fragmentar texto, vetorizar conteúdo, inferir recursos ou adicionar estrutura ao conteúdo para melhorar a 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 de parceiros. Consulte galeria Fontes de dados para obter a lista completa. |
| Documentação | 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 que visam a coleção de documentos (/docs) de um índice. Todas as operações realizadas na coleção, como upload, fusão, exclusão ou consulta de documentos, ocorrem no contexto de um único índice, portanto, as operações de documento no formato URL sempre incluem /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 que são 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 campos são usados na pesquisa de texto completo e, portanto, tokenizados durante a indexação. Um índice também define outras construções, como perfis de pontuação para ajuste de relevância, sugestões, 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 capacidade de 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 ambos. Existem habilidades incorporadas para análise de imagens, incluindo OCR, e processamento de linguagem natural. Outros exemplos de habilidades incorporadas incluem reconhecimento de entidades, extração de frases-chave, fragmentação 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 é operacional apenas dentro do processamento do indexador. Como um objeto de alto nível, você pode projetar um conjunto de habilidades uma vez e, em seguida, fazer referência a ele em vários indexadores. |
| Mapas de sinónimos | Um mapa de sinônimo é um objeto de nível de serviço que contém sinônimos definidos pelo usuário. Este objeto é mantido independentemente dos índices de pesquisa. Uma vez carregado, 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 do Microsoft Entra ID.
de autenticação baseada em chave depende de chaves de API geradas para o serviço de pesquisa. Ter uma chave válida estabelece confiança, por solicitação, entre o aplicativo que envia a solicitação e o serviço que a manipula. Você pode usar um de chave da API de Administração do
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. autenticação do Microsoft Entra ID e de controle de acesso baseado em função requer que você tenha um locatário estabelecido no 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ê pode criar funções personalizadas se as funções internas forem insuficientes.
Funções Acesso Colaborador do Serviço de Pesquisa Acesso a objetos, mas sem acesso ao conteúdo do í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 objetos. Contribuidor 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 aplicativos e usuários que executam consultas.
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 o 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, ela só se aplicará a operações de plano de dados. As operações do plano de controle, como a administração de serviços, sempre usam autenticação baseada em função. Consulte autenticação de ID do Microsoft Entra e controle de acesso baseado em função para o Azure AI Search 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 índices, 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 o api-version. O valor deve ser definido como uma versão suportada, formatada como mostrado neste exemplo:
GET https://[search service name].search.windows.net/indexes?api-version=2023-11-01Os cabeçalhos de solicitação devem incluir um de chave de apiou um token de portador para conexões autenticadas. Opcionalmente, você pode definir o cabeçalho Accept HTTP. Se o cabeçalho do tipo de conteúdo não estiver definido, o padrão será assumido como application/json.