Notificaciones de Pub/Sub

• Completa el codelab de configuración de APIs para configurar un proyecto de Google Cloud y crear una cuenta de servicio para llamar a la API Cloud Channel.

• Te recomendamos que uses la Consola de Channel Services Console de este codelab.

• Familiarízate con los conceptos principales de Pub/Sub.

Información general

La API Cloud Channel utiliza Pub/Sub para enviar notificaciones sobre varios eventos de clientes y derechos de autor.

Esto resulta especialmente útil para:

• Refleja los cambios realizados directamente en la Consola de Channel Services en tus propios sistemas (por ejemplo, si un miembro del equipo de asistencia cancela una opción de acceso a un espacio de trabajo de Google).
• Detectar eventos críticos que activen tus clientes de reventa. Por ejemplo:
  • Un cliente de Workspace de Google acepta los Términos del Servicio.
  • Un cliente de Google Workspace que está verificando su dominio.
  • Un cliente de Google Workspace que añade usuarios con una flexibilidad flexible.
  • Un cliente de Google Workspace transferira

La configuración de Pub/Sub consta de tres pasos:

1. Habilita la API Pub/Sub y prepara tu cuenta de servicio.

2. Crea un tema de Pub/Sub. Este tema es propiedad de Channel Services y se especifica una cuenta de servicio que puede crear una suscripción.

3. Crea una suscripción de Pub/Sub. Esta suscripción se puede enviar con webhooks (el método preferido) o recuperar.

En una suscripción push, debes alojar un webhook que reciba los eventos emitidos por los servicios del canal:

Formato de las notificaciones

Este es un ejemplo de notificación de Pub/Sub. Los datos de los mensajes se transmiten como una cadena JSON codificada en base64.

{
  "message": {
    "attributes": {
      "event_type": "LICENSE_ASSIGNMENT_CHANGED",
      "subscriber_event_type": "ENTITLEMENT_EVENT"
    },
    "data": "eyJlbnRpdGxlbWVudF9ldmVudCI6eyJldmVudF90eXBlIjoiTElDRU5TRV9BU1NJR05NRU5UX0NIQU5HRUQiLCJlbnRpdGxlbWVudCI6ImFjY291bnRzL0MwMTIzNDU2L2N1c3RvbWVycy9TMDEyMzQ1NjcvZW50aXRsZW1lbnRzL1NhYmNkZWYxMjM0NSJ9fQ==",
    "message_id": 1918124788439510,
    "publish_time": "2021-01-14T01:23:45.678Z"
  },
  "subscription": "projects/project/subscriptions/channel-pubsub-test"
}

Son los mismos datos de mensaje, decodificado:

{
  "entitlement_event": {
    "event_type": "LICENSE_ASSIGNMENT_CHANGED",
    "entitlement": "accounts/C0123456/customers/S01234567/entitlements/Sabcdef12345"}
  }
}

Paso 1: Habilita la API Pub/Sub y prepara tu cuenta de servicio

Para ejecutar este codelab, necesitas lo siguiente:

• La dirección de correo electrónico de una cuenta de servicio de tu proyecto. Esta dirección tendrá el siguiente formato: [e-mail].
• Acceso a una cuenta de superadministrador de un dominio de distribuidor, preferiblemente la consola de servicios del canal de prueba.
• El ID de tu cuenta. Encontrarás esta opción en la configuración de la Consola de Channel Services.

Para preparar tu cuenta de servicio:

• Ve a la sección Biblioteca de APIs en la consola de Google Cloud y habilita la API Pub/Sub.
• Concede el rol de IAM de Pub/Sub en el proyecto a tu cuenta de servicio. La concesión de roles/pubsub.editor es una buena opción para este laboratorio de programación, pero puede que debas usar privilegios más pormenorizados en la integración de producción. Puedes consultar la referencia completa en la página de control de acceso de Pub/Sub.

Precaución: Si la cuenta de servicio no tiene roles de gestión de identidades y accesos, recibirás errores 403.

Paso 2: Crea el tema de tu cuenta

Para crear el tema de Pub/Sub, tienes que usar el método accounts.register. Este método incluye un parámetro de correo electrónico de la cuenta de servicio como parámetro. Solo pueden suscribirse al nuevo tema las cuentas de servicio autorizadas mediante este método.

1. Ve a la documentación de accounts.register y haz clic en Probar.
2. En el campo account, introduce accounts/ACCOUNT_ID y sustituye ACCOUNT_ID por el ID de tu cuenta.
3. Haz clic en Añadir parámetros del cuerpo de solicitud, selecciona serviceAccount e introduce la dirección de correo electrónico de tu cuenta de servicio.
4. Haz clic en Execute (Ejecutar) para asegurarte de que inicias sesión como superadministrador de tu dominio de distribuidor.

Deberías obtener una respuesta 200 como la siguiente:

{
  "topic": "projects/cloud-channel-pubsub/topics/C0123456-notify"
}

Este es el tema de Pub/Sub en el que se publicarán los eventos.

Nota: Este valor es obligatorio en el paso 3b.

Paso 3: Suscríbete al tema

Después de crear el tema de Pub/Sub, debes configurar la forma en que la aplicación consume eventos de cambio. Existen dos opciones:

• Suscripción push: se proporciona una retrollamada HTTP POST. Pub/Sub usará esto para notificar a tu aplicación los eventos nuevos.
• Suscripción de extracción: tu aplicación realiza periódicamente llamadas HTTP para obtener cambios en cola.

En este codelab, utilizaremos Push y enviaremos todos los eventos a una función de Cloud Functions que iniciará sesión en Cloud Logging.

Paso 3a: Crear una función de Cloud Functions

En este paso, vamos a crear una función de Cloud Functions que registrará los mensajes recibidos.

1. Ve a la sección Cloud Functions de la consola de Google Cloud. Puede que tengas que habilitar la API de Cloud Functions.
2. Haz clic en Crear función.
3. En la pantalla Configuration (Configuración), sigue estos pasos:
   1. Cambia el nombre de la función. Si quieres, puedes seleccionar otra región.
   2. En el activador de HTTP, cambia Autenticación a Permitir invocaciones sin autenticar y haz clic en Guardar.
   3. Anota la URL del activador. Lo necesitarás en el siguiente paso.
   4. Haz clic en Siguiente.

4. En la pantalla Código:

   1. Elige cualquier entorno de ejecución de Node.js
   2. Cambia el Punto de entrada a log.
   3. En el archivo index.js, sustituye el código de muestra por lo siguiente:

   exports.log = (req, res) => {
     if (req.body && req.body.message) {
       console.log(req.body);
       const message = req.body.message;
       // data is base64-encoded JSON
       const data = new Buffer.from(message.data, 'base64').toString();
       console.log(data);
     }
     res.status(200).send('OK');
   };
   

Puedes continuar con el siguiente paso mientras se despliega la función Cloud Functions.

Paso 3b: Crea la suscripción

Solo pueden crear una suscripción las cuentas de servicio que se hayan registrado en el tema "Servicios de canal" (consulta el paso 2).

Para ello, puedes llamar a la API Pub/Sub con las credenciales de tu cuenta de servicio. Asegúrate de no suplantar el superadministrador de tu dominio de distribuidor, ya que es obligatorio cuando se llama a la API Cloud Channel.

En este codelab, usarás la herramienta de herramientas gcloud de Cloud Shell.

1. Haz clic en Activar Cloud Shell en la parte superior de la consola de Google Cloud.

2. Cuando el shell esté listo, ejecuta el siguiente comando. Sustituye los valores de SERVICE_ACCOUNT por la dirección de correo electrónico de tu cuenta de servicio, TOPIC por el tema creado en el paso 2, y PUSH_ENDPOINT por la URL del activador de la nube. Función creada en el paso 3a:

   SERVICE_ACCOUNT=[e-mail]
   TOPIC=projects/cloud-channel-pubsub/topics/C0123456-notify
   PUSH_ENDPOINT=https://us-central1-project.cloudfunctions.net/pubsub
   

3. Activa la cuenta de servicio en el shell:

   gcloud iam service-accounts keys create sa-keys.json \
       --iam-account=$SERVICE_ACCOUNT
   gcloud auth activate-service-account --key-file=sa-keys.json
   

4. Crea la suscripción:

   gcloud pubsub subscriptions create channel-pubsub-test \
       --topic=$TOPIC \
       --push-endpoint=$PUSH_ENDPOINT
   

Para confirmar que la suscripción está configurada, ve a la sección de suscripciones de Pub/Sub.

Generar datos

Cuando haya realizado los pasos anteriores, estará listo para recibir datos.

La forma más sencilla de hacerlo es crear un cliente en la Consola de Channel Services y aprovisionar un producto. Si has terminado con el codelab de aprovisionamiento del espacio de trabajo completo, puedes ejecutar el código de muestra para crear un cliente con un espacio de trabajo de Google.

Ve a la función en la consola de Google Cloud y abre la pestaña Registros. A continuación, te mostramos un ejemplo de lo que debes ver.

Nota: En raras ocasiones, la suscripción de Pub/Sub puede tardar unos minutos en empezar a recibir eventos del tema.

Limpieza

• Eliminar función de Cloud Functions
• Eliminar una suscripción

El tema se borrará automáticamente cuando no tenga ningún suscriptor restante.

Pasos siguientes

En este codelab se descubrió el proceso de descubrir cómo los servicios de canales utilizan Pub/Sub para crear la integración de forma reactiva y a escala.

Referencia de eventos

Consulta en la referencia de RPC la lista de eventos que generan los servicios de canal.

Referencia de la API

Este codelab utiliza la consola de Google Cloud, pero puedes realizar estos pasos mediante programación. Para ello, sigue estos pasos:

• Utiliza accounts.register para crear el tema.
• Utiliza la subscriptions.create de la API Pub/Sub para crear la suscripción.
• Consulta accounts.listSubscribers y accounts.unregister para saber qué puntos de conexión adicionales puedes usar en la integración.

Garantías y prácticas recomendadas de Pub/Sub

El retraso entre un evento y su notificación no está garantizado. Del mismo modo, no se garantiza el orden de las notificaciones. Por último, los mensajes se pueden entregar varias veces.

Prácticas recomendadas de puntos de conexión de inserción:

• Como los mensajes pueden retrasarse, enviarse desordenados o enviarse varias veces, el punto de conexión debe ser idempotente y utilizar customers.get y entitlements.get

• Aunque el tiempo de espera predeterminado de Pub/Sub para las inserciones es de 10 segundos (se puede aumentar mediante la ackDeadline de la suscripción Pub/Sub, se recomienda utilizar una arquitectura basada en mensajes y hacer que el punto de conexión responde lo más rápido posible.

• Si el punto de conexión está inactivo o devuelve errores 5xx, Pub/Sub volverá a intentarlo. En la documentación de Pub/Sub, encontrarás más información sobre cómo recibir mensajes mediante inserción.

Si prefieres usar Pull, puedes encontrar información sobre cómo recibir mensajes mediante la extracción en la documentación de Pub/Sub.

Filtrado de eventos

Como las notificaciones de los servicios de canales incluyen attributes, puedes crear suscripciones detalladas mediante la creación de suscripciones Pub/Sub específicas con los filtros de Pub/Sub.

Por ejemplo, si filtras por attributes.event_type = "LICENSE_ASSIGNMENT_CHANGED", podrás hacer un seguimiento de todos los cambios de asientos del espacio de trabajo de Google.