Usar a API de Pesquisa da Microsoft para consultar dados

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.

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 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 usuários não podem acessar mais itens em uma pesquisa do que poderiam obter de uma operação GET correspondente com as mesmas permissões e controle de acesso.

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.

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 do 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 tem uma coluna personalizada recuperável em um listItem ou driveItem, é possível 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 estiverem 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 maneira 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 Copilot para essa conexão específica.

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 termos 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:

• Propriedades do email
• Propriedades do site

Recolher resultados da pesquisa

A propriedade collapseProperties contém um conjunto de critérios, campos e tamanho limite, que são usados para recolher resultados em um corpo de resposta. O uso de collapseProperties afeta apenas o cancelamento, 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 que você especifique um conjunto de uma ou mais propriedades de recolher.

No momento, há suporte para o recolhimento de resultados nos seguintes tipos de entidade: driveItem, listItem, drive, list, site, externalItem.

As propriedades nas quais a cláusula de colapso é aplicada precisam ser consultáveis e classificáveis ou refináveis. Para recolher em 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 retornará um HTTP 400 Bad Request erro.

Para obter exemplos que mostram como recolher resultados, consulte Recolher 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 personalizar a ordem de pesquisa especificando o 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 classificação de resultados só tem suporte nos seguintes tipos do SharePoint e do OneDrive: driveItem, listItem, list, site.

As propriedades às quais a cláusula sort é aplicada precisam ser classificáveis 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 a classificação de 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 refinadores 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 para apenas os elementos correspondentes contidos em um searchBucket. Isso é obtido passando de volta o valor aggregationsFilterToken na propriedade aggregationFilters do searchRequest subsequente.

Atualmente, há suporte para agregações para qualquer propriedade refinável nos seguintes tipos do SharePoint e do OneDrive: driveItem, listItem, list, site, e em conectores do Copilot 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.

Pesquisa de convidado

A API de Pesquisa permite que os usuários convidados pesquisem itens no SharePoint ou no OneDrive que foram 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	Perguntas e respostas	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	-	-
  Perguntas e respostas	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 acrônimo, indicador, mensagem, chatMessage, evento, pessoa, qna ou externalItem.

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

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

• A pesquisa de convidado não dá suporte a pesquisas por 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 resultados, podem interferir nas operações da API de Pesquisa da Microsoft.

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

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. No futuro, use a versão do recurso no namespace Microsoft.Graph.ExternalConnectors . Certifique-se de atualizar todas as dependências de namespace antes da data especificada. Como alternativa, considere fazer 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 os nomes de propriedade e tipo atuais e obter os nomes de propriedade atuais na resposta. Para manter a compatibilidade com versões anteriores, as propriedades e os tipos originais estão acessíveis e funcionais até 30 de setembro de 2023, após o qual serão removidos.

Conteúdo relacionado

• Saiba mais sobre alguns dos principais casos de uso:

  • Pesquisar mensagens do Teams
  • Pesquisar mensagens do Outlook
  • Pesquisar eventos do calendário
  • Pesquisar pessoa
  • Pesquisar conteúdo no OneDrive e Microsoft Office SharePoint Online
  • Pesquisar tipos personalizados importados usando conectores
  • Recolher resultados da pesquisa
  • Classificar resultados de pesquisa
  • Refinar resultados de pesquisa
  • Solicitar verificação ortográfica
  • Usar layout de exibição de pesquisa
  • Pesquisar com permissão do aplicativo
  • Resultados da pesquisa XRANK
  • Resultados de intercalação de pesquisa

• Explore as APIs no Explorador do Graph.