Notificaciones push

Descripción general

La API de Reseller usa la API de Pub/Sub para enviar notificaciones push sobre diferentes eventos de suscripción de Google Workspace. Por ejemplo, puedes configurar notificaciones push para recibir una notificación cuando cambie el estado de suscripción 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 tu cuenta de servicio en tu proyecto de Cloud. Otorgar el rol roles/pubsub.editor es un buen compromiso (fácil y no demasiado amplio), pero te recomendamos que uses permisos de Pub/Sub más específicos.

Crea un tema

Para crear un tema, debes registrarte en la API de Reseller con el método resellernotify.register. El método resellernotify.register toma una dirección de correo electrónico de la cuenta de servicio como parámetro. Solo las cuentas de servicio autorizadas por este método pueden suscribirse a tu tema recién creado.

POST https://reseller.googleapis.com/apps/reseller/v1/resellernotify/register
{
  "serviceAccountEmailAddress": "[e-mail]"
}

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.

A continuación, se muestra una respuesta de ejemplo:

{
  "topicName": "projects/partner-watch/topics/C0abcdefg"
}

Para autorizar cuentas de servicio adicionales para que usen tu tema, puedes volver a llamar a resellernotify.register.

Cómo revocar el acceso de una cuenta de servicio

La API de Reseller también permite anular el registro de cuentas de servicio con el extremo resellernotify.unregister:

POST https://reseller.googleapis.com/apps/reseller/v1/resellernotify/unregister
{
  "serviceAccountEmailAddress": "[e-mail]"
}

Suscríbete a un tema

Después de crear el tema de Pub/Sub, debes configurar cómo tu aplicación consume los eventos de cambio. Elige una de las siguientes opciones:

• Suscripción push: Proporcionas una devolución de llamada POST HTTP. 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 periódicamente una llamada HTTP para obtener todos los cambios en fila.

Nota: Necesitas un cliente de Pub/Sub para realizar esta solicitud y debes autenticarte con una de las cuentas de servicio registradas en el paso anterior. Para obtener más información, consulta Suscriptor.

El siguiente es 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 tu 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 devuelve un código de estado HTTP 200. A continuación, se muestra una respuesta de ejemplo:

{
  "name": "projects/PROJECT/subscriptions/SUBSCRIPTION_NAME",
  "topic": "TOPIC_NAME",
  "pushConfig": {
    "pushEndpoint": "PUSH_NOTIFICATION_ENDPOINT"
    },
  "ackDeadlineSeconds": 10
}

Formatos de notificaciones

El siguiente es un ejemplo de notificación de Pub/Sub. Los datos del mensaje se transmiten como una cadena JSON codificada en base64.

{
  "message": {
    "attributes": {},
    "data": "eyJza3VfaWQiOiAiR29vZ2xlLUFwcHMtVW5saW1pdGVkIiwgImV2ZW50X3R5cGUiOiAiU1VCU0NSSVBUSU9OX0NBTkNFTExFRCIsICJjdXN0b21lcl9kb21haW5fbmFtZSI6ICJkb21haW4uY29tIiwgInN1YnNjcmlwdGlvbl9pZCI6ICIxMjM0NTY3IiwgImN1c3RvbWVyX2lkIjogIkMwYWJjZGVmIiwgIm1lc3NhZ2VfaWQiOiAiODY3NTMwOSIsICJwdWJsaXNoX3RpbWUiOiB7InNlY29uZHMiOiAxNDU3NzMxODQ2LCAibmFub3MiOiAzNDkwMDAwMDB9LCAicmVzZWxsZXJfY3VzdG9tZXJfaWQiOiAiQzByZXNlbGxlciJ9",
    "message_id": 1234567891012131
  },
  "subscription": "projects/PROJECT/subscriptions/SUBSCRIPTION_NAME"
}

El siguiente es 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 cambió de un plan flexible a uno anual. Este evento no se activa si el cliente cambia de un plan de tipo de compromiso a un plan flexible como parte de una renovación.
• COMMITMENT_CHANGED: Se aumentó o disminuyó el compromiso anual.
• SUBSCRIPTION_RENEWED: Se renovó una suscripción anual.
• SUBSCRIPTION_SUSPENDED: La suscripción está suspendida. 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 para este evento:

  • Convierte la suscripción directa en una suscripción de distribuidor.
  • Convierte la suscripción pagada en una oferta de gracia.
  • Convierte la suscripción en línea en una sin conexión.

• SUBSCRIPTION_UPGRADE: Se actualizó el SKU de la suscripción. Por ejemplo, la suscripción se actualizó de Google Workspace Business Starter a Business Standard.

• SUBSCRIPTION_DOWNGRADE: Se cambió a una versión inferior del SKU de la suscripción. Por ejemplo, la suscripción se cambió de Google Workspace Business Standard a Business Starter.

• LICENSE_ASSIGNMENT_CHANGED: Se asignó una licencia a un usuario o se le revocó una. Puedes usar este evento para hacer un seguimiento reactivo de los cambios en la cantidad de asientos de las suscripciones flexibles.

Motivos de cancelación de la suscripción

El motivo de cancelación de la suscripción se completa cuando el event_type es SUBSCRIPTION_CANCELLED. Estos son algunos de los posibles motivos de cancelación:

• TRANSFERRED_OUT: El cliente se transfirió a la facturación directa o a otro distribuidor.
• PURCHASE_OF_SUBSUMING_SKU: El cliente actualizó a un SKU que anula otro. Por ejemplo, si un cliente con Google Workspace Business Starter y Google Vault actualiza a Google Workspace Business Plus, la suscripción a Vault se incluye porque se incluye en Google Workspace Business Plus.
• RESELLER_INITIATED: El revendedor canceló la suscripción.
• OTHER: La suscripción se canceló por un motivo que no se incluye en la lista.

Motivos de suspensión de la suscripción

El motivo de la suspensión de la suscripción se completa cuando event_type es SUBSCRIPTION_SUSPENDED. Estos son algunos de los posibles motivos de suspensión:

• PENDING_TOS_ACCEPTANCE: El cliente no accedió ni aceptó las Condiciones del Servicio de Google Workspace para revendedores.
• RENEWAL_WITH_TYPE_CANCEL: El compromiso del cliente finalizó y su servicio se canceló al final del período.
• RESELLER_INITIATED: El distribuidor suspendió la suscripción de forma manual.
• TRIAL_ENDED: La prueba del cliente venció y no seleccionó un plan sin prueba.
• OTHER: El cliente se suspendió por un motivo interno de Google, por ejemplo, abuso.

Limitaciones de Pub/Sub

No se garantiza el orden de las notificaciones push. Es posible que los mensajes se entreguen varias veces y, en situaciones extremas, no se entreguen en absoluto. Te recomendamos que uses reseller.subscriptions.get en todas las suscripciones modificadas para extraer el estado actual.