Notificaciones de Pub/Sub

• Asegúrate de completar el Codelab de configuración de la API para configurar una proyecto de Google Cloud y crea una cuenta de servicio para llamar al API de Cloud Channel.

• Te recomendamos que uses la Test Partner Sales Console para este codelab.

• Familiarízate con Pub/Sub conceptos.

Descripción general

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

Esto es particularmente útil para lo siguiente:

• Refleja los cambios realizados directamente en Partner Sales Console en tu propio (por ejemplo, alguien de tu equipo de asistencia al cliente que cancela un derechos de Google Workspace).
• Detecta eventos críticos que activan tus clientes de reventa. Para ejemplo:
  • Un cliente de Google Workspace aceptando 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 se transfiere.

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

1. Habilitar la API de Pub/Sub y preparar tu cuenta de servicio

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

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

Para una suscripción de envío, alojarás un webhook que reciba el eventos emitidos por los Servicios de canal:

Formato de las notificaciones

El siguiente es un ejemplo de notificación de Pub/Sub. Los datos del mensaje se 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 de 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, necesitas lo siguiente:

• La dirección de correo electrónico de una cuenta de servicio en 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)
• Su ID de la cuenta. Puedes encontrarlo en la configuración de tu Partner Sales Console.

Para preparar tu cuenta de servicio, sigue estos pasos:

• Ve a la sección Biblioteca de APIs de la consola de Google Cloud. habilitar la API de Pub/Sub.
• Otórgale 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 en su lugar, debes otorgarle el 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 el servicio. de servicio predeterminada.

Paso 2: Crea un tema para tu cuenta

Para crear el tema de Pub/Sub, debes usar el accounts.register. Este método toma un correo electrónico de la cuenta de servicio como paramétero. Solo las cuentas de servicio autorizadas con 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, ingresa accounts/ACCOUNT_ID y reemplaza ACCOUNT_ID con tu ID de la 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 revendedor dominio.

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 el modo en que tu aplicación y consume eventos de cambio. Tienes dos opciones:

• Suscripción de envío: Proporciona 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 periódicamente para obtener cambios en cola.

En este codelab, usaremos la función Push y enviaremos todos los eventos a un Función de Cloud Run que registrará Cloud Logging.

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

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

1. Ve a la sección sección Cloud Run functions de la Consola de Google Cloud Es posible que debas habilitar la API de funciones de Cloud Run.
2. Haz clic en Crear función.
3. En la pantalla Configuración, sigue estos pasos:
   1. Cambia el nombre de la función. De forma opcional, elige otra región.
   2. En el activador HTTP, cambia Authentication a Permite las 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, haz lo siguiente:

   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 con 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 registraron en el tema Servicios de canal (consulta el paso 2) pueden crear una suscripción.

Puedes hacerlo con código si llamas a la API de Pub/Sub con tu servicio las credenciales de tu cuenta. Asegurarse de no suplantar la identidad del dominio de su distribuidor Administrador avanzado, que es obligatorio cuando se llama a la API de Cloud Channel.

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

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

2. Cuando la shell esté lista, ejecuta el siguiente comando. Reemplaza los valores de SERVICE_ACCOUNT por la dirección de correo electrónico de la 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 de suscripciones a Pub/Sub.

Genera algunos datos

Después de completar los pasos anteriores, ya puedes recibir datos.

La forma más sencilla es crear un cliente en tu Partner Sales Console y aprovisionar un producto. Si has terminado la codelab de aprovisionamiento de Workspace de extremo a extremo puedes crear un cliente con una cuenta de Google Workspace ejecutando código.

Ve a tu función en la consola de Google Cloud y abre la pestaña Registros. El siguiente es un ejemplo de lo que deberías ver.

Nota: En casos excepcionales, Pub/Sub puede tardar unos minutos. para comenzar a recibir eventos del tema.

Limpia

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

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

Próximos pasos

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

Referencia de eventos

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 las pasos de forma programática. Para ello, deberás hacer lo siguiente:

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

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

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

Prácticas recomendadas del extremo de envío:

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

• Mientras que el tiempo de espera predeterminado de Pub/Sub para el envío es de 10 segundos (esto se puede aumentar mediante la API de ackDeadline), se recomienda usar una arquitectura basada en mensajes y hacer que el endpoint responda lo más rápido posible.

• Si tu extremo no funciona o devuelve errores 5xx, Pub/Sub vuelve a intentarlo. Puedes encontrar más información sobre cómo recibir mensajes a través de push 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 todo Cambios en las licencias de Google Workspace.