REST do serviço de Pesquisa Cognitiva do AzureAzure Cognitive Search Service REST

O Azure Pesquisa Cognitiva é um serviço de pesquisa de nuvem totalmente gerenciado que fornece uma experiência de pesquisa avançada a aplicativos personalizados.Azure Cognitive Search is a fully managed cloud search service that provides a rich search experience to custom applications. Uma maneira de adicionar a capacidade de pesquisa é por meio das APIs REST, com operações que criam e gerenciam índices, carregam dados, implementam recursos de pesquisa, executam consultas e manipulam resultados.One way to add search capability is through the REST APIs, with operations that create and manage indexes, load data, implement search features, execute queries, and handle results.

Uma API REST separada é usada para provisionar e alterar uma configuração de serviço de pesquisa.A separate REST API is used to provision and alter a search service configuration. Como alternativa, você pode usar o Portal.Alternatively, you can use the portal. Para obter mais informações, consulte criar um serviço de pesquisa no portal do Azure ou no REST do gerenciamento de pesquisa cognitiva do Azure.For more information, see Create a search service in Azure portal or Azure Cognitive Search Management REST.

Principais conceitosKey concepts

Pesquisa Cognitiva tem os conceitos de Serviços e índices de pesquisa e documentos:Cognitive Search has the concepts of search services and indexes and documents:

  • Um serviço de pesquisa contém um ou mais índices.A search service contains one or more indexes.
  • Um índice fornece armazenamento persistente de documentos de pesquisa.An index provides persistent storage of search documents.
  • 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.Search documents are loaded from external sources in the form of JSON documents and pushed to an index to make it searchable.

Se você usar um indexador para carregar um índice, poderá automatizar as operações de carregamento de dados.If you use an indexer to load an index, you can automate data upload operations. Um indexador pode rastrear uma fonte de dados e serializar o conteúdo como JSON, em rota para um índice de destino.An indexer can crawl a data source and serialize the content as JSON, in route to a destination index.

O enriquecimento de ia no pesquisa cognitiva tem o conceito de habilidades.AI enrichment in Cognitive Search has the concept of skillsets. Um contratador de qualificações é anexado a um indexador.A skillset is attached to an indexer. Durante a ingestão de dados, ele define uma sequência de etapas que detectam, estruturam ou transformam conteúdo que, de outra maneira, não são pesquisáveis.During data ingestion, it defines a sequence of steps that detect, structure, or transform content that is otherwise unsearchable.

Juntos, há cinco tipos de operações que podem ser executadas em relação ao serviço:All together, there are five types of operations that can be executed against the service:

OperaçãoOperation DescriçãoDescription
IndexIndex Criar, excluir, atualizar ou configurar um índice de pesquisa.Create, delete, update, or configure a search index.
DocumentoDocument Adicionar, atualizar ou excluir documentos no índice, consultar o índice ou pesquisar documentos específicos por ID.Add, update, or delete documents in the index, query the index, or look up specific documents by ID.
IndexadorIndexer 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.Automate aspects of an indexing operation by configuring a data source and an indexer that you can schedule or run on demand. Esse recurso tem suporte para um número limitado de tipos de fonte de dados no Azure.This feature is supported for a limited number of data source types on Azure.
QualificaçõesSkillset Parte de uma carga de trabalho de enriquecimento de ia , um conjunto de qualificações define uma série de processamento de enriquecimento.Part of an AI enrichment workload, a skillset defines a series of enrichment processing. Um configurador de qualificações é consumido por um indexador.A skillset is consumed by an indexer.
Mapa de sinônimosSynonym map Um mapa de sinônimos é um recurso de nível de serviço que contém sinônimos definidos pelo usuário.A synonym map is service-level resource that contains user-defined synonyms. Esse recurso é mantido independentemente dos índices de pesquisa.This resource is maintained independently from search indexes. Depois de carregado, você pode apontar qualquer campo pesquisável para o mapa de sinônimos (um por campo).Once uploaded, you can point any searchable field to the synonym map (one per field).

Chamando as APIsCalling the 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.The APIs documented in this section provide access to operations on search data, such as index creation and population, document upload, and queries. Ao chamar APIs, tenha em mente os seguintes pontos:When calling APIs, keep the following points in mind:

  • As solicitações devem ser emitidas via HTTPS (na porta padrão 443).Requests must be issued over HTTPS (on the default port 443).

  • As solicitações devem incluir a versão de API no URI.Requests must include the api-version in the URI. O valor deve ser definido como uma versão com suporte, formatado conforme mostrado neste exemplo: GET https://[search service name].search.windows.net/indexes?api-version=2020-06-30The value must be set to a supported version, formatted as shown in this example: GET https://[search service name].search.windows.net/indexes?api-version=2020-06-30

  • Os cabeçalhos de solicitação devem incluir uma chave de API que foi gerada para o serviço de pesquisa que você provisionou.Request headers must include an api-key that was generated for the search service you provisioned. 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.Having a valid key establishes trust, on a per request basis, between the application sending the request and the service that handles it.

    Opcionalmente, você pode definir o cabeçalho HTTP Accept.Optionally, you can set the Accept HTTP header. Se o cabeçalho não for definido, o padrão será considerado application/json .If the header is not set, the default is assumed to be application/json.

Autenticação de chaveKey authentication

Cada solicitação HTTP para o serviço de pesquisa é autenticada com base em duas partes de informação: uma URL de serviço de pesquisa e uma chave de API que fornece prova de que a solicitação é de uma entidade confiável.Every HTTP request to your search service is authenticated based on two pieces of information: a search service URL and an api-key that provides proof the request is from a trusted entity. Há dois tipos de chaves de API para diferentes níveis de operação.There are two types of api-keys for different levels of operation.

ChaveKey DescriçãoDescription LimitesLimits
AdminAdmin As chaves de administração concedem direitos totais a todas as operações, incluindo a capacidade de gerenciar o serviço, obter definições de status e de objeto e criar e excluir índices, indexadores e fontes de dados.Admin keys grant full rights to all operations, including the ability to manage the service, get status and object definitions, and create and delete indexes, indexers, and data sources.

Duas chaves de API de administração, chamadas de chaves primárias e secundárias no portal, são geradas automaticamente quando o serviço é criado e podem ser regeneradas individualmente sob demanda.Two admin api-keys, referred to as primary and secondary keys in the portal, are automatically generated when the service is created and can be individually regenerated on demand. Ter duas chaves permite que você substitua uma chave enquanto usa a segunda chave de acesso contínuo para o serviço.Having two keys allows you to roll over one key while using the second key for continued access to the service.

As chaves de administrador são especificadas somente nos cabeçalhos de solicitação HTTP.Admin keys are only specified in HTTP request headers. Você não pode colocar uma chave de API de administrador em uma URL.You cannot place an admin api-key in a URL.
Máximo de dois por serviçoMaximum of 2 per service
ConsultaQuery As chaves de consulta concedem acesso somente leitura ao conteúdo dentro de um índice (documentos) e normalmente são distribuídas para aplicativos cliente que emitem solicitações de pesquisa.Query keys grant read-only access to content within an index (documents), and are typically distributed to client applications that issue search requests.

As chaves de consulta são criadas sob demanda.Query keys are created on demand. Você pode criá-las manualmente no portal ou programaticamente por meio da API REST de gerenciamento.You can create them manually in the portal or programmatically via the Management REST API.

As chaves de consulta podem ser especificadas em um cabeçalho de solicitação HTTP para pesquisa, sugestões ou operação de pesquisa.Query keys can be specified in an HTTP request header for search, suggestion, or lookup operation. Como alternativa, você pode passar uma chave de consulta como um parâmetro em uma URL.Alternatively, you can pass a query key as a parameter on a 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:Depending on how your client application formulates the request, it might be easier to pass the key as a query parameter:

GET /indexes/hotels/docs?search=*&$orderby=lastRenovationDate desc&api-version=2020-06-30&api-key=[query key]
50 por serviço50 per service

Visualmente, não há nenhuma distinção entre as chaves de administrador ou de consulta.Visually, there is no distinction between an admin key or query key. Ambas as chaves são cadeias de caracteres compostas de 32 de caractere alfanuméricos gerados aleatoriamente.Both keys are strings composed of 32 randomly-generated alpha-numeric characters. Se você perder o controle de qual tipo de chave está especificado em seu aplicativo, poderá verificar os valores de chave no portal ou usar a API REST para retornar o valor e o tipo de chave.If you lose track of what type of key is specified in your application, you can check the key values in the portal or use the REST API to return the value and key type.

Observação

Passar dados confidenciais, como um api-key, no URI de solicitação, é considerado uma prática de segurança inadequada.It is considered a poor security practice to pass sensitive data such as an api-key in the request URI. Por esse motivo, o Azure Pesquisa Cognitiva aceitará apenas uma chave de consulta como uma api-key na cadeia de caracteres de consulta e você deverá evitar fazer isso, a menos que o conteúdo do índice esteja disponível publicamente.For this reason, Azure Cognitive Search will only accept a query key as an api-key in the query string, and you should avoid doing so unless the contents of your index should be publicly available. Em vez disso, recomendamos passar a api-key como um cabeçalho de solicitação.As a general rule, we recommend passing your api-key as a request header.

AutorizaçãoAuthorization

A autorização está disponível para operações administrativas por meio de RBAC (controles de acesso baseado em função) fornecidos no portal do Azure.Authorization is available for administrative operations via the role-based access controls (RBAC) provided in the Azure portal. As funções RBAC são usadas para definir níveis de acesso para administração de serviço de forma consistente em todos os serviços.RBAC roles are used to set levels of access for service administration in a way that is consistent across all services. Por exemplo, a exibição de dados confidenciais, como a chave do administrador, é restrita às funções de Proprietário e Colaborador, enquanto a exibição do status do serviço fica disponível para os membros de qualquer função.For example, viewing sensitive data, such as the admin key, is restricted to the Owner and Contributor roles, whereas viewing service status is available to members of any role.

Para suas próprias operações centradas na pesquisa, o Azure Pesquisa Cognitiva não fornece um modelo de autorização.For its own search-centric operations, Azure Cognitive Search does not provide an authorization model. No entanto, se você tiver a capacidade de carregar um índice com associações de documento e de usuário, você poderá filtrar os resultados da pesquisa com base na identidade do usuário.However, if you have the ability to load an index with document and user associations, you can filter search results based on user identity. Para obter mais informações, consulte filtros de segurança para aparar resultados no Azure pesquisa cognitiva.For more information, see Security filters for trimming results in Azure Cognitive Search.

Veja tambémSee also