Recibir notificaciones push

En este documento, se describe cómo usar las notificaciones push que informan a tu aplicación cuando cambia un recurso.

Descripción general

La API de Calendario de Google proporciona notificaciones push que te permiten supervisar los cambios en los recursos. Puedes usar esta función para mejorar el rendimiento de tu aplicación. Te permite eliminar los costos adicionales de red y procesamiento que implica sondear los recursos para determinar si cambiaron. Cada vez que cambia un recurso observado, la API de Calendario de Google notifica a tu aplicación.

Para usar las notificaciones push, debes hacer lo siguiente:

  • Configurar tu URL de recepción o receptor de devolución de llamada de "webhook".

    Este es un servidor HTTPS que controla los mensajes de notificación de la API que se activan cuando cambia un recurso.

  • Configurar un (canal de notificaciones) para cada extremo de recurso que deseas observar.

    Un canal especifica la información de enrutamiento para los mensajes de notificación mensajes. Como parte de la configuración del canal, debes identificar la URL específica en la que deseas recibir notificaciones. Cada vez que cambia el recurso de un canal, la API de Calendario de Google envía un mensaje de notificación como una POST solicitud a esa URL.

Actualmente, la API de Calendario de Google admite notificaciones de cambios en los recursos de ACL, CalendarList, Events y Settings.

Crea canales de notificaciones

Para solicitar notificaciones push, debes configurar un canal de notificaciones para cada recurso que deseas supervisar. Después de configurar los canales de notificaciones, la API de Calendario de Google informa a tu aplicación cuando cambia cualquier recurso observado.

Realiza solicitudes de observación

Cada recurso de la API de Google Calendar que se puede observar tiene un método watch asociado en un URI del siguiente formato:

https://www.googleapis.com/API_NAME/API_VERSION/RESOURCE_PATH/watch

Para configurar un canal de notificaciones para mensajes sobre cambios en un recurso en particular, envía una POST solicitud al watch método del recurso.

Cada canal de notificaciones está asociado con un usuario y un recurso (o conjunto de recursos) en particular. Una solicitud watch no tendrá éxito a menos que el usuario actual sea propietario de este recurso o tenga permiso para acceder a él.

Ejemplo

Comienza a observar los cambios en una colección de eventos en un calendario determinado:

POST https://www.googleapis.com/calendar/v3/calendars/my_calendar@gmail.com/events/watch
Authorization: Bearer auth_token_for_current_user
Content-Type: application/json

{
  "id": "01234567-89ab-cdef-0123456789ab",
  "type": "web_hook",
  "address": "https://mydomain.com/notifications",
  ...
  "token": "target=myApp-myCalendarChannelDest",
  "expiration": 1426325213000
}

En el cuerpo de la solicitud, proporciona el id de tu canal, el type como web_hook y tu URL de recepción en address. De manera opcional, también puedes proporcionar lo siguiente:

  • Un token para usar como token de canal
  • Un tiempo de expiration en milisegundos para el tiempo de vencimiento del canal solicitado

Propiedades obligatorias

Con cada solicitud watch, debes proporcionar estos campos:

  • Una cadena de propiedad id que identifica de forma única este nuevo canal de notificaciones dentro de tu proyecto. Recomendamos usar un identificador único universal (UUID) o cualquier cadena única similar. Longitud máxima: 64 caracteres.

    El valor de ID que establezcas se mostrará en el X-Goog-Channel-Id encabezado HTTP de cada mensaje de notificación que recibas para este canal.

  • Una cadena de propiedad type establecida en el valor web_hook.

  • Una cadena de propiedad address establecida en la URL que escucha y responde a las notificaciones de este canal de notificaciones. Esta es la URL de devolución de llamada de tu webhook, y debe usar HTTPS.

    Ten en cuenta que la API de Calendario de Google puede enviar notificaciones a esta dirección HTTPS solo si hay un certificado SSL válido instalado en tu servidor web. Entre los certificados no válidos se incluyen los siguientes:

    • Certificados autofirmados
    • Certificados firmados por una fuente no confiable
    • Certificados revocados
    • Certificados que tienen un asunto que no coincide con el nombre de host de destino

Propiedades opcionales

También puedes especificar estos campos opcionales con tu watch solicitud:

  • Una propiedad token que especifica un valor de cadena arbitrario para usar como token de canal. Puedes usar tokens de canal de notificaciones para varios propósitos. Por ejemplo, puedes usar el token para verificar que cada mensaje entrante sea para un canal que creó tu aplicación (para asegurarte de que la notificación no se suplante) o para enrutar el mensaje al destino correcto dentro de tu aplicación según el propósito de este canal. Longitud máxima: 256 caracteres.

    El token se incluye en el X-Goog-Channel-Token encabezado HTTP en cada mensaje de notificación que recibe tu aplicación para este canal.

    Si usas tokens de canal de notificaciones, te recomendamos que hagas lo siguiente:

    • Usa un formato de codificación extensible, como parámetros de consulta de URL. Ejemplo: forwardTo=hr&createdBy=mobile

    • No incluyas datos sensibles, como tokens de OAuth.

  • Una cadena de propiedad expiration establecida en una marca de tiempo de Unix (en milisegundos) de la fecha y hora en que deseas que la API de Calendario de Google deje de enviar mensajes para este canal de notificaciones.

    Si un canal tiene un tiempo de vencimiento, se incluye como el valor del encabezado HTTP X-Goog-Channel-Expiration (en formato legible ) en cada mensaje de notificación que recibe tu aplicación para este canal.

Para obtener más detalles sobre la solicitud, consulta el método watch para los recursos de ACL, CalendarList, Events y Settings en la referencia de la API.

Observa la respuesta

Si la solicitud watch crea correctamente un canal de notificaciones, muestra un código de estado HTTP 200 OK.

El cuerpo del mensaje de la respuesta de observación proporciona información sobre el canal de notificaciones que acabas de crear, como se muestra en el siguiente ejemplo.

{
  "kind": "api#channel",
  "id": "01234567-89ab-cdef-0123456789ab",
  "resourceId": "o3hgv1538sdjfh",
  "resourceUri": "https://www.googleapis.com/calendar/v3/calendars/my_calendar@gmail.com/events",
  "token": "target=myApp-myCalendarChannelDest",
  "expiration": 1426325213000
}

El cuerpo de la respuesta proporciona detalles del canal, como los siguientes:

  • kind: Identifica esto como un recurso de canal de la API.
  • id: El ID que especificaste para este canal.
  • resourceId: El ID del recurso observado.
  • resourceUri: El ID específico de la versión del recurso observado.
  • token: El token proporcionado en el cuerpo de la solicitud.
  • expiration: El tiempo de vencimiento del canal como una marca de tiempo de Unix en milisegundos.

Además de las propiedades que enviaste como parte de tu solicitud, la información que se muestra también incluye resourceId y resourceUri para identificar el recurso que se observa en este canal de notificaciones.

Puedes pasar la información que se muestra a otras operaciones del canal de notificaciones, como cuando deseas dejar de recibir notificaciones.

Para obtener más detalles sobre la respuesta, consulta el watch método para los recursos de ACL, CalendarList, Events y Settings en la referencia de la API.

Sincronizar mensaje

Después de crear un canal de notificaciones para observar un recurso, la API de Calendario de Google envía un mensaje sync para indicar que se iniciarán las notificaciones. El X-Goog-Resource-State valor del encabezado HTTP para estos mensajes es sync. Debido a problemas de sincronización de la red, es posible que recibas el mensaje sync incluso antes de recibir la respuesta del método watch.

Es seguro ignorar la notificación sync, pero también puedes usarla. Por ejemplo, si decides que no quieres conservar el canal, puedes usar los valores X-Goog-Channel-ID y X-Goog-Resource-ID en una llamada para dejar de recibir notificaciones. También puedes usar la sync notificación para realizar alguna inicialización para prepararte para eventos posteriores.

A continuación, se muestra el formato de los mensajes sync que la API de Calendario de Google envía a tu URL de recepción.

POST https://mydomain.com/notifications // Your receiving URL.
X-Goog-Channel-ID: channel-ID-value
X-Goog-Channel-Token: channel-token-value
X-Goog-Channel-Expiration: expiration-date-and-time // In human-readable format. Present only if the channel expires.
X-Goog-Resource-ID: identifier-for-the-watched-resource
X-Goog-Resource-URI: version-specific-URI-of-the-watched-resource
X-Goog-Resource-State: sync
X-Goog-Message-Number: 1

Los mensajes de sincronización siempre tienen un X-Goog-Message-Number HTTP valor de encabezado de 1. Cada notificación posterior para este canal tiene un número de mensaje más grande que el anterior, aunque los números de mensaje no serán secuenciales.

Renueva los canales de notificaciones

Un canal de notificaciones puede tener un tiempo de vencimiento, con un valor determinado por tu solicitud o por los límites o valores predeterminados internos de la API de Calendario de Google (se usa el valor más restrictivo). El tiempo de vencimiento del canal, si tiene uno, se incluye como una marca de tiempo de Unix (en milisegundos) en la información que muestra el watch método. Además, la fecha y hora de vencimiento se incluyen (en formato legible) en cada mensaje de notificación que recibe tu aplicación para este canal en el X-Goog-Channel-Expiration encabezado HTTP.

Actualmente, no hay una forma automática de renovar un canal de notificaciones. Cuando un canal está cerca de su vencimiento, debes reemplazarlo por uno nuevo llamando al método watch. Como siempre, debes usar un valor único para la propiedad id del canal nuevo. Ten en cuenta que es probable que haya un período de "superposición" cuando los dos canales de notificaciones para el mismo recurso estén activos.

Recibir notificaciones

Cada vez que cambia un recurso observado, tu aplicación recibe un mensaje de notificación que describe el cambio. La API de Calendario de Google envía estos mensajes como solicitudes POST HTTPS a la URL que especificaste como la address propiedad para este canal de notificaciones.

Interpreta el formato del mensaje de notificación

Todos los mensajes de notificación incluyen un conjunto de encabezados HTTP que tienen X-Goog- prefijos. Algunos tipos de notificaciones también pueden incluir un cuerpo del mensaje.

Encabezados

Los mensajes de notificación que publica la API de Calendario de Google en tu URL de recepción incluyen los siguientes encabezados HTTP:

Encabezado Descripción
Siempre presente
X-Goog-Channel-ID UUID u otra cadena única que proporcionaste para identificar este canal de notificaciones
X-Goog-Message-Number Número entero que identifica este mensaje para este canal de notificaciones (el valor siempre es 1 para los mensajes sync) (los números de mensaje aumentan para cada mensaje posterior en el canal, pero no son secuenciales)
X-Goog-Resource-ID Un valor opaco que identifica el recurso observado (este ID es estable en todas las versiones de la API)
X-Goog-Resource-State El nuevo estado del recurso que activó la notificación (valores posibles: sync, exists o not_exists)
X-Goog-Resource-URI Un identificador específico de la versión de la API para el recurso observado
A veces presente
X-Goog-Channel-Expiration Fecha y hora de vencimiento del canal de notificaciones, expresadas en formato legible (solo está presente si se define)
X-Goog-Channel-Token Token de canal de notificaciones que estableció tu aplicación y que puedes usar para verificar la fuente de la notificación (solo está presente si se define)

Los mensajes de notificación que publica la API de Calendar en tu URL de recepción no incluyen un cuerpo del mensaje. Estos mensajes no contienen información específica sobre los recursos actualizados; debes realizar otra llamada a la API para ver los detalles completos del cambio.

Ejemplo

Mensaje de notificación de cambio para la colección modificada de eventos:

POST https://mydomain.com/notifications
Content-Type: application/json; utf-8
Content-Length: 0
X-Goog-Channel-ID: 4ba78bf0-6a47-11e2-bcfd-0800200c9a66
X-Goog-Channel-Token: 398348u3tu83ut8uu38
X-Goog-Channel-Expiration: Tue, 19 Nov 2013 01:13:52 GMT
X-Goog-Resource-ID:  ret08u3rv24htgh289g
X-Goog-Resource-URI: https://www.googleapis.com/calendar/v3/calendars/my_calendar@gmail.com/events
X-Goog-Resource-State:  exists
X-Goog-Message-Number: 10

Responder notificaciones

Para indicar éxito, puedes mostrar cualquiera de los siguientes códigos de estado: 200, 201, 202, 204 o 102.

Si tu servicio usa la biblioteca cliente de la API de Google y muestra 500,502, 503, o 504, la API de Google Calendar vuelve a intentarlo con un retroceso exponencial. Cualquier otro código de estado de retorno se considera una falla del mensaje.

Comprende los eventos de notificación de la API de Calendario de Google

En esta sección, se proporcionan detalles sobre los mensajes de notificación que puedes recibir cuando usas notificaciones push con la API de Calendario de Google.

X-Goog-Resource-State Se aplica a Se entrega cuando
sync ACLs, listas de calendarios, eventos y configuración Se creó correctamente un canal nuevo. Ahora se pueden recibir notificaciones.
exists ACLs, listas de calendarios, eventos y configuración Cambió un recurso. Los posibles cambios incluyen la creación de un recurso nuevo o la modificación o eliminación de un recurso existente.

Detener notificaciones

La propiedad expiration controla cuándo se detienen las notificaciones automáticamente. Puedes dejar de recibir notificaciones para un canal en particular antes de que venza llamando al método stop en el siguiente URI:

https://www.googleapis.com/workspace/calendar/api/v3/reference/channels/stop

Este método requiere que proporciones al menos las propiedades id y resourceId del canal, como se muestra en el ejemplo siguiente. Ten en cuenta que, si la API de Calendario de Google tiene varios tipos de recursos que tienen watch métodos, solo hay un stop método.

Solo los usuarios con el permiso adecuado pueden detener un canal. En particular:

  • Si el canal se creó con una cuenta de usuario normal, solo el mismo usuario del mismo cliente (identificado por los IDs de cliente de OAuth 2.0 de los tokens de autenticación) que creó el canal puede detenerlo.
  • Si el canal se creó con una cuenta de servicio, cualquier usuario del mismo cliente puede detenerlo.

En la siguiente muestra de código, se muestra cómo dejar de recibir notificaciones:

POST https://www.googleapis.com/workspace/calendar/api/v3/reference/channels/stop
  
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

{
  "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a66",
  "resourceId": "ret08u3rv24htgh289g"
}