Notificaciones push

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

Descripción general

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

Para usar notificaciones push, debes hacer lo siguiente:

  • Configura la URL de destino o el receptor de devolución de llamada "Webhook".

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

  • Configura un canal de notificaciones para cada extremo de recursos que desees supervisar.

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

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

Cómo crear canales de notificaciones

A fin de solicitar notificaciones push, debes configurar un canal de notificaciones para cada recurso que desees mirar. Después de configurar los canales de notificaciones, la API del Calendario de Google informará a tu aplicación cuando cambie algún recurso observado.

Cómo hacer solicitudes de reproducción

Cada recurso observable de la API del Calendario de Google tiene un método watch asociado en un URI del siguiente formato:

https://www.googleapis.com/apiName/apiVersion/resourcePath/watch

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

Cada canal de notificaciones se asocia 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 buscar 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", // Your channel ID.
  "type": "web_hook",
  "address": "https://mydomain.com/notifications", // Your receiving URL.
  ...
  "token": "target=myApp-myCalendarChannelDest", // (Optional) Your channel token.
  "expiration": 1426325213000 // (Optional) Your requested channel expiration time.
}

Propiedades obligatorias

Con cada solicitud watch, debes proporcionar lo siguiente:

  • Una string de propiedad id que identifica de forma única este nuevo canal de notificación dentro de tu proyecto. Te recomendamos usar un identificador único universal (UUID) o cualquier string única similar. Longitud máxima: 64 caracteres

    El valor de ID que estableces se repite en el encabezado HTTP X-Goog-Channel-Id de cada mensaje de notificación que recibes para este canal.

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

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

    Ten en cuenta que la API del Calendario de Google podrá 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 con un asunto que no coincide con el nombre de host de destino

Propiedades opcionales

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

  • Una propiedad token que especifica un valor de string arbitrario para usar como token de canal. Puedes usar tokens de canal de notificaciones para varios propósitos. Por ejemplo, puedes usar el token a fin de verificar que cada mensaje entrante sea para un canal que creó tu aplicación (a fin de asegurarte de que no se está falsificando la notificación) 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 encabezado HTTP X-Goog-Channel-Token en cada mensaje de notificación que tu aplicación recibe para este canal.

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

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

    • No incluyas datos sensibles, como tokens de OAuth.

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

    Si un canal tiene un plazo de vencimiento, se incluye como el valor del encabezado HTTP X-Goog-Channel-Expiration (esta vez en formato legible) en todos los mensajes de notificación que tu aplicación recibe para este canal.

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

Ver 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 del reloj 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"", // ID you specified for this channel.
  "resourceId": "o3hgv1538sdjfh", // ID of the watched resource.
  "resourceUri": "https://www.googleapis.com/calendar/v3/calendars/my_calendar@gmail.com/events", // Version-specific ID of the watched resource.
  "token": "target=myApp-myCalendarChannelDest", // Present only if one was provided.
  "expiration": 1426325213000, // Actual expiration time as Unix timestamp (in ms), if applicable.
}

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 mira en este canal de notificaciones.

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

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

Sincronizar mensaje

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

Es seguro ignorar la notificación de sync, pero también puedes usarla. Por ejemplo, si decides que no deseas mantener 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 notificación sync a fin de realizar una inicialización para prepararte para eventos posteriores.

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

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 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 valor de encabezado HTTP X-Goog-Message-Number de 1. Cada notificación posterior de este canal tendrá un número de mensaje mayor que el anterior, aunque los números de mensaje no serán secuenciales.

Renovación de canales de notificaciones

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

Actualmente, no hay manera automática de renovar un canal de notificación. Cuando un canal está cerca de vencer, debes llamar al método watch para crear uno nuevo. 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.

Recibe notificaciones

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

Información sobre el formato de los mensajes de notificación

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

Encabezados

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

Título Descripción
Siempre presente
X-Goog-Channel-ID UUID o cualquier otra string ú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 es siempre 1 para sync mensajes. 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 está definido.
X-Goog-Channel-Token Es el 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 está definido.

Los mensajes de notificación publicados por la API de Calendario de Google en tu URL de destino no incluyen un cuerpo de mensaje. Estos mensajes no contienen información específica sobre los recursos actualizados. Deberás hacer otra llamada a la API para ver los detalles completos del cambio.

Ejemplos

Cambiar el mensaje de notificación para la colección modificada de eventos:

POST https://mydomain.com/notifications // Your receiving URL.
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

Cómo responder notificaciones

Para indicar el é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 del Calendario de Google vuelve a intentarlo con la retirada exponencial. El resto del código de estado de devolución se considera un error de mensaje.

Información sobre 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 del Calendario de Google.

X-Goog-Resource-State Se aplica a Entregado cuando
sync LCA, listas de calendario, eventos y configuración. Se creó un nuevo canal correctamente. Es posible que comiences a recibir notificaciones sobre el contenido.
exists LCA, listas de calendario, eventos y configuración. Se produjo un cambio en un recurso. Los cambios posibles incluyen la creación de un recurso nuevo, o la modificación o eliminación de un recurso existente.

Cómo detener las notificaciones

La fecha de vencimiento es cuando las notificaciones se detienen automáticamente. Puedes optar por dejar de recibir notificaciones de un canal en particular antes de que caduque. Para ello, llama al método stop en el siguiente URI:

https://www.googleapis.com/calendar/v3/channels/stop

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

Solo los usuarios que tienen el permiso adecuado pueden detener un canal. En particular, considera lo siguiente:

  • Si el canal se creó con una cuenta de usuario común, solo el mismo usuario del mismo cliente (identificado por los ID de cliente de OAuth 2.0 a partir 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.
POST https://www.googleapis.com/calendar/v3/channels/stop
  
Authorization: Bearer {auth_token_for_current_user}
Content-Type: application/json

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