Notificaciones de Pub/Sub

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

• Te recomendamos que uses tu consola de Partner Sales de prueba para este codelab.

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

Información general

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

Esto resulta especialmente útil para lo siguiente:

• Reflejar 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 eventos críticos activados por tus clientes revendedores. Por ejemplo:
  • Un cliente de Google Workspace acepta los Términos del Servicio.
  • Un cliente de Google Workspace que verifica su dominio.
  • Un cliente de Google Workspace que añade usuarios con un derecho flexible.
  • Un cliente de Google Workspace que va a cambiar de proveedor.

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

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 especificarás una cuenta de servicio que pueda crear una suscripción.

3. Crea una suscripción de Pub/Sub. Esta suscripción puede ser de tipo push mediante webhooks (el método preferido) o de tipo pull.

En el caso de una suscripción push, alojarás un webhook que reciba los eventos emitidos por los servicios de canales:

Formato de las notificaciones

A continuación, se muestra 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 Pub/Sub y prepara tu cuenta de servicio

Para completar este codelab, necesitas lo siguiente:

• La dirección de correo de una cuenta de servicio de tu proyecto. Esta dirección tendrá el siguiente formato: [e-mail].
• Acceso a una cuenta de superadministrador de dominio de distribuidor (preferiblemente, tu consola de Partner Sales de prueba).
• Tu ID de cuenta. Puedes encontrarlo en la configuración de tu consola Partner Sales.

Para preparar tu cuenta de servicio, sigue estos pasos:

• Ve a la sección Biblioteca de APIs de la consola Google Cloud y habilita la API Pub/Sub.
• Concede a tu cuenta de servicio el rol de gestión de identidades y accesos de Pub/Sub en el proyecto. Conceder el rol roles/pubsub.editor (nombre del rol = "Editor de Pub/Sub") es suficiente para este codelab, pero puede que quieras usar privilegios más específicos en tu integración de producción. Puedes consultar todos los detalles de los roles de gestión de identidades y accesos en la página Control de acceso de Pub/Sub.
• Si decides aplicar un rol personalizado, debes concederle el permiso pubsub.subscriptions.create para crear suscripciones.

Puede haber un retraso después de aplicar estos roles y permisos a tu cuenta.

Advertencia: Recibirás errores 403 si no hay roles de gestión de identidades y accesos 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 como parámetro una dirección de correo de una cuenta de servicio. Solo las cuentas de servicio autorizadas mediante este método pueden suscribirse a tu nuevo tema.

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 tu ID de cuenta.
3. Haz clic en Añadir parámetros del cuerpo de la solicitud, selecciona serviceAccount e introduce tu dirección de correo de la cuenta de servicio.
4. Haz clic en Ejecutar e inicia sesión como superadministrador de tu dominio de distribuidor.

Deberías obtener una respuesta 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 consume tu aplicación los eventos de cambio. Dispones de dos opciones:

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

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

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

En este paso, vamos a crear una función de Cloud Run que registre los mensajes recibidos.

1. Ve a la sección Cloud Run functions (Funciones de Cloud Run) de laGoogle Cloud consola. Es posible que tengas que habilitar la API de funciones de Cloud Run.
2. Haz clic en Crear función.
3. En la pantalla Configuración:
   1. Cambia el nombre de la función. También puedes elegir otra región.
   2. En el activador HTTP, cambia Autenticación a Permitir invocaciones no autenticadas y haz clic en Guardar.
   3. Apunta la URL de activación. 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 ejemplo 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 en el tema Channel Services (consulta el paso 2) pueden crear una suscripción.

Para ello, puedes usar código y llamar a la API Pub/Sub con las credenciales de tu cuenta de servicio. Asegúrate de no suplantar la identidad del superadministrador del dominio de tu distribuidor, lo cual es obligatorio al llamar a la API Cloud Channel.

En este laboratorio, usarás la herramienta de la CLI de gcloud en Cloud Shell.

1. En la parte superior de la Google Cloud console, haz clic en Activar Cloud Shell.

2. Cuando el shell esté listo, ejecuta el siguiente comando. Sustituye los valores de SERVICE_ACCOUNT por la dirección de correo de tu cuenta de servicio, TOPIC por el tema creado en el paso 2 y PUSH_ENDPOINT por la URL de activación 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 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, vaya a la sección Suscripciones de Pub/Sub.

Generar datos

Cuando hayas completado los pasos anteriores, podrás recibir datos.

La forma más sencilla es crear un cliente en la consola de Partner Sales y aprovisionar un producto. Si has completado el codelab completo de aprovisionamiento del espacio de trabajo, puedes crear un cliente con un espacio de trabajo de Google ejecutando el código de ejemplo.

Ve a tu función en la Google Cloud consola 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 de Pub/Sub puede tardar unos minutos en empezar a recibir eventos del tema.

Limpieza

• Eliminar la función de Cloud Run
• Eliminar la suscripción

El tema se limpiará automáticamente cuando no le queden suscriptores.

Pasos siguientes

En este codelab, has descubierto cómo aprovecha Channel Services Pub/Sub para permitirte crear tu integración de forma reactiva y a gran escala.

Referencia de eventos

Consulta la referencia de RPC para ver la lista de eventos que genera Channel Services.

Referencia de la API

En este codelab se usa la consola Google Cloud , pero puedes realizar estos pasos mediante programación. Para ello:

• Usa accounts.register para crear el tema.
• Usa las APIs de Pub/Sub subscriptions.create para crear la suscripción de Pub/Sub.
• Consulta accounts.listSubscribers y accounts.unregister para ver otros endpoints que puedes usar en tu integración.

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

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

Prácticas recomendadas para los endpoints push:

• Como los mensajes pueden retrasarse, enviarse en un orden incorrecto o enviarse varias veces, tu endpoint debe ser idempotente y usar customers.get y entitlements.get.

• Aunque el tiempo de espera predeterminado de Pub/Sub para las notificaciones push es de 10 segundos (se puede aumentar mediante el campo ackDeadline de la suscripción de Pub/Sub), se recomienda usar una arquitectura basada en mensajes y hacer que el endpoint responda lo más rápido posible.

• Si tu endpoint no funciona o devuelve errores 5xx, Pub/Sub volverá a intentarlo. Puedes consultar más información sobre cómo recibir mensajes mediante push en la documentación de Pub/Sub.

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

Filtrado de eventos

Como las notificaciones de Channel Services incluyen attributes, puedes crear suscripciones detalladas creando suscripciones específicas de Pub/Sub con filtrado de Pub/Sub.

Por ejemplo, si filtras por attributes.event_type = "LICENSE_ASSIGNMENT_CHANGED", puedes monitorizar todos los cambios de puestos de Google Workspace.