Descripción general
La API de revendedor usa la API de Pub/Sub para entregar notificaciones push sobre diferentes eventos de suscripción de Google Workspace. Por ejemplo, puedes configurar notificaciones push para recibir notificaciones cuando cambien los estados de las suscripciones de tus clientes.
Requisitos previos
- Habilita la API de Pub/Sub para tu proyecto de Google Cloud.
- Otorga roles de IAM de Pub/Sub a la cuenta de servicio en el
proyecto de Cloud. Otorgar la función
roles/pubsub.editor
es una buena concesión (fácil y no demasiado amplio), pero es posible que desees usar permisos de Pub/Sub más específicos.
Crea un tema
Para crear un tema, debes registrarte con la API de revendedor con el método resellernotify.register
.
El método resellernotify.register
toma una dirección de correo electrónico de una cuenta de servicio como parámetro. Solo las cuentas de servicio autorizadas por este método pueden suscribirse al tema recién creado.
POST https://reseller.googleapis.com/apps/reseller/v1/resellernotify/register
{
"serviceAccountEmailAddress": "reseller@reseller-project.iam.gserviceaccount.com"
}
Una respuesta correcta muestra un código de estado HTTP 200
y una respuesta JSON que contiene el nombre de tu tema de Pub/Sub.
La siguiente es una respuesta de ejemplo:
{
"topicName": "projects/partner-watch/topics/C0abcdefg"
}
Para autorizar que las cuentas de servicio adicionales usen tu tema, puedes volver a llamar a resellernotify.register
.
Revoca el acceso a una cuenta de servicio
La API de revendedor también proporciona la capacidad de cancelar el registro de cuentas de servicio con el extremo resellernotify.unregister
:
POST https://reseller.googleapis.com/apps/reseller/v1/resellernotify/unregister
{
"serviceAccountEmailAddress": "reseller@reseller-project.iam.gserviceaccount.com"
}
Suscribirse a un tema
Después de crear el tema de Pub/Sub, debes configurar la forma en que tu aplicación consume los eventos de cambio. Elige una de las siguientes opciones:
- Suscripción de envío: Proporciona una devolución de llamada HTTP
POST
. Pub/Sub usa esta devolución de llamada para notificar a tu aplicación sobre eventos nuevos. - Suscripción de extracción: Tu aplicación realiza una llamada HTTP de forma periódica para obtener todos los cambios en cola.
A continuación, se muestra un ejemplo de solicitud para suscribirse a un tema:
PUT https://pubsub.googleapis.com/v1/projects/PROJECT/subscriptions/SUBSCRIPTION_NAME { "topic": "TOPIC_NAME" // Only needed for push configurations "pushConfig": { "pushEndpoint": "PUSH_NOTIFICATION_ENDPOINT" }, }
Reemplaza lo siguiente:
PROJECT
: Es el proyecto de Google Cloud.SUBSCRIPTION_NAME
: Es un nombre de identificación para la suscripción.TOPIC_NAME
: Es el tema de Pub/Sub que creaste antes.PUSH_NOTIFICATION_ENDPOINT
: Es el extremo del controlador de notificaciones push.
Una respuesta correcta muestra un código de estado HTTP 200
. La siguiente es una respuesta de ejemplo:
{ "name": "projects/PROJECT/subscriptions/SUBSCRIPTION_NAME", "topic": "TOPIC_NAME", "pushConfig": { "pushEndpoint": "PUSH_NOTIFICATION_ENDPOINT" }, "ackDeadlineSeconds": 10 }
Formatos de notificación
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": {}, "data": "eyJza3VfaWQiOiAiR29vZ2xlLUFwcHMtVW5saW1pdGVkIiwgImV2ZW50X3R5cGUiOiAiU1VCU0NSSVBUSU9OX0NBTkNFTExFRCIsICJjdXN0b21lcl9kb21haW5fbmFtZSI6ICJkb21haW4uY29tIiwgInN1YnNjcmlwdGlvbl9pZCI6ICIxMjM0NTY3IiwgImN1c3RvbWVyX2lkIjogIkMwYWJjZGVmIiwgIm1lc3NhZ2VfaWQiOiAiODY3NTMwOSIsICJwdWJsaXNoX3RpbWUiOiB7InNlY29uZHMiOiAxNDU3NzMxODQ2LCAibmFub3MiOiAzNDkwMDAwMDB9LCAicmVzZWxsZXJfY3VzdG9tZXJfaWQiOiAiQzByZXNlbGxlciJ9", "message_id": 1234567891012131 }, "subscription": "projects/PROJECT/subscriptions/SUBSCRIPTION_NAME" }
A continuación, se muestra el objeto message.data
de ejemplo después de la decodificación:
{
"customer_id": "C0abcdef",
"customer_domain_name": "domain.com",
"event_type": "SUBSCRIPTION_CANCELLED",
"sku_id": "Google-Apps-Unlimited",
"subscription_id": "1234567",
// Optional fields depended on event_type
"subscription_suspension_reasons": [],
"subscription_cancellation_reason": "REASON"
}
Tipos de eventos
La siguiente lista contiene todos los tipos de eventos posibles:
NEW_SUBSCRIPTION_CREATED
: Se creó una suscripción nueva.SUBSCRIPTION_TRIAL_ENDED
: Finalizó la prueba de una suscripción.PRICE_PLAN_SWITCHED
: El cliente pasó de un plan flexible a un plan anual. Este evento no se activa si el cliente pasa de un plan de tipo compromiso a uno flexible como parte de una renovación.COMMITMENT_CHANGED
: El compromiso anual aumentó o disminuyó.SUBSCRIPTION_RENEWED
: Se renovó una suscripción anual.SUBSCRIPTION_SUSPENDED
: Se suspendió la suscripción. Consulta el camposubscription_suspension_reasons
.SUBSCRIPTION_SUSPENSION_REVOKED
: Se revocó la suspensión de una suscripción suspendida anteriormente.SUBSCRIPTION_CANCELLED
: Se canceló la suscripción. Consulta el camposubscription_cancellation_reason
. También se puede usar para detectar transferencias.SUBSCRIPTION_CONVERTED
: Se convirtió la suscripción. Estos son algunos ejemplos de casos de este evento:- Convierte la suscripción directa en una suscripción de revendedor.
- Convierte la suscripción pagada en una oferta de gracia.
- Convierte la suscripción en línea en una suscripción sin conexión.
SUBSCRIPTION_UPGRADE
: Se actualizó el SKU de suscripción. Por ejemplo, la suscripción se actualizó de Google Workspace Business Starter a Business Standard.SUBSCRIPTION_DOWNGRADE
: El SKU de suscripción cambió a una versión inferior. Por ejemplo, la suscripción pasó de Google Workspace Business Standard a Business Starter.LICENSE_ASSIGNMENT_CHANGED
: La licencia se asignó o se revocó a un usuario. Puedes usar este evento para realizar un seguimiento reactiva de los cambios en el recuento de licencias de las suscripciones flexibles.
Motivos de la cancelación de la suscripción
El motivo de cancelación de la suscripción se propaga cuando el valor de event_type
es SUBSCRIPTION_CANCELLED
. A continuación, se indican los posibles motivos de cancelación:
TRANSFERRED_OUT
: El cliente se transfirió a facturación directa o a otro revendedor.PURCHASE_OF_SUBSUMING_SKU
: El cliente se actualizó a un SKU que anula otro. Por ejemplo, si un cliente con Google Workspace Business Starter y Google Vault se actualiza a Google Workspace Business Plus, la suscripción a Vault se incluye en Google Workspace Business Plus.RESELLER_INITIATED
: El revendedor canceló la suscripción.OTHER
: Se canceló la suscripción por algún motivo distinto del que se indica.
Motivos de suspensión de la suscripción
El motivo de suspensión de la suscripción se propaga cuando el valor de event_type
es SUBSCRIPTION_SUSPENDED
. A continuación, se indican algunos de los posibles motivos de suspensión:
PENDING_TOS_ACCEPTANCE
: El cliente no accedió y no aceptó las Condiciones del Servicio de Reventa de Google Workspace.RENEWAL_WITH_TYPE_CANCEL
: El compromiso del cliente finalizó y su servicio se canceló al final del período.RESELLER_INITIATED
: El revendedor suspendió la suscripción de forma manual.TRIAL_ENDED
: Venció la prueba del cliente y este no seleccionó un plan de prueba.OTHER
: El cliente está suspendido por un motivo interno de Google, por ejemplo, por abuso.
Limitaciones de Pub/Sub
No se garantiza el orden de las notificaciones push. Los mensajes se pueden entregar varias veces y en situaciones extremas, pero no en absoluto. Recomendamos usar reseller.subscriptions.get
en todas las suscripciones modificadas para extraer el estado actual.