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 canal de Cloud.

  • Te recomendamos que uses la Consola de servicios de canal de prueba para este codelab.

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

Descripción general

La API de Cloud Channel utiliza Pub/Sub para enviar notificaciones sobre varios eventos de cliente y autorización.

Esto resulta particularmente útil para lo siguiente:

  • Refleja los cambios realizados directamente en la Consola de servicios de canal en tus propios sistemas (por ejemplo, alguien de tu equipo de asistencia cancela una autorización de lugar de trabajo de Google).
  • Detecta eventos críticos que activan los clientes de reventa. Por ejemplo:
    • Un cliente del lugar de trabajo de Google acepta las Condiciones del Servicio.
    • Un cliente del lugar de trabajo de Google que verifica su dominio
    • Un cliente del lugar de trabajo de Google agrega usuarios a una autorización flexible.
    • Un cliente del lugar de trabajo de Google se va a transferir.

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 Channel Services, y especificarás una cuenta de servicio que puede 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 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

A continuación, se muestra un ejemplo de una 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á así: service-account@project.iam.gserviceaccount.com.
  • Acceso a una cuenta de administrador avanzado de dominio de distribuidor (preferentemente la consola de servicios del canal de prueba)
  • El ID de su cuenta. Lo puedes encontrar en la configuración de la Consola de servicios de canal.

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 la función de IAM de Pub/Sub en el proyecto a tu cuenta de servicio. La asignación de roles/pubsub.editor es una buena opción para este lab de código, pero es posible que desees usar privilegios más detallados en tu integración de producción. Puedes encontrar la referencia completa en la página de control de acceso de Pub/Sub.

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 un correo electrónico de la cuenta de servicio como parámetro. 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 accounts.register y haz clic en Probar.
  2. En el campo account, ingresa accounts/ACCOUNT_ID y reemplaza ACCOUNT_ID con tu ID de 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 el administrador avanzado 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 donde 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 eventos de cambio. Tienes estas dos opciones:

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

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

Cómo enviar notificaciones de servicios de canal a una función de Cloud Functions

Paso 3a: Crea una Cloud Function

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

  1. Ve a la sección Cloud Functions de Google Cloud Console. Es posible que debas habilitar la API de Cloud 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 manera opcional, elige otra región.
    2. En el activador HTTP, cambia la Autenticación por Permitir invocaciones no autenticadas y haz clic en Guardar.
    3. Toma nota de la URL del activador. La necesitarás en el próximo paso.
    4. Haga clic en Next.
  4. En la pantalla Código:

    1. Elige cualquier entorno de ejecución de Node.js
    2. Cambie 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 Functions.

Paso 3b: Crea la suscripción

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

Puedes hacerlo con el código si llamas a la API de Pub/Sub con las credenciales de tu cuenta de servicio. Asegúrate de no suplantar la identidad de la cuenta de administrador avanzado de tu dominio de distribuidor, que es necesaria cuando se llama a la API del canal de Cloud.

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

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

  2. Una vez que el shell esté listo, ejecuta el siguiente comando. Reemplaza los valores de SERVICE_ACCOUNT con la dirección de correo electrónico de tu cuenta de servicio, TOPIC con el tema creado en los pasos 2 y PUSH_ENDPOINT con la URL del activador de la nube. Función 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
    
  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
    

Puedes confirmar la configuración de la suscripción en la sección de suscripciones de Pub/Sub.

Genera algunos datos

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

La forma más fácil es crear un cliente en tu Consola de servicios de canal y aprovisionar un producto. Si terminaste el codelab de aprovisionamiento del lugar de trabajo de extremo a extremo, puedes ejecutar el código de muestra para crear un cliente con un lugar de trabajo de Google.

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

Registros de muestra de eventos de Pub/Sub

Limpia

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

El tema se limpiará de forma automática cuando no tenga ningún suscriptor restante.

Próximos pasos

Este codelab te ayudó a descubrir cómo los servicios de canal aprovechan Pub/Sub para que puedas compilar tu integración de manera reactiva y a gran escala.

Referencia de eventos

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

Referencia de API

En este codelab, se usa Google Cloud Console, pero puedes seguir estos pasos de manera programática. Para ello, deberás hacer lo siguiente:

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 extremo de envío:

  • Como los mensajes se pueden retrasar, enviar de forma desordenada 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 la suscripción de Pub/Sub ackDeadline), se recomienda usar una arquitectura basada en mensajes y hacer el extremo responde lo más rápido posible.

  • Si tu extremo está inactivo o muestra errores 5xx, Pub/Sub volverá a intentarlo. Puedes encontrar más información sobre cómo recibir mensajes mediante envío 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 con la creación de 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 del lugar de trabajo de Google.