En este documento, se describe cómo usar 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 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 relacionados con los recursos de sondeo para determinar si cambiaron. Cada vez que cambia un recurso observado, la API de Directory notifica a tu aplicación.
Para usar notificaciones push, debes seguir dos pasos:
Configura tu URL de recepción o receptor de devolución de llamada de "webhook".
Este es un servidor HTTPS que maneja 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 observar.
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.
En la actualidad, la API de Directory admite notificaciones de cambios en el recurso Users.
Cómo crear canales de notificaciones
Si quieres solicitar notificaciones push, debes configurar un canal de notificaciones para cada recurso que quieras supervisar. Una vez configurados los canales de notificación, la API de Directory informa a tu aplicación cuándo cambia cualquier recurso observado.
Cómo realizar solicitudes de supervisión
Cada recurso de la API de Directory que se puede mirar tiene un método watch
asociado en un URI con la siguiente forma:
https://www.googleapis.com/API_NAME/API_VERSION/RESOURCE_PATH/watch
Si deseas 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 está asociado con un usuario y un recurso específicos (o conjunto de recursos). Una solicitud watch
no se llevará a cabo correctamente, a menos que el usuario actual o la cuenta de servicio sean propietarios del recurso o tengan permiso para acceder a él.
Ejemplos
Todas las solicitudes de supervisión del recurso User
para un solo dominio tienen la forma 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", // Your channel ID. "type": "web_hook", "address": "https://mydomain.com/notifications", // Your receiving URL. ... "token": "target=myApp-myFilesChannelDest", // (Optional) Your channel token. "params": { "ttl": 3600 // (Optional) Your requested time-to-live for this channel. } }
Usa los parámetros domain y event para especificar el dominio y el tipo de evento del que deseas recibir notificaciones.
Todas las solicitudes de observación del recurso Usuario de un cliente tienen el 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", // Your channel ID. "type": "web_hook", "address": "https://mydomain.com/notifications", // Your receiving URL. ... "token": "target=myApp-myFilesChannelDest", // (Optional) Your channel token. "params": { "ttl": 3600 // (Optional) Your requested time-to-live for this channel. } }
Usa los parámetros customer y event para especificar el ID único de la Cuenta de Google del cliente y el tipo de evento del que quieres recibir notificaciones.
Estos son los valores posibles para event:
add
: evento creado por el usuariodelete
: Evento borrado por el usuariomakeAdmin
: Evento de cambio de estado del administrador del usuarioundelete
: el usuario recuperó el eventoupdate
: Evento actualizado por el usuario
Nota: En los siguientes ejemplos, se omite el cuerpo de la solicitud para mayor claridad.
Observa los eventos creados por los usuarios 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 los usuarios 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 de watch
, debes proporcionar estos campos:
-
Una cadena de propiedad
id
que identifica de forma única este canal de notificación nuevo dentro del proyecto. Te recomendamos que uses 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 de este canal. -
Una string de propiedad
type
establecida en el valorweb_hook
. -
Una cadena de propiedad
address
establecida en la URL que escucha y responde las notificaciones de este canal de notificaciones Esta es la URL de devolución de llamada de webhook, y debe usar HTTPS.Ten en cuenta que la API de Directory 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 con un asunto que no coincide con el nombre de host de destino.
Propiedades opcionales
También puedes especificar estos campos opcionales con la solicitud watch
:
-
Una propiedad
token
que especifica un valor de string arbitrario para usar como token de canal. Puedes usar los tokens del canal de notificaciones para varios fines. Por ejemplo, puedes usar el token para verificar que cada mensaje entrante corresponda a un canal que creó tu aplicación (a fin de asegurarte de que no se falsificó la notificación) o para enrutar el mensaje al destino correcto dentro de tu aplicación según el propósito de ese 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 canales de notificaciones, te recomendamos 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.
-
Una string de propiedad
expiration
establecida en una marca de tiempo Unix (en milisegundos) de la fecha y hora en la que deseas que la API de Directory deje de enviar mensajes para este canal de notificaciones.Si un canal tiene una fecha de vencimiento, se incluye como el valor del encabezado HTTP
X-Goog-Channel-Expiration
(en un formato legible) en cada mensaje de notificación que tu aplicación recibe para este canal.
Si deseas obtener más detalles sobre la solicitud, consulta el método watch
para el recurso Users en la referencia de la API.
Ver respuesta
Si la solicitud watch
crea correctamente un canal de notificaciones, mostrará 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 notificación 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": "B4ibMJiIhTjAQd7Ff2K2bexk8G4", // ID of the watched resource. "resourceUri": "https://admin.googleapis.com/admin/directory/v1/users?domain=domain&event=event", // Version-specific ID of the watched resource. "token": "target=myApp-myFilesChannelDest", // Present only if one was provided. "expiration": 1384823632000, // Actual expiration time as Unix timestamp (in ms), if applicable. }
Además de las propiedades que enviaste como parte de la 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.
Si deseas obtener más detalles sobre la respuesta, consulta el método watch
para el recurso Users en la referencia de la API.
Sincronizar mensaje
Después de crear un canal de notificaciones para mirar un recurso, la API de Directory envía un mensaje sync
para indicar que se están iniciando 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 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 notificación sync
para realizar una inicialización y prepararte para eventos posteriores.
A continuación, se muestra el formato de los mensajes de sync
que la API de Directory 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 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 mensajes no serán secuenciales.
Renovar canales de notificaciones
Un canal de notificaciones puede tener una fecha de vencimiento, con un valor determinado por tu solicitud o por cualquier límite interno o predeterminado de la API de Directory (el valor más restrictivo se usa). La hora de vencimiento del canal, si tiene una, se incluye como una marca de tiempo Unix (en milisegundos) en la información que muestra el método watch
. Además, la fecha y hora de vencimiento se incluyen (en un formato legible por humanos) en cada mensaje de notificación que recibe tu aplicación para este canal en el encabezado HTTP X-Goog-Channel-Expiration
.
Actualmente, no existe una forma automática de renovar un canal de notificaciones. Cuando un canal está por 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” cuando estén activos los dos canales de notificaciones para el mismo recurso.
Recepción de notificaciones
Cada vez que cambia un recurso observado, tu aplicación recibe un mensaje de notificación que describe el cambio. La API de Directory envía estos mensajes como solicitudes POST
HTTPS a la URL que especificaste como la propiedad address
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 con prefijos X-Goog-
.
Algunos tipos de notificaciones también pueden incluir el cuerpo del mensaje.
Encabezados
Los mensajes de notificación que publica la API de Directory en tu URL receptora incluyen los siguientes encabezados HTTP:
Encabezado | Descripción |
---|---|
Siempre presente | |
|
UUID o cualquier otra cadena única que proporcionaste para identificar este canal de notificaciones. |
|
Número entero que identifica este mensaje para este canal de notificaciones El valor es siempre 1 para los mensajes sync . La cantidad
de mensajes aumenta para cada mensaje posterior en el canal, pero no
es secuencial. |
|
Un valor opaco que identifica el recurso observado. Este ID es estable en todas las versiones de la API. |
|
El estado del recurso nuevo que activó la notificación.
Valores posibles: sync o un nombre de evento.
|
|
Un identificador específico de la versión de la API para el recurso observado. |
A veces presente | |
|
Es la fecha y hora del vencimiento del canal de notificaciones, expresadas en un formato legible. Solo está presente si está definido. |
|
Token del canal de notificaciones que configuró tu aplicación y que puedes usar para verificar la fuente de notificaciones. Solo está presente si está definido. |
Los mensajes de notificación para los usuarios contienen la siguiente información en el cuerpo de la solicitud:
Propiedad | Descripción |
---|---|
kind |
Lo identifica como un recurso de usuario. Valor: La cadena fija "admin#directory#user " |
id |
Es el identificador único del recurso del usuario. |
etag |
ETag del mensaje de notificación. Es diferente de la ETag del recurso Usuario. |
primaryEmail |
La dirección de correo electrónico principal del usuario. |
Ejemplos
Los mensajes de notificación para los eventos de recursos User
tienen el formato general:
POST https://mydomain.com/notifications // Your receiving URL. 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 }
Ejemplo de un evento que borró el usuario:
POST https://mydomain.com/notifications // Your receiving URL. 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 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 de Directory vuelve a intentarlo con una retirada exponencial.
Todos los demás códigos de estado de retorno se consideran mensajes con errores.
Detener notificaciones
La propiedad expiration
controla cuándo se detienen automáticamente las notificaciones. Puedes optar por dejar de recibir notificaciones de un canal específico antes de que venza. Para ello, llama 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 con métodos watch
, solo hay un método stop
.
Solo los usuarios con el permiso adecuado pueden detener un canal. En particular, considera lo siguiente:
- 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 una cuenta de servicio creó el canal, 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" }