Usar a API de Pesquisa da Microsoft para pesquisar mensagens do Outlook

Use a API de Pesquisa da Microsoft no Microsoft Graph para pesquisar informações em mensagens de email, retornar mensagens classificadas por relevância e renderizar uma experiência de pesquisa dedicada. A pesquisa aplica-se ao corpo e aos anexos de mensagens na própria caixa de correio do usuário conectado.

Cuidado

O esquema da API de pesquisa foi alterado na versão beta. Algumas propriedades em uma solicitação e resposta de pesquisa foram renomeadas ou removidas. Para obter detalhes, consulte Aviso de substituição de alteração de esquema. Os exemplos neste tópico mostram o esquema atualizado.

Uma consulta de pesquisa pode incluir filtros que os usuários finais inserem na caixa de texto de pesquisa do Outlook.

Os resultados da pesquisa de mensagens são classificados por receivedDateTime em ordem decrescente.

A pesquisa de mensagens aplica-se a contas corporativas ou de estudante. Os usuários podem pesquisar suas próprias caixas de correio, mas não podem pesquisar caixas de correio delegadas. Para obter detalhes, consulte limitações conhecidas.

A pesquisa de mensagens também procura anexos. Os tipos de arquivo com suporte para a pesquisa de anexos de mensagens são os mesmos da pesquisa do SharePoint Online.

Exemplo 1: Pesquisar mensagens na caixa de correio de um usuário

O exemplo a seguir consulta mensagens na caixa de correio do usuário conectado que contêm a cadeia de caracteres "contoso" em qualquer parte da mensagem (o nome do remetente, assunto, corpo da mensagem ou quaisquer anexos). A consulta retorna os primeiros 25 resultados. Os resultados da pesquisa são ordenados por DateTime decrescente.

Solicitação

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

{
  "requests": [
    {
      "entityTypes": [
        "message"
      ],
      "query": {
        "queryString": "contoso"
      },
      "from": 0,
      "size": 25
    }
  ]
}

Resposta

A seguir está um exemplo da resposta, que contém uma mensagem que corresponde ao critério de pesquisa.

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

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#search",
  "value": [
    {
      "searchTerms": [
        "contoso"
      ],
      "hitsContainers": [
        {
          "total": 1,
          "moreResultsAvailable": false,
          "hits": [
            {
              "hitId": "ptWLQ4o6HYpQg8xmAAATzOzRAAA=",
              "rank": 1,
              "summary": "Here is a summary of your messages from last week",
              "resource": {
                "@odata.type": "#microsoft.graph.message",
                "createdDateTime": "2019-10-07T10:00:08Z",
                "lastModifiedDateTime": "2019-10-07T10:00:11Z",
                "receivedDateTime": "2019-10-07T10:00:09Z",
                "sentDateTime": "2019-10-07T09:59:52Z",
                "hasAttachments": false,
                "subject": "Weekly digest: Microsoft 365 changes",
                "bodyPreview": "Here is a summary of your messages from last week -   New Feature: Live captions in English-US a",
                "importance": "normal",
                "replyTo": [
                  {
                    "emailAddress": {
                      "name": "Goncalo Torres"
                    }
                  }
                ],
                "sender": {
                  "emailAddress": {
                    "name": "Office365 Message Center",
                    "address": "gtorres@contoso.com"
                  }
                },
                "from": {
                  "emailAddress": {
                    "name": "Office365 Message Center",
                    "address": "gtorres@contoso.com"
                  }
                }
              }
            }
          ]
        }
      ]
    }
  ]
}

Exemplo 2: mensagens de resultados principais da pesquisa

O exemplo a seguir usa a consulta de pesquisa mostrada no Exemplo 1 e classifica os resultados por relevância.

Solicitação

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

{
  "requests": [
    {
      "entityTypes": [
        "message"
      ],
      "query": {
        "queryString": "contoso"
      },
      "from": 0,
      "size": 15,
      "enableTopResults": true
    }
  ]
}

Resposta

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

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#search",
  "value": [
    {
      "searchTerms": [
        "contoso"
      ],
      "hitsContainers": [
        {
          "total": 1,
          "moreResultsAvailable": false,
          "hits": [
            {
              "hitId": "ptWLQ4o6HYpQg8xmAAATzOzRAAA=",
              "rank": 1,
              "summary": "Here is a summary of your messages from last week",
              "resource": {
                "@odata.type": "#microsoft.graph.message",
                "createdDateTime": "2019-10-07T10:00:08Z",
                "lastModifiedDateTime": "2019-10-07T10:00:11Z",
                "receivedDateTime": "2019-10-07T10:00:09Z",
                "sentDateTime": "2019-10-07T09:59:52Z",
                "hasAttachments": false,
                "subject": "Weekly digest: Microsoft 365 changes",
                "bodyPreview": "Here is a summary of your messages from last week -   New Feature: Live captions in English-US a",
                "importance": "normal",
                "replyTo": [
                  {
                    "emailAddress": {
                      "name": "Goncalo Torres"
                    }
                  }
                ],
                "sender": {
                  "emailAddress": {
                    "name": "Office365 Message Center",
                    "address": "gtorres@contoso.com"
                  }
                },
                "from": {
                  "emailAddress": {
                    "name": "Office365 Message Center",
                    "address": "gtorres@contoso.com"
                  }
                }
              }
            }
          ]
        }
      ]
    }
  ]
}

Limitações conhecidas

  • Você pode acessar apenas a própria caixa de correio do usuário conectado. Não há suporte para a pesquisa de caixas de correio delegadas.
  • Para mensagens, a propriedade total do tipo searchHitsContainer contém o número de resultados na página, não o número total de resultados correspondentes.
  • Não há suporte para a classificação de resultados para eventos. Uma cláusula sort na solicitação retornará um código de erro de Solicitação Inválida na resposta.

Próximas etapas

  • Last updated on