Referencia de la API de REST de las notificaciones de transmisión por secuencias de Outlook (versión preliminar)

  • Artículo

Se aplica a: Exchange Online | Office 365 | Hotmail.com | Live.com | MSN.com | Outlook.com | Passport.com

Nota

Esta versión de la documentación trata sobre la API de notificaciones de transmisión por secuencias en la versión preliminar Las características de la versión preliminar están sujetas a cambios antes de la finalización, y pueden interrumpir el código que las usa. Por ello, en general, debe utilizar solo una versión de producción de una API en su código de producción. Si está disponible, la versión 2.0 es la preferida actualmente.

La API REST de notificaciones de transmisión por secuencias de Outlook envía notificaciones en conexión directa para que las aplicaciones de los clientes sepan los cambios de los datos del buzón del usuario. Estos cambios pueden producirse en los datos de correo, calendario, contactos o tareas del usuario protegidos por Azure Active Directory en Office 365 y en datos similares en cuentas de Microsoft, específicamente en estos dominios: Hotmail.com, Live.com, MSN.com, Outlook.com y Passport.com.

Nota

Para simplificar la referencia, en el resto de este artículo se utiliza Outlook.com para englobar a estos dominios de cuentas Microsoft.

Información general

El servicio de notificaciones de transmisión por secuencias de Office 365 establece una conexión directa con un cliente y envía notificaciones de cambios de datos solicitadas por una aplicación de cliente.

Cuando una aplicación se suscribe a notificaciones de un tipo de evento de cambio en un recurso específico (como mensajes en la Bandeja de entrada del usuario), se establece una conexión duradera entre el servidor de Office 365 y el cliente. Cuando se produce un evento desencadenante (como un nuevo mensaje en la Bandeja de entrada), el servicio de Office 365 transmite en secuencias una notificación al cliente. El cliente analiza la notificación y realiza acciones de acuerdo con su lógica empresarial, como obtener el nuevo mensaje y actualizar el recuento de no leídos.

Comparar la transmisión por secuencias y las notificaciones de inserción

Las aplicaciones de correo, calendario y CRM generalmente utilizan las notificaciones para actualizar su caché local, las vistas de cliente correspondientes o el sistema backend cuando se producen cambios. Outlook es compatible tanto con las notificaciones de transmisión por secuencias como con las notificaciones push. notificaciones. Las notificaciones de inserción requieren que el cliente proporcione un servicio web de escucha para recibir notificaciones del servidor de Office 365, mientras que las notificaciones de transmisión requieren solo una conexión directa entre el cliente y el servidor de Office 365. Una vez que se establece una conexión con el servidor, la conexión permanece abierta durante un período específico. Durante este tiempo, el cliente publica una solicitud GetNotifications duradera solo una vez; cada vez que se produce un evento desencadenante, el servidor puede simplemente enviar una notificación como parte de la secuencia de respuesta. Esto continúa hasta que el tiempo de espera se agota, el cliente termina la conexión o se produce un problema en la red.

Usar la API REST de las notificaciones de transmisión por secuencias

Autenticación

Para suscribirse, obtener y cerrar notificaciones, especifique los ámbitos adecuados para los tipos de recursos de los que quiere recibir notificaciones.

Ámbito mínimo necesario

Uno de los siguientes ámbitos de lectura correspondiente al recurso de destino:

Como cualquier otra API REST de Outlook, para cada solicitud a la API de notificaciones de transmisión por secuencias de Outlook, debería incluir un token de acceso válido. Obtener un token de acceso le obliga a registrar e identificar su aplicación y a obtener la autorización correspondiente.

Puede obtener más información sobre algunas opciones de registro y autorización simplificadas para usted. Tenga esto en cuenta a medida que avance con las operaciones específicas en la API de notificaciones.

Versión de la API

Actualmente, esta API está en estado de la versión preliminar y solo está disponible en la versión beta del extremo de la API REST:

https://outlook.office.com/api/beta/

Usuario objetivo

Las solicitudes de la API de notificaciones de transmisión por secuencias siempre se realizan en nombre del usuario actual.

Operaciones de notificaciones de transmisión por secuencias

Suscribirse a los cambios en mi correo, calendario, contactos o tareas

Se suscribe a las notificaciones de transmisión cuando el correo, los eventos del calendario, los contactos o las tareas cambian en un buzón de Office 365 o Outlook.com. Este es el primer paso para que un cliente empiece a recibir notificaciones de un recurso (una entidad o colección de entidades).

POST https://outlook.office.com/api/beta/me/subscriptions

Especifique en el cuerpo de la solicitud las siguientes propiedades obligatorias para una solicitud de suscripción de transmisión por secuencias. Para obtener más información, consulte  Entidades de notificación.

  • odata.type - Incluido "@odata.type":"#Microsoft.OutlookServices.StreamingSubscription".

  • ChangeType : especifica los tipos de eventos que se supervisarán para ese recurso. Consulte en ChangeType los tipos admitidos.

  • Resource : especifica el recurso que se supervisará y sobre el que se recibirán notificaciones. Puede usar los parámetros de consulta opcionales, $filter o $select, para restringir las condiciones de una notificación o incluir propiedades específicas en una notificación enriquecida. Los recursos admitidos son los siguientes:

    • Una carpeta normal o una carpeta de búsquedas para mensajes, eventos, contactos o tareas. Por ejemplo:

      https://outlook.office.com/api/beta/me/mailfolders('inbox')/messages

      https://outlook.office.com/api/beta/me/taskfolders('{folder_id}')/tasks

    • O una colección de entidades de nivel superior de mensajes, eventos, contactos o tareas, como por ejemplo:

      https://outlook.office.com/api/beta/me/messages

      https://outlook.office.com/api/beta/me/events

      https://outlook.office.com/api/beta/me/contacts

      https://outlook.office.com/api/beta/me/tasks

Si la solicitud de suscripción se procesa correctamente, se devuelve un id. de suscripción. De forma predeterminada, este id. de suscripción caduca en 90 minutos a menos que el cliente empiece a estar receptivo para notificaciones de una conexión. Mientras la conexión esté abierta, la suscripción se renovará automáticamente.

Ejemplo de solicitud de suscripción

La siguiente solicitud crea una suscripción de transmisión por secuencias a los cambios realizados, actualizados y eliminados en la Bandeja de entrada del usuario.

POST https://outlook.office.com/api/beta/me/subscriptions HTTP/1.1
Content-Type: application/json

{
   @odata.type: "#Microsoft.OutlookServices.StreamingSubscription",
   Resource: "https://outlook.office.com/api/beta/me/mailfolders('inbox')/Messages",
   ChangeType: "Created,Updated,Deleted"
}

Ejemplo de respuesta de suscripción

Una respuesta correcta devuelve HTTP 201 e incluye el id. de suscripción. A continuación, puede ver un ejemplo de respuesta:

HTTP/1.1 201 Created

{
    "@odata.context":"https://outlook.office.com/api/beta/$metadata#Me/Subscriptions/$entity",
    "@odata.type":"#Microsoft.OutlookServices.StreamingSubscription",
    "@odata.id":"https://outlook.office.com/api/beta/Users('266efe5a-0fd7-4edd-877b-b2d1e561f193@ae01a323-3934-4475-a32d-af1274312bb0')/Subscriptions('RUM4OEJFNUIQUQ4MQ==')",
    "Id":"RUM4OEJFNUIQUQ4MQ==",
    "Resource":"https://outlook.office.com/api/beta/me/mailfolders('inbox')/Messages",
    "ChangeType":"Created, Updated, Deleted, Missed"
}

Refinar las condiciones de notificación

Puede limitar las notificaciones a un subconjunto de elementos utilizando una cláusula $filter. Por ejemplo, la siguiente solicitud de suscripción crea una suscripción que desencadena una notificación solo cuando se realizan cambios en los mensajes cuyo campo de asunto sea "Suplementos".

POST https://outlook.office.com/api/beta/me/subscriptions HTTP/1.1
Content-Type: application/json

{
   @odata.type: "#Microsoft.OutlookServices.StreamingSubscription",
   Resource: "https://outlook.office.com/api/beta/me/mailfolders('inbox')/Messages?$filter=Subject%20eq%20%27Supplements%27",
   ChangeType: "Created,Updated,Deleted"
}

Una suscripción correcta tiene un aspecto similar al siguiente:

HTTP/1.1 201 Created

{
    "@odata.context":"https://outlook.office.com/api/beta/$metadata#Me/Subscriptions/$entity",
    "@odata.type":"#Microsoft.OutlookServices.StreamingSubscription",
    "@odata.id":"https://outlook.office.com/api/beta/Users('266efe5a-0fd7-4edd-877b-b2d1e561f193@ae01a323-3934-4475-a32d-af1274312bb0')/Subscriptions('MjcwOUQ2MjEtQUQ4MQ==')",
    "Id":"MjcwOUQ2MjEtQUQ4MQ==",
    "Resource":"https://outlook.office.com/api/beta/me/mailfolders('inbox')/Messages?$filter=Subject%20eq%20%27Supplements%27",
    "ChangeType":"Created, Updated, Deleted, Missed"
}

Suscribirse a notificaciones de transmisión por secuencias enriquecidas

Una suscripción configurada simplemente para una colección de recursos devuelve el id. de una instancia de recursos que ha cambiado. Debe obtener por separado las propiedades de esa instancia. La primera solicitud de suscripción anterior es un ejemplo de este tipo de suscripción. La transmisión por secuencias de notificaciones en la siguiente sección solo muestra que el id. de recurso se ha devuelto en una notificación.

Alternativamente, puede usar un $select parámetro en la solicitud de suscripción, especifique las propiedades que le interesan y devuelva esos valores de propiedad también en las notificaciones de transmisión por secuencias.

En el ejemplo siguiente, se solicitan notificaciones de transmisión por secuencias para incluir la propiedad Subject cuando se ha creado un evento:

POST https://outlook.office.com/api/beta/me/subscriptions HTTP/1.1
Content-Type: application/json

{
    @odata.type:"#Microsoft.OutlookServices.StreamingSubscription",
    Resource: "https://outlook.office.com/api/beta/me/events?$select=Subject",
    ChangeType: "Created"
}

Después de suscribirse correctamente a las notificaciones enriquecidas de transmisión por secuencias, escuche las notificaciones para obtener la propiedad Subject en las cargas útiles de notificación enriquecidas.

Escuchar notificaciones

El cliente crea una conexión POST pendiente duradera de las suscripciones especificadas para solicitar al servidor que inicie las notificaciones de transmisión por secuencias.

POST https://outlook.office.com/api/beta/Me/GetNotifications

Esta solicitud POST no se completa hasta que el elemento ConnectionTimeoutinMinutes especificado se alcanza y el servidor finaliza el blob JSON en la respuesta, o si hay otros problemas y el cliente o el servidor cierran la conexión.

Siempre que la conexión esté abierta, todas las suscripciones que usan la conexión se renuevan automáticamente. Si la conexión finaliza, estas suscripciones también caducarán en 90 minutos, a menos que el cliente establezca una nueva conexión para estas suscripciones.

Asegúrese de que el código que crea esta solicitud POST gestione el código de estado de retorno HTTP 404 Not found, que se devolverá si una suscripción especificada realmente ha caducado. Si eso ocurre, solicite una nueva suscripción antes de escuchar las notificaciones de nuevo.

Parámetro del cuerpo obligatorio Tipo Descripción
ConnectionTimeoutInMinutes int32 Número de minutos durante los que la conexión debe permanecer activa.
KeepAliveNotificationIntervalInSeconds int32 El intervalo utilizado por el servidor para enviar notificaciones de mantenimiento de conexión para notificar al cliente que la conexión sigue abierta.
SubscriptionIds Colección (Cadena) Identificadores de las suscripciones sobre las que se notificará en esta conexión.

Ejemplos de solicitudes de escucha

POST https://outlook.office.com/api/beta/Me/GetNotifications HTTP/1.1
Content-Type: application/json

{
   ConnectionTimeoutInMinutes: 30,
   KeepAliveNotificationIntervalInSeconds: 15,
   SubscriptionIds: [
       "N0UzMEU4RjMtMjg1Ri00OEFGLUE5NzEtRDM5MkI3NjBDMDY5XzdFMzU4QTE1LTFCQjAtNDc4NS04MTg2LUYwRjFFNUVFNTNDRg=="
   ]
}

Puede usar la misma conexión de larga duración para escuchar notificaciones de varias suscripciones incluyendo más de un id. de suscripción en la solicitud POST.

POST https://outlook.office.com/api/beta/Me/GetNotifications HTTP/1.1
Content-Type: application/json

{
   ConnectionTimeoutInMinutes: 30,
   KeepAliveNotificationIntervalInSeconds: 15,
   SubscriptionIds: [
       "N0UzMEU4RjMtMjg1Ri00OEFGLUE5NzEtRDM5MkI3NjBDMDY5XzdFMzU4QTE1LTFCQjAtNDc4NS04MTg2LUYwRjFFNUVFNTNDRg==",
       "Dc4NS04MTg2LUYwRjFFNUVFNTNDRgN0UzMEU4RjMtMjg1Ri00OEFGLUE5NzEtRDM5MkI3NjBDMDY5XzdFMzU4QTE1LTFCQjAtN=="
   ]
}

Ejemplo de transmisión por secuencias de notificaciones

Una vez que el servicio está configurado, el cliente recibe el inicio del blob JSON de las notificaciones.

{
    {"@odata.context":"https://outlook.office.com/api/beta/metadata#Notifications", 
    "value": [

El servidor envía una notificación de mantenimiento de conexión a intervalos fijos para que mantener la conexión abierta y activa. Este intervalo lo establece el cliente en la propiedad KeepAliveNotificationIntervalInSeconds. El formato de la notificación de mantenimiento de conexión debe ser así:

{
    "@odata.type": "#Microsoft.OutlookServices.KeepAliveNotification",
    "Status": "OK"
}

Cuando se realiza un cambio en el servidor, este envía una notificación al cliente mediante la conexión. En cada notificación, el servidor establece la propiedad SubscriptionExpirationDateTime y sigue renovándola siempre que la notificación anterior sea correcta.

{ 
    "@odata.type": "#Microsoft.OutlookServices.Notification",
    "Id": null, 
    "SubscriptionId": "N0UzMEU4...", 
    "SubscriptionExpirationDateTime": "2016-09-09T18:36:42.3454926Z",
    "SequenceNumber": 9, 
    "ChangeType": "Created", 
    "Resource": "https://outlook.office.com/api/beta/Users('bee8ce18AAA')/Messages('AAMkADdlAA=')", 
    "ResourceData": { 
        "@odata.type": "#Microsoft.OutlookServices.Message", 
        "@odata.id": "https://outlook.office.com/api/beta/Users('bee8ce18AAA')/Messages('AAMkADdlAA=')", 
        "@odata.etag": "W/\"CQAAABYAAAB+0z/4Ly/1ToDr5FGl5k99AAABl5Do\"", 
        "Id": "AAMkADdlAA=" 
    } 
}

Cuando su aplicación escucha varias notificaciones en la misma conexión de larga duración, puede usar el campo SubscriptionId para determinar qué suscripción envió la notificación.

Nota

La segunda notificación y las posteriores enviadas desde el servidor tienen una coma inicial antes del corchete de apertura para hacer que la notificación sea un JSON válido.

,{
    "Id": null, 
    "SubscriptionId": "N0UzMEU4...", 
    ...
}

Ejemplo de carga útil de notificación enriquecida

Si su solicitud de suscripción especifica que se devuelvan ciertas propiedades, las cargas útiles de notificación incluirán los valores de esas propiedades. Siguiendo el ejemplo anterior para suscribirse a notificaciones enriquecidas, una carga útil de notificación enriquecida que incluye la propiedad Subject puede tener este aspecto:

{
  "@odata.context": "https://outlook.office.com/api/beta/$metadata#Notifications",
    {
      "@odata.type": "#Microsoft.OutlookServices.Notification",
      "Id": null,
      "SubscriptionId": "QjQzNzAwBQQ==",
      "SubscriptionExpirationDateTime": "2017-01-18T00:57:28.6134733Z",
      "SequenceNumber": 1,
      "ChangeType": "Created",
      "Resource": "https://outlook.office.com/api/beta/Users('6ed6de00-b4c1-4f9b-8ce0-30908c54da0a@ea54488f-a8f6-4c8d-acad-c3a1da54f79f')/Events('AAMkAGAAAAACisAAA=')",
      "ResourceData": {
        "@odata.type": "#Microsoft.OutlookServices.Event",
        "@odata.id": "https://outlook.office.com/api/beta/Users('6ed6de00-b4c1-4f9b-8ce0-30908c54da0a@ea54488f-a8f6-4c8d-acad-c3a1da54f79f')/Events('AAMkAGAAAAACisAAA=')",
        "@odata.etag": "W/\"IpGjeMHoYUS/RhJxluiSeAAAAAAyoQ==\"",
        "Id": "AAMkAGAAAAACisAAA=",
        "Subject": "Quarterly meeting CY17Q1"
      }
    }
  ]
}

Cerrar la conexión

Cuando el tiempo de espera especificado en la propiedad ConnectionTimeoutInMinutes se agota, el servidor cierra la conexión y envía el final del blob de JSON de la siguiente manera.

    ]
}

La conexión puede desactivarse en otras circunstancias, como por problemas de red y cambios en el servidor (p. ej., reinicios). El cliente puede usar las notificaciones de mantenimiento de conexión con el objetivo de determinar si la conexión aún está activa o se ha terminado. En este último caso, el cliente debe intentar volver a conectarse utilizando el id. de suscripción existente. Si el id. de suscripción ha caducado, se debe realizar una nueva solicitud de suscripción para restablecer la conexión.

Si el cliente ya no quiere escuchar una suscripción, puede cancelar la solicitud POST y desactivar la conexión. La próxima vez que el servidor intente enviar una notificación, recibirá un error, detectará la caída de la conexión, detendrá las notificaciones de mantenimiento de conexión y cerrará la conexión.

Entidades de notificación y enumeraciones

Suscripción

Representa la suscripción base. Esta es una clase base de resumen.

Tipo de base: Entity

Propiedad Tipo Descripción ¿Se puede grabar? Filterable
Recurso cadena Especifica el recurso sobre el que se supervisarán los cambios. Sí N/A
ChangeType ChangeType Indica el tipo de eventos que generarán una notificación. Consulte en ChangeType los tipos admitidos. Sí N/A

Notification

Representa una notificación enviada al cliente.

Tipo de base: Entity

Propiedad Tipo Descripción ¿Se puede grabar? Filterable
SubscriptionId cadena Identificador único de la suscripción. No N/A
SequenceNumber int32 Indica el valor de secuencia de la notificación de cambio. No N/A
ChangeType cadena Indica el tipo de evento que generó la notificación. Consulte en ChangeType los tipos admitidos. No N/A
Resource cadena Especifica el elemento de recurso que se supervisa para detectar cambios No N/A
ResourceData Entity Identifica la entidad que ha cambiado. Es una propiedad de navegación No N/A

ChangeType

Una enumeración que especifica los tipos de eventos que ocurren en los recursos admitidos que pueden generar una notificación.

Valores admitidos:

  • Agradecimientos
  • Creada (created)
  • Deleted (eliminada)
  • Missed (fallada). Se produce una notificación Missed cuando el servicio de notificaciones no puede enviar la notificación solicitada.
  • Updated (actualizada)

Pasos siguientes

Tanto si está listo para empezar a compilar una aplicación como si simplemente desea obtener más información, tenemos todo lo que necesita.

O bien, obtenga más información sobre el uso de la plataforma de Office 365: