Compartilhar via

Usar a API de Pesquisa da Microsoft para consultar dados

  • Artigo

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 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 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.

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
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. Observe que as bibliotecas de documentos também são retornadas como listas.
listItem Sites.Read.All, Sites.ReadWrite.All SharePoint e OneDrive Listar itens. Observe que os arquivos e as pastas também são retornados como itens de lista; listItem é a superclasse de driveItem.
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, você pode incluir na propriedade campos as propriedades de entidade específica para retornar nos resultados da pesquisa. Isso é semelhante a usar a opção $select, da consulta do sistema OData, em solicitações REST. A pesquisa do API não oferece suporte técnico 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 e externalItem são as únicas entidades suportadas que permitem a obtenção de campos extensíveis de recuperação configurados no esquema. Você não pode recuperar as 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 você tem uma coluna personalizada recuperável em uma listItem, você pode recuperar essas propriedades da pesquisa. Para recuperar uma propriedade estendida de um arquivo, especifique o tipo de listItem 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 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 estendidas, listItem e externalItem se comportam de forma diferente quando nenhum campo é passado na solicitação:

  • listItem não retornará nenhum campo personalizado.
  • 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 utilizado para fechar resultados num corpo de resposta. A utilização de collapseProperties só afeta a recolha, mas não as ações de 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.

Tenha em atenção que fechar os resultados é atualmente suportado para os seguintes tipos de entidade: driveItem, listItem, unidade, lista, site, externalItem.

Para utilizar a cláusula de fecho de forma eficaz, as propriedades às quais a aplica têm de ser consultados e ordenáveis ou refináveis. Ao utilizar o colapso de vários níveis, é importante ter em atenção que o tamanho limite de cada propriedade subsequente especificado num pedido de vários níveis deve ser igual ou menor do que o anterior. Se o tamanho limite de uma propriedade subsequente exceder o anterior, o servidor responderá com um HTTP 400 Bad Request erro.

Veja fechar os resultados da pesquisa para obter mais exemplos de resultados 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-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, só há suporte para a classificação de resultados nos seguintes tipos de SharePoint e OneDrive: driveItem, listItem, list e site.

As propriedades nas quais a cláusula de classificação é aplicada devem 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. Observe que 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 muito popular de melhorar a 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.

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. 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.

No corpo de solicitação do método query, especifique as queryAlterationOptions que devem ser aplicadas à consulta para as verificações ortográficas. A descrição das queryAlterationOptions são definidas em searchRequest.

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 em searchresponse, você deve definir como true a propriedade enableResultTemplate, definida em resultTemplateOptions, em searchRequest. A resposta inclui um resultTemplateId para cada searchHit, que mapeia para um dos layouts de exibição incluídos no dicionário resultTemplates incluído na resposta.

Para obter exemplos que mostram como renderizar os resultados da pesquisa, consulte Usar o layout de exibição de pesquisa.

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.

Conteúdo relacionado