Table of contents
TOC
Collapse the table of content
Expand the table of content
Última actualización: 20/06/2018

Referencia de la API REST de notificaciones push de Outlook

Esta versión de la documentación trata sobre la API de notificaciones push en versión preliminar. Las características en versión preliminar pueden cambiar antes de su finalización, y pueden dañar código que las utilice. Por ello, en general, debería utilizar solo una versión de producción de una API en su código de producción. Si está disponible, v2.0 es actualmente la versión preferida.

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

La API REST de notificaciones push de Outlook envía notificaciones a un servicio web del lado cliente para que las aplicaciones conozcan los cambios en los datos del buzón de un 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 incluir estos dominios de cuenta de Microsoft.

¿No está interesado en la versión beta de la API? Utilice el control en la esquina superior derecha y seleccione la versión que desee.

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

La API REST de notificaciones push de Outlook envía notificaciones mediante un webhook a un servicio web del lado cliente para notificar a las aplicaciones sobre cambios en los datos del buzón de un 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 incluir estos dominios de cuenta de Microsoft.

¿No está interesado en la versión 2.0 de la API? Utilice el control en la esquina superior derecha y seleccione la versión que desee.

Información general

La API y el servicio de notificaciones push de Office 365 funcionan con clientes que brindan un servicio web con una dirección de devolución de llamada y utilizan webhooks para entregar notificaciones a las aplicaciones cliente. Los webhooks son devoluciones de llamada de HTTP configuradas normalmente por un servicio web backend de terceros de confianza. El servicio web puede configurar webhooks para hacer que eventos desencadenantes de un sitio invoquen comportamientos en otro.

Cuando una aplicación se suscribe a notificaciones de un recurso específico (como mensajes en la Bandeja de entrada del usuario), especifica una URL de devolución de llamada de webhook en la solicitud de suscripción. Cuando se produce un evento desencadenante (como un nuevo mensaje en la Bandeja de entrada), el servicio de notificación de Office 365 envía una notificación mediante un webhook a la URL de devolución de llamada. La aplicación, a su vez, realiza acciones de acuerdo con su lógica de negocios, como obtener el nuevo mensaje y actualizar el recuento de no leídos.

Las aplicaciones deben renovar sus suscripciones antes de que caduquen. También pueden finalizar la suscripción en cualquier momento para dejar de recibir notificaciones.

La API y el servicio de notificaciones push de Office 365 funcionan con clientes que brindan un servicio web con una dirección de devolución de llamada y utilizan webhooks para entregar notificaciones a las aplicaciones cliente. Los webhooks son devoluciones de llamada de HTTP configuradas normalmente por un servicio web backend de terceros de confianza. El servicio web puede configurar webhooks para hacer que eventos desencadenantes de un sitio invoquen comportamientos en otro.

Cuando una aplicación se suscribe a notificaciones de un recurso específico (como mensajes en la Bandeja de entrada del usuario), especifica una URL de devolución de llamada de webhook en la solicitud de suscripción. Cuando se produce un evento desencadenante (como un nuevo mensaje en la Bandeja de entrada), el servicio de notificación de Office 365 envía una notificación mediante un webhook a la URL de devolución de llamada. La aplicación, a su vez, realiza acciones de acuerdo con su lógica de negocios, como obtener el nuevo mensaje y actualizar el recuento de no leídos.

Las aplicaciones deben renovar sus suscripciones antes de que caduquen. También pueden finalizar la suscripción en cualquier momento para dejar de recibir notificaciones.

Comparación de la transmisión por secuencias y las notificaciones push

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 con ambas, las notificaciones de transmisión por secuencias y las notificaciones push. Actualmente, las aplicaciones móviles habitualmente utilizan las notificaciones push, ya que no requieren que los clientes sondeen si hay cambios y ponen las actualizaciones a disposición de los clientes de forma prácticamente inmediata.

En comparación con las notificaciones de transmisión por secuencias, las notificaciones push requieren que el cliente proporcione su propio servicio web para recibir notificaciones, mientras que las notificaciones de transmisión por secuencias requieren solo una conexión directa entre el cliente y el servicio de notificaciones de transmisión por secuencias de Office 365.

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 con ambas, las notificaciones de transmisión por secuencias y las notificaciones push. Actualmente, las aplicaciones móviles habitualmente utilizan las notificaciones push, ya que no requieren que los clientes sondeen si hay cambios y ponen las actualizaciones a disposición de los clientes de forma prácticamente inmediata.

En comparación con las notificaciones de transmisión por secuencias, las notificaciones push requieren que el cliente proporcione su propio servicio web para recibir notificaciones, mientras que las notificaciones de transmisión por secuencias requieren solo una conexión directa entre el cliente y el servicio de notificaciones de transmisión por secuencias de Office 365.

Utilice la API REST de notificaciones push

Autenticación

Para suscribirse, consultar, renovar y eliminar suscripciones, especifique los ámbitos apropiados para los tipos de recursos sobre los que desea que se le notifique.

Alcance mínimo requerido: uno de los siguientes ámbitos de lectura correspondientes al recurso de destino:

Como cualquier otra API REST de Outlook, para cada solicitud a la API de notificaciones push de Outlook, debería incluir un token de acceso válido. Obtener un token de acceso requiere que haya registrado e identificado su aplicación y obtenido la autorización correspondiente. Puede obtener más información sobre algunas opciones de registro y autorización optimizadas para usted. Tenga esto en cuenta a medida que avance con las operaciones específicas en la API de notificaciones push.

Para suscribirse, consultar, renovar y eliminar suscripciones, especifique los ámbitos apropiados para los tipos de recursos sobre los que desea que se le notifique.

Alcance mínimo requerido: uno de los siguientes ámbitos de lectura correspondientes al recurso de destino:

Como cualquier otra API REST de Outlook, para cada solicitud a la API de notificaciones push de Outlook, debería incluir un token de acceso válido. Obtener un token de acceso requiere que haya registrado e identificado su aplicación y obtenido la autorización correspondiente. Puede obtener más información sobre algunas opciones de registro y autorización optimizadas para usted. Tenga esto en cuenta a medida que avance con las operaciones específicas en la API de notificaciones push.

Versión de la API

El estado de esta API se ha promocionado de versión preliminar a disponibilidad general. Es compatible con las versiones 2.0 y beta de la API REST de Outlook.

El estado de esta API se ha promocionado de versión preliminar a disponibilidad general. Es compatible con las versiones 2.0 y beta de la API REST de Outlook.

Usuario de destino

Las solicitudes de la API de notificaciones push siempre se realizan en nombre del usuario actual.

Consulte Utilizar la API REST de Outlook para obtener más información común a todos los subconjuntos de la API REST de Outlook.


Las solicitudes de la API de notificaciones push siempre se realizan en nombre del usuario actual.

Consulte Utilizar la API REST de Outlook para obtener más información común a todos los subconjuntos de la API REST de Outlook.


Operaciones de notificación push

Suscribirse a notificaciones | Renovar la suscripción | Eliminar suscripción

Suscribirse a notificaciones | Renovar la suscripción | Eliminar suscripción

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

Proceso de suscripción

El proceso de suscripción es el siguiente:

  1. Una aplicación cliente realiza una solicitud de suscripción (POST) para un recurso específico. Incluye una URL de notificación, entre otras propiedades.

  2. El servicio de notificaciones de Outlook intenta validar la URL de notificación con el servicio de escucha. Incluye un token de validación en la solicitud de validación.

  3. Si el servicio de escucha valida con éxito la URL, devuelve una respuesta correcta en 5 segundos de la siguiente manera:

    • Establece el tipo de contenido en el encabezado de respuesta en text\plain.
    • Incluye el mismo token de validación en el cuerpo de respuesta.
    • Devuelve un código de respuesta HTTP 200. El escucha puede descartar el token de validación posteriormente.
  4. Según el resultado de validación de URL, el servicio de notificaciones de Outlook envía una respuesta a la aplicación cliente:

    • Si la validación de URL se ha realizado correctamente, el servicio crea la suscripción con un Id. de suscripción único y envía la respuesta al cliente.
    • Si la validación de URL no se ha realizado correctamente, el servicio envía una respuesta de error con un código de error y otros detalles.
  5. Tras recibir una respuesta correcta, la aplicación cliente almacena el Id. de suscripción para correlacionar futuras notificaciones con esta suscripción.

Solicitud de suscripción

Se suscribe a un servicio de escucha para recibir notificaciones cuando el correo, los eventos del calendario, los contactos o las tareas cambian en 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 para una solicitud de suscripción de push. Con la excepción de ClientState, todas las propiedades son necesarias. Para obtener más información, consulte Entidades de notificación.

  • odata.type - Include "@odata.type":"#Microsoft.OutlookServices.PushSubscription". La entidad PushSubscription define NotificationURL.
  • ChangeType : especifica los tipos de eventos que se supervisarán para ese recurso. Consulte en ChangeType los tipos admitidos.
  • ClientState: propiedad opcional que indica que cada notificación se debe enviar con un encabezado con el mismo valor de ClientState. Esto permite al escucha verificar la legitimidad de cada notificación.
  • NotificationURL : especifica a dónde deben enviarse las notificaciones. Esta URL representa un servicio web normalmente implementado por el cliente.
  • Resource : especifica el recurso que se supervisará y sobre el que se recibirán notificaciones. Puede utilizar el parámetro de consulta opcional, $filter, para restringir las condiciones de una notificación, o $select, para incluir propiedades específicas en una notificación enriquecida. Los recursos compatibles 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

Ejemplo de una solicitud de suscripción

El siguiente ejemplo muestra cómo suscribirse a nuevos eventos.

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

{
   "@odata.type":"#Microsoft.OutlookServices.PushSubscription",
   "Resource": "https://outlook.office.com/api/beta/me/events",
   "NotificationURL": "https://mywebhook.azurewebsites.net/api/send/myNotifyClient",  
   "ChangeType": "Created",
   "ClientState": "c75831bd-fad3-4191-9a66-280a48528679"
}

Restrinja las condiciones de notificación

Puede restringir aún más las condiciones de una notificación utilizando el parámetro de consulta $filter.

El ejemplo siguiente solicita una notificación para un Mensaje que se está creado en la carpeta Borradores, que contiene uno o más archivos adjuntos, y la importancia es High:

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

{ 
  @odata.type:"#Microsoft.OutlookServices.PushSubscription", 
  Resource: "https://outlook.office.com/api/beta/me/mailfolders('Drafts')/messages?$filter=HasAttachments%20eq%20true%20AND%20Importance%20eq%20%27High%27", 
  NotificationURL: "https://mywebhook.azurewebsites.net/api/send/myNotifyClient", 
  ChangeType: "Created", 
  ClientState: "Has attachments and high importance" 
} 

El ejemplo siguiente solicita una notificación para un Evento de todo el día que se está creando:

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

{ 
  @odata.type:"#Microsoft.OutlookServices.PushSubscription", 
  Resource: "https://outlook.office.com/api/beta/me/events?$filter=IsAllDay%20eq%20true", 
  NotificationURL: "https://mywebhook.azurewebsites.net/api/send/myNotifyClient", 
  ChangeType: "Created", 
  ClientState: "Notifications for events that IsAllDay." 
} 

El ejemplo siguiente solicita una notificación para un Contacto que se está creando, en el que la compañía es Contoso:

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

{ 
  @odata.type:"#Microsoft.OutlookServices.PushSubscription", 
  Resource: "https://outlook.office.com/api/beta/me/contacts?$filter=CompanyName%20eq%20%27Contoso%27", 
  NotificationURL: "https://mywebhook.azurewebsites.net/api/send/myNotifyClient", 
  ChangeType: "Created", 
  ClientState: "Contacts in Contoso." 
} 

Una aplicación habitual de $filter es recibir una notificación sobre un cambio en una propiedad específica del recurso especificado. Por ejemplo, puede utilizar $filter para suscribirse a mensajes no leídos de una carpeta (la propiedad IsRead es false) e incluir todos los tipos de cambio:

  • Un mensaje agregado o marcado como no leído en la carpeta activaría una notificación Created.
  • Leer un mensaje o marcarlo como leído en la carpeta desencadenaría una notificación Deleted.
  • El cambio de cualquier propiedad, que no sea IsRead, de un mensaje de la carpeta desencadenaría una notificación Updated.

Puede crear una suscripción de este tipo de la forma siguiente:

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

{
  @odata.type:"#Microsoft.OutlookServices.PushSubscription",
  Resource: "https://outlook.office.com/api/beta/me/mailfolders('folder_id')/messages$filter=IsRead%20eq%20false",
  NotificationURL: "https://mywebhook.azurewebsites.net/api/send/myNotifyClient",
  ChangeType: "Created,Deleted,Updated",
  ClientState: "Message unread"
}

Si no utiliza un $filter al crear la suscripción (como se muestra a continuación):

  • Agregar un mensaje a la carpeta resultaría en una notificación Created.
  • Leer un mensaje de la carpeta, marcar el mensaje como leído o cambiar cualquier otra propiedad de mensaje de un mensaje de esa carpeta resultaría en una notificación Updated.
  • Eliminar el mensaje resultaría en una notificación Delete.
POST https://outlook.office.com/api/beta/me/subscriptions HTTP/1.1
Content-Type: application/json

{
  @odata.type:"#Microsoft.OutlookServices.PushSubscription",
  Resource: "https://outlook.office.com/api/beta/me/mailfolders('folder_id')/messages,
  NotificationURL: "https://mywebhook.azurewebsites.net/api/send/myNotifyClient",
  ChangeType: "Created,Deleted,Updated",
  ClientState: "Message unread"
}

Solicitud de validación

La solicitud de validación intenta validar la propiedad NotificationURL que especifica una aplicación cliente en una solicitud de suscripción:

POST https://{notificationUrl}?validationToken={token}

El servicio de Outlook especifica la propiedad NotificationURL en la solicitud de suscripción en {notificationUrl} y define una cadena {token} como el token de validación. El servicio de Outlook también incluye un encabezado ClientState si la aplicación cliente incluye uno en la solicitud de suscripción.

Respuesta de suscripción

La respuesta de suscripción incluye las propiedades en la solicitud y las siguientes propiedades adicionales:

  • Id: Id. de suscripción único que la aplicación cliente debe guardar para la coincidencia con las notificaciones futuras.
  • ChangeType: además de los valores especificados en la solicitud, la respuesta incluye el tipo de notificación adicional, Perdido.
  • SubscriptionExpirationDateTime: fecha y la hora de caducidad de la suscripción. Si la solicitud de suscripción no especifica una fecha de caducidad, o si la solicitud especifica una fecha de caducidad posterior a la máxima permitida, esta propiedad se establecerá en la duración máxima permitida desde el momento del envío de la solicitud. Para una suscripción que solicita notificaciones enriquecidas de propiedades específicas, el máximo permitido es de 1 día. Para otras suscripciones, el máximo es de 7 días.
  • Otras propiedades relacionadas con OData.

Ejemplo de respuesta de suscripción

Esta respuesta indica que el servicio de escucha debe esperar recibir notificaciones de nuevos eventos y cambios perdidos. Si hay cambios perdidos, el cliente deberá sincronizarse con el servicio para capturarlos.

{
    "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Subscriptions/$entity",
    "@odata.type": "#Microsoft.OutlookServices.PushSubscription",
    "@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-7d04-b48b-20075df800e5@1717622f-1d94-c0d4-9d74-f907ad6677b4')/Subscriptions('Mjk3QNERDQQ==')",
    "Id": "Mjk3QNERDQQ==",
    "Resource": "https://outlook.office.com/api/beta/me/events",
    "ChangeType": "Created, Missed",
    "ClientState": "c75831bd-fad3-4191-9a66-280a48528679",
    "NotificationURL": "https://mywebhook.azurewebsites.net/api/send/myNotifyClient",
    "SubscriptionExpirationDateTime": "2015-04-23T22:46:13.8805047Z"
}

Consultar una suscripción Puede encontrar información sobre cualquiera de las suscripciones existentes del usuario que inició sesión especificando su ID de suscripción. Como ejemplo, para consultar la suscripción creada en el último ejemplo:

GET https://outlook.office.com/api/beta/Users('ddfcd489-628b-7d04-b48b-20075df800e5@1717622f-1d94-c0d4-9d74-f907ad6677b4')/Subscriptions('Mjk3QNERDQQ==')

Si el resultado es correcto, la respuesta tendría los mismos datos de respuesta que el último ejemplo, excepto que excluiría cualquier ClientState
Se ha especificado la aplicación cliente para evitar posibles riesgos de seguridad.

Notificaciones

Cada notificación contiene las propiedades siguientes, independientemente de cuál sea su tipo:

  • Encabezado ClientState: presente solo si el cliente ha especificado la propiedad ClientState en la solicitud de suscripción. Utilizado por el escucha para verificar la legitimidad de la notificación.
  • SuscripciónId: identifica a la aplicación cliente la suscripción a la que pertenece esta notificación.
  • SubscriptionExpirationDateTime: fecha y hora de caducidad de la suscripción.
  • SequenceNumber: número secuencial de una notificación, para ayudar en la identificación de la aplicación cliente si falta una notificación.
  • ChangeType: tipos de eventos sobre los que la aplicación cliente desea que se le notifique (por ejemplo, un tipo de evento Creado cuando se recibe correo, o un tipo de evento Actualizar cuando se lee un mensaje).
  • Resource: URL del elemento de recurso específico que se está supervisando (por ejemplo, una URL para el mensaje o evento modificado).
  • ResourceData: una notificación relacionada con un cambio de recurso (como recibir, leer o eliminar un mensaje) tiene esta propiedad adicional que contiene el Id. de recurso del elemento que se ha modificado. Un cliente puede utilizar este Id. de recurso para manejar este elemento de acuerdo con su lógica de negocios (por ejemplo, recuperar este elemento, sincronizar su carpeta).

NOTA: la propiedad Id no se utiliza en entidades Notificación.

Cambiar la carga útil de notificación

En el ejemplo siguiente, cuando el usuario recibe un evento nuevo, el servicio de notificaciones envía una notificación con ChangeType establecido en "Creado". El encabezado de la notificación incluiría ClientState tal como se especifica en la solicitud de suscripción inicial. La notificación de evento de recepción tiene una carga útil similar a esta:

{
    "value": [
        {
            "@odata.type": "#Microsoft.OutlookServices.Notification",
            "Id": null,
            "SubscriptionId": "Mjk3QNERDQQ==",
            "SubscriptionExpirationDateTime": "2015-04-23T22:46:13.8805047Z",
            "SequenceNumber": 1,
            "ChangeType": "Created",
            "Resource" : "https://outlook.office.com/api/beta/Users('ddfcd489-628b-7d04-b48b-20075df800e5@1717622f-1d94-c0d4-9d74-f907ad6677b4')/Events('AAMkADNkNmAA=')",
            "ResourceData": {
                "@odata.type": "#Microsoft.OutlookServices.Event",
                "@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-7d04-b48b-20075df800e5@1717622f-1d94-c0d4-9d74-f907ad6677b4')/Events('AAMkADNkNmAA=')",
                "Id": "AAMkADNkNmAA="
            }
        }
    ]
}

Obtener propiedades de instancia suscribiéndose a notificaciones enriquecidas

Como hemos visto en el último ejemplo de una carga útil de notificación de cambio, una suscripción de notificación push configurada para una colección de recursos solo devuelve el ID de una instancia de recurso que ha cambiado. Necesita obtener por separado las propiedades de esa instancia.

Puede guardar una llamada API GET por separado si utiliza un parámetro $select en la solicitud de suscripción y especifica las propiedades que le interesan. En el ejemplo siguiente se solicita una notificación 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.PushSubscription",
    "Resource": "https://outlook.office.com/api/beta/me/events?$select=Subject",
    "NotificationURL": "https://mywebhook.azurewebsites.net/api/send/myRichNotifyClient",
    "ChangeType": "Created"
}

Ejemplo de carga útil de notificación enriquecida

Una carga útil de notificación enriquecida incluye los valores de las propiedades especificadas en la solicitud de suscripción. Siguiendo el último ejemplo, una notificación enriquecida incluye la propiedad Subject de la forma siguiente:

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

Proceso de suscripción

El proceso de suscripción es el siguiente:

  1. Una aplicación cliente realiza una solicitud de suscripción (POST) para un recurso específico. Incluye una URL de notificación, entre otras propiedades.

  2. El servicio de notificaciones de Outlook intenta validar la URL de notificación con el servicio de escucha. Incluye un token de validación en la solicitud de validación.

  3. Si el servicio de escucha valida con éxito la URL, devuelve una respuesta correcta en 5 segundos de la siguiente manera:

    • Establece el tipo de contenido en el encabezado de respuesta en text\plain.
    • Incluye el mismo token de validación en el cuerpo de respuesta.
    • Devuelve un código de respuesta HTTP 200. El escucha puede descartar el token de validación posteriormente.
  4. Según el resultado de validación de URL, el servicio de notificaciones de Outlook envía una respuesta a la aplicación cliente:

    • Si la validación de URL se ha realizado correctamente, el servicio crea la suscripción con un Id. de suscripción único y envía la respuesta al cliente.
    • Si la validación de URL no se ha realizado correctamente, el servicio envía una respuesta de error con un código de error y otros detalles.
  5. Tras recibir una respuesta correcta, la aplicación cliente almacena el Id. de suscripción para correlacionar futuras notificaciones con esta suscripción.

Solicitud de suscripción

Se suscribe a un servicio de escucha para recibir notificaciones cuando el correo, los eventos del calendario, los contactos o las tareas cambian en 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/v2.0/me/subscriptions

Especifique en el cuerpo de la solicitud las siguientes propiedades para una solicitud de suscripción de push. Con la excepción de ClientState, todas las propiedades son necesarias. Para obtener más información, consulte Entidades de notificación.

  • odata.type - Include "@odata.type":"#Microsoft.OutlookServices.PushSubscription". La entidad PushSubscription define NotificationURL.
  • ChangeType : especifica los tipos de eventos que se supervisarán para ese recurso. Consulte en ChangeType los tipos admitidos.
  • ClientState: propiedad opcional que indica que cada notificación se debe enviar con un encabezado con el mismo valor de ClientState. Esto permite al escucha verificar la legitimidad de cada notificación.
  • NotificationURL : especifica a dónde deben enviarse las notificaciones. Esta URL representa un servicio web normalmente implementado por el cliente.
  • Resource - - Resource : especifica el recurso que se supervisará y sobre el que se recibirán notificaciones. Puede utilizar el parámetro de consulta opcional, $filter, para restringir las condiciones de una notificación, o $select, para incluir propiedades específicas en una notificación enriquecida. Los recursos compatibles 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/v2.0/me/mailfolders('inbox')/messages

      https://outlook.office.com/api/v2.0/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/v2.0/me/messages

      https://outlook.office.com/api/v2.0/me/events

      https://outlook.office.com/api/v2.0/me/contacts

      https://outlook.office.com/api/v2.0/me/tasks

Ejemplo de solicitud

El siguiente ejemplo muestra cómo suscribirse a nuevos eventos.

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

{
   "@odata.type":"#Microsoft.OutlookServices.PushSubscription",
   "Resource": "https://outlook.office.com/api/v2.0/me/events",
   "NotificationURL": "https://mywebhook.azurewebsites.net/api/send/myNotifyClient",  
   "ChangeType": "Created",
   "ClientState": "c75831bd-fad3-4191-9a66-280a48528679"
}

Restrinja las condiciones de notificación

Puede restringir aún más las condiciones de una notificación utilizando el parámetro de consulta $filter.

El ejemplo siguiente solicita una notificación para un Mensaje que se está creado en la carpeta Borradores, que contiene uno o más archivos adjuntos, y la importancia es High:

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

{ 
  @odata.type:"#Microsoft.OutlookServices.PushSubscription", 
  Resource: "https://outlook.office.com/api/v2.0/me/mailfolders('Drafts')/messages?$filter=HasAttachments%20eq%20true%20AND%20Importance%20eq%20%27High%27", 
  NotificationURL: "https://mywebhook.azurewebsites.net/api/send/myNotifyClient", 
  ChangeType: "Created", 
  ClientState: "Has attachments and high importance" 
} 

El ejemplo siguiente solicita una notificación para un Evento de todo el día que se está creando:

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

{ 
  @odata.type:"#Microsoft.OutlookServices.PushSubscription", 
  Resource: "https://outlook.office.com/api/v2.0/me/events?$filter=IsAllDay%20eq%20true", 
  NotificationURL: "https://mywebhook.azurewebsites.net/api/send/myNotifyClient", 
  ChangeType: "Created", 
  ClientState: "Notifications for events that IsAllDay." 
} 

El ejemplo siguiente solicita una notificación para un Contacto que se está creando, en el que la compañía es Contoso:

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

{ 
  @odata.type:"#Microsoft.OutlookServices.PushSubscription", 
  Resource: "https://outlook.office.com/api/v2.0/me/contacts?$filter=CompanyName%20eq%20%27Contoso%27", 
  NotificationURL: "https://mywebhook.azurewebsites.net/api/send/myNotifyClient", 
  ChangeType: "Created", 
  ClientState: "Contacts in Contoso." 
} 

Una aplicación habitual de $filter es recibir una notificación sobre un cambio en una propiedad específica del recurso especificado. Por ejemplo, puede utilizar $filter para suscribirse a mensajes no leídos de una carpeta (la propiedad IsRead es false) e incluir todos los tipos de cambio:

  • Un mensaje agregado o marcado como no leído en la carpeta activaría una notificación Created.
  • Leer un mensaje o marcarlo como leído en la carpeta desencadenaría una notificación Deleted.
  • El cambio de cualquier propiedad, que no sea IsRead, de un mensaje de la carpeta desencadenaría una notificación Updated.

Puede crear una suscripción de este tipo de la forma siguiente:

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

{
  @odata.type:"#Microsoft.OutlookServices.PushSubscription",
  Resource: "https://outlook.office.com/api/v2.0/me/mailfolders('folder_id')/messages$filter=IsRead%20eq%20false",
  NotificationURL: "https://mywebhook.azurewebsites.net/api/send/myNotifyClient",
  ChangeType: "Created,Deleted,Updated",
  ClientState: "Message unread"
}

Si no utiliza un $filter al crear la suscripción (como se muestra a continuación):

  • Agregar un mensaje a la carpeta resultaría en una notificación Created.
  • Leer un mensaje de la carpeta, marcar el mensaje como leído o cambiar cualquier otra propiedad de mensaje de un mensaje de esa carpeta resultaría en una notificación Updated.
  • Eliminar el mensaje resultaría en una notificación Delete.
POST https://outlook.office.com/api/v2.0/me/subscriptions HTTP/1.1
Content-Type: application/json

{
  @odata.type:"#Microsoft.OutlookServices.PushSubscription",
  Resource: "https://outlook.office.com/api/v2.0/me/mailfolders('folder_id')/messages,
  NotificationURL: "https://mywebhook.azurewebsites.net/api/send/myNotifyClient",
  ChangeType: "Created,Deleted,Updated",
  ClientState: "Message unread"
}

Solicitud de validación

La solicitud de validación intenta validar la propiedad NotificationURL que especifica una aplicación cliente en una solicitud de suscripción:

POST https://{notificationUrl}?validationToken={token}

El servicio de Outlook especifica la propiedad NotificationURL en la solicitud de suscripción en {notificationUrl} y define una cadena {token} como el token de validación. El servicio de Outlook también incluye un encabezado ClientState si la aplicación cliente incluye uno en la solicitud de suscripción.

Respuesta de suscripción

La respuesta de suscripción incluye las propiedades en la solicitud y las siguientes propiedades adicionales:

  • Id: Id. de suscripción único que la aplicación cliente debe guardar para la coincidencia con las notificaciones futuras.
  • ChangeType: además de los valores especificados en la solicitud, la respuesta incluye el tipo de notificación adicional, Perdido.
  • SubscriptionExpirationDateTime: fecha y la hora de caducidad de la suscripción. Si la solicitud de suscripción no especifica una fecha de caducidad, o si la solicitud especifica una fecha de caducidad posterior a la máxima permitida, esta propiedad se establecerá en la duración máxima permitida desde el momento del envío de la solicitud. Para una suscripción que solicita notificaciones enriquecidas de propiedades específicas, el máximo permitido es de 1 día. Para otras suscripciones, el máximo es de 7 días.
  • Otras propiedades relacionadas con OData.

Ejemplo de datos de respuesta

Esta respuesta indica que el servicio de escucha debe esperar recibir notificaciones de nuevos eventos y cambios perdidos. Si hay cambios perdidos, el cliente deberá sincronizarse con el servicio para capturarlos.

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Subscriptions/$entity",
    "@odata.type": "#Microsoft.OutlookServices.PushSubscription",
    "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfcd489-628b-7d04-b48b-20075df800e5@1717622f-1d94-c0d4-9d74-f907ad6677b4')/Subscriptions('Mjk3QNERDQQ==')",
    "Id": "Mjk3QNERDQQ==",
    "Resource": "https://outlook.office.com/api/v2.0/me/events",
    "ChangeType": "Created, Missed",
    "ClientState": "c75831bd-fad3-4191-9a66-280a48528679",
    "NotificationURL": "https://mywebhook.azurewebsites.net/api/send/myNotifyClient",
    "SubscriptionExpirationDateTime": "2015-04-23T22:46:13.8805047Z"
}

Consultar una suscripción Puede encontrar información sobre cualquiera de las suscripciones existentes del usuario que inició sesión especificando su ID de suscripción. Como ejemplo, para consultar la suscripción creada en el último ejemplo:

GET https://outlook.office.com/api/v2.0/Users('ddfcd489-628b-7d04-b48b-20075df800e5@1717622f-1d94-c0d4-9d74-f907ad6677b4')/Subscriptions('Mjk3QNERDQQ==')

Si el resultado es correcto, la respuesta tendría los mismos datos de respuesta que el último ejemplo, excepto que excluiría cualquier ClientState
Se ha especificado la aplicación cliente para evitar posibles riesgos de seguridad.

Notificaciones

Cada notificación contiene las propiedades siguientes, independientemente de cuál sea su tipo:

  • Encabezado ClientState: presente solo si el cliente ha especificado la propiedad ClientState en la solicitud de suscripción. Utilizado por el escucha para verificar la legitimidad de la notificación.
  • SuscripciónId: identifica a la aplicación cliente la suscripción a la que pertenece esta notificación.
  • SubscriptionExpirationDateTime: fecha y hora de caducidad de la suscripción.
  • SequenceNumber: número secuencial de una notificación, para ayudar en la identificación de la aplicación cliente si falta una notificación.
  • ChangeType: tipos de eventos sobre los que la aplicación cliente desea que se le notifique (por ejemplo, un tipo de evento Creado cuando se recibe correo, o un tipo de evento Actualizar cuando se lee un mensaje).
  • Resource: URL del elemento de recurso específico que se está supervisando (por ejemplo, una URL para el mensaje o evento modificado).
  • ResourceData: una notificación relacionada con un cambio de recurso (como recibir, leer o eliminar un mensaje) tiene esta propiedad adicional que contiene el Id. de recurso del elemento que se ha modificado. Un cliente puede utilizar este Id. de recurso para manejar este elemento de acuerdo con su lógica de negocios (por ejemplo, recuperar este elemento, sincronizar su carpeta).

NOTA: la propiedad Id no se utiliza en entidades Notificación.

Cambiar la carga útil de notificación

En el ejemplo siguiente, cuando el usuario recibe un evento nuevo, el servicio de notificaciones envía una notificación con ChangeType establecido en "Creado". El encabezado de la notificación incluiría ClientState tal como se especifica en la solicitud de suscripción inicial. La notificación de evento de recepción tiene una carga útil similar a esta:

{
    "value": [
        {
            "@odata.type": "#Microsoft.OutlookServices.Notification",
            "Id": null,
            "SubscriptionId": "Mjk3QNERDQQ==",
            "SubscriptionExpirationDateTime": "2015-04-23T22:46:13.8805047Z",
            "SequenceNumber": 1,
            "ChangeType": "Created",
            "Resource" : "https://outlook.office.com/api/v2.0/Users('ddfcd489-628b-7d04-b48b-20075df800e5@1717622f-1d94-c0d4-9d74-f907ad6677b4')/Events('AAMkADNkNmAA=')",
            "ResourceData": {
                "@odata.type": "#Microsoft.OutlookServices.Event",
                "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfcd489-628b-7d04-b48b-20075df800e5@1717622f-1d94-c0d4-9d74-f907ad6677b4')/Events('AAMkADNkNmAA=')",
                "Id": "AAMkADNkNmAA="
            }
        }
    ]
}

Obtener propiedades de instancia suscribiéndose a notificaciones enriquecidas

Como hemos visto en el último ejemplo de una carga útil de notificación de cambio, una suscripción de notificación push configurada para una colección de recursos solo devuelve el ID de una instancia de recurso que ha cambiado. Necesita obtener por separado las propiedades de esa instancia.

Puede guardar una llamada API GET por separado si utiliza un parámetro $select en la solicitud de suscripción y especifica las propiedades que le interesan. En el ejemplo siguiente se solicita una notificación para incluir la propiedad subject cuando se ha creado un evento:

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

{
    "@odata.type":"#Microsoft.OutlookServices.PushSubscription",
    "Resource": "https://outlook.office.com/api/v2.0/me/events?$select=Subject",
    "NotificationURL": "https://mywebhook.azurewebsites.net/api/send/myRichNotifyClient",
    "ChangeType": "Created"
}

Ejemplo de carga útil de notificación enriquecida

Una carga útil de notificación enriquecida incluye los valores de las propiedades especificadas en la solicitud de suscripción. Siguiendo el último ejemplo, una notificación enriquecida incluye la propiedad Subject de la forma siguiente:

{
  "@odata.context": "https://outlook.office.com/api/v2.0/$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/v2.0/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/v2.0/Users('6ed6de00-b4c1-4f9b-8ce0-30908c54da0a@ea54488f-a8f6-4c8d-acad-c3a1da54f79f')/Events('AAMkAGAAAAACisAAA=')",
        "@odata.etag": "W/\"IpGjeMHoYUS/RhJxluiSeAAAAAAyoQ==\"",
        "Id": "AAMkAGAAAAACisAAA=",
        "Subject": "Quarterly meeting CY17Q1"
      }
    }
  ]
}

Renovar suscripción

Renueve una suscripción por la duración máxima desde el momento de la solicitud de renovación.

PATCH https://outlook.office.com/api/beta/me/subscriptions/{subscriptionId}

La duración de la suscripción predeterminada es de 7 días para las solicitudes de suscripción que no requieren propiedades de instancia específicas en la respuesta, y de 1 día para las suscripciones a las notificaciones enriquecidas.

Puede enviar la solicitud de renovación sin una carga útil y la suscripción se ampliará por el período máximo correspondiente.

Ejemplo de solicitud

PATCH https://outlook.office.com/api/beta/me/subscriptions/Mjk3QNERDQQ==

{
   @odata.type:"#Microsoft.OutlookServices.PushSubscription",
   "SubscriptionExpirationDateTime": "2015-05-28T17:17:45.9028722Z"
}

Una respuesta correcta se indica mediante un código de respuesta HTTP 200.

Renueve una suscripción por la duración máxima desde el momento de la solicitud de renovación.

PATCH https://outlook.office.com/api/v2.0/me/subscriptions/{subscriptionId}

La duración de la suscripción predeterminada es de 7 días para las solicitudes de suscripción que no requieren propiedades de instancia específicas en la respuesta, y de 1 día para las suscripciones a las notificaciones enriquecidas.

Puede enviar la solicitud de renovación sin una carga útil y la suscripción se ampliará por el período máximo correspondiente.

Ejemplo de solicitud

PATCH https://outlook.office.com/api/v2.0/me/subscriptions/Mjk3QNERDQQ==

{
   @odata.type:"#Microsoft.OutlookServices.PushSubscription",
   "SubscriptionExpirationDateTime": "2015-05-28T17:17:45.9028722Z"
}

Una respuesta correcta se indica mediante un código de respuesta HTTP 200.

Eliminar suscripción

Elimine una suscripción especificando el Id. de la suscripción.

DELETE https://outlook.office.com/api/beta/me/subscriptions('{subscriptionId}')

Ejemplo de solicitud

Delete https://outlook.office.com/api/beta/me/subscriptions('Mjk3QNERDQQ==')

Una respuesta correcta se indica mediante un código de respuesta HTTP 204 No Content.

Elimine una suscripción especificando el Id. de la suscripción.

DELETE https://outlook.office.com/api/v2.0/me/subscriptions('{subscriptionId}')

Ejemplo de solicitud

Delete https://outlook.office.com/api/v2.0/me/subscriptions('Mjk3QNERDQQ==')

Una respuesta correcta se indica mediante un código de respuesta HTTP 204 No Content.

Suscripción de

de entidades y enumeraciones de la API de notificaciones

Representa la suscripción base. Esta es una clase base abstracta.

Tipo de base: Entidad

PropiedadTipoDescripción¿Es grabable?¿Se puede filtrar?
RecursocadenaEspecifica el recurso del que se supervisarán los cambios.N/D
ChangeTypeChangeTypeIndica el tipo de eventos que generarán una notificación. Consulte en ChangeType los tipos admitidos.N/D

Representa la suscripción base. Esta es una clase base abstracta.

Tipo de base: Entidad

PropiedadTipoDescripción¿Es grabable?¿Se puede filtrar?
RecursocadenaEspecifica el recurso del que se supervisarán los cambios.N/D
ChangeTypeChangeTypeIndica el tipo de eventos que generarán una notificación. Consulte en ChangeType los tipos admitidos.N/D

Notificación

Representa una notificación enviada al cliente. En el caso de las notificaciones push, la notificación se envía al servicio de escucha especificado por el cliente.

Tipo de base: Entidad

PropiedadTipoDescripción¿Es grabable?¿Se puede filtrar?
SubscriptionIdcadenaIdentificador único de la suscripción.NoNo
SubscriptionExpirationDateTimeEdm.DateTimeOffsetEspecifica la fecha y hora de caducidad de la suscripción de notificación. La hora es en UTC.N/D
SequenceNumberint32Indica el valor de secuencia de la notificación de cambio.NoN/D
ChangeTypeChangeTypeIndica el tipo de evento que generó la notificación. Los valores de enumeración son: Creado = 1, Actualizado = 2, Suprimido = 4, Perdido = 16. Se produce una notificación Perdido cuando el servicio de notificaciones no puede enviar la notificación solicitada.NoN/D
RecursocadenaEspecifica el elemento de recurso que se supervisa para detectar cambios.N/D
ResourceDataEntidadIdentifica la entidad que ha cambiado. Es una propiedad de navegación.NoN/D

Representa una notificación enviada al cliente. En el caso de las notificaciones push, la notificación se envía al servicio de escucha especificado por el cliente.

Tipo de base: Entidad

PropiedadTipoDescripción¿Es grabable?¿Se puede filtrar?
SubscriptionIdcadenaIdentificador único de la suscripción.NoNo
SubscriptionExpirationDateTimeEdm.DateTimeOffsetEspecifica la fecha y hora de caducidad de la suscripción de notificación. La hora es en UTC.N/D
SequenceNumberint32Indica el valor de secuencia de la notificación de cambio.NoN/D
ChangeTypeChangeTypeIndica el tipo de evento que generó la notificación. Los valores de enumeración son: Creado = 1, Actualizado = 2, Suprimido = 4, Perdido = 16. Se produce una notificación Perdido cuando el servicio de notificaciones no puede enviar la notificación solicitada.NoN/D
RecursocadenaEspecifica el elemento de recurso que se supervisa para detectar cambios.N/D
ResourceDataEntidadIdentifica la entidad que ha cambiado. Es una propiedad de navegación.NoN/D

PushSubscription

Representa una suscripción que utiliza el mecanismo de notificación push.

Tipo de base: Suscripción

PropiedadTipoDescripción¿Es grabable?¿Se puede filtrar?
NotificationURLcadenaLa URL de la aplicación que recibirá las notificaciones push.N/D
SubscriptionExpirationDateTimeEdm.DateTimeOffsetEspecifica la fecha y hora de caducidad de la suscripción de notificación. La hora es en UTC.N/D
ClientStatecadenaEspecifica el valor del encabezado ClientState enviado por el servicio para cada notificación. La longitud máxima es 255 caracteres. El cliente puede verificar que la notificación procede del servicio comparando el valor establecido en la propiedad ClientState con el valor del encabezado ClientState recibido con cada notificación.No

Representa una suscripción que utiliza el mecanismo de notificación push.

Tipo de base: Suscripción

PropiedadTipoDescripción¿Es grabable?¿Se puede filtrar?
NotificationURLcadenaLa URL de la aplicación que recibirá las notificaciones push.N/D
SubscriptionExpirationDateTimeEdm.DateTimeOffsetEspecifica la fecha y hora de caducidad de la suscripción de notificación. La hora es en UTC.N/D
ClientStatecadenaEspecifica el valor del encabezado ClientState enviado por el servicio para cada notificación. La longitud máxima es 255 caracteres. El cliente puede verificar que la notificación procede del servicio comparando el valor establecido en la propiedad ClientState con el valor del encabezado ClientState recibido con cada notificación.No

<a "name"="ChangeType">

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
  • Creado
  • Eliminado
  • Perdido Se produce una notificación Missed cuando el servicio de notificaciones no puede enviar la notificación solicitada.
  • Actualizado

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

Valores admitidos:

  • Agradecimientos
  • Creado
  • Eliminado
  • Perdido Se produce una notificación Missed cuando el servicio de notificaciones no puede enviar la notificación solicitada.
  • Actualizado

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:

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:

© 2018 Microsoft