Notificaciones push

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 campo subscription_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 campo subscription_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.