Notificaciones push

Propiedades obligatorias

Con cada solicitud watch, debes proporcionar estos campos:

• Una cadena de propiedad id que identifica de forma única este canal de notificaciones nuevo dentro del 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 estableces se repite en el encabezado HTTP X-Goog-Channel-Id de cada mensaje de notificación que recibes para este canal.

• Una cadena de propiedades type establecida 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. Esta es la URL de devolución de llamada de tu 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 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 del canal de notificaciones 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 tu aplicación recibe 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.

• 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.

Mirar respuesta

Si la solicitud de watch crea un canal de notificación correctamente, muestra 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": "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 tu solicitud, la información que se muestra también incluye resourceId y resourceUri para identificar el recurso que se está mirando en este canal de notificaciones.

Puedes pasar la información que se muestra a otras operaciones del canal de notificaciones, por ejemplo, cuando quieras 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.

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 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 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 la notificación sync para realizar la inicialización y prepararte para los 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 de este canal tiene un número de mensaje que es mayor que la anterior, aunque los números de mensaje no serán secuenciales.

Cómo 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 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, la fecha y hora de vencimiento se incluyen (en 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. Cuando esté por vencer un canal, deberás 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 notificaciones para el mismo recurso están activos.

Cómo interpretar 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.

Los mensajes de notificación de las actividades contienen la siguiente información en el cuerpo de la solicitud:

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
        }
      ]
    }
  ]
}

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 devolución se consideran un error 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 usas notificaciones push con la API del SDK de Admin.

Las notificaciones push de la API de Reports contienen dos tipos de mensajes: notificaciones de eventos y mensajes de sincronización. 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:

• admin
• calendario
• drive
• grupos
• login
• móvil
• saml
• token
• user_accounts