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 del SDK de Admin 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 involucrados en el sondeo de recursos para determinar si cambiaron. Cada vez que cambia un recurso supervisado, la API del SDK de Admin notifica a tu aplicación.
Para usar notificaciones push, debes realizar las siguientes dos acciones:
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 notificación 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. Cuando cambian los recursos de un canal, la API del SDK de Admin envía un mensaje de notificación como una solicitud
POST
a esa URL.
Actualmente, la API del SDK de Admin admite notificaciones de cambios en el recurso Activities.
Cómo crear canales de notificaciones
A fin de solicitar notificaciones push, debes configurar un canal de notificaciones para cada recurso que desees supervisar. Una vez configurados los canales de notificaciones, la API del SDK de Admin informa a la aplicación cuando cambia un recurso observado.
Cómo realizar solicitudes de observación
Cada recurso de la API del SDK de Admin que se puede ver 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 notificación está asociado tanto a un usuario en particular como a un recurso (o conjunto de recursos) determinados. Una solicitud watch
no se realizará de forma correcta, a menos que el usuario o la cuenta de servicio actuales sean propietarios de este recurso o tengan permiso para acceder a él.
Ejemplos
Todas las solicitudes de observación del recurso Actividades tienen la forma general:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/userKey or all/applications/applicationName/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-myFilesChannelDest", // (Optional) Your channel token. "payload": true, // (Optional) Whether to include the payload (message body) in notifications. "expiration": 3600 // (Optional) Your requested channel expiration time. }
Puedes usar los parámetros userKey, applicationName, eventName
y filters
para recibir solo notificaciones de eventos, usuarios o aplicaciones específicos.
Nota: En los siguientes ejemplos, se omite el cuerpo de la solicitud para mayor claridad.
Observa todas las actividades del administrador:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin/watch
Mira todas las actividades de documentos:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/docs/watch
Busca la actividad del administrador de un usuario específico:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/liz@example.com/applications/admin/watch
Presta atención a un evento específico, como el cambio de la contraseña de un usuario:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin/watch?eventName=CHANGE_PASSWORD
Observa si hay cambios en un documento específico:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/docs/watch?eventName=EDIT&filters==doc_id=123456abcdef
Propiedades obligatorias
Con cada solicitud watch
, debes proporcionar estos campos:
-
Una cadena de propiedad
id
que identifica de manera única este canal de notificación nuevo dentro del proyecto. Recomendamos usar un identificador único universal (UUID) o cualquier string única similar. La longitud máxima es de 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 valorweb_hook
. -
Una string 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 del SDK de Admin 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 tokens de canal de notificaciones para diversos fines. Por ejemplo, puedes usar el token para verificar que cada mensaje entrante corresponda a un canal que haya creado tu aplicación (a fin de garantizar que la notificación no sea falsificada) 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 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 string de propiedad
expiration
establecida en una marca de tiempo Unix (en milisegundos) de la fecha y hora en las que deseas que la API del SDK de Admin 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 formato legible) en cada mensaje de notificación que recibe tu aplicación para este canal.
Si deseas obtener más detalles sobre la solicitud, consulta el método watch
para el recurso Activities en la Referencia de la API.
Mirar 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 la 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": "reportsApiId", // ID you specified for this channel. "resourceId": "o3hgv1538sdjfh", // ID of the watched resource. "resourceUri": "https://admin.googleapis.com/admin/reports/v1/activity/userKey/applications/applicationName", // Version-specific ID of the watched resource. "token": "target=myApp-myFilesChannelDest", // Present only if one was provided. "expiration": 3600, // 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 Activities en la referencia de la API.
Sincronizar mensaje
Después de crear un canal de notificaciones para observar un recurso, la API del SDK de Admin 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 tiempo 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 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 inicializarte y prepararte para eventos posteriores.
A continuación, se muestra el formato de los mensajes de sync
que la API del SDK de Admin 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 para este canal tiene un número de mensaje mayor que el anterior, aunque los números de mensaje 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 del SDK de Admin (se usa el valor más restrictivo). 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, se incluyen la fecha y hora de vencimiento (en un formato legible por humanos) en el encabezado HTTP X-Goog-Channel-Expiration
de cada mensaje de notificación que tu aplicación recibe para este canal.
Actualmente, no hay 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 del 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 del SDK de Admin envía estos mensajes como solicitudes POST
HTTPS a la URL que especificaste como la propiedad address
para este canal de notificaciones.
Cómo interpretar 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 de un mensaje.
Encabezados
Los mensajes de notificación publicados por la API del SDK de Admin en tu URL de recepción incluyen los siguientes encabezados HTTP:
Encabezado | Descripción |
---|---|
Siempre presente | |
|
UUID o cualquier otra string única que proporcionaste para identificar este canal de notificaciones. |
|
Es el número entero que identifica este mensaje para este canal de notificaciones. El valor es siempre 1 para sync mensajes. Los números de mensajes aumentan para cada mensaje posterior en el canal, pero no son secuenciales. |
|
Un valor opaco que identifica el recurso observado. Este ID es estable en todas las versiones de la API. |
|
El nuevo estado del recurso 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. |
Presente en ocasiones | |
|
Es la fecha y hora de vencimiento del canal de notificaciones, expresada en un formato legible. Solo está presente si está definido. |
|
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 está definido. |
Los mensajes de notificación para actividades contienen la siguiente información en el cuerpo de la solicitud:
Propiedad | Descripción |
---|---|
kind |
Identifica esto como un recurso de Activity. Valor: Es la cadena fija "admin#reports#activity ". |
id |
Es el identificador único del registro de actividad. |
id.time |
Hora en la que ocurrió la actividad. El valor debe estar en formato de fecha y hora ISO 8601. La hora es la fecha completa más las horas, los minutos y los segundos en el formato AAAA-MM-DDThh:mm:ssTZD. Por ejemplo, 2010-04-05T17:30:04+01:00. |
id.uniqueQualifier |
Calificador único si varios eventos tienen el mismo tiempo. |
id.applicationName |
Es el nombre de la aplicación a la que pertenece el evento. Entre los valores posibles, se incluyen los siguientes: |
id.customerId |
Es el identificador único de una cuenta de Google Workspace. |
actor |
Usuario que realiza la acción |
actor.callerType |
Corresponde al tipo de autor que realizó la actividad que se indica en el informe. En esta versión de la API, callerType es la solicitud de entidad USER o de OAuth 2LO que realizó la acción que se indica en el informe . |
actor.email |
Es la dirección de correo electrónico principal del usuario cuyas actividades se informan. |
actor.profileId |
El ID de perfil único de Google Workspace del usuario. |
ownerDomain |
Dominio de la Consola del administrador o del propietario del documento de la aplicación de Documentos. Este es el dominio que se ve afectado por el evento del informe. |
ipAddress |
Dirección IP del usuario que realiza la acción. Esta es la dirección de protocolo de Internet (IP) del usuario cuando accede a Google Workspace, que puede o no reflejar la ubicación física del usuario. Por ejemplo, la dirección IP puede ser la dirección del servidor proxy del usuario o una dirección de red privada virtual (VPN). La API es compatible con IPv4 y IPv6. |
events[] |
Eventos de actividad del informe. |
events[].type |
Es el tipo de evento. El servicio o la función de Google Workspace que un administrador cambia se identifica en la propiedad type , la cual identifica un evento con la propiedad eventName . |
events[].name |
Nombre del evento. Este es el nombre específico de la actividad que informa la API. Además, cada eventName está relacionado con una función o un servicio específico de Google Workspace que la API organiza en tipos de eventos.
Para los parámetros de solicitud eventName en general, haz lo siguiente:
|
events[].parameters[] |
Pares de valores de parámetros para varias aplicaciones. |
events[].parameters[].name |
El nombre del parámetro. |
events[].parameters[].value |
Es el valor de string del parámetro. |
events[].parameters[].intValue |
Valor entero del parámetro. |
events[].parameters[].boolValue |
El valor booleano del parámetro. |
Ejemplos
Los mensajes de notificación para los eventos de recursos de actividad 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: reportsApiId 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/reports/v1/activity/userKey/applications/applicationName X-Goog-Resource-State: eventName X-Goog-Message-Number: 10 { "kind": "admin#reports#activity", "id": { "time": datetime, "uniqueQualifier": long, "applicationName": string, "customerId": string }, "actor": { "callerType": string, "email": string, "profileId": long }, "ownerDomain": string, "ipAddress": string, "events": [ { "type": string, "name": string, "parameters": [ { "name": string, "value": string, "intValue": long, "boolValue": boolean } ] } ] }
Ejemplo de un evento de actividad del administrador:
POST https://mydomain.com/notifications // Your receiving URL. Content-Type: application/json; utf-8 Content-Length: 596 X-Goog-Channel-ID: reportsApiId X-Goog-Channel-Token: 245t1234tt83trrt333 X-Goog-Channel-Expiration: Tue, 29 Oct 2013 20:32:02 GMT X-Goog-Resource-ID: ret987df98743md8g X-Goog-Resource-URI: https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin?alt=json X-Goog-Resource-State: CREATE_USER X-Goog-Message-Number: 23 { "kind": "admin#reports#activity", "id": { "time": "2013-09-10T18:23:35.808Z", "uniqueQualifier": "-0987654321", "applicationName": "admin", "customerId": "ABCD012345" }, "actor": { "callerType": "USER", "email": "admin@example.com", "profileId": "0123456789987654321" }, "ownerDomain": "apps-reporting.example.com", "ipAddress": "192.0.2.0", "events": [ { "type": "USER_SETTINGS", "name": "CREATE_USER", "parameters": [ { "name": "USER_EMAIL", "value": "liz@example.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 del SDK de Admin vuelve a intentarlo con retirada exponencial.
Todos los demás códigos de estado de devolución se consideran errores del mensaje.
Información sobre los eventos de notificación de la API del SDK de Admin
En esta sección, se proporcionan detalles sobre los mensajes de notificación que puedes recibir cuando usas notificaciones push con la API del SDK de Admin.
Las notificaciones push de la API de informes contienen dos tipos de mensajes: los mensajes de sincronización y las notificaciones de eventos. El tipo de mensaje se indica en el encabezado HTTP X-Goog-Resource-State
. Los valores posibles de las notificaciones de eventos son los mismos que para el método activities.list
. Cada aplicación tiene eventos únicos:
Detener notificaciones
La propiedad expiration
controla cuándo se detienen automáticamente las notificaciones. Si quieres dejar de recibir notificaciones de un canal específico antes de su vencimiento, llama al método stop
en el siguiente URI:
https://www.googleapis.com/admin/reports_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 del SDK de Admin tiene varios tipos de recursos con métodos watch
, solo habrá 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 común, 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 detener el canal.
- 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/reports_v1/channels/stop Authorization: Bearer CURRENT_USER_AUTH_TOKEN Content-Type: application/json { "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a66", "resourceId": "ret08u3rv24htgh289g" }