REST do Serviço Azure Cognitive Search
Azure Cognitive Search é um serviço de pesquisa de nuvem totalmente gerenciado que fornece uma experiência de pesquisa avançada em relação ao conteúdo de propriedade do usuário. Uma maneira de adicionar a funcionalidade de pesquisa é por meio das APIs REST de Pesquisa, com operações que criam e gerenciam índices, carregam dados, implementam recursos de pesquisa, executam consultas e manipulam resultados.
Uma API REST de Gerenciamento separada pode ser usada para criar ou modificar o próprio serviço. Como alternativa, você pode usar o portal para muitas tarefas de gerenciamento de serviço e conteúdo. Para começar, confira Criar um serviço de pesquisa no portal do Azure.
Principais conceitos
O Cognitive Search tem os conceitos de serviços de pesquisa , índices e documentos:
- Um serviço de pesquisa contém um ou mais índices.
- Um índice fornece armazenamento persistente de documentos de pesquisa.
- Os documentos de pesquisa são carregados de fontes externas na forma de documentos JSON e enviados por push para um índice para torná-lo pesquisável.
Você também pode criar um indexador para automatizar a indexação. Um indexador tem uma fonte de dados e aponta para um índice. Opcionalmente, ele também pode ter um conjunto de habilidades que adiciona IA ao pipeline do indexador.
O enriquecimento de IA é uma extensão de indexadores que adiciona transformações de aprendizado de máquina que extraem ou geram texto ou adicionam estrutura ao conteúdo para que ele possa ser indexado por um serviço de pesquisa. O constructo que impulsiona o enriquecimento de IA é chamado de conjunto de habilidades. Durante a ingestão de dados, ele define uma sequência de etapas que detectam, estruturam ou transformam conteúdo que, de outra forma, não é pesquisável (por exemplo, conteúdo de imagem).
Ao todo, há cinco tipos de operações que podem ser executadas no serviço:
| Operação | Descrição |
|---|---|
| Index | Criar, excluir, atualizar ou configurar um índice de pesquisa. |
| Documento | Adicione, atualize ou exclua documentos no índice, consulte o índice ou procure documentos específicos por ID. |
| Indexador | Automatize aspectos de uma operação de indexação configurando uma fonte de dados e um indexador que você pode agendar ou executar sob demanda. Esse recurso tem suporte para um número limitado de tipos de fonte de dados no Azure. |
| Conjunto de habilidades | Parte de uma carga de trabalho de enriquecimento de IA , um conjunto de habilidades define uma série de processamento de enriquecimento que extrai ou cria texto pesquisável de texto não estruturado, arquivos de aplicativo ou arquivos de imagem. Um conjunto de habilidades é invocado por um indexador. |
| Mapa de sinônimos | Um mapa de sinônimos é um recurso de nível de serviço que contém sinônimos definidos pelo usuário. Esse recurso é 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). |
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).
As solicitações devem incluir a api-version no URI. 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=2020-06-30Os cabeçalhos de solicitação devem incluir uma chave de api que foi gerada para o serviço de pesquisa provisionado. 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. Opcionalmente, você pode definir o cabeçalho Aceitar HTTP. Se o cabeçalho não estiver definido, o padrão será considerado
application/json.
Autenticação de chave
Cada solicitação HTTP para seu serviço de pesquisa é autenticada com base em duas informações: uma URL de serviço de pesquisa e uma chave de api que fornece uma prova de que a solicitação é de uma entidade confiável. Há dois tipos de chaves de api para diferentes níveis de operação.
| Chave | Descrição | Limites |
|---|---|---|
| Admin | Administração chaves concedem direitos completos a todas as operações, incluindo a capacidade de gerenciar o serviço, obter definições de status e objeto e criar e excluir índices, indexadores e fontes de dados. Duas chaves de api de administrador, conhecidas como chaves primárias e secundárias no portal, são geradas automaticamente quando o serviço é criado e podem ser regeneradas individualmente sob demanda. Ter duas chaves permite que você substitua uma chave enquanto usa a segunda chave de acesso contínuo para o serviço. Administração chaves são especificadas apenas em cabeçalhos de solicitação HTTP. Você não pode colocar uma chave de API de administrador em uma URL. | Máximo de dois por serviço |
| Consulta | As chaves de consulta concedem acesso somente leitura ao conteúdo em um índice (documentos) e normalmente são distribuídas para aplicativos cliente que emitem solicitações de pesquisa. As chaves de consulta são criadas sob demanda. Você pode criá-las manualmente no portal ou programaticamente por meio da API REST de gerenciamento. As chaves de consulta podem ser especificadas em um cabeçalho de solicitação HTTP para pesquisa, sugestão ou operação de pesquisa. Como alternativa, você pode passar uma chave de consulta como um parâmetro em uma URL. Dependendo de como seu aplicativo cliente formula a solicitação, pode ser mais fácil passar a chave como um parâmetro de consulta: GET /indexes/hotels/docs?search=*&$orderby=lastRenovationDate desc&api-version=2020-06-30&api-key=[query key] |
50 por serviço |
Visualmente, não há nenhuma distinção entre as chaves de administrador ou de consulta. As duas chaves são cadeias de caracteres compostas de 32 caracteres alfanuméricos gerados aleatoriamente. Se você perder o controle de qual tipo de chave é especificado em seu aplicativo, poderá verificar os valores de chave no portal ou usar a API REST de Gerenciamento para retornar o valor e o tipo de chave.
Observação
Passar dados confidenciais, como um api-key, no URI de solicitação, é considerado uma prática de segurança inadequada. Por esse motivo, Azure Cognitive Search aceitará apenas uma chave de consulta como uma api-key na cadeia de caracteres de consulta e você deve evitar fazer isso, a menos que o conteúdo do índice esteja disponível publicamente. Em vez disso, recomendamos passar a api-key como um cabeçalho de solicitação.
Autorização
O Cognitive Search dá suporte ao RBAC (controle de acesso baseado em função) do Azure para administração do serviço de pesquisa, por meio das funções Proprietário, Colaborador e Leitor.
Opcionalmente, para soluções de pesquisa que podem usar recursos de visualização, você pode usar o RBAC do Azure para controlar o acesso a índices e outros objetos em um serviço de pesquisa. Essa abordagem requer um serviço de pesquisa configurado para o RBAC do Azure no plano de dados e um cabeçalho de autorização em chamadas à API REST que são autenticadas usando o Azure Active Directory.