Usar la API Búsqueda de Microsoft para buscar Outlook mensajes

Use la API Búsqueda de Microsoft para buscar información en mensajes de correo electrónico, devolver mensajes clasificados por relevancia y representar una experiencia de búsqueda dedicada. La búsqueda se aplica al cuerpo y los datos adjuntos de los mensajes en el propio buzón del usuario que ha iniciado sesión.

Precaución

El esquema de la API de búsqueda ha cambiado en la versión beta con algunas propiedades de una solicitud de búsqueda y respuesta cuyo nombre o respuesta se han quitado. Obtenga más información sobre el desuso. En los ejemplos de este tema se muestra el esquema actualizado que se va a usar en v1.0 y beta.

Una consulta de búsqueda puede incluir filtros que los usuarios finales escriben en el cuadro de texto Buscar en Outlook.

Los resultados de la búsqueda de mensajes se ordenan por receivedDateTime en orden descendente.

La búsqueda de mensajes se aplica a cuentas profesionales o educativas. Los usuarios pueden buscar en su propio buzón, pero no pueden buscar buzones delegados. Para obtener más información, vea limitaciones conocidas.

La búsqueda de mensajes también busca datos adjuntos. Los tipos de archivo admitidos para la búsqueda de datos adjuntos de mensajes son los mismos que para SharePoint búsqueda en línea.

Ejemplo 1: Buscar mensajes en el buzón de un usuario

En el ejemplo siguiente se consultan mensajes en el buzón del usuario que ha iniciado sesión que contienen la cadena "contoso" en cualquier parte del mensaje (el nombre del remitente, el asunto, el cuerpo del mensaje o los datos adjuntos). La consulta devuelve los primeros 25 resultados. Los resultados de la búsqueda se ordenan por DateTime descendente.

Solicitud

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

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

Respuesta

A continuación se muestra un ejemplo de la respuesta, que contiene un mensaje que coincide con el criterio de búsqueda.

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"
                  }
                }
              }
            }
          ]
        }
      ]
    }
  ]
}

Ejemplo 2: Buscar mensajes de resultados principales

En el ejemplo siguiente se usa la consulta de búsqueda que se muestra en el ejemplo 1 y se ordenan los resultados por relevancia.

Solicitud

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
    }
  ]
}

Respuesta

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"
                  }
                }
              }
            }
          ]
        }
      ]
    }
  ]
}

Limitaciones conocidas

  • Solo puede tener acceso al buzón del usuario que ha iniciado sesión. No se admite la búsqueda de buzones delegados.
  • Para los mensajes, la propiedad total del tipo searchHitsContainer contiene el número de resultados de la página, no el número total de resultados que coinciden.
  • Los resultados de ordenación no se admiten para eventos. Una cláusula de ordenación de la solicitud devolverá un código de error De solicitud mala en la respuesta.

Pasos siguientes