SaaS プロダクトのお客様のエンタイトルメントを管理する

顧客がソフトウェアの料金プランを選択すると、顧客が Cloud Marketplace からプロダクトを購入したことを示すエンタイトルメントが作成されます。このセクションでは、Partner Procurement API を使用して顧客のエンタイトルメントを作成し、管理する方法について再確認します。

利用資格の管理の詳細については、リファレンス ドキュメントをご覧ください。

始める前に

• アプリを統合するの説明に従って、Cloud Commerce Partner Procurement API へのアクセスを設定します。

同じプロダクトの複数の注文を有効にしている場合、Partner Procurement API では、同じ ACCOUNT_ID の値に対して ENTITLEMENT_ACTIVE イベントタイプの複数のイベントを送信できます。各イベントには、異なるオファーを表す一意の ENTITLEMENT_ID が設定されています。つまり、アプリのイベント処理ロジックが ACCOUNT_ID や PRODUCT_ID ではなく ENTITLEMENT_ID に応答できるようにする必要があります。

フロントエンドの統合で、JWT ペイロードに含まれる新しい orders オブジェクトを処理できることを確認する必要があります。詳細については、アプリのフロントエンドの統合をご覧ください。

同じプロダクトの複数の注文を有効にする場合について詳しくは、同じプロダクトの複数の注文を有効にするをご覧ください。

エンタイトルメントを承認する

顧客が料金プランを選択すると、Cloud Marketplace によってエンタイトルメントが作成され、アプリに次の Pub/Sub メッセージが送信されます。

{
  "eventId": "...",
  "eventType": "ENTITLEMENT_CREATION_REQUESTED",
  "providerId": "YOUR_PARTNER_ID",
  "entitlement": {
    "id": "ENTITLEMENT_ID",
    "updateTime": "...",
    "newOfferDuration": "P2Y3M",   // Contract duration for offer-based entitlements
  },
}

ENTITLEMENT_ID は、Cloud Marketplace によって作成された ID です。 オファーに指定された期間がある場合、その期間は年と月で指定されます。オファーに期間ではなく終了日が指定されている場合、期間を示すフィールドは空になります。

システムでは、ユーザーがプランを購入したことを反映するためにユーザーのアカウントを更新します。次に、エンタイトルメントを承認するために、Partner Procurement API に対して HTTP POST リクエストを発行し、承認する ENTITLEMENT_ID を送信します。

POST v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID:approve

エンタイトルメントを拒否する

エンタイトルメントを拒否するには、Partner Procurement API に対して HTTP POST リクエストを発行し、リクエストで reject メソッドを使用します。

POST v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID:reject

リクエスト本文でエンタイトルメントの拒否理由を指定するには、次の形式を使用します。

{
  "reason": "..."
}

エンタイトルメント プランを変更する

料金プランの設定方法によっては、顧客がプランを変更できる場合があります。顧客が新しい料金プランを選択すると、次の形式の Pub/Sub メッセージが届きます。

{
  "eventId": "...",
  "eventType": "ENTITLEMENT_PLAN_CHANGE_REQUESTED",
  "providerId": "YOUR_PARTNER_ID",
  "entitlement": {
    "id": "ENTITLEMENT_ID",
    "newPlan": "ultimate",   // New plan
    "updateTime": "...",
    "newOfferDuration": "P2Y3M",   // Contract duration for the new offer, for offer-based entitlements
    "newProduct": "test-product.cloud.goog"
    "newOffer": "projects/1234567/services/test-product.cloud.goog/standardOffers/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
  },
}

オファーに指定された期間がある場合、その期間は年と月で指定されます。オファーに期間ではなく終了日が指定されている場合、期間を示すフィールドは空になります。

プランの変更を承認するには、Partner Procurement API に次の HTTP POST リクエストを行います。

POST v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID:approvePlanChange

リクエストの本文には、承認されるプランが必要です。

{
  "pendingPlanName": PLAN_NAME
}

変更が承認されると、変更が有効になったときに別の Pub/Sub メッセージが届きます。メッセージの eventType フィールドが ENTITLEMENT_PLAN_CHANGED に変わります。プランのステータスを確認するには、Partner Procurement API に次の HTTP GET リクエストを行います。

GET v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID

レスポンスは次と似たようになります。state フィールドには、新しいプランが有効かどうか、プランの変更がまだ保留中であるかどうかが示されます。

{
  "name": "providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID",
  "provider": "YOUR_PARTNER_ID",
  "account": "USER_ACCOUNT_ID",
  "product": "example-server",
  "plan": "pro",
  "state": "ENTITLEMENT_PENDING_PLAN_CHANGE",
  "newPendingPlan": "ultimate",
  ...
}

エンタイトルメントをキャンセルする

ユーザーがエンタイトルメントをキャンセルすることにした場合、Pub/Sub 通知が届きます。プランを変更する場合と同様に、実際のキャンセルは現在の請求期間の終了時に有効になる場合があります。

通知の形式は次のとおりです。

{
  "eventId": "...",
  // If the entitlement is canceled at the end of the month,
  // eventType is ENTITLEMENT_PENDING_CANCELLATION
  "eventType": "ENTITLEMENT_CANCELLED",
  "providerId": "YOUR_PARTNER_ID",
  "entitlement": {
    "id": "ENTITLEMENT_ID",
    "updateTime": "..."
  },
}

エンタイトルメントを削除する

ユーザーが Google サポートに直接リクエストを行った場合や、Google プラットフォームから離脱した場合は、エンタイトルメントは直ちにキャンセルされ、60 日間の猶予期間の後にエンタイトルメントとアカウントが削除されます。ユーザーのプライバシーを保護するには、通知を受け取ったときにサーバーからデータを削除する必要があります。

エンタイトルメントがキャンセルされ、アカウントが削除されると、次のような通知が届きます。

{
  "eventId": "...",
  "eventType": "ENTITLEMENT_DELETED",
  "providerId": "YOUR_PARTNER_ID",
  "entitlement": {
    "id": "ENTITLEMENT_ID",
    "updateTime": "...",
  },
}

{
  "eventId": "...",
  "eventType": "ACCOUNT_DELETED",
  "providerId": "YOUR_PARTNER_ID",
  "account": {
    "id": "USER_ACCOUNT_ID",
    "updateTime": "...",
  },
}

アカウント タスクのイベントタイプのリスト

以下は、アプリが Pub/Sub メッセージで受信する可能性がある eventType のリストです。