顧客がソフトウェアの料金プランを選択すると、顧客が 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 のリストです。
| eventType | 説明 |
|---|---|
| ACCOUNT_CREATION_REQUESTED | 非推奨 |
| ACCOUNT_ACTIVE | 顧客のアカウントが作成されたことを示します。 |
| ACCOUNT_DELETED | 顧客のアカウントが Google Cloud システムから削除されたことを示します。 |
| ENTITLEMENT_CREATION_REQUESTED | 顧客が料金プランの 1 つを選択したことを示します。 |
| ENTITLEMENT_OFFER_ACCEPTED | お客様がオファーを承諾したことを示します。オファーのスケジュール設定された開始時刻（存在する場合）が含まれます。 このイベントは、プライベート オファーとスタンダード オファー（一般公開の購入）の両方で送信されます。 |
| ENTITLEMENT_ACTIVE | 顧客が選択したプランが現在アクティブであることを示します。 |
| ENTITLEMENT_PLAN_CHANGE_REQUESTED | 顧客が新しいプランを選択したことを示します。 |
| ENTITLEMENT_PLAN_CHANGED | 顧客のプラン変更が承認され、変更が有効になったことを示します。 |
| ENTITLEMENT_PLAN_CHANGE_CANCELLED | 顧客のプラン変更が承認されなかったか、顧客が以前のプランに切り替えたために、キャンセルされたことを示します。 |
| ENTITLEMENT_PENDING_CANCELLATION | 顧客がプランをキャンセルし、キャンセルは請求期間の終了まで保留されていることを示します。 |
| ENTITLEMENT_CANCELLATION_REVERTED | 顧客の保留中のキャンセルが元に戻されたことを示します。キャンセルは確定後は元に戻せません。 |
| ENTITLEMENT_CANCELLED | 顧客のプランがキャンセルされたことを示します。 |
| ENTITLEMENT_CANCELLING | 顧客のプランがキャンセルの処理中であることを示します。 |
| ENTITLEMENT_RENEWED | 顧客のエンタイトルメントの期間が更新されたことを示します。更新を完了するための操作はありません。 |
| ENTITLEMENT_OFFER_ENDED | 顧客のプライベート オファーが終了したことを示します。顧客のエンタイトルメントがキャンセルされている場合は、別の ENTITLEMENT_CANCELLED イベントがトリガーされます。顧客のエンタイトルメントがまだ有効な場合、顧客のプランは割引前の料金に戻ります。 |
| ENTITLEMENT_DELETED | 顧客のプランに関する情報が Cloud Marketplace から削除されたことを示します。 |