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

Обзор

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 : Была обновлена ​​версия подписки (SKU). Например, подписка была обновлена ​​с 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 для всех измененных подписок, чтобы получить текущее состояние.