Notificaciones de Pub/Sub

Asegúrate de completar el codelab de configuración de la API a fin de configurar un proyecto de Google Cloud y crear una cuenta de servicio para llamar a la API de Cloud Channel.
Para este codelab, te recomendamos que uses tu Partner Sales Console de prueba.
Familiarízate con los conceptos de Pub/Sub.

Descripción general

La API de Cloud Channel usa Pub/Sub para entregar 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, alguien de tu equipo de asistencia que cancela un derecho de Google Workspace).
Detecta eventos críticos que activan tus clientes de reventa. Por ejemplo:
- Un cliente de Google Workspace que acepta las Condiciones del Servicio
- Un cliente de Google Workspace verifica su dominio.
- Un cliente de Google Workspace que agrega usuarios con derechos flexibles.
- Un cliente de Google Workspace que se va a transferir.

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

Habilita la API de Pub/Sub y prepara tu cuenta de servicio.
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.
Crea una suscripción a Pub/Sub. Esta suscripción puede ser de push mediante webhooks (el método preferido) o de push.

Para una suscripción push, alojarás un webhook que reciba los eventos emitidos por los servicios de canal:

Notificaciones push para 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 string 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 mensajes, 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: service-account@project.iam.gserviceaccount.com.
Acceso a una cuenta de administrador avanzado de dominio de revendedor (preferentemente, tu Consola de Ventas para socios de prueba)
El ID de tu cuenta. Puedes encontrarlo en la configuración de tu Partner Sales Console.

Para preparar tu cuenta de servicio, sigue estos pasos:

Navega a la sección Biblioteca de API en Google Cloud Console 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 la función = '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 la función de IAM en la página Control de acceso de Pub/Sub.
Si eliges aplicar una función personalizada, debes otorgarle el permiso pubsub.subscriptions.create para crear suscripciones.

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

Paso 2: Crea el tema para tu cuenta

Para crear el tema de Pub/Sub, debes usar el método accounts.register. Este método toma el correo electrónico de una cuenta de servicio como parámetro. Solo las cuentas de servicio autorizadas con este método pueden suscribirse a tu tema nuevo.

Consulta la documentación de accounts.register y haz clic en Probar.
En el campo account, ingresa accounts/ACCOUNT_ID y reemplaza ACCOUNT_ID por el ID de tu cuenta.
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.
Haz clic en Ejecutar y asegúrate de acceder como administrador avanzado de tu dominio de revendedor.

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.

Paso 3: Suscríbete al tema

Después de crear el tema de Pub/Sub, debes configurar la forma en que tu aplicación consume los 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 de forma periódica para obtener cambios en cola.

En este codelab, usaremos Push y enviaremos todos los eventos a una Cloud Function que registrará Cloud Logging.

Envía notificaciones de los servicios de canal a una Cloud Function

Paso 3a: Crea una Cloud Function

En este paso, crearemos una Cloud Function que registrará los mensajes recibidos.

Ve a la sección Cloud Functions de la consola de Google Cloud. Es posible que debas habilitar la API de Cloud Functions.
Haz clic en Crear función.
En la pantalla Configuración, haz lo siguiente:
1. Cambia el nombre de la función. Si lo deseas, puedes elegir una región diferente.
2. En el activador HTTP, cambia la 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.

En la pantalla Code, haz lo siguiente:

Elige cualquier entorno de ejecución de Node.js
Cambia el Punto de entrada a log.
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 Cloud Function.

Paso 3b: Crea la suscripción

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

Puedes hacerlo con código; para ello, llama a la API de Pub/Sub con las credenciales de tu cuenta de servicio. Asegúrate de no suplantar la identidad del administrador avanzado de tu dominio de revendedor, lo cual es necesario cuando llamas a la API de Cloud Channel.

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

Haz clic en Activar Cloud Shell en la parte superior de la consola de Google Cloud.
Una vez que la shell esté lista, 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 Cloud Function creada en el paso 3a:
```
SERVICE_ACCOUNT=service-account@project.iam.gserviceaccount.com
TOPIC=projects/cloud-channel-pubsub/topics/C0123456-notify
PUSH_ENDPOINT=https://us-central1-project.cloudfunctions.net/pubsub
```

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

Crea la suscripción:

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

Puedes confirmar que la suscripción está configurada en la sección de suscripciones de Pub/Sub.

Genera algunos datos

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

La forma más sencilla es crear un cliente en tu Partner Sales Console y aprovisionar un producto. Si finalizaste el codelab de aprovisionamiento de Workspace de extremo a extremo, puedes crear un cliente con un Google Workspace mediante la ejecución del código de muestra.

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.

Registros de muestra para eventos de Pub/Sub

Limpia

Borra la función de Cloud Functions
Borrar la suscripción

El tema se limpiará automáticamente cuando no haya suscriptores restantes.

Próximos pasos

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

Referencia del evento

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

Referencia de la API

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

Usa accounts.register para crear el tema.
Usa el elemento subscriptions.create de la API de Pub/Sub para crear la suscripción a Pub/Sub.
Consulta accounts.listSubscribers y accounts.unregister para obtener 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, no se garantiza el orden de las notificaciones. Por último, los mensajes se pueden entregar varias veces.

Prácticas recomendadas para extremos de envío:

Como los mensajes se pueden retrasar, enviar desordenados 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 los envíos es de 10 segundos (se puede aumentar mediante el ackDeadline de la suscripción a 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 mediante envíos 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 específicas de Pub/Sub con el filtrado de Pub/Sub para crear suscripciones detalladas.

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