Compartilhar via

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 secção lista os casos de utilização comuns do método de consulta, com base nas propriedades e parâmetros que definiu no corpo searchRequest da 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 utilizadores não podem aceder a mais itens numa pesquisa do que podem obter de outra forma a partir de uma operação GET correspondente com as mesmas permissões e controlo 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
Fechar os resultados da pesquisa 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ónimos Acrónimos.Read.All Pesquisa da Microsoft Acrónimos no Microsoft Search na sua organização.
bookmark Marcador.Read.All Pesquisa da Microsoft Marcadores no Microsoft Search na 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 devolvidas como listas.
listItem Sites.Read.All, Sites.ReadWrite.All SharePoint e OneDrive Listar itens. Os ficheiros e pastas também são devolvidos 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 FAQ.Ler.Tudo Pesquisa da Microsoft Perguntas e respostas no Microsoft Search na 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. Tecnicamente, a API de pesquisa não suporta estas 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 suportadas que permitem obter campos recuperáveis expandidos configurados no esquema. Não pode obter propriedades expandidas de todas as outras entidades com a API de pesquisa. Por exemplo, se tiver criado um campo recuperável para externalItem no esquema de pesquisa ou se tiver uma coluna personalizada recuperável num listItem ou driveItem, pode obter estas propriedades a partir da pesquisa. Para obter uma propriedade expandida num ficheiro, especifique o tipo listItem ou driveItem no pedido.

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

Se não especificar campos no pedido, obterá o conjunto predefinido de propriedades para todos os tipos. Para propriedades expandidas, listItem, driveItem e externalItem comportam-se de forma diferente quando não são transmitidos campos no pedido:

  • listItem não devolverá nenhum campo personalizado.
  • driveItem devolverá 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 dos itens com base em determinadas ocorrências de termos na expressão de correspondência, sem alterar os itens que 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:

Fechar os resultados da pesquisa

A propriedade collapseProperties contém um conjunto de critérios, campos e tamanho de limite, que são utilizados para fechar resultados num corpo de resposta. A utilização de collapseProperties só afeta a revocação, mas não a classificação/ordenação.

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

Atualmente, a resolução de resultados é suportada nos seguintes tipos de entidade: driveItem, listItem, unidade, lista, site, externalItem.

As propriedades nas quais a cláusula de fecho é aplicada têm de ser consultadas e ordenáveis ou refináveis. Para o colapso de vários níveis, cada tamanho de limite de propriedade subsequente especificado num pedido de vários níveis deve ser menor ou igual ao anterior; caso contrário, a resposta devolve um HTTP 400 Bad Request erro.

Para obter exemplos que mostram como fechar resultados, veja fechar os resultados da pesquisa.

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-lhe personalizar a ordem de pesquisa ao especificar sortProperties 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, a ordenação dos resultados só é suportada nos seguintes tipos do SharePoint e oneDrive: driveItem, listItem, list, site.

As propriedades nas quais a cláusula de ordenação é aplicada têm de ser ordenáveis no esquema de pesquisa do SharePoint. Se a propriedade especificada no pedido não for ordenável ou não existir, a resposta devolverá um erro, HTTP 400 Bad Request. Não pode especificar a ordenação de documentos por relevância com 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 refinadores no SharePoint) são uma forma popular de melhorar 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 devolve HTTP 400 Bad Request.

Assim que a resposta for devolvida com a coleção de objetos searchBucket , é possível refinar o pedido de pesquisa apenas para os elementos correspondentes contidos num searchBucket. Isto é conseguido ao devolver 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 de Pesquisa permite que os utilizadores convidados procurem itens no SharePoint ou no OneDrive que tenham sido partilhados com os mesmos. Para aceder à lista de utilizadores convidados, aceda ao centro de administração do Microsoft 365 e, no painel de navegação esquerdo, selecione Utilizadores e selecione Utilizadores 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 seguinte lista as combinações suportadas.

    Tipo de Entidade acrónimos indicador mensagem chatMessage Unidade driveItem event externalItem list listItem pessoa qna site
    acrónimos 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 suporta ordenação personalizada para acrónimo, marcador, mensagem, chatMessage, evento, pessoa, qna ou externalItem.

  • A API de pesquisa não suporta agregações para acrónimo, marcador, mensagem, evento, site, pessoa, qna ou unidade.

  • A API de pesquisa não suporta xrank para acrónimo, marcador, mensagem, chatMessage, evento, pessoa, qna ou externalItem.

  • A pesquisa de convidados não suporta pesquisas de acrónimos, marcadores, mensagens, chatMessage, evento, pessoa, qna ou externalItem.

  • As personalizações na pesquisa do SharePoint, como um esquema de pesquisa personalizado ou origens de resultados, podem interferir com as operações da API do Microsoft Search.

  • A API de pesquisa não suporta o esquema de pesquisa ao nível do site. Utilize o esquema de pesquisa predefinido ou ao nível do inquilino.

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 espaço de nomes do Microsoft Graph será preterida. No futuro, utilize a versão do recurso no espaço de nomes Microsoft.Graph.ExternalConnectors . Certifique-se de que atualiza quaisquer dependências de espaço de nomes antes da data especificada. Em 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 atualize as aplicações existentes para utilizar a propriedade e os nomes dos tipos atuais e que obtenha os nomes das propriedades atuais na resposta. Para retrocompatibilidade, as propriedades e tipos originais estão acessíveis e funcionais até 30 de setembro de 2023, após o qual serão removidos.

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