Usar a API de Pesquisa da Microsoft para consultar dadosUse the Microsoft Search API to query data

Importante

APIs na /beta versão no Microsoft Graph estão sujeitas a alterações.APIs under the /beta version in Microsoft Graph are subject to change. Não há suporte para o uso dessas APIs em aplicativos de produção.Use of these APIs in production applications is not supported. Para determinar se uma API está disponível em v1.0, use o seletor De versão.To determine whether an API is available in v1.0, use the Version selector.

Você pode utilizar a API de Pesquisa da Microsoft para consultar os dados do Microsoft 365 nos seus aplicativos.You can use the Microsoft Search API to query Microsoft 365 data in your apps.

As solicitações de pesquisa são executadas no contexto do usuário conectado, identificado usando um token de acesso com permissões delegadas.Search requests run in the context of the signed-in user, identified using an access token with delegated permissions.

Cuidado

Os recursos usados em uma solicitação e resposta da API Pesquisa da Microsoft têm propriedades renomeadas ou removidas ou estão sendo preteridas.Resources used in a Microsoft Search API request and response have had properties renamed or removed, or are being deprecated. Encontre mais detalhes sobre a substituição.Find more details about the deprecation. Atualize as consultas da API de pesquisa em todos os aplicativos anteriores.Update search API queries in any earlier apps accordingly.

Casos de uso comunsCommon use cases

A API de pesquisa da Microsoft fornece um método de consulta para pesquisar os dados na Pesquisa da Microsoft, no qual você passa umsearchRequest no corpo da solicitação, definindo as especificações da pesquisa.The Microsoft Search API provides a query method to search across your data in Microsoft Search, where you pass a searchRequest in the request body, defining the specifics of your search.

Essa seção lista os casos de uso comuns do método de consulta, com base nas propriedades e parâmetros definidos no corpo da consulta searchRequest.This section lists the common use cases of the query method, based on the properties and parameters you set in the query searchRequest body.

As solicitações de pesquisa são executadas em nome do usuário.Search requests run on behalf of the user. Os resultados da pesquisa têm escopo para impor o controle de acesso aplicado aos itens.Search results are scoped to enforce any access control applied to the items. Por exemplo, no contexto de arquivos, as permissões em relação aos arquivos serão avaliadas como parte da solicitação de pesquisa.For example, in the context of files, permissions on the files are evaluated as part of the search request. Os usuários não podem acessar mais itens em uma pesquisa do que eles poderiam obter de uma operação GET correspondente com as mesmas permissões e controle de acesso.Users cannot access more items in a search than they can otherwise obtain from a corresponding GET operation with the same permissions and access control.

Casos de usoUse cases Propriedades a serem definidas no corpo da solicitação de consultaProperties to define in the query request body
Resultados da pesquisa de escopo com base em tipos de entidadeScope search results based on entity types entityTypesentityTypes
Resultados da páginaPage results from e sizefrom and size
Obter os emails mais relevantesGet the most relevant emails enableTopResultsenableTopResults
Obter as propriedades selecionadasGet selected properties camposfields
Usar KQL em termos de consultaUse KQL in query terms queryquery
Classificar resultados de pesquisaSort search results sortsort
Refinar os resultados usando agregaçõesRefine results using aggregations aggregationsaggregations
Pesquisar tipos personalizados importados usando conectoresSearch custom types imported using connectors contentSourcescontentSources
Solicitar verificação ortográficaRequest spelling correction queryAlterationOptionsqueryAlterationOptions

Pesquisa de escopo com base em tipos de entidadeScope search based on entity types

Defina o escopo da solicitação de pesquisa usando a propriedade entityTypes no conteúdo da solicitação query.Define the scope of the search request using the entityTypes property in the query request payload. A tabela a seguir descreve os tipos disponíveis para consulta e as permissões com suporte para acessar os dados.The following table describes the types available to query and the supported permissions to access the data.

EntityTypeEntityType Escopo de permissão necessário para acessar os itensPermission scope required to access the items OrigemSource ComentárioComment
messagemessage Mail.Read, Mail.ReadWriteMail.Read, Mail.ReadWrite Exchange OnlineExchange Online Mensagens de email.Email messages.
eventevent Calendars.Read, Calendars.ReadWriteCalendars.Read, Calendars.ReadWrite Exchange OnlineExchange Online Eventos do calendário.Calendar events.
unidadedrive Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.AllFiles.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All SharePointSharePoint Bibliotecas de documentos.Document libraries.
driveItemdriveItem Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.AllFiles.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All SharePoint e OneDriveSharePoint and OneDrive Arquivos, pastas, páginas e notícias.Files, folders, pages, and news.
listlist Sites.Read.All, Sites.ReadWrite.AllSites.Read.All, Sites.ReadWrite.All SharePoint e OneDriveSharePoint and OneDrive Listas.Lists. Observe que as bibliotecas de documentos também são retornadas como listas.Note that document libraries are also returned as lists.
listItemlistItem Sites.Read.All, Sites.ReadWrite.AllSites.Read.All, Sites.ReadWrite.All SharePoint e OneDriveSharePoint and OneDrive Listar itens.List items. Observe que os arquivos e as pastas também são retornados como itens de lista; listItem é a superclasse de driveItem.Note that files and folders are also returned as list items; listItem is the super class of driveItem.
sitesite Sites.Read.All, Sites.ReadWrite.AllSites.Read.All, Sites.ReadWrite.All SharePointSharePoint Sites no SharePoint.Sites in SharePoint.
externalItemexternalItem ExternalItem.Read.AllExternalItem.Read.All Conectores do Microsoft GraphMicrosoft Graph connectors Todo o conteúdo está absorvido pela API dos conectores do Microsoft Graph.All content ingested with the Microsoft Graph connectors API.

Resultados da pesquisa de páginaPage search results

Para controlar a paginação dos resultados da pesquisa, especifique as duas seguintes propriedades no corpo da solicitação query:Control pagination of the search results by specifying the following two properties in the query request body:

  • from – um número inteiro que indica o ponto de partida baseado em 0 para listar os resultados da pesquisa na página.from - An integer that indicates the 0-based starting point to list search results on the page. O valor padrão é 0.The default value is 0.

  • size – um número inteiro que indica o número de resultados a serem retornados para uma página.size - An integer that indicates the number of results to be returned for a page. O valor padrão é 25.The default value is 25.

Observe os seguintes limites se você estiver pesquisando a entidade event ou message:Note the following limits if you're searching the event or message entity:

  • from deve começar em zero na primeira solicitação de página; caso contrário, a solicitação resultará em um HTTP 400 Bad request.from must start at zero in the first page request; otherwise, the request results in an HTTP 400 Bad request.
  • O máximo de resultados por página (size) é 25 por mensagem e evento.The maximum results per page (size) is 25 for message and event.

Não há um limite superior para itens do SharePoint ou do OneDrive.There is no upper limit for SharePoint or OneDrive items. Um tamanho de página razoável é 200.A reasonable page size is 200. Um tamanho de página maior geralmente gera uma latência maior.A larger page size generally incurs higher latency.

Práticas recomendadas:Best practices:

  • Especifique uma primeira página menor na solicitação inicial.Specify a smaller first page in the initial request. Por exemplo, especifique from como 0 e size como 25.For example, specify from as 0, size as 25.

  • Pagine as páginas subsequentes atualizando as propriedades from e size.Paginate subsequent pages by updating the from and size properties. Você pode aumentar o tamanho de página em cada solicitação subsequente.You can increase the page size in each subsequent request. A tabela a seguir mostra um exemplo.The following table shows an example.

    PáginaPage fromfrom sizesize
    11 00 2525
    22 2525 5050
    33 7575 7575
    44 150150 100100

Obter os emails mais relevantesGet the most relevant emails

Quando você pesquisa na entidade mensagem, a especificação de enableTopResults comotrue retorna uma lista híbrida de mensagens: as três primeiras mensagens na resposta são classificadas por relevância; as mensagens restantes são classificadas por data/hora.When searching the message entity, specifying enableTopResults as true returns a hybrid list of messages: the first three messages in the response are sorted by relevance; the remaining messages are sorted by date/time.

Obter as propriedades selecionadasGet selected properties

Ao pesquisar um tipo de entidade, como mensagem, evento, unidade, driveItem, lista, listItem, site, externalItem, você pode incluir na propriedade campos as propriedades de entidade específica para retornar nos resultados da pesquisa.When searching an entity type, such as message, event, drive, driveItem, list, listItem, site, externalItem, you can include in the fields property specific entity properties to return in the search results. Isso é semelhante a usar a opção $select, da consulta do sistema OData, em solicitações REST.This is similar to using the OData system query option, $select in REST requests. A pesquisa do API não oferece suporte técnico a essas opções de consulta porque o comportamento é expresso no corpo POST.The search API does not technically support these query options because the behavior is expressed in the POST body.

Para todos esses tipos de entidade, especificar a propriedade campos reduz o número de propriedades retornadas na resposta, melhorando a carga na conexão.For all these entity types, specifying the fields property reduces the number of properties returned in the response, optimizing the payload over the wire.

As entidades listItem e externalItem são as únicas entidades com suporte que permitem a colocação de campos estendidos configurados no esquema.The listItem and externalItem entities are the only supported entities that allow getting extended fields configured in the schema. Não é possível recuperar propriedades estendidas de todas as outras entidades.You cannot retrieve extended properties from all the other entities. Por exemplo, se você criou um campo para externalItem no esquema de pesquisa ou se tiver uma coluna personalizada em uma listItem, você pode recuperar essas propriedades da pesquisa.For example, if you created a field for externalItem in the search schema, or if you have a custom column on a listItem, you can retrieve these properties from search. Para recuperar uma propriedade estendida de um arquivo, especifique o tipo listItem na solicitação.To retrieve an extended property on a file, specify the listItem type in the request.

Se os campos especificados na solicitação não estiverem presentes no esquema, eles não serão retornados na resposta.If the fields specified in the request are not present in the schema, they will not be returned in the response. Campos inválidos na solicitação são ignorados silenciosamente.Invalid fields in the request are silently ignored.

Se você não especificar nenhum campo na solicitação, obterá o conjunto padrão de propriedades para todos os tipos.If you do not specify any fields in the request, you will get the default set of properties for all types. Para propriedades estendidas, listItem e externalItem se comportam de forma diferente quando nenhum campo é passado na solicitação:For extended properties, listItem and externalItem behave differently when no fields are passed in the request:

  • listItem não retornará nenhum campo personalizado.listItem will not return any custom field.
  • externalItem retornará todos os campos marcados com o atributo recuperável no esquema do conector do Microsoft Graph para essa conexão em particular.externalItem will return all the fields marked with the retrievable attribute in the Microsoft Graph connector schema for that particular connection.

Suporte a KQL (Linguagem de Consulta de Palavra-chave)Keyword Query Language (KQL) support

Especifique palavras-chave de texto livre, operadores (como AND, OR) e restrições de propriedade na sintaxe KQL na cadeia de caracteres de consulta de pesquisa real (propriedade query do corpo da solicitação query).Specify free text keywords, operators (such as AND, OR), and property restrictions in KQL syntax in the actual search query string (query property of the query request body). A sintaxe e o comando dependem dos tipos de entidade (na propriedade entityTypes) que você direciona no corpo da solicitação query.The syntax and command depend on the entity types (in the entityTypes property) you target in the same query request body.

Dependendo do tipo de entidade, as propriedades pesquisáveis variam.Depending on the entity type, the searchable properties vary. Veja mais detalhes em:For details, see:

Classificar resultados de pesquisaSort search results

Os resultados da pesquisa na resposta são classificados na ordem de classificação padrão a seguir:Search results in the response are sorted in the following default sort order:

  • mensagem e evento são classificados por data.message and event are sorted by date.
  • Todos os tipos de conectores SharePoint e OneDrive são classificados por relevância.All SharePoint, OneDrive and connector types are sorted by relevance.

O método de consulta permite que você personalize a ordem de pesquisa especificando as sortProperties no parâmetro requests, que é uma coleção de objetos searchRequest.The query method lets you customize the search order by specifying the sortProperties on the requests parameter, which is a collection of searchRequest objects. Isso permite especificar uma lista de uma ou mais propriedades classificáveis e a ordem de classificação.This allows you to specify a list of one or more sortable properties and the sort order.

Atualmente, só há suporte para a classificação de resultados nos seguintes tipos de SharePoint e OneDrive: driveItem, listItem, list e site.Note that sorting results is currently only supported on the following SharePoint and OneDrive types: driveItem, listItem, list, site.

As propriedades nas quais a cláusula de classificação é aplicada devem ser classificáveis no esquema de pesquisa do SharePoint.The properties on which the sort clause are applied need to be sortable in the SharePoint search schema. Se a propriedade especificada na solicitação não for classificável ou não existir, a resposta retornará um erro, HTTP 400 Bad Request.If the property specified in the request is not sortable or does not exist, the response will return an error, HTTP 400 Bad Request. Observe que você não pode especificar a classificação de documentos por relevância usando sortProperty.Note that you cannot specify to sort documents by relevance using sortProperty.

Ao especificar o nome de um objeto sortProperty, você pode usar o nome da propriedade do tipo Microsoft Graph (por exemplo, em driveItem) ou o nome da propriedade gerenciada no índice de pesquisa.When specifying the name of a sortProperty object, you can either use the property name from the Microsoft Graph type (for example, in driveItem), or the name of the managed property in the search index.

Confira classificar resultados de pesquisa para obter exemplos que mostram como classificar resultados.See sort search results for examples that show how to sort results.

Refinar os resultados usando agregaçõesRefine results using aggregations

As agregações (também conhecidas como refinadores no SharePoint) são uma maneira muito popular de melhorar a experiência de pesquisa.Aggregations (also known as refiners in SharePoint) are a very popular way to enhance a search experience. Além dos resultados, eles fornecem algum nível de informações agregadas no conjunto de resultados de pesquisa.In addition to the results, they provide some level of aggregate information on the matching set of search results. Por exemplo, você pode fornecer informações sobre os autores mais representados dos documentos correspondentes à consulta, ou os tipos de arquivo mais representados, etc.For example, you can provide information on the most represented authors of the documents matching the query, or the most represented file types, etc.

NasearchRequest, especifique as agregações que devem ser retornadas além dos resultados da pesquisa.In the searchRequest, specify the aggregations that should be returned in addition to the search results. A descrição de cada agregação é definida naaggregationOption, que especifica a propriedade na qual a agregação deve ser calculada, e o número de searchBucket a ser retornado na resposta.The description of each aggregation is defined in the aggregationOption, which specifies the property on which the aggregation should be computed, and the number of searchBucket to be returned in the response.

As propriedades nas quais a agregação é solicitada devem ser refináveis no esquema de pesquisa do SharePoint.The properties on which the aggregation is requested need to be refinable in the SharePoint search schema. Se a propriedade especificada não for refinável ou não existir, a resposta retornará HTTP 400 Bad Request.If the property specified is not refinable or does not exist, the response returns HTTP 400 Bad Request.

Uma vez que a resposta é retornada contendo a coleção de objetos searchBucket, é possível refinar a solicitação de pesquisa somente aos elementos correspondentes contidos em uma searchBucket.Once the response is returned containing the collection of searchBucket objects, it is possible to refine the search request to only the matching elements contained in one searchBucket. Isso é conseguido passando o valor aggregationsFilterToken na propriedade aggregationsFilters na posterior searchRequest.This is achieved by passing back the aggregationsFilterToken value in the aggregationFilters property of the subsequent searchRequest.

As agregações atualmente têm suporte para qualquer propriedade refinável nos seguintes tipos do SharePoint e OneDrive: driveItem, listItem, list, site e nos conectores do Microsoft Graph externalItem.Aggregations are currently supported for any refinable property on the following SharePoint and OneDrive types: driveItem, listItem, list, site, and on Microsoft Graph connectors externalItem.

Confira refinar os resultados da pesquisa para obter exemplos que mostram como usar a agregação para melhorar e restringir os resultados da pesquisa.See refine search results for examples that show using aggregation to enhance and narrow down search results.

Solicitar verificação ortográficaRequest spelling correction

A verificação ortográfica é uma maneira popular de lidar com incompatibilidades entre erros de digitação em uma consulta do usuário e as palavras corretas em conteúdos combinados.Spelling correction is a popular way to handle mismatches between typos in a user query and the correct words in matched contents. Quando erros de digitação são detectados na consulta original do usuário, você pode obter o resultado da pesquisa tanto para a consulta original do usuário quanto para a consulta alternativa corrigida.When typos are detected in the original user query, you can get the search result either for the original user query or the corrected alternate query. Você também pode obter as informações de verificação ortográfica para erros de digitação na propriedade queryAlterationResponse da searchresponse.You can also get the spelling correction information for typos in the queryAlterationResponse property of the searchresponse.

No corpo de solicitação do método query, especifique as queryAlterationOptions que devem ser aplicadas à consulta para as verificações ortográficas.In the request body of the query method, specify the queryAlterationOptions that should be applied to the query for spelling corrections. A descrição das queryAlterationOptions são definidas nas searchAlterationOptions.The description of queryAlterationOptions is defined in the searchAlterationOptions.

Para exemplos que mostram como usar verificações ortográficas, consulte Solicitar verificação ortográfica.For examples that show how to use spelling corrections, see Request spelling correction.

Tratamento de errosError handling

A API de pesquisa retorna respostas de erro conforme estipulado pela definição de objeto de erro OData. Cada uma delas é um objeto JSON que contém um código e uma mensagem.The search API returns error responses as defined by OData error object definition, each of which is a JSON object containing a code and a message.

Limitações conhecidasKnown limitations

A API de pesquisa tem as seguintes limitações:The search API has the following limitations:

  • O método query é definido para permitir a passagem de um conjunto de uma ou mais instâncias de searchRequest de uma só vez.The query method is defined to allow passing a collection of one or more searchRequest instances at once. No entanto, atualmente o serviço dá suporte apenas a um único searchRequest por vez.However, the service currently supports only a single searchRequest at a time.

  • O recurso searchRequest dá suporte à passagem de vários tipos de entidades por vez.The searchRequest resource supports passing multiple types of entities at a time. No entanto, no momento, a única combinação com suporte é para os entityTypes do SharePoint e o OneDrive: driveItem, drive, site, list, listItem.However, currently the only supported combination is for SharePoint and OneDrive entityTypes: driveItem, drive, site, list, listItem. As combinações envolvendo mensagem, evento, tipos do SharePoint e do OneDrive ou externalItem não têm suporte no momento.Any combinations involving message, event, SharePoint and OneDrive types , or externalItem are currently not supported.

  • A propriedade contentSource, que define a conexão a ser usada, só será aplicável quando entityType for especificada como externalItem.The contentSource property, which defines the connection to use, is only applicable when entityType is specified as externalItem.

  • A API de pesquisa não dá suporte à classificação personalizada para mensagem, evento ou externalItem.The search API does not support custom sort for message, event or externalItem.

  • A API de pesquisa não dá suporte a agregações para mensagem, evento, site ou unidade.The search API does not support aggregations for message, event, site or drive.

  • As personalizações na pesquisa do SharePoint, como um esquema de pesquisa personalizado ou fontes de resultados, podem interferir na operação da API de Pesquisa da Microsoft.Customizations in SharePoint search, such as a custom search schema or result sources, can interfere with the operation of the Microsoft Search API.

Aviso de preterição de mudança de esquemaSchema change deprecation warning

Na versão beta, as propriedades usadas em uma solicitação e resposta de pesquisa foram renomeadas ou removidas.In the beta version, properties used in a search request and response have been renamed or removed. Na maioria dos casos, as propriedades originais estão sendo reprovadas e substituídas pelas propriedades atuais, conforme listado na tabela a seguir.In most cases, the original properties are being deprecated and replaced by the current properties, as listed in the following table.

Comece a atualizar os aplicativos existentes para usar os nomes atuais da propriedade e do tipo e obter os nomes atuais das propriedades na resposta.Start updating any existing apps to use current property and type names, and to get current property names in the response. Para compatibilidade com versões anteriores, as propriedades e tipos originais são acessíveis e funcionais até o dia 31 de dezembro de 2020, depois do qual eles serão removidos.For backward compatibility, the original properties and types are accessible and functional until December 31, 2020, after which they will be removed.

RecursoResource Tipo de alteraçãoChange type Propriedade originalOriginal property Propriedade atualCurrent property
searchRequestsearchRequest Renomear PropriedadeRename property stored_fieldsstored_fields camposfields
searchQuerysearchQuery Renomear propriedadeRename property query_stringquery_string queryStringqueryString
searchQueryStringsearchQueryString Substituir recursoDeprecate resource Não aplicávelNot applicable Não aplicávelNot applicable
searchHitsearchHit Renomear propriedadeRename property _id_id hitIdhitId
searchHitsearchHit Renomear propriedadeRename property _score_score classificaçãorank
searchHitsearchHit Remover propriedadeRemove property _sortField_sortField Não aplicávelNot applicable
searchHitsearchHit Renomear propriedadeRename property _source_source recursoresource
searchHitsearchHit Renomear propriedadeRename property _summary_summary resumosummary

Confira tambémSee also

O que há de novoWhat's new

Saiba mais sobre os novos recursos e atualizações mais recentes para este conjunto de APIs.Find out about the latest new features and updates for this API set.