管理 SaaS 产品的客户权限

当客户选择您的软件的某个定价方案时，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。

您必须确保前端集成可以处理 JWT 载荷中包含的新 orders 对象。如需了解详情，请参阅 集成应用的前端。

如需详细了解如何开启同一产品的多个订单，请参阅 开启同一产品的多个订单。

批准权益

当客户选择定价方案时，Cloud Marketplace 会创建权益，并将以下 Pub/Sub 消息发送到您的应用：

{
  "eventId": "...",
  "eventType": "ENTITLEMENT_CREATION_REQUESTED",
  "providerId": "YOUR_PARTNER_ID",
  "entitlement": {
    "id": "ENTITLEMENT_ID",
    "updateTime": "...",
    "newPendingOfferDuration": "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",
    "newPendingPlan": "ultimate",   // New plan
    "updateTime": "...",
    "newPendingOfferDuration": "P2Y3M",   // Contract duration for the new offer, for offer-based entitlements
    "newProduct": "test-product.cloud.goog"
    "newPendingOffer": "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": "...",
  },
}

权益状态转换

下表显示了权益如何根据不同的事件在状态之间转换。

当前状态 触发事件 新状态 备注
（无） ENTITLEMENT_CREATION_REQUESTED ENTITLEMENT_ACTIVATION_REQUESTED 客户选择方案。
ENTITLEMENT_ACTIVATION_REQUESTED 提供方批准使用权 ENTITLEMENT_ACTIVE 权益变为有效状态。
ENTITLEMENT_ACTIVATION_REQUESTED 提供方拒绝使用权 ENTITLEMENT_CANCELLED 系统不会创建权益。
ENTITLEMENT_ACTIVE ENTITLEMENT_PLAN_CHANGE_REQUESTED ENTITLEMENT_PENDING_PLAN_CHANGE_APPROVAL 或 ENTITLEMENT_PENDING_PLAN_CHANGE 客户请求更改方案。
ENTITLEMENT_ACTIVE ENTITLEMENT_CANCELLING ENTITLEMENT_PENDING_CANCELLATION 客户取消了方案，取消操作将在期限结束时生效。
ENTITLEMENT_ACTIVE ENTITLEMENT_CANCELLED ENTITLEMENT_CANCELLED 客户立即取消了方案。
ENTITLEMENT_PENDING_PLAN_CHANGE_APPROVAL 提供方批准方案更改 ENTITLEMENT_PENDING_PLAN_CHANGE 或 ENTITLEMENT_ACTIVE 如果当前方案要求结算周期完成，则会进入待处理状态。否则，它会变为有效状态。
ENTITLEMENT_PENDING_PLAN_CHANGE_APPROVAL 提供方拒绝方案更改 ENTITLEMENT_ACTIVE 权益恢复为旧方案。
ENTITLEMENT_PENDING_PLAN_CHANGE ENTITLEMENT_PLAN_CHANGED ENTITLEMENT_ACTIVE 结算周期完成，新方案生效。
ENTITLEMENT_PENDING_PLAN_CHANGE ENTITLEMENT_OFFER_ENDED，然后是 ENTITLEMENT_PLAN_CHANGED ENTITLEMENT_PENDING_CANCELLATION 客户接受了非公开优惠，导致方案发生更改，并且转换生效。
ENTITLEMENT_PENDING_CANCELLATION ENTITLEMENT_CANCELLED ENTITLEMENT_CANCELLED 结算周期完成，权益已完全取消。
ENTITLEMENT_PENDING_CANCELLATION ENTITLEMENT_CANCELLATION_REVERTED ENTITLEMENT_ACTIVE 客户还原了待处理的取消操作。

账号任务的事件类型列表

以下是您的应用可能在 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_PLAN_CHANGE_REQUESTED 和 ENTITLEMENT_OFFER_ENDED 事件后，当收到 ENTITLEMENT_PLAN_CHANGED 事件时，权益处于此状态。
ENTITLEMENT_CANCELLATION_REVERTED表示客户的处于待处理状态的取消操作已还原。请注意，取消操作在结束之后不可还原。
ENTITLEMENT_CANCELLED表示客户计划已取消。
ENTITLEMENT_CANCELLING表示客户的方案正在被取消。
ENTITLEMENT_RENEWED表示客户的授权续订了又一个期限。 您无需执行任何操作来完成续订。
ENTITLEMENT_OFFER_ENDED表示面向客户的非公开优惠已结束。如果客户的授权已取消，则会另行触发一个 ENTITLEMENT_CANCELLED 事件。如果客户的授权仍然有效，他们的方案将恢复为无折扣价。
ENTITLEMENT_DELETED表示有关客户方案的信息已从 Cloud Marketplace 中删除。
上一页
管理用户账号