管理 SaaS 产品的客户权限

当客户选择您的软件的某个价格方案时,Google 会创建一项权益,表明客户已从 Cloud Marketplace 购买了您的产品。本部分将介绍如何使用 Partner Procurement API 为您的客户创建和管理权益。

如需详细了解如何管理权益,请参阅参考文档

准备工作

  • 按照说明设置对 Cloud Commerce Partner Procurement API 的访问权限 集成您的应用

如果您为同一商品启用了多笔订单,Partner Procurement API 可以针对相同的 ACCOUNT_ID 值发送多个事件(事件类型为 ENTITLEMENT_ACTIVE),每个事件都有一个代表不同商品的唯一 ENTITLEMENT_ID。也就是说,您必须 确保应用的事件处理逻辑可以响应 ENTITLEMENT_ID 而不是 ACCOUNT_IDPRODUCT_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 中删除。