当客户选择您的软件的某个价格方案时,Google 会创建一项权益,表明客户已从 Cloud Marketplace 购买了您的产品。本部分将介绍如何使用 Partner Procurement API 为您的客户创建和管理权益。
如需详细了解如何管理权益,请参阅参考文档。
准备工作
- 按照说明设置对 Cloud Commerce Partner Procurement API 的访问权限 集成您的应用。
如果您为同一商品启用了多笔订单,Partner Procurement API 可以针对相同的 ACCOUNT_ID
值发送多个事件(事件类型为 ENTITLEMENT_ACTIVE
),每个事件都有一个代表不同商品的唯一 ENTITLEMENT_ID
。也就是说,您必须
确保应用的事件处理逻辑可以响应 ENTITLEMENT_ID
而不是 ACCOUNT_ID
或 PRODUCT_ID
。
您必须确保前端集成可以处理新的 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 }, }
如果优惠有指定的有效期,则该有效期以年和月为单位。如果优惠有指定的结束日期,而不是时长,则此字段 表示时长为空。
要批准方案更改,请向 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 | 表示客户选择了您的一个定价方案。 |
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 中删除。 |