Usar a API do Microsoft Pesquisa para pesquisar com resultados intercalados

Artigo
11/07/2024

O recurso searchRequest do Microsoft Pesquisa dá suporte à passagem de vários tipos de entidade em uma única solicitação e retorna resultados intercalados com os tipos de entidade solicitados classificados por relevância.

Combinações de entidade com suporte

A tabela a seguir mostra a relação entre diferentes tipos de entidade que podem ser intercalados. O tipo de entidade qna só tem suporte em beta.

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	-
mensagem	-	-	Verdadeiro	Verdadeiro	-	-	-	-	-	-	-	-	-
chatMessage	-	-	Verdadeiro	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
Pessoa	-	-	-	-	-	-	-	-	-	-	Verdadeiro	-	-
Qna	Verdadeiro	Verdadeiro	-	-	-	-	-	-	-	-	-	Verdadeiro	-
site	-	-	-	-	Verdadeiro	Verdadeiro	-	Verdadeiro	Verdadeiro	Verdadeiro	-	-	Verdadeiro

Exemplos

Exemplo 1: Pesquisa com tipos de arquivo do SharePoint e todas as combinações de conectores

O exemplo a seguir mostra uma solicitação que pesquisa com tipos de arquivo do SharePoint e toda a combinação de conectores.

Solicitação

O exemplo a seguir mostra uma solicitação.

POST https://graph.microsoft.com/beta/search/query
Content-Type: application/json

{
  "requests": [
    {
      "entityTypes": [
        "listItem",
        "site",
        "externalItem"
      ],
      "query": {
        "queryString": "contoso"
      },
      "contentSources": [
        "/external/connections/*"
      ],
      "from": 0,
      "size": 25
    }
  ]
}

Resposta

O exemplo a seguir mostra a resposta de intercalação.

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#search",
  "value": [
    {
      "searchTerms": [
        "contoso"
      ],
      "hitsContainers": [
        {
          "total": 4,
          "moreResultsAvailable": false,
          "hits": [
            {
              "hitId": "adce5789-c324-485a-a8bf-66bb809527ff",
              "rank": 1,
              "summary": "Test listItem 1",
              "resource": {
                "@odata.type": "#microsoft.graph.listItem",
                "createdDateTime": "2019-10-07T10:00:08Z",
                "lastModifiedDateTime": "2019-10-07T10:00:11Z",
                "title": "Here is a summary of your messages from last week -   New Feature: Live captions in English-US a"
              }
            },
            {
              "hitId": "microsoft.sharepoint.com,9fb3f597-167e-4c3d-b5e6-1ddc18d22d48,c53cd46e-9033-4b42-af94-0ad76ab75fd0",
              "rank": 2,
              "summary": "Test site",
              "resource": {
                "@odata.type": "#microsoft.graph.site",
                "createdDateTime": "2019-10-07T10:00:08Z",
                "lastModifiedDateTime": "2019-10-07T10:00:11Z",
                "title": "Test site summary"
              }
            },
            {
              "hitId": "ad60906b-1317-495c-b566-7b8ce1be5555",
              "rank": 4,
              "summary": "Test listItem 2",
              "resource": {
                "@odata.type": "#microsoft.graph.listItem",
                "createdDateTime": "2019-10-07T10:00:08Z",
                "lastModifiedDateTime": "2019-10-07T10:00:11Z",
                "title": "Test listItem summary 2"
              }
            }
          ]
        }
      ]
    }
  ]
}

Exemplo 2: Pesquisa com tipos de arquivo do SharePoint e combinação de conector específica

O exemplo a seguir mostra uma solicitação que pesquisa com tipos de arquivo do SharePoint e uma combinação específica de conectores.

Solicitação

O exemplo a seguir mostra uma solicitação.

POST https://graph.microsoft.com/beta/search/query
Content-Type: application/json

{
  "requests": [
    {
      "entityTypes": [
        "listItem",
        "site",
        "externalItem"
      ],
      "query": {
        "queryString": "contoso"
      },
      "contentSources": [
        "/external/connections/MicrosoftPowerBI",
        "/external/connections/Learning"
      ],
      "from": 0,
      "size": 25
    }
  ]
}

Resposta

O exemplo a seguir mostra a resposta de intercalação.

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#search",
  "value": [
    {
      "searchTerms": [
        "contoso"
      ],
      "hitsContainers": [
        {
          "total": 5,
          "moreResultsAvailable": false,
          "hits": [
            {
              "hitId": "adce5789-c324-485a-a8bf-66bb809527ff",
              "rank": 1,
              "summary": "Test listItem 1",
              "resource": {
                "@odata.type": "#microsoft.graph.listItem",
                "createdDateTime": "2019-10-07T10:00:08Z",
                "lastModifiedDateTime": "2019-10-07T10:00:11Z",
                "title": "Here is a summary of your messages from last week -   New Feature: Live captions in English-US a"
              }
            },
            {
              "hitId": "microsoft.sharepoint.com,9fb3f597-167e-4c3d-b5e6-1ddc18d22d48,c53cd46e-9033-4b42-af94-0ad76ab75fd0",
              "rank": 2,
              "summary": "Test site",
              "resource": {
                "@odata.type": "#microsoft.graph.site",
                "createdDateTime": "2019-10-07T10:00:08Z",
                "lastModifiedDateTime": "2019-10-07T10:00:11Z",
                "title": "Test site summary"
              }
            },
            {
              "hitId": "adce5789-c324-485a-a8bf-66bb809527ff=",
              "rank": 3,
              "summary": "Test externalItem",
              "contentSource": "MicrosoftPowerBI",
              "resource": {
                "@odata.type": "#microsoft.graph.externalConnectors.externalItem",
                "title": "Test externalItem summary",
              }
            },
            {
              "hitId": "adce5789-c324-485a-a8bf-66bb809527ff=",
              "rank": 4,
              "summary": "Learning externalItem",
              "contentSource": "Learning",
              "resource": {
                "@odata.type": "#microsoft.graph.externalConnectors.externalItem",
                "title": "Test externalItem summary",
              }
            },
            {
              "hitId": "ad60906b-1317-495c-b566-7b8ce1be5555",
              "rank": 5,
              "summary": "Test listItem 2",
              "resource": {
                "@odata.type": "#microsoft.graph.listItem",
                "createdDateTime": "2019-10-07T10:00:08Z",
                "lastModifiedDateTime": "2019-10-07T10:00:11Z",
                "title": "Test listItem summary 2"
              }
            }
          ]
        }
      ]
    }
  ]
}

Exemplo 3: Pesquisa com indicador e combinação de acrônimo

O exemplo a seguir mostra uma solicitação que pesquisa com indicador e acrônimo como tipos de entidade.

Solicitação

O exemplo a seguir mostra uma solicitação.

POST https://graph.microsoft.com/beta/search/query
Content-Type: application/json

{
  "requests": [
    {
      "entityTypes": [
        "bookmark",
        "acronym"
      ],
      "query": {
        "queryString": "POC"
      },
      "from": 0,
      "size": 25
    }
  ]
}

Resposta

O exemplo a seguir mostra a resposta de intercalação para indicador e acrônimo.

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#search",
  "value": [
    {
      "searchTerms": [
        "POC"
      ],
      "hitsContainers": [
        {
          "total": 2,
          "moreResultsAvailable": false,
          "hits": [
            {
              "hitId": "adce5789-c324-485a-a8bf-66bb809527ff",
              "rank": 1,
              "summary": "",
              "resource": {
                "@odata.type": "#microsoft.graph.search.acronym",
                "id": "adce5789-c324-485a-a8bf-66bb809527ff",
                "displayName": "POC",
                "description": "Acronym in Spanish",
                "webUrl": "",
                "standsFor": "prueba de concepto"
              }
            },
            {
              "hitId": "1c0599db-2e89-4327-827a-3935c999f6cc",
              "rank": 2,
              "summary": "",
              "resource": {
                "@odata.type": "#microsoft.graph.search.bookmark",
                "id": "1c0599db-2e89-4327-827a-3935c999f6cc",
                "displayName": "POC",
                "description": "A proof of concept (POC) is an exercise in which work is focused on determining whether an idea can be turned into a reality. ",
                "webUrl": "https://en.wikipedia.org/wiki/POC"
              }
            }
          ]
        }
      ]
    }
  ]
}

Exemplo 4: Intercalar conteúdo do Teams e do Outlook

O exemplo a seguir mostra como intercalar a mensagem de chat do Teams e o conteúdo da mensagem do Outlook.

Solicitação

O exemplo a seguir mostra uma solicitação.

POST https://graph.microsoft.com/v1.0/search/query
Content-Type: application/json

{
    "requests": [
        {
            "entityTypes": [
                "chatMessage",
                "message"
            ],
            "query": {
                "queryString": "*"
            },
            "from": 0,
            "size": 5
        }
    ]
}

Resposta

O exemplo a seguir mostra a resposta de intercalação.

HTTP/1.1 200 OK
Content-type: application/json

{
    "value": [
        {
            "searchTerms": [],
            "hitsContainers": [
                {
                    "hits": [
                        {
                            "hitId": "AQMkAGNhZjFkYzQ3LTc2MDYtNGZiMS04ZGE3LTQ2MjUyZmRlMzA0NgBGAAAD7MLXbKjTeUeUiM62OAqxBAcA/PUmjl3OgEumTcnPoOXsegAAAgFYAAAA/PUmjl3OgEumTcnPoOXsegABBugTfgAAAA==",
                            "rank": 1,
                            "summary": "hi",
                            "resource": {
                                "@odata.type": "microsoft.graph.chatMessage",
                                "id": "1657786709667",
                                "createdDateTime": "2022-07-14T08:18:30Z",
                                "lastModifiedDateTime": "2022-07-14T08:19:07Z",
                                "subject": "",
                                "importance": "normal",
                                "webLink": "https://teams.microsoft.com/l/message/19%3a8b00f92f-63ba-4ad7-822e-862219ba93b3_ba9f3156-32ae-4308-bd33-64a92319b578%40unq.gbl.spaces/1657786709667?context=%7B%22contextType%22:%22chat%22%7D",
                                "from": {
                                    "emailAddress": {
                                        "name": "Tong Zheng",
                                        "address": "Tong.Zheng@microsoft.com"
                                    }
                                },
                                "channelIdentity": {
                                    "channelId": "19:8b00f92f-63ba-4ad7-822e-862219ba93b3_ba9f3156-32ae-4308-bd33-64a92319b578@unq.gbl.spaces"
                                },
                                "etag": "1657786709667",
                                "chatId": "19:8b00f92f-63ba-4ad7-822e-862219ba93b3_ba9f3156-32ae-4308-bd33-64a92319b578@unq.gbl.spaces"
                            }
                        },
                        {
                            "hitId": "AQMkAGNhZjFkYzQ3LTc2MDYtNGZiMS04ZGE3LTQ2MjUyZmRlMzA0NgBGAAAD7MLXbKjTeUeUiM62OAqxBAcA-PUmjl3OgEumTcnPoOXsegAAAgEBAAAAAPz1Jo5dzoBLpk3Jz6Dl7HoAAAIJWgAAAA==",
                            "rank": 2,
                            "summary": "",
                            "resource": {
                                "@odata.type": "#microsoft.graph.message",
                                "createdDateTime": "2021-06-11T23:17:11Z",
                                "lastModifiedDateTime": "2021-06-12T02:58:00Z",
                                "receivedDateTime": "2021-06-11T23:17:11Z",
                                "sentDateTime": "2021-06-11T23:17:11Z",
                                "hasAttachments": false,
                                "internetMessageId": "<DM5PR00MB0406C60478A4456D6B0F83F8D4349@DM5PR00MB0406.namprd00.prod.outlook.com>",
                                "bodyPreview": "",
                                "importance": "normal",
                                "parentFolderId": "AQMkAGNhZjFkYzQ3LTc2MDYtNGZiMS04ZGE3LTQ2MjUyZmRlMzA0NgAuAAAD7MLXbKjTeUeUiM62OAqxBAEA-PUmjl3OgEumTcnPoOXsegAAAgEBAAAAAA==",
                                "conversationId": "AAQkAGNhZjFkYzQ3LTc2MDYtNGZiMS04ZGE3LTQ2MjUyZmRlMzA0NgAQANQdjNmPALIE6YAJmOz4Qn4=",
                                "isRead": true,
                                "isDraft": true,
                                "webLink": "https://outlook.office365.com/owa/?ItemID=AQMkAGNhZjFkYzQ3LTc2MDYtNGZiMS04ZGE3LTQ2MjUyZmRlMzA0NgBGAAAD7MLXbKjTeUeUiM62OAqxBAcA%2FPUmjl3OgEumTcnPoOXsegAAAgEBAAAAAPz1Jo5dzoBLpk3Jz6Dl7HoAAAIJWgAAAA%3D%3D&exvsurl=1&viewmodel=ReadMessageItem",
                                "inferenceClassification": "focused"
                            }
                        }
                    ],
                    "total": 2,
                    "moreResultsAvailable": false
                }
            ]
        }
    ],
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(microsoft.graph.searchResponse)"
}

Limitações conhecidas

Não há suporte para classificação personalizada em cenários de intercalação, todos os itens são ordenados por relevância.
O QueryTemplate só tem suporte para itens de arquivo em uma consulta de intercalação. Os resultados do item externo não são filtrados na resposta. Não recomendamos que você use queryTemplate em solicitações de intercalação.
Não há suporte para o colapso.
Não há suporte para modificação de ortográfico. Há suporte apenas para sugestões de ortográfico.
Não há suporte para o modelo de resultado.
As limitações de agregação ocorrerão se o campo agregado existir em vários tipos de arquivo do Sharepoint (site, unidade, driveItem, list, listItem) e conectores. Os resultados da agregação mostram dois buckets de agregação com o mesmo nome; para ignorar a limitação, renomeie um deles.

Próximas etapas

Usar a API de Pesquisa da Microsoft para consultar dados

Compartilhar via

Usar a API do Microsoft Pesquisa para pesquisar com resultados intercalados

Combinações de entidade com suporte

Exemplos

Exemplo 1: Pesquisa com tipos de arquivo do SharePoint e todas as combinações de conectores

Solicitação

Resposta

Exemplo 2: Pesquisa com tipos de arquivo do SharePoint e combinação de conector específica

Solicitação

Resposta

Exemplo 3: Pesquisa com indicador e combinação de acrônimo

Solicitação

Resposta

Exemplo 4: Intercalar conteúdo do Teams e do Outlook

Solicitação

Resposta

Limitações conhecidas

Próximas etapas

Comentários

Recursos adicionais