Referência da API REST do Azure AI Pesquisa
O Pesquisa de IA do Azure (anteriormente conhecido como Azure Cognitive Search) é um serviço de pesquisa na cloud totalmente gerido que fornece a obtenção de informações sobre conteúdo propriedade do utilizador.
As APIs REST do plano de dados são utilizadas para indexar e consultar fluxos de trabalho e estão documentadas nesta secção.
As operações do plano de controlo são acedidas através de uma API REST de Gestão separada.
Documentos da API com versão
Os documentos da API REST têm agora o controlo de versões. Quando abre uma página de referência da API, é apresentado um seletor de versões acima do índice. Certifique-se de que a referência da API é da pasta Plano de Dados de Referência>.
Conceitos-chave
O Azure AI Pesquisa tem os conceitos de serviços de pesquisa, índices, documentos, indexadores, origens de dados, conjuntos de competências e mapas de sinónimos.
- Um serviço de pesquisa aloja índices, indexadores, origens de dados, conjuntos de competências 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 os seus dados, articulados como uma coleção de campos, carregados a partir de origens externas e enviados para um índice para torná-lo pesquisável.
- Um indexador de pesquisa adiciona automatização, lê dados em formatos nativos e serializa-os em JSON.
- Um indexador tem uma origem de dados e aponta para um índice.
- Um indexador também pode ter um conjunto de competências que adiciona o melhoramento de IA e a vetorização integrada ao pipeline de indexação. Os conjuntos de competências estão sempre ligados a um indexador. Invocam machine learning para extrair ou segmentar texto, vetorizar conteúdo, inferir funcionalidades ou adicionar estrutura ao conteúdo para que possa ser indexado por um serviço de pesquisa.
No total, pode criar os seguintes objetos num serviço de pesquisa:
| Objetos | Description |
|---|---|
| Origens de dados | Uma ligação de origem de dados utilizada por um indexador para obter e atualizar documentos para indexação. As origens de dados têm um type. Pode utilizar as ligações fornecidas pela Microsoft para o Azure ou conectores de terceiros através de parceiros. Veja Galeria de origens de dados para obter a lista completa. |
| Documentos | Conceptualmente, um documento é uma entidade no seu índice. Mapear este conceito para equivalentes de base de dados mais familiares: um índice de pesquisa equivale a uma tabela e os documentos são aproximadamente equivalentes a linhas numa tabela. Os documentos só existem num índice e são obtidos apenas através de consultas que visam a coleção de documentos (/docs) de um índice. Todas as operações efetuadas na coleção, como carregar, intercalar, eliminar ou consultar documentos, ocorrem no contexto de um único índice, pelo que as operações do documento de formato de URL serão sempre incluídas /indexes/[index name]/docs para um determinado nome de índice. |
| Índices | Um índice é armazenado no seu serviço de pesquisa e preenchido com documentos JSON indexados e tokens para obtençã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 a forma como são utilizados. Por exemplo, searchable os campos são utilizados na pesquisa de texto completo e, portanto, tokens durante a indexação. Um índice também define outras construções, como perfis de classificação para otimização de relevância, sugestores, configurações semânticas e analisadores personalizados. |
| Indexadores | Os indexadores fornecem automatização de indexação. Um indexador liga-se a uma origem de dados, lê os dados e transmite-os a um motor de busca para indexação num índice de pesquisa de destino. Os indexadores leem a partir de uma origem externa com informações de ligação numa origem de dados e serializam os dados recebidos em documentos de pesquisa JSON. Além de uma origem de dados, um indexador também requer um índice. O índice especifica os campos e atributos dos documentos de pesquisa. |
| Conjuntos de competências | Um conjunto de competências adiciona passos de processamento externos à execução do indexador e é normalmente utilizado para adicionar modelos de IA ou aprendizagem profunda para analisar ou transformar conteúdos para torná-lo pesquisável num índice. Os conteúdos de um conjunto de competências são uma ou mais competências, que podem ser competências incorporadas criadas pela Microsoft, competências personalizadas ou uma combinação de ambas. Existem competências incorporadas para a análise de imagens, incluindo o OCR e o processamento de linguagem natural. Outros exemplos de competências incorporadas incluem o reconhecimento de entidades, a extração de expressões-chave, a segmentação de texto em páginas lógicas, entre outros. Um conjunto de competências é um objeto autónomo de alto nível que existe num nível equivalente a índices, indexadores e origens de dados, mas está operacional apenas no processamento de indexadores. Como um objeto de alto nível, pode estruturar um conjunto de competências 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 utilizador. Este objeto é mantido independentemente dos índices de pesquisa. Depois de carregado, pode apontar qualquer campo pesquisável para o mapa de sinónimos (um por campo). |
Permissões e controlo de acesso
Pode utilizar a autenticação baseada em chaves ou baseada em funções através de Microsoft Entra ID.
A autenticação baseada em chaves baseia-se em chaves de API geradas para o serviço de pesquisa. Ter uma chave válida estabelece fidedignidade, numa base por pedido, entre a aplicação a enviar o pedido e o serviço que o processa. Pode utilizar uma chave de API Administração para operações de leitura/escrita 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 controlo de acesso baseado em funções requer que tenha um inquilino estabelecido no Microsoft Entra ID, com principais de segurança e atribuições de funções. Os membros das seguintes funções têm acesso ao plano de dados. Pode criar funções personalizadas se as funções incorporadas forem insuficientes.
Função Access Contribuidor do Serviço Pesquisa Acesso a objetos, mas sem acesso ao conteúdo do índice. Esta função não consegue consultar um índice de pesquisa ou adicionar, remover ou atualizar documentos num índice de pesquisa. Esta função destina-se a administradores que precisam de gerir objetos, mas sem a capacidade de ver ou aceder a dados de objetos. Contribuidor do Índice de Dados do Pesquisa Acesso de leitura/escrita ao conteúdo do índice. Esta função destina-se a programadores ou proprietários de índices que precisam de importar, atualizar ou consultar a coleção de documentos de um índice. Leitor do Índice de Dados do Pesquisa Acesso de leitura ao conteúdo do índice. Esta função destina-se a aplicações e utilizadores que executam consultas.
Ao utilizar funções na ligação, a aplicação cliente apresenta um token de portador no cabeçalho de autorização. Veja Autorizar o acesso a uma aplicação de pesquisa através de Microsoft Entra ID para obter ajuda com a configuração.
Pode desativar a autenticação baseada em chaves ou a autenticação baseada em funções. Se desativar a autenticação baseada em funções, algumas funções incorporadas continuarão a ter acesso. Veja Microsoft Entra ID autenticação e controlo de acesso baseado em funções para Pesquisa de IA do Azure para obter detalhes.
Chamar as APIs
As APIs documentadas nesta secção fornecem acesso a operações em dados de pesquisa, tais como criação e população de índices, carregamento de documentos e consultas. Ao chamar APIs, tenha em atenção os seguintes pontos:
Os pedidos têm de ser emitidos através de HTTPS (na porta predefinida 443).
Os URIs do pedido têm de incluir a versão da API. O valor tem de ser definido para uma versão suportada, formatada conforme mostrado neste exemplo:
GET https://[search service name].search.windows.net/indexes?api-version=2020-06-30Os cabeçalhos de pedido têm de incluir uma chave de API ou um token de portador para ligações autenticadas. Opcionalmente, pode definir o cabeçalho Aceitar HTTP. Se o cabeçalho do tipo de conteúdo não estiver definido, assume-se que a predefinição é
application/json.