此页面由 Cloud Translation API 翻译。

管理 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。

您必须确保前端集成可以处理新的 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 中删除。

管理 SaaS 产品的用户账号

报告用量的最佳做法