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:
Habilitar la API de Pub/Sub y preparar tu cuenta de servicio
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.
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: cuenta-de-servicio@proyecto.iam.gserviceaccount.com.
- 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.
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.
- Ve a la documentación de accounts.register y haz clic en Probar.
- En el campo
account
, ingresaaccounts/ACCOUNT_ID
y reemplazaACCOUNT_ID
con tu ID de la 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 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.
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.
- 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.
- Haz clic en Crear función.
- En la pantalla Configuración, sigue estos pasos:
- Cambia el nombre de la función. De forma opcional, elige otra región.
- En el activador HTTP, cambia Authentication a Permite las invocaciones no autenticadas y haz clic en Guardar.
- Anota la URL del activador. La necesitarás en el próximo paso.
- 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 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
Haz clic en Activar Cloud Shell en la parte superior de la consola de Google Cloud.
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 servicioTOPIC
por el tema creado en el paso 2 yPUSH_ENDPOINT
por la URL del activador de la función de Cloud Run 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
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.
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
yaccounts.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
yentitlements.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.