プッシュ通知

概要

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 トピックを作成したら、アプリケーションによる変更イベントの使用方法を設定する必要があります。次のいずれかのオプションを選択します。

  • push サブスクリプション: 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 を使用して、現在の状態を pull することをおすすめします。