このページは Cloud Translation 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 に登録する必要があります。resellernotify.register メソッドは、サービスアカウントのメールアドレスをパラメータとして受け取ります。この方法で承認されたサービスアカウントのみが、新しく作成されたトピックをサブスクライブできます。

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: プッシュ通知ハンドラの 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 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 をオーバーライドする SKU にアップグレードしました。たとえば、Google Workspace Business Starter と Google Vault をご利用のお客様が Google Workspace Business Plus にアップグレードした場合、Google Workspace Business Plus に Vault が含まれているため、Vault サブスクリプションは統合されます。
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 を使用して現在の状態を取得することをおすすめします。