このページは 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: プッシュ通知ハンドラのエンドポイント。

成功すると、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 にアップグレードした場合、Vault サブスクリプションは Google Workspace 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 を使用して現在の状態を取得することをおすすめします。