Notificaciones de Pub/Sub

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

• Te recomendamos que uses la Consola de ventas para socios de prueba para este codelab.

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

Descripción general

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

Esto es particularmente útil para lo siguiente:

• Refleja los cambios realizados directamente en Partner Sales Console en tus propios sistemas (por ejemplo, si alguien de tu equipo de asistencia cancela un derecho de Google Workspace).
• Detecta los eventos críticos que activan tus clientes revendidos. Por ejemplo:
  • Un cliente de Google Workspace acepta las Condiciones del Servicio.
  • Un cliente de Google Workspace verifica su dominio.
  • Un cliente de Google Workspace que agrega usuarios con un derecho flexible
  • Un cliente de Google Workspace que se transfiere

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

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

2. Cree un tema de Pub/Sub. Este tema es propiedad de los servicios de canal y deberás especificar una cuenta de servicio que pueda crear una suscripción.

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

Para una suscripción de envío, alojarás un webhook que reciba los eventos que emiten los servicios de canal:

Formato de las notificaciones

El siguiente es un ejemplo de notificación de Pub/Sub. Los datos del mensaje 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"
}

Estos son los mismos datos del mensaje, decodificados:

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

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

Para ejecutar este codelab, necesitarás lo siguiente:

• La dirección de correo electrónico de una cuenta de servicio de tu proyecto. Esta dirección se verá de la siguiente manera: [e-mail].
• Acceso a una cuenta de administrador avanzado de un dominio de revendedor (preferentemente, tu Console de Ventas para socios de prueba)
• Tu ID de cuenta. Puedes encontrar esta información en la configuración de Partner Sales Console.

Para preparar tu cuenta de servicio, sigue estos pasos:

• Navega a la sección Biblioteca de API en la consola de Google Cloud y habilita la API de Pub/Sub.
• Otorga a tu cuenta de servicio el rol de IAM de Pub/Sub en el proyecto. Otorgar roles/pubsub.editor (nombre de rol = "Editor de Pub/Sub") es suficiente para este codelab, pero te recomendamos que uses privilegios más detallados en tu integración de producción. Puedes encontrar los detalles completos de los roles de IAM en la página Control de acceso de Pub/Sub.
• Si decides aplicar un rol personalizado, debes otorgarle a ese rol el permiso pubsub.subscriptions.create para crear suscripciones.

Es posible que haya una demora después de aplicar estos roles y permisos a tu cuenta.

Precaución: Recibirás errores 403 si no hay roles de IAM en la cuenta de servicio.

Paso 2: Crea el tema de tu cuenta

Para crear el tema de Pub/Sub, debes usar el método accounts.register. Este método toma un correo electrónico de la cuenta de servicio como paramétero. Solo las cuentas de servicio autorizadas a través de este método pueden suscribirse a tu tema nuevo.

1. Ve a la documentación de accounts.register y haz clic en Probar.
2. En el campo account, ingresa accounts/ACCOUNT_ID y reemplaza ACCOUNT_ID por el ID de tu cuenta.
3. Haz clic en Agregar parámetros del cuerpo de la solicitud, selecciona serviceAccount y, luego, ingresa la dirección de correo electrónico de tu cuenta de servicio.
4. Haz clic en Ejecutar y asegúrate de acceder como administrador avanzado de tu dominio de revendedor.

Deberías obtener una respuesta de 200 similar a 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 necesario en el paso 3b.

Paso 3: Suscríbete al tema

Después de crear el tema de Pub/Sub, debes configurar cómo tu aplicación consume los eventos de cambio. Tienes dos opciones:

• Suscripción push: Proporcionas una devolución de llamada HTTP POST. Pub/Sub lo usará para notificar a tu aplicación sobre eventos nuevos.
• Suscripción de extracción: Tu aplicación realiza llamadas HTTP de forma periódica para obtener cambios en fila.

En este codelab, usaremos Push y enviaremos todos los eventos a una función de Cloud Run que se registrará en Cloud Logging.

Paso 3a: Crea una función de Cloud Run

En este paso, crearemos una función de Cloud Run que registrará los mensajes recibidos.

1. Ve a la sección Funciones de Cloud Run de la consola de Google Cloud. Es posible que debas habilitar la API de Cloud Run Functions.
2. Haz clic en Crear función.
3. En la pantalla Configuración, haz lo siguiente:
   1. Cambia el nombre de la función. De forma opcional, elige otra región.
   2. En el activador de HTTP, cambia Autenticación a Permitir invocaciones no autenticadas y haz clic en Guardar.
   3. Anota la URL del activador. La necesitarás en el próximo paso.
   4. Haz clic en Siguiente.

4. En la pantalla Code, sigue estos pasos:

   1. Elige cualquier entorno de ejecución de Node.js
   2. Cambia el Punto de entrada a log.
   3. En el archivo index.js, reemplaza 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 implementa la función de Cloud Run.

Paso 3b: Crea la suscripción

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

Para hacerlo con código, llama a la API de Pub/Sub con las credenciales de tu cuenta de servicio. Asegúrate de no suplantar la identidad del superadministrador de tu dominio de distribuidor, lo que es obligatorio cuando se llama a la API de Cloud Channel.

Para este codelab, usarás la herramienta de gcloud CLI en Cloud Shell.

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

2. Una vez que el shell esté listo, ejecuta el siguiente comando. Reemplaza 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 función de Cloud Run 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 la 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 Suscripciones a Pub/Sub.

Genera algunos datos

Después de completar los pasos anteriores, estarás listo para recibir datos.

La forma más sencilla es crear un cliente en Partner Sales Console y aprovisionar un producto. Si completaste el codelab de aprovisionamiento de Workspace de extremo a extremo, puedes crear un cliente con Google Workspace ejecutando el código de muestra.

Ve a tu función en la consola de Google Cloud y abre la pestaña Registros. A continuación, se muestra un ejemplo de lo que deberías ver.

Nota: En casos excepcionales, la suscripción a Pub/Sub puede tardar unos minutos en comenzar a recibir eventos del tema.

Realiza una limpieza

• Borra la Cloud Run Function
• Borra la suscripción

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

Próximos pasos

En este codelab, descubriste cómo los servicios de canal aprovechan Pub/Sub para permitirte compilar tu integración de forma reactiva y a gran escala.

Referencia del evento

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

Referencia de API

En este codelab, se usa la consola de Google Cloud, pero puedes realizar estos pasos de forma programática. Para ello, deberás hacer lo siguiente:

• Usa accounts.register para crear el tema.
• Usa subscriptions.create de la API de Pub/Sub para crear la suscripción a Pub/Sub.
• Consulta accounts.listSubscribers y accounts.unregister para ver los extremos adicionales que puedes usar en tu integración.

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

No se garantiza la demora entre un evento y su notificación. Del mismo modo, el orden de las notificaciones no está garantizado. Por último, es posible que los mensajes se entreguen varias veces.

Prácticas recomendadas para los extremos de push:

• Dado que los mensajes pueden retrasarse, enviarse fuera de orden o enviarse varias veces, tu extremo debe ser idempotente y usar customers.get y entitlements.get.

• Si bien el tiempo de espera predeterminado de Pub/Sub para el envío es de 10 segundos (se puede aumentar a través de ackDeadline de la suscripción de Pub/Sub), se recomienda usar una arquitectura basada en mensajes y hacer que el extremo responda lo más rápido posible.

• Si tu extremo no está disponible o muestra errores 5xx, Pub/Sub volverá a intentarlo. Puedes encontrar más información sobre cómo recibir mensajes a través de la publicación en la documentación de Pub/Sub.

Si prefieres usar pull, puedes encontrar información sobre cómo recibir mensajes a través de extracción en la documentación de Pub/Sub.

Filtrado de eventos

Debido a que las notificaciones de los servicios de canal incluyen attributes, puedes crear suscripciones detalladas si creas suscripciones específicas de Pub/Sub con el filtrado de Pub/Sub.

Por ejemplo, filtrar con attributes.event_type = "LICENSE_ASSIGNMENT_CHANGED" te permite hacer un seguimiento de todos los cambios de asientos de Google Workspace.