Эта страница переведена с помощью Cloud Translation API.

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

Обзор

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

Предварительные условия

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

Создать тему

Чтобы создать тему, вам необходимо зарегистрироваться в Reseller 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 вам необходимо настроить, как ваше приложение будет использовать ваши события изменений. Выберите один из следующих вариантов:

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