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 Directory 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 supervisado, la API de Directory notifica a tu aplicación.

Para usar las notificaciones push, debes hacer dos cosas:

Configura 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.
Configura un (canal de notificaciones) para cada extremo de recurso que quieras 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 notificaciones. Cada vez que cambia el recurso de un canal, la API de Directory envía un mensaje de notificación como una solicitud POST a esa URL.

Actualmente, la API de Directory admite notificaciones sobre cambios en el recurso Users.

Crea canales de notificaciones

Para solicitar notificaciones push, debes configurar un canal de notificaciones para cada recurso que desees supervisar. Después de configurar tus canales de notificaciones, la API de Directory le informa a tu aplicación cuando cambia algún recurso supervisado.

Cómo realizar solicitudes de reloj

Cada recurso de la API de Directory que se puede observar tiene un método watch asociado en un URI con el siguiente formato:

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

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

Cada canal de notificación se asocia con un usuario y un recurso (o conjunto de recursos) en particular. Una solicitud watch no se completará correctamente a menos que el usuario actual o la cuenta de servicio sean propietarios de este recurso o tengan permiso para acceder a él.

Ejemplos

Todas las solicitudes de observación del recurso User para un solo dominio tienen el siguiente formato general:

POST https://admin.googleapis.com/admin/directory/v1/users/watch?domain=domain&event=event
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-myFilesChannelDest",
  "params": {
    "ttl": 3600
  }
}

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

Es un token que se usará como token del canal.
Un ttl en params para solicitar un tiempo de actividad para este canal en segundos.

Usa los parámetros domain y event para especificar el dominio y el tipo de evento para los que deseas recibir notificaciones.

Todas las solicitudes de observación del recurso User de un cliente tienen el siguiente formato general:

POST https://admin.googleapis.com/admin/directory/users/v1/watch?customer=customer&event=event
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-myFilesChannelDest",
  "params": {
    "ttl": 3600
  }
}

Usa los parámetros customer y event para especificar el ID único de la Cuenta de Google del cliente y el tipo de evento para el que deseas recibir notificaciones.

Los valores posibles de event son los siguientes:

add: Evento de usuario creado
delete: Evento de usuario borrado
makeAdmin: Evento de cambio de estado de administrador del usuario
undelete: Evento de recuperación de usuario
update: Evento de actualización del usuario

Nota: En los siguientes ejemplos, se omite el cuerpo de la solicitud para mayor claridad.

Observa los eventos creados por el usuario para el dominio mydomain.com:

POST https://admin.googleapis.com/admin/directory/v1/users/watch?domain=mydomain.com&event=add

Observa los eventos creados por el usuario para el cliente my_customer:

POST https://admin.googleapis.com/admin/directory/v1/users/watch?customer=my_customer&event=add

Propiedades obligatorias

Con cada solicitud watch, debes proporcionar los siguientes campos:

Es 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. La longitud máxima es de 64 caracteres.

El valor del ID que estableces se devuelve en el encabezado HTTP X-Goog-Channel-Id de cada mensaje de notificación que recibes para este canal.
Es una cadena de propiedad type establecida en el valor web_hook.
Es una cadena de propiedad de 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 del webhook y debe usar HTTPS.

Ten en cuenta que la API de Directory solo puede enviar notificaciones a esta dirección HTTPS 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 solicitud watch:

Es una propiedad token que especifica un valor de cadena arbitrario para usar como token de canal. Puedes usar tokens de canales de notificación 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 no se suplante la notificación, o bien 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 recibe tu aplicación para este canal.

Si usas tokens de canales de notificación, te recomendamos que hagas lo siguiente:
- Usa un formato de codificación extensible, como los parámetros de consulta de URL. Ejemplo: forwardTo=hr&createdBy=mobile
- No incluyas datos sensibles, como tokens de OAuth.
Nota: Si debes enviar datos altamente sensibles, asegúrate de que estén encriptados antes de agregarlos al token.
Es 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 Directory deje de enviar mensajes para este canal de notificaciones.

Si un canal tiene una hora de vencimiento, se incluye como el valor del encabezado HTTP X-Goog-Channel-Expiration (en formato legible para las personas) 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 del recurso Users en la referencia de la API.

Respuesta del reloj

Si la solicitud watch crea correctamente un canal de notificaciones, devuelve 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": "B4ibMJiIhTjAQd7Ff2K2bexk8G4",
  "resourceUri": "https://admin.googleapis.com/admin/directory/v1/users?domain=domain&event=event",
  "token": "target=myApp-myFilesChannelDest",
  "expiration": 1384823632000
}

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

id: Es el ID que especificaste para este canal.
resourceId: Es el ID del recurso observado.
resourceUri: Es el ID específico de la versión del recurso observado.
token: Es el token proporcionado en el cuerpo de la solicitud.
expiration: Es la hora 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 devuelve también incluye resourceId y resourceUri para identificar el recurso que se supervisa en este canal de notificaciones.

Nota: La propiedad resourceId es un identificador estable e independiente de la versión para el recurso. La propiedad resourceUri es el URI canónico del recurso observado en el contexto de la versión actual de la API, por lo que es específica de la versión.

Puedes pasar la información que se devolvió a otras operaciones del canal de notificaciones, por ejemplo, cuando quieras dejar de recibir notificaciones.

Para obtener más detalles sobre la respuesta, consulta el método watch del recurso Users en la referencia de la API.

Mensaje de sincronización

Después de crear un canal de notificación para observar un recurso, la API de Directory envía un mensaje sync para indicar que se iniciarán 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 que recibas el mensaje sync incluso antes de recibir la respuesta del método watch.

Puedes ignorar la notificación de 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 a dejar de recibir notificaciones. También puedes usar la notificación sync para realizar alguna inicialización y prepararte para eventos posteriores.

A continuación, se muestra el formato de los mensajes sync que la API de Directory 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 valor de encabezado HTTP X-Goog-Message-Number de 1. Cada notificación posterior de este canal tiene un número de mensaje mayor que el anterior, aunque los números de mensaje no serán secuenciales.

Renueva los canales de notificaciones

Un canal de notificación puede tener una hora de vencimiento, con un valor determinado por tu solicitud o por los límites o valores predeterminados internos de la API de Directory (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 milisegundos) en la información que muestra el método watch. Además, la fecha y hora de vencimiento se incluyen (en formato legible) en cada mensaje de notificación que tu aplicación recibe para este canal en el encabezado HTTP X-Goog-Channel-Expiration.

Actualmente, no hay una forma automática de renovar un canal de notificaciones. Cuando un canal esté cerca de vencer, 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" en el que los dos canales de notificación para el mismo recurso estén activos.

Recibir notificaciones

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

Nota: Las solicitudes HTTPS de entrega de notificaciones especifican un usuario-agente de APIs-Google y respetan las directivas de robots.txt, como se describe en Usuario-agente de APIs de Google.

Interpreta el formato del mensaje 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 un cuerpo del mensaje.

Encabezados

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

Encabezado	Descripción
Siempre presente
`X-Goog-Channel-ID`	Es el UUID o alguna otra cadena única que proporcionaste para identificar este canal de notificación.
`X-Goog-Message-Number`	Es un 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 los mensajes aumentan para cada mensaje posterior en el canal, pero no son secuenciales.
`X-Goog-Resource-ID`	Es un valor opaco que identifica el recurso observado. Este ID es estable en todas las versiones de la API.
`X-Goog-Resource-State`	Es el estado del recurso nuevo que activó la notificación. Los valores posibles son: `sync` o un nombre de evento.
`X-Goog-Resource-URI`	Es 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 notificación, expresadas en formato legible. Solo está presente si se define.
`X-Goog-Channel-Token`	Es el token del canal de notificación que configuró 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 para los usuarios contienen la siguiente información en el cuerpo de la solicitud:

Propiedad	Descripción
`kind`	Identifica este objeto como un recurso User. Valor: La cadena fija "`admin#directory#user`".
`id`	Es el identificador único del recurso del usuario.
`etag`	Es el ETag del mensaje de notificación. Es diferente de la ETag del recurso User.
`primaryEmail`	Es la dirección de correo electrónico principal del usuario.

Ejemplos

Los mensajes de notificación para los eventos de recursos User tienen la siguiente forma general:

POST https://mydomain.com/notifications
Content-Type: application/json; utf-8
Content-Length: 0
X-Goog-Channel-ID: directoryApiId
X-Goog-Channel-Token: 398348u3tu83ut8uu38
X-Goog-Channel-Expiration: Tue, 29 Oct 2013 20:32:02 GMT
X-Goog-Resource-ID:  ret08u3rv24htgh289g
X-Goog-Resource-URI: https://admin.googleapis.com/admin/directory/v1/users?domain=domain&event=event
X-Goog-Resource-State:  event
X-Goog-Message-Number: 10

{
  "kind": "admin#directory#user",
  "id": long,
  "etag": string,
  "primaryEmail": string
}

A continuación, se muestra un ejemplo de un evento de usuario borrado:

POST https://mydomain.com/notifications
Content-Type: application/json; utf-8
Content-Length: 189
X-Goog-Channel-ID: deleteChannel
X-Goog-Channel-Token: 245t1234tt83trrt333
X-Goog-Channel-Expiration: Mon, 09 Dec 2013 22:24:23 GMT
X-Goog-Resource-ID:  B4ibMJiIhTjAQd7Ff2K2bexk8G4
X-Goog-Resource-URI: https://admin.googleapis.com/admin/directory/v1/users?domain=mydomain.com&event=delete&alt=json
X-Goog-Resource-State:  delete
X-Goog-Message-Number: 236440

{
  "kind": "admin#directory#user",
  "id": "111220860655841818702",
  "etag": "\"Mf8RAmnABsVfQ47MMT_18MHAdRE/evLIDlz2Fd9zbAqwvIp7Pzq8UAw\"",
  "primaryEmail": "user@mydomain.com"
}

Responder notificaciones

Para indicar que la operación se realizó correctamente, puedes devolver 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 devuelve 500,502, 503 o 504, la API de Directory vuelve a intentarlo con retirada exponencial. Todos los demás códigos de estado de devolución se consideran errores de mensaje.

Detener notificaciones

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

https://www.googleapis.com/admin/directory_v1/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, si la API de Directory tiene varios tipos de recursos que tienen métodos watch, solo hay un método stop.

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 desde el mismo cliente (identificado por los IDs de cliente de OAuth 2.0 de los tokens de autorizació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 indica cómo dejar de recibir notificaciones:

POST https://www.googleapis.com/admin/directory_v1/channels/stop
  
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

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

Notificaciones push Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Descripción general

Crea canales de notificaciones

Cómo realizar solicitudes de reloj

Ejemplos

Propiedades obligatorias

Propiedades opcionales

Respuesta del reloj

Mensaje de sincronización

Renueva los canales de notificaciones

Recibir notificaciones

Interpreta el formato del mensaje de notificación

Encabezados

Ejemplos

Responder notificaciones

Detener notificaciones

Notificaciones push