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 alertas cuando cambien los estados 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 de roles/pubsub.editor es una buena opción intermedia (fácil y no demasiado amplia), pero es posible que desees usar 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 la 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 que acabas de crear.

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

Una respuesta correcta devuelve 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 a usar tu tema, puedes volver a llamar a resellernotify.register.

Cómo revocar el acceso de una cuenta de servicio

La API para revendedores 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]"
}

Cómo suscribirse a un tema

Después de crear el tema de Pub/Sub, debes configurar la forma en que tu aplicación consumirá los eventos de cambio. Elige una de las siguientes opciones:

• Suscripción de envío: Proporcionas una devolución de llamada POST HTTP. Pub/Sub usa esta devolución de llamada para notificar a tu aplicación sobre los eventos nuevos.
• Suscripción de extracción: Tu aplicación realiza periódicamente una llamada HTTP para obtener todos los cambios en cola.

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.

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 tu suscripción.
• TOPIC_NAME: Es el tema de Pub/Sub que creaste anteriormente.
• 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 un ejemplo de respuesta:

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

Formatos de notificación

A continuación, se muestra un ejemplo de una 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"
}

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 cambió de un plan flexible a un plan anual. Este evento no se activa si el cliente cambia de un plan de tipo 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 que se había suspendido 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 una suscripción directa en una suscripción de revendedor.
  • Cambia la suscripción pagada a una oferta de período de gracia.
  • Convertir una suscripción en línea en una suscripción sin conexión

• SUBSCRIPTION_UPGRADE: Se actualizó el SKU de la suscripción. Por ejemplo, se actualizó la suscripción 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, se degradó la suscripción de Google Workspace Business Standard a Business Starter.

• LICENSE_ASSIGNMENT_CHANGED: Se asignó o revocó una licencia a un usuario. Puedes usar este evento para hacer un seguimiento reactivo de los cambios en el recuento 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 event_type es SUBSCRIPTION_CANCELLED. A continuación, se indican los posibles motivos de cancelación:

• TRANSFERRED_OUT: El cliente se transfirió a la facturación directa o a otro revendedor.
• 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 su suscripción a Google Workspace Business Plus, la suscripción a Vault se subsume porque se incluye con Google Workspace Business Plus.
• RESELLER_INITIATED: El revendedor canceló la suscripción.
• OTHER: La suscripción se canceló por algún motivo que no se encuentra 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ó y aceptó las Condiciones del Servicio de Google Workspace revendido.
• RENEWAL_WITH_TYPE_CANCEL: Finalizó el compromiso del cliente y se canceló el servicio al final del período.
• RESELLER_INITIATED: El revendedor suspendió manualmente la suscripción.
• TRIAL_ENDED: La prueba del cliente venció y este no seleccionó un plan que no sea de prueba.
• OTHER: Se suspendió al cliente 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, que no se entreguen. Te recomendamos que uses reseller.subscriptions.get en todas las suscripciones modificadas para extraer el estado actual.