Referência da API REST do Azure AI Search
do Azure AI Search (anteriormente conhecido como do 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 plano de controle para administração de serviço são cobertas por um separadoda API REST de Gerenciamento de Gerenciamento.
Documentos de API com versão
Os documentos da API REST agora estão em 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 à API é da pasta Reference > Data Plane.
Principais conceitos
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 í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 de enriquecimento de IA e de 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 da 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, portanto, as operações de documento de formato de 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 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 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.
de autenticação baseada em chave depende das 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 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.
autenticação do Microsoft Entra ID e controle de acesso baseado em função requer 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.
Papel 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 objeto. Colaborador do Índice de Dados de Pesquisa Acesso de leitura e 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 Ler o acesso 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 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 autenticação do Microsoft Entra ID e controle de acesso baseado em função para do 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 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 ode 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-01Cabeç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 Aceitar HTTP. Se o cabeçalho do tipo de conteúdo não estiver definido, o padrão será considerado application/json.