Se usó la API de Cloud Translation para traducir esta página.

Notificaciones push

Este documento describe cómo usar notificaciones push que informen a tus cuando un recurso cambia.

Descripción general

La API de Directory proporciona notificaciones push que 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 que implican los recursos de sondeo para determinar si cambiaron. Cuando cambia un recurso bajo observación, la API de Directory notifica a tu y mantener la integridad de su aplicación.

Para usar las notificaciones push, debes hacer lo siguiente:

Configura tu URL de recepción o el receptor de devolución de llamada de "webhook".
Esta es un servidor HTTPS que controla los mensajes de notificación de la API que se que se activa cuando cambia un recurso.
Configura un (canal de notificaciones) para cada extremo de recurso que quieras observar.
Un canal especifica la información de enrutamiento para la notificación mensajes nuevos. 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 de 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 los canales de notificaciones la API de Directory informa a tu aplicación cuando se detecta cambios.

Realiza solicitudes de reloj

Cada recurso de la API de Directory watchable 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 notificación 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 en particular y de un recurso (o conjunto de recursos) en particular. Una solicitud de watch no tendrá éxito a menos que el usuario actual o cuenta de servicio es propietario de este recurso o tiene permiso para acceder a él.

Ejemplos

Todas las solicitudes de observación del recurso User para un solo dominio tienen la siguiente 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 para el que deseas recibir notificaciones.

Todas las solicitudes de vigilancia para el recurso Usuario 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", // 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 para el que deseas recibir notificaciones.

Los valores posibles de event son los siguientes:

add: evento creado por el usuario
delete: evento borrado por el usuario
makeAdmin: Evento de cambio de estado de administrador del usuario
undelete: Evento de usuario que no se borró
update: 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 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 completar estos campos:

Es una cadena de propiedad id que identifica de forma única este canal de notificaciones nuevo dentro de tu proyecto. Te recomendamos que uses un identificador único universal (UUID) o cualquier cadena única similar. Longitud máxima: 64 caracteres.

El valor de ID que establezcas se replicará en la Encabezado HTTP X-Goog-Channel-Id de cada notificación que recibas para este canal.
Una cadena de propiedad type configurada en el valor web_hook
Es una cadena de propiedad address establecida en la URL que escucha y responde a las notificaciones de este canal de notificaciones. Este es la URL de devolución de llamada del webhook que 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 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 de watch:

Una propiedad token que especifica una cadena arbitraria valor para usar como token del canal. Puedes usar tokens de canal de notificación para varios fines. 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 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 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 los parámetros de consulta de la URL. Ejemplo: forwardTo=hr&createdBy=mobile
- No incluyas datos sensibles, como tokens de OAuth.
Nota: Si debes enviar mensajes de texto datos, asegúrate de que estén encriptados antes de agregarlos a la el token de acceso.
Una cadena de propiedad expiration establecida en un Marca de tiempo Unix (en milisegundos) de la fecha y hora en que deseas que la API de Directory dejar de enviar mensajes para este canal de notificaciones.

Si un canal tiene un período de vencimiento, se incluye como valor del encabezado HTTP X-Goog-Channel-Expiration (en formato legible formato) en todos los mensajes de notificación que recibe la 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.

Mirar respuesta

Si la solicitud watch crea correctamente una notificación muestra un código de estado HTTP 200 OK.

El cuerpo del mensaje de la respuesta de Watch 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": "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 está observando en este canal de notificaciones.

Nota: La propiedad resourceId es un identificador estable e independiente de la versión para el recurso. El La propiedad resourceUri es el URI canónico del contenido visualizado recurso 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 muestra 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 watch. para el recurso Users en la Referencia de la API.

Sincronizar mensaje

Después de crear un canal de notificaciones para supervisar 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 la red problemas de tiempo, es posible recibir el mensaje sync incluso antes de recibir la respuesta del método watch.

Puedes ignorar la notificación sync de forma segura, 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 sync para realizar la inicialización y prepararte eventos posteriores.

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

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

Cómo renovar canales de notificaciones

Un canal de notificaciones puede tener una fecha de vencimiento, con un valor determinados por tu solicitud o por los límites internos de la API de Directory o valores predeterminados (se usa el valor más restrictivo). El vencimiento del canal hora, 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, el se incluyen la fecha y hora de vencimiento (en un formato legible) en cada mensaje de notificación que recibe tu aplicación para este canal en el Encabezado HTTP X-Goog-Channel-Expiration.

Actualmente, no hay una forma automática de renovar un canal de notificaciones. Cuándo un canal está por vencer, debes reemplazarlo por uno nuevo llamando el método watch Como siempre, debes usar un valor único para la propiedad id del canal nuevo. Ten en cuenta que probablemente como una "superposición" período en el que los dos canales de notificación del mismo recurso estén activos.

Recepción de notificaciones

Cada vez que cambia un recurso observado, tu aplicación recibe un mensaje de notificación en el que se 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.

Nota: Solicitudes HTTPS de entrega de notificaciones especifica un usuario-agente de APIs-Google y respeta robots.txt directivas, como se describe en APIs de Google Usuario-agente.

Cómo interpretar el formato del mensaje de notificación

Todos los mensajes de notificación incluyen un conjunto de encabezados HTTP que tienen 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 destino incluyen los siguientes encabezados HTTP:

Encabezado	Descripción
Siempre presente
`X-Goog-Channel-ID`	UUID o alguna otra cadena única que hayas proporcionado para identificar este canal de notificaciones
`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`	Un valor opaco que identifica el recurso observado. Este ID es estable entre las versiones de API.
`X-Goog-Resource-State`	Es el nuevo estado del recurso que activó la notificación. Valores posibles: `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 está presente
`X-Goog-Channel-Expiration`	Fecha y hora de vencimiento del canal de notificación, expresadas en en un formato legible por humanos. Solo está presente si se define.
`X-Goog-Channel-Token`	Es el token del canal de notificaciones 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`	Lo identifica como recurso de usuario. Valor: la cadena fija "`admin#directory#user`"
`id`	Es el identificador único del recurso del usuario.
`etag`	Es la ETag del mensaje de notificación. Es diferente de la ETag del recurso de usuario.
`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 el siguiente 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 borrado por 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 que la operación se realizó correctamente, 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 reintentos con retirada exponencial. Todos los demás códigos de estado de retorno se consideran como errores de mensaje.

Detener notificaciones

La propiedad expiration controla cuándo se detienen automáticamente las notificaciones. 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 el id y las propiedades 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 uno stop.

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

Si una cuenta de usuario normal creó el canal, solo el mismo usuario del mismo cliente (como lo identifican 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"
}