プッシュ通知

このページでは、Reseller API でプッシュ通知を使用する方法について説明します。

概要

Reseller API は Pub/Sub API を使用して、Google Workspace サブスクリプションイベントに関するプッシュ通知を配信します。たとえば、お客様のサブスクリプションステータスが変更されたときに通知されるようにプッシュ通知を設定できます。

前提条件

Google Cloud プロジェクトで Pub/Sub API を有効にします。
Cloud プロジェクトのサービスアカウントに Pub/Sub IAM ロールを付与します。roles/pubsub.editor ロールを付与することをおすすめしますが、より具体的な Pub/Sub 権限を使用することもできます。

トピックの作成

トピックを作成するには、 resellernotify.register メソッドを使用して Reseller API に登録します。このメソッドは、サービスアカウントのメールアドレスをパラメータとして受け取ります。このメソッドで承認されたサービスアカウントのみがトピックをサブスクライブできます。

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

成功したレスポンスは、HTTP 200 ステータスコードと、Pub/Sub トピック名を含む JSON レスポンスを返します。

レスポンスの例:

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

他のサービスアカウントを承認するには、resellernotify.register を再度呼び出します。

サービスアカウントのアクセス権を取り消す

Reseller 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 はこのコールバックを使用して、新しいイベントをアプリケーションに通知します。
pull サブスクリプション: アプリケーションは定期的に 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: プッシュ通知ハンドラのエンドポイント。

成功したレスポンスは、HTTP 200 ステータスコードを返します。レスポンスの例:

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

通知形式

次に、Pub/Sub 通知の例を示します。メッセージデータは、Base64 エンコードされた JSON 文字列です。

{
  "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 dependent 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 をオーバーライドする SKU にアップグレードしました。例: Google Workspace Business Starter と Vault をご利用のお客様が、Vault を含む Business Plus にアップグレードした場合。
RESELLER_INITIATED: 販売パートナーがサブスクリプションを解約しました。
OTHER: サブスクリプションが別の理由で解約されました。

サブスクリプションの停止理由

停止理由は、event_type が SUBSCRIPTION_SUSPENDED の場合に設定されます。次のような原因が考えられます。

PENDING_TOS_ACCEPTANCE: お客様が Google Workspace 販売パートナー向け利用規約に同意していません。
RENEWAL_WITH_TYPE_CANCEL: お客様の契約が終了し、サービスが解約されました。
RESELLER_INITIATED: 販売パートナーがサブスクリプションを手動で停止しました。
TRIAL_ENDED: お客様が試用版以外のプランを選択せずに試用期間が終了しました。
OTHER: お客様が不正使用などの Google 内部の理由で停止されています。

Pub/Sub の制限事項

プッシュ通知の順序は必ずしも連続していません。メッセージが複数回配信される場合や、まったく配信されない場合があります。変更されたサブスクリプションで reseller.subscriptions.get を使用して、現在の状態を取得することをおすすめします。