Utilizar a API de Pesquisa da Microsoft para procurar mensagens do Outlook

Utilize a API de Pesquisa da Microsoft no Microsoft Graph para procurar informações em mensagens de e-mail, devolver mensagens classificadas por relevância e compor uma experiência de pesquisa dedicada. A pesquisa aplica-se ao corpo e anexos das mensagens na caixa de correio do utilizador com sessão iniciada.

Uma consulta de pesquisa pode incluir filtros que os utilizadores finais introduzem na caixa de texto Procurar no Outlook.

Os resultados da pesquisa de mensagens são ordenados por receivedDateTime por ordem descendente.

A pesquisa de mensagens aplica-se a contas escolares ou profissionais. Os utilizadores podem procurar na sua própria caixa de correio, mas não podem procurar caixas de correio delegadas. Para obter detalhes, veja limitações conhecidas.

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

Exemplo 1: procurar mensagens na caixa de correio de um utilizador

O exemplo seguinte consulta mensagens na caixa de correio do utilizador com sessão iniciada que contêm a cadeia "contoso" em qualquer parte da mensagem (o nome do remetente, o assunto, o corpo da mensagem ou quaisquer anexos). A consulta devolve os primeiros 25 resultados. Os resultados da pesquisa são ordenados por DateTime descendente.

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

Segue-se 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: procurar mensagens de resultados principais

O exemplo seguinte utiliza a consulta de pesquisa apresentada no Exemplo 1 e ordena 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

• Só pode aceder à caixa de correio do utilizador com sessão iniciada. A pesquisa de caixas de correio delegadas não é suportada.
• Para mensagens, a propriedade total do tipo searchHitsContainer contém o número de resultados na página e não o número total de resultados correspondentes.
• A ordenação de resultados não é suportada para eventos. Uma cláusula de ordenação no pedido devolverá um código de erro Pedido Incorreto na resposta.

Próximas etapas

• Usar a API de Pesquisa da Microsoft para consultar dados