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 del SDK de Admin proporciona notificaciones push cambios en los recursos. Puedes usar esta función para mejorar el rendimiento de tu aplicación. Te permite eliminar la red adicional y el procesamiento los costos relacionados con los recursos de sondeo para determinar si cambiaron. Cuando cambia un recurso bajo observación, la API de SDK de Admin le notifica y mantener la integridad de su aplicación.

Para usar las notificaciones push, debes hacer dos cosas:

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 donde quieres recibir notificaciones. Cada vez que cambia el recurso 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.

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 del SDK de Admin informa a tu aplicación cuando cambia un recurso observado.

Realiza solicitudes de reloj

Cada recurso de la API del SDK de Admin para mirar tiene un watch en un URI con la siguiente forma:

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 notificación está asociado con un usuario y un recurso (o conjunto de recursos) en particular. Una solicitud 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 reloj para el recurso Activities tienen el siguiente formato 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, aplicaciones o usuarios 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

Observa la actividad de 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 cambiar 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 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 a nivel universal (UUID) o cualquier opción similar o una cadena única. Longitud máxima: 64 caracteres.

El valor de ID que establezcas se repetirá en el encabezado HTTP X-Goog-Channel-Id de cada mensaje de notificación que recibas para este canal.
Una cadena de propiedades type establecida en el valor web_hook
Una cadena de propiedad address configurada en la URL que escucha y responde las notificaciones de este canal. Este es la URL de devolución de llamada del webhook que 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 objetivo nombre de host.

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 notificación mensaje 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 una consulta de URL parámetros. Ejemplo: forwardTo=hr&createdBy=mobile
- No incluyas datos sensibles, como tokens de OAuth.
Nota: Si debes enviar datos muy 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 la que deseas que la API del SDK de Admin 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 por humanos) en cada mensaje de notificación que recibe tu aplicación para este canal.

Nota: Para la API del SDK de Admin, el tiempo de vencimiento máximo es de 21,600 segundos. Si no estableces propiedad expiration en tu solicitud, el vencimiento el tiempo predeterminado es de 21,600 segundos después de la hora actual.

Para obtener más detalles sobre la solicitud, consulta el método watch. para el recurso Actividades en la Referencia de la API.

Cómo ver la 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": "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 está observando en este canal de notificaciones.

Nota: La propiedad resourceId es una un identificador estable independiente de la versión del 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 método watch del recurso Activities en la Referencia de la API.

Mensaje de sincronización

Después de crear un canal de notificaciones para supervisar 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 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 mantener el canal, puedes usar X-Goog-Channel-ID y valores de X-Goog-Resource-ID en una llamada a dejar de recibir notificaciones. También puedes usar la notificación sync para realizar una inicialización y prepararte para eventos posteriores.

El formato de los mensajes de sync que envía la API del SDK de Admin a tu URL de recepción se muestra debajo.

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.

Cómo renovar canales de notificaciones

Un canal de notificaciones puede tener un tiempo 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 fecha de vencimiento del canal, si la tiene, se incluye como una marca de tiempo de 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 existe una manera automática de renovar un canal de notificaciones. Cuando un canal esté por vencer, debes llamar al método watch para reemplazarlo por 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 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 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.

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.

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

Mensajes de notificación publicados por la API del SDK de Admin para el destinatario Las URL 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`	Número entero que identifica el mensaje de esta notificación canal. El valor siempre es `1` para los mensajes `sync`. Mensaje aumentan para cada mensaje posterior en el canal, pero son y no secuencial.
`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`	El nuevo estado del recurso que activó la notificación. Valores posibles: `sync` o un nombre de evento.
`X-Goog-Resource-URI`	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 está definido.
`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 sobre actividades contienen la siguiente información en el cuerpo de la solicitud:

Propiedad	Descripción
`kind`	Identifica esto como un recurso de actividad. Valor: la cadena fija "`admin#reports#activity`"
`id`	Identificador único del registro de actividad.
`id.time`	Hora en que ocurrió la actividad. El valor se encuentra en Formato de fecha y hora ISO 8601. La hora es la fecha completa más horas, minutos y segundos en el formato AAAA-MM-DDThh:mm:ssZH. Por ejemplo, 2010-04-05T17:30:04+01:00.
`id.uniqueQualifier`	Es un calificador único si varios eventos tienen la misma hora.
`id.applicationName`	Es el nombre de la aplicación al que pertenece el evento. Entre los valores posibles, se incluyen los siguientes: administrador calendario drive grupos groups_enterprise login móvil saml token user_accounts
`id.customerId`	Es el identificador único de una cuenta de Google Workspace.
`actor`	El usuario realiza la acción.
`actor.callerType`	Indica el 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 de OAuth 2LO o `USER` que realizó la acción que se indica en el informe .
`actor.email`	La dirección de correo electrónico principal del usuario cuyas actividades se están denunciando.
`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. Es la dirección de Protocolo de Internet (IP) del usuario cuando accede a Google Workspace, la cual puede reflejar su ubicación física o no. 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 admite 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 cambia un administrador se identifica en la propiedad `type`, que identifica un evento con la propiedad `eventName`.
`events[].name`	Nombre del evento. Este es el nombre específico de la actividad informada por la API. Además, cada `eventName` está relacionado con un servicio o una función específicos de Google Workspace que la API organiza en tipos de eventos. Para los parámetros de solicitud `eventName` en general: Si no se proporciona un `eventName`, el informe muestra todas las instancias posibles de un `eventName`. Cuando solicitas un `eventName`, la respuesta de la API muestra todas las actividades que contienen ese `eventName`. Es posible que las actividades que se devuelvan tengan otras propiedades `eventName` además de la solicitada.
`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 cadena del parámetro.
`events[].parameters[].intValue`	Es el valor de número entero del parámetro.
`events[].parameters[].boolValue`	Valor booleano del parámetro.

Ejemplos

Los mensajes de notificación para los eventos de recursos de la actividad 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: 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 que 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 del SDK de Admin vuelve a intentarlo con un tiempo de espera exponencial. Todos los demás códigos de estado de retorno se consideran como errores de mensaje.

Comprende 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 se usen notificaciones push con la API del SDK de Admin.

Las notificaciones push de la API de Reports 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 para 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. Puedes decide dejar de recibir notificaciones de un canal en particular antes de que expira llamando 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, el nombre de tu canal id y las propiedades resourceId, como se muestra en ejemplo a continuación. Ten en cuenta que si la API del SDK de Admin tiene varios tipos de recursos que tienen métodos watch, solo hay uno stop.

Solo los usuarios con el permiso correcto pueden detener un canal. En particular:

Si el canal se creó con una cuenta de usuario común, solo se admitirá usuario del mismo cliente (identificado por los IDs de cliente de OAuth 2.0 del tokens de autenticación) que crearon el canal pueden 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/reports_v1/channels/stop
  
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

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