Всплывающее уведомление

Обзор

API реселлеров использует API Pub/Sub для отправки push-уведомлений о различных событиях подписки Google Workspace. Например, вы можете настроить push-уведомления, чтобы получать уведомления об изменении статуса подписки ваших клиентов.

Предпосылки

  • Включите API Pub/Sub для вашего проекта Google Cloud.
  • Предоставьте IAM-роли Pub/Sub вашей учетной записи сервиса в вашем облачном проекте. Предоставление роли roles/pubsub.editor — хороший компромисс (простой и не слишком широкий), но вам может потребоваться использовать более конкретные разрешения Pub/Sub .

Создать тему

Чтобы создать тему, необходимо зарегистрироваться в API реселлера с помощью метода resellernotify.register . Метод resellernotify.register принимает в качестве параметра адрес электронной почты учётной записи сервиса. Подписаться на созданную вами тему могут только учётные записи сервисов, авторизованные этим методом.

POST https://reseller.googleapis.com/apps/reseller/v1/resellernotify/register
{
  "serviceAccountEmailAddress": "reseller@reseller-project.iam.gserviceaccount.com"
}

Успешный ответ возвращает код статуса HTTP 200 и ответ JSON, содержащий название вашей темы Pub/Sub.

Ниже приведен пример ответа:

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

Чтобы разрешить дополнительным учетным записям служб использовать вашу тему, вы можете повторно вызвать resellernotify.register .

Отозвать доступ к учетной записи службы

API реселлера также предоставляет возможность отменять регистрацию учетных записей служб с помощью конечной точки resellernotify.unregister :

POST https://reseller.googleapis.com/apps/reseller/v1/resellernotify/unregister
{
  "serviceAccountEmailAddress": "reseller@reseller-project.iam.gserviceaccount.com"
}

Подписаться на тему

После создания темы Pub/Sub необходимо настроить, как ваше приложение будет обрабатывать события изменений. Выберите один из следующих вариантов:

  • Push-подписка : вы предоставляете обратный вызов HTTP POST . Pub/Sub использует этот обратный вызов для уведомления вашего приложения о новых событиях.
  • Подписка по запросу : ваше приложение периодически выполняет HTTP-вызов, чтобы получить все изменения, поставленные в очередь.

Ниже приведен пример запроса на подписку на тему:

PUT https://pubsub.googleapis.com/v1/projects/PROJECT/subscriptions/SUBSCRIPTION_NAME
{
  "topic": "TOPIC_NAME"
  // Only needed for push configurations
  "pushConfig": {
    "pushEndpoint": "PUSH_NOTIFICATION_ENDPOINT"
  },
}

Заменить следующее:

  • PROJECT : Ваш проект Google Cloud.
  • SUBSCRIPTION_NAME : Идентификационное имя вашей подписки.
  • TOPIC_NAME : Тема Pub/Sub, которую вы создали ранее.
  • PUSH_NOTIFICATION_ENDPOINT : Конечная точка обработчика push-уведомлений.

Успешный ответ возвращает код статуса HTTP 200 Ниже приведён пример ответа:

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

Форматы уведомлений

Ниже приведён пример уведомления Pub/Sub. Данные сообщения передаются в виде строки JSON в кодировке Base64.

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

Ниже приведен пример объекта message.data после декодирования:

{
  "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"
}

Типы событий

Следующий список содержит все возможные типы событий:

  • NEW_SUBSCRIPTION_CREATED : Создана новая подписка.
  • SUBSCRIPTION_TRIAL_ENDED : Пробный период подписки завершен.
  • PRICE_PLAN_SWITCHED : Клиент перешёл с гибкого плана на годовой. Это событие не активируется, если клиент перешёл с плана с обязательствами на гибкий в рамках продления подписки.
  • COMMITMENT_CHANGED : Годовое обязательство было увеличено или уменьшено.
  • SUBSCRIPTION_RENEWED : Годовая подписка была возобновлена.
  • SUBSCRIPTION_SUSPENDED : Подписка приостановлена. См. поле subscription_suspension_reasons .
  • SUBSCRIPTION_SUSPENSION_REVOKED : Приостановка была отменена для ранее приостановленной подписки.
  • SUBSCRIPTION_CANCELLED : Подписка отменена. См. поле subscription_cancellation_reason . Также может использоваться для обнаружения переносов.

  • SUBSCRIPTION_CONVERTED : Подписка была преобразована. Вот несколько примеров этого события:

    • Преобразовать прямую подписку в подписку реселлера.
    • Конвертируйте платную подписку в льготное предложение.
    • Конвертируйте онлайн-подписку в офлайн-подписку.

  • SUBSCRIPTION_UPGRADE : Номер подписки был обновлен. Например, подписка была обновлена с Google Workspace Business Starter до Business Standard.

  • SUBSCRIPTION_DOWNGRADE : Номер подписки был понижен. Например, подписка была понижена с Google Workspace Business Standard до Business Starter.

  • LICENSE_ASSIGNMENT_CHANGED : Лицензия назначена пользователю или отозвана у него. Это событие можно использовать для отслеживания изменений количества рабочих мест для гибких подписок.

Причины отмены подписки

Причина отмены подписки заполняется, когда event_type — SUBSCRIPTION_CANCELLED . Возможные причины отмены:

  • TRANSFERRED_OUT : Клиент перешел на прямой биллинг или к другому реселлеру.
  • PURCHASE_OF_SUBSUMING_SKU : Клиент перешёл на SKU, который переопределяет другой. Например, если клиент с Google Workspace Business Starter и Google Vault переходит на Google Workspace Business Plus, подписка на Vault поглощается, поскольку она входит в Google Workspace Business Plus.
  • RESELLER_INITIATED : Реселлер отменил подписку.
  • OTHER : Подписка была отменена по какой-то причине, не указанной в списке.

Причины приостановки подписки

Причина приостановки подписки заполняется, когда event_type — SUBSCRIPTION_SUSPENDED . Возможные причины приостановки:

  • PENDING_TOS_ACCEPTANCE : Клиент не вошел в систему и не принял Условия предоставления услуг Google Workspace Resold.
  • RENEWAL_WITH_TYPE_CANCEL : Обязательства клиента закончились, и его обслуживание было отменено по окончании срока действия.
  • RESELLER_INITIATED : Реселлер вручную приостановил подписку.
  • TRIAL_ENDED : Срок действия пробной версии клиента истек, и клиент не выбрал план без пробной версии.
  • OTHER : Клиент заблокирован по внутренней причине Google, например, из-за злоупотребления.

Ограничения публикации/подписки

Порядок push-уведомлений не гарантируется. Сообщения могут быть доставлены несколько раз, а в крайних случаях — не доставлены вовсе. Мы рекомендуем использовать reseller.subscriptions.get для всех изменённых подписок, чтобы получить информацию о текущем состоянии.