Usar a API de Pesquisa da Microsoft para consultar dados

  • Artigo

Importante

As APIs na versão /beta no Microsoft Graph estão sujeitas a alterações. Não há suporte para o uso dessas APIs em aplicativos de produção. Para determinar se uma API está disponível na v1.0, use o seletor Versão.

Você pode utilizar a API de Pesquisa da Microsoft para consultar os dados do Microsoft 365 nos seus aplicativos.

As solicitações de pesquisa são executadas no contexto do usuário conectado, identificado usando um token de acesso com permissões delegadas.

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. Encontre mais detalhes sobre a substituição. Atualize as consultas da API de pesquisa em todos os aplicativos anteriores.

Casos de uso comuns

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.

Esta seção lista os casos de uso comuns do método de consulta, com base nas propriedades e parâmetros definidos no corpo searchRequest de consulta.

As solicitações de pesquisa são executadas em nome do usuário. Os resultados da pesquisa têm escopo para impor o controle de acesso aplicado aos itens. Por exemplo, no contexto de arquivos, as permissões em relação aos arquivos serão avaliadas como parte da solicitação de pesquisa. Os usuários não podem acessar mais itens em uma pesquisa do que podem obter de uma operação GET correspondente com as mesmas permissões e controle de acesso.

Casos de uso Propriedades a serem definidas no corpo da solicitação de consulta
Resultados da pesquisa de escopo com base em tipos de entidade entityTypes
Resultados da página from e size
Obter os emails mais relevantes enableTopResults
Obter as propriedades selecionadas campos
Usar KQL em termos de consulta query
Resultados da pesquisa de colapso collapseProperties
Classificar resultados de pesquisa sortProperties
Refinar os resultados usando agregações aggregations
Pesquisar tipos personalizados importados usando conectores contentSources
Solicitar verificação ortográfica queryAlterationOptions
Layout de exibição de pesquisa (visualização) resultTemplateOptions

Pesquisa de escopo com base em tipos de entidade

Defina o escopo da solicitação de pesquisa usando a propriedade entityTypes no conteúdo da solicitação query. A tabela a seguir descreve os tipos disponíveis para consulta e as permissões com suporte para acessar os dados.

EntityType Escopo de permissão necessário para acessar os itens Origem Comentário
Acrônimo Acronym.Read.All Pesquisa da Microsoft Acrônimos no Microsoft Pesquisa em sua organização.
bookmark Bookmark.Read.All Pesquisa da Microsoft Indicadores no Microsoft Pesquisa em sua organização.
chatMessage Chat.Read, Chat.ReadWrite, ChannelMessage.Read.All Teams Mensagens do Teams.
message Mail.Read, Mail.ReadWrite Exchange Online Mensagens de email.
event Calendars.Read, Calendars.ReadWrite Exchange Online Eventos do calendário.
unidade Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All SharePoint Bibliotecas de documentos.
driveItem Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All SharePoint e OneDrive Arquivos, pastas, páginas e notícias.
list Sites.Read.All, Sites.ReadWrite.All SharePoint e OneDrive Listas. As bibliotecas de documentos também são retornadas como listas.
listItem Sites.Read.All, Sites.ReadWrite.All SharePoint e OneDrive Listar itens. Arquivos e pastas também são retornados como itens de lista; listItem é a super classe de driveItem.
externalItem ExternalItem.Read.All Conectores do Microsoft Graph Todo o conteúdo está absorvido pela API dos conectores do Microsoft Graph.
pessoa People.Read Troca Online Contatos pessoais e contatos ou objetos endereçáveis na sua organização.
Qna QnA.Read.All Pesquisa da Microsoft Perguntas e respostas no Microsoft Pesquisa em sua organização.
site Sites.Read.All, Sites.ReadWrite.All SharePoint Sites no SharePoint.

Resultados da pesquisa de página

Para controlar a paginação dos resultados da pesquisa, especifique as duas seguintes propriedades no corpo da solicitação query:

  • from – um número inteiro que indica o ponto de partida baseado em 0 para listar os resultados da pesquisa na página. O valor padrão é 0.

  • size – um número inteiro que indica o número de resultados a serem retornados para uma página. O padrão é 25 resultados. O máximo é de 1000 resultados.

Observe os seguintes limites se você estiver pesquisando a entidade event ou message:

  • 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.
  • O número máximo de resultados por página (size) é 25 para message e event.

O limite superior para itens do SharePoint ou do OneDrive é 1000. Um tamanho de página razoável é 200. Um tamanho de página maior geralmente gera uma latência maior.

Práticas recomendadas:

  • Especifique uma primeira página menor na solicitação inicial. Por exemplo, especifique from como 0 e size como 25.

  • Pagine as páginas subsequentes atualizando as propriedades from e size. Você pode aumentar o tamanho de página em cada solicitação subsequente. A tabela a seguir mostra um exemplo.

    Página from size
    1 0 25
    2 25 50
    3 75 75
    4 150 100

Obter os emails mais relevantes

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.

Obter as propriedades selecionadas

Ao pesquisar um tipo de entidade, como mensagem, evento, unidade, driveItem, lista, listItem, site, externalItem ou pessoa, você pode incluir nos fields propriedades de entidade específicas para retornar nos resultados da pesquisa. Isso é semelhante a usar a opção $select, da consulta do sistema OData, em solicitações REST. A API de pesquisa não dá suporte tecnicamente a essas opções de consulta porque o comportamento é expresso no corpo post.

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.

As entidades listItem, driveItem e externalItem são as únicas entidades com suporte que permitem obter campos recuperáveis estendidos configurados no esquema. Você não pode recuperar propriedades estendidas de todas as outras entidades usando a API de pesquisa. Por exemplo, se você criou um campo recuperável para externalItem no esquema de pesquisa ou se tiver uma coluna personalizada recuperável em um listItem ou driveItem, poderá recuperar essas propriedades da pesquisa. Para recuperar uma propriedade estendida em um arquivo, especifique o tipo listItem ou driveItem na solicitação.

Se os campos especificados na solicitação não estiverem presentes no esquema ou não forem marcados como recuperáveis, eles não serão retornados na resposta. Campos inválidos na solicitação são ignorados silenciosamente.

Se você não especificar nenhum campo na solicitação, obterá o conjunto padrão de propriedades para todos os tipos. Para propriedades estendidas, listItem, driveItem e externalItem se comportam de forma diferente quando nenhum campo é passado na solicitação:

  • listItem não retornará nenhum campo personalizado.
  • driveItem retornará um listItem interno com um campo vazio.
  • externalItem retornará todos os campos marcados com o atributo recuperável no esquema do conector do Microsoft Graph para essa conexão em particular.

Suporte a KQL (Linguagem de Consulta de Palavra-chave)

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). O operador XRANK aumenta a classificação dinâmica de itens com base em determinadas ocorrências de termo dentro da expressão de correspondência, sem alterar quais itens correspondem à consulta. A sintaxe e o comando dependem dos tipos de entidade (na propriedade entityTypes) que você direciona no corpo da solicitação query.

Dependendo do tipo de entidade, as propriedades pesquisáveis variam. Veja mais detalhes em:

Resultados da pesquisa de colapso

A propriedade collapseProperties contém um conjunto de critérios, campos e tamanho de limite, que são usados para o colapso resulta em um corpo de resposta. O uso de collapseProperties só afeta o recall, mas não a classificação/classificação.

O método de consulta permite personalizar a propriedade collapse especificando collapseProperties no requests parâmetro, que é uma coleção de objetos collapseProperty . Isso permite especificar um conjunto de uma ou mais propriedades de colapso.

Atualmente, há suporte para resultados em colapso nos seguintes tipos de entidade: driveItem, listItem, drive, list, site, externalItem.

As propriedades nas quais a cláusula de colapso é aplicada precisam ser consultadas e classificáveis ou refináveis. Para o colapso de vários níveis, cada tamanho de limite de propriedade subsequente especificado em uma solicitação de vários níveis deve ser menor ou igual ao anterior; caso contrário, a resposta retorna um HTTP 400 Bad Request erro.

Para obter exemplos que mostram como recolher resultados, confira resultados da pesquisa de colapso.

Classificar resultados de pesquisa

Os resultados da pesquisa na resposta são classificados na ordem de classificação padrão a seguir:

  • mensagem e evento são classificados por data.
  • Todos os tipos de SharePoint, OneDrive, pessoas e conectores são classificados por relevância.

O método de consulta permite personalizar a ordem de pesquisa especificando as classificaçõesProperties no requests parâmetro, que é uma coleção de objetos sortProperty . Isso permite especificar uma lista de uma ou mais propriedades classificáveis e a ordem de classificação.

Atualmente, os resultados de classificação só têm suporte nos seguintes tipos do SharePoint e do OneDrive: driveItem, listItem, list, site.

As propriedades nas quais a cláusula de classificação é aplicada precisam ser classificadas no esquema de pesquisa do SharePoint. 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. Você não pode especificar para classificar documentos por relevância usando 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.

Confira classificar resultados de pesquisa para obter exemplos que mostram como classificar resultados.

Refinar os resultados usando agregações

As agregações (também conhecidas como refinarias no SharePoint) são uma maneira popular de aprimorar uma experiência de pesquisa. Além dos resultados, eles fornecem algum nível de informações agregadas no conjunto de resultados de pesquisa. Por exemplo, você pode fornecer informações sobre os autores mais representados dos documentos correspondentes à consulta, ou os tipos de arquivo mais representados, etc.

NasearchRequest, especifique as agregações que devem ser retornadas além dos resultados da pesquisa. 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.

As propriedades nas quais a agregação é solicitada devem ser refináveis no esquema de pesquisa do SharePoint. Se a propriedade especificada não for refinável ou não existir, a resposta retornará HTTP 400 Bad Request.

Depois que a resposta é retornada contendo a coleção de objetos searchBucket , é possível refinar a solicitação de pesquisa apenas para os elementos correspondentes contidos em um searchBucket. Isso é obtido passando de volta o valor aggregationsFilterToken na propriedade aggregationFilters da pesquisa subsequenteRequest.

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.

Confira refinar os resultados da pesquisa para obter exemplos que mostram como usar a agregação para melhorar e restringir os resultados da pesquisa.

Solicitar verificação ortográfica

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. 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. Você também pode obter as informações de verificação ortográfica para erros de digitação na propriedade queryAlterationResponse da searchresponse.

Em searchRequest, especifique as queryAlterationOptions que devem ser aplicadas à consulta para correções ortográficas. Para obter detalhes sobre a propriedade queryAlterationOptions, consulte searchAlterationOptions.

Para exemplos que mostram como usar verificações ortográficas, consulte Solicitar verificação ortográfica.

Layout de exibição de pesquisa

A API de pesquisa permite renderizar resultados de pesquisa de conectores, usando o layout de exibição ou modelo de resultado configurado pelo administrador de TI para cada conector. Os modelos de resultados são Cartões Adaptáveis, que são uma combinação semanticamente significativa de layout e dados.

Para obter o modelo de resultado no searchResponse, você tem que definir verdadeiro o enableResultTemplate propriedade, definida no resultTemplateOptions, em o searchRequest. A resposta inclui um resultTemplateId para cada ocorrência de pesquisa, que mapeia para um dos layouts de exibição incluídos no dicionário resultTemplates incluído na resposta.

Confira Usar layout de exibição de pesquisa para obter exemplos.

A API Pesquisa permite que os usuários convidados pesquisem itens no SharePoint ou no OneDrive compartilhados com eles. Para acessar a lista de usuários convidados, acesse o Centro de administração do Microsoft 365 e, na navegação à esquerda, escolha Usuários e selecione Usuários convidados.

Tratamento de erros

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.

Limitações conhecidas

A API de pesquisa tem as seguintes limitações:

  • O método query é definido para permitir a passagem de um conjunto de uma ou mais instâncias de searchRequest de uma só vez. No entanto, atualmente o serviço dá suporte apenas a um único searchRequest por vez.

  • O recurso searchRequest dá suporte à passagem de vários tipos de entidades por vez. A tabela a seguir lista as combinações com suporte.

    Tipo de entidade Acrônimo indicador mensagem chatMessage Unidade driveItem event externalItem list listItem Pessoa Qna site
    Acrônimo Verdadeiro Verdadeiro - - - - - - - - - Verdadeiro -
    indicador Verdadeiro Verdadeiro - - - - - - - - - Verdadeiro -
    chatMessage - - - Verdadeiro - - - - - - - - -
    Unidade - - - - Verdadeiro Verdadeiro - Verdadeiro Verdadeiro Verdadeiro - - Verdadeiro
    driveItem - - - - Verdadeiro Verdadeiro - Verdadeiro Verdadeiro Verdadeiro - - Verdadeiro
    event - - - - - - Verdadeiro - - - - - -
    externalItem - - - - Verdadeiro Verdadeiro - Verdadeiro Verdadeiro Verdadeiro - - Verdadeiro
    list - - - - Verdadeiro Verdadeiro - Verdadeiro Verdadeiro Verdadeiro - - Verdadeiro
    listItem - - - - Verdadeiro Verdadeiro - Verdadeiro Verdadeiro Verdadeiro - - Verdadeiro
    mensagem - - Verdadeiro - - - - - - - - - -
    Pessoa - - - - - - - - - - Verdadeiro - -
    Qna Verdadeiro Verdadeiro - - - - - - - - - Verdadeiro -
    site - - - - Verdadeiro Verdadeiro - Verdadeiro Verdadeiro Verdadeiro - - Verdadeiro

  • A propriedade contentSource, que define a conexão a ser usada, só será aplicável quando entityType for especificada como externalItem.

  • A API de pesquisa não dá suporte à classificação personalizada para sigla, indicador, mensagem, chatMessage, evento, pessoa, qna ou externalItem.

  • A API de pesquisa não dá suporte a agregações para sigla, indicador, mensagem, evento, site, pessoa, qna ou unidade.

  • A API de pesquisa não dá suporte a xrank para sigla, indicador, mensagem, chatMessage, evento, pessoa, qna ou externalItem.

  • A pesquisa de convidado não dá suporte a pesquisas de acrônimo, indicador, mensagem, chatMessage, evento, pessoa, qna ou externalItem.

  • Personalizações na pesquisa do SharePoint, como um esquema de pesquisa personalizado ou fontes de resultado, podem interferir nas operações de API do Microsoft Pesquisa.

  • A API de pesquisa não dá suporte ao esquema de pesquisa no nível do site. Use o esquema de pesquisa no nível do locatário ou padrão.

Aviso de preterição de mudança de esquema

A partir de 31 de agosto de 2023, a versão beta do recurso externalItem no namespace do Microsoft Graph será preterida. Daqui para frente, use a versão do recurso no namespace Microsoft.Graph.ExternalConnectors . Certifique-se de atualizar as dependências do namespace antes da data especificada. Como alternativa, considere a transição para a versão v1.0 da API.

Na versão beta, as propriedades usadas em uma solicitação e resposta de pesquisa foram renomeadas ou removidas. Na maioria dos casos, as propriedades originais estão sendo reprovadas e substituídas pelas propriedades atuais, conforme listado na tabela a seguir.

Recomendamos que você atualize os aplicativos existentes para usar a propriedade atual e nomes de tipo e para obter nomes de propriedade atuais na resposta. Para compatibilidade com versões anteriores, as propriedades e tipos originais são acessíveis e funcionais até 30 de setembro de 2023, após as quais serão removidas.

Recurso Tipo de alteração Propriedade original Propriedade atual
searchRequest Renomear Propriedade stored_fields campos
searchQuery Renomear propriedade query_string queryString
searchQueryString Substituir recurso Não aplicável Não aplicável
searchHit Renomear propriedade _id hitId
searchHit Renomear propriedade _score classificação
searchHit Remover propriedade _sortField Não aplicável
searchHit Renomear propriedade _source recurso
searchHit Renomear propriedade _summary resumo
entityTypes Renomear o valor de enumeração unknownfuturevalue unknownFutureValue

Conteúdo relacionado