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

  • Artículo

Use microsoft Búsqueda API en Microsoft Graph para buscar información en los 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 a los datos adjuntos de los mensajes del 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. Algunas propiedades de una solicitud de búsqueda y una respuesta se han cambiado de nombre o se han quitado. Para obtener más información, consulte Advertencia de desuso del cambio de esquema. En los ejemplos de este tema se muestra el esquema actualizado.

Una consulta de búsqueda puede incluir filtros que los usuarios finales escriban en el cuadro de texto Búsqueda de 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 en buzones delegados. Para obtener más información, consulte 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 la búsqueda de SharePoint Online.

Ejemplo 1: Búsqueda mensajes en el buzón de un usuario

En el ejemplo siguiente se consultan los mensajes del 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. DateTime descendente ordena los resultados de la búsqueda.

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: Búsqueda 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 acceder 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 coincidentes.
  • 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 incorrecta en la respuesta.

Pasos siguientes