集成应用的后端

本部分介绍了使用 Google Cloud Marketplace 集成应用后端的步骤。通过此集成,您可以管理用户的帐号和权益,这表明用户已从 Google Cloud Marketplace 购买了您的产品。如果您选择了基于用量的价格模式,则还会集成后端以向 Google 报告使用情况。

如需了解有关将基本应用与 Google Cloud Marketplace 集成的示例以及示例代码演示,请参阅代码实验室来集成托管式服务

如需代码实验室中使用的示例代码,请参阅 GitHub 代码库

准备工作

  • 设置对 Cloud Commerce Partner Procurement API 的访问权限,如集成您的应用:设置中所述。
  • 如果您选择了基于用量的价格方案,请验证您的合作伙伴工程师是否已创建您可以据以报告使用情况的服务。

用户帐号任务

概括来讲,您的应用必须应对以下情景:

  1. 用户在 Google Cloud Marketplace 中发出请求或进行更改,例如注册您的解决方案。

  2. Google Cloud Marketplace 通过 Pub/Sub 向您的应用发送通知,其中的 eventType 中包含有关请求的信息。例如,如果用户更改其权益,则 eventTypeENTITLEMENT_PLAN_CHANGE

    请参阅可用的 eventType 的完整列表。

  3. 为了批准该请求,您的应用会向 Partner Procurement API 发送一个 HTTP POST 请求。

以下部分介绍了用户可以发出的请求类型,以及应用为处理请求而必须执行的操作。

对于本部分中介绍的 API 调用,请使用此端点:

https://cloudcommerceprocurement.googleapis.com/

为新用户创建帐号

用户首次购买您的解决方案时,Google Cloud Marketplace 会创建一个帐号资源来跟踪用户与您的关系。创建帐号资源后,您将通过系统为您创建的 Pub/Sub 主题获得通知。Pub/Sub 消息格式如下:

{
  "eventId": "...",
  "account": {
    "id": "USER_ACCOUNT_ID",
    "updateTime": "..."
  }
}

其中 USER_ACCOUNT_ID 是由 Google Cloud Marketplace 创建的帐号 ID。

同时,用户会被定向到您的注册页面,并通过该页面在您的系统中创建帐号。如需了解如何创建注册页面,请参阅集成应用的前端

在用户成功注册后,您的应用必须调用 Procurement API 并指明该帐号已获得批准。帐号在创建时处于 ACCOUNT_ACTIVE 状态,但是它们在 approvals 字段中有一个名为 signupPENDING 条目,表示用户尚未注册。要在用户注册后批准该帐号,请使用以下 HTTP POST 请求:

POST v1/providers/YOUR_PARTNER_ID/accounts/USER_ACCOUNT_ID:approve {'approvalName': 'signup'}

其中 YOUR_PARTNER_ID 是合作伙伴工程师向您授予对 Partner Procurement API 的访问权限时分配给您的 ID。

要检查关联帐号的状态,请使用以下 HTTP GET 请求:

GET v1/providers/YOUR_PARTNER_ID/accounts/USER_ACCOUNT_ID

响应的格式如下:

{
  "name": "providers/YOUR_PARTNER_ID/accounts/USER_ACCOUNT_ID",
  "provider": "acme-services",
  "state": "ACCOUNT_ACTIVE",
  "approvals": [{
    "name": "signup",
    "state": "APPROVED",
    "updateTime": "...",
  }],
  "updateTime": "...",
  "createTime": "..."
}

有关可用帐号状态的列表,请参阅 providers.accounts API 参考

创建权益

当客户选择您的软件的某个价格方案时,Google 会创建一项权益,表明客户已从 Google Cloud Marketplace 购买了您的解决方案。

当客户选择方案时,系统会向您的应用发送以下 Pub/Sub 消息:

{
  "eventId": "...",
  "eventType": "ENTITLEMENT_CREATION_REQUESTED",
  "entitlement": {
    "id": "ENTITLEMENT_ID",
    "updateTime": "...",
  },
}

其中 ENTITLEMENT_ID 是由 Google Cloud Marketplace 创建的 ID。

在您的系统中,更新用户的帐号以反映他们购买了方案。然后,要批准权利,请向 Partner Procurement API 发出 HTTP POST 请求,并发送您要批准的 ENTITLEMENT_ID

POST v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID:approve

更改权益方案

根据您设置的价格方案,客户可能可以更改其方案。如果客户选择新的价格方案,您将收到以下格式的 Pub/Sub 消息:

{
  "eventId": "...",
  "eventType": "ENTITLEMENT_PLAN_CHANGE_REQUESTED",
  "entitlement": {
    "id": "ENTITLEMENT_ID",
    "newPlan": "ultimate",   // New plan
    "updateTime": "...",
  },
}

要批准方案更改,请向 Partner 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",
  ...
}

向用户发送状态消息

如果用户选择价格方案与您的后端批准权益之间相差几个小时或更长时间,建议您向用户提供状态消息。在此消息中,指明批准的进度,以及指明预计完成批准的时间(如果可行)。

要提供状态消息,请向 Procurement API 发出以下 HTTP POST 请求:

POST v1/providers/your-partner-id/entitlements/entitlement_id:updateUserMessage

在请求正文中,提供消息的文本,类似于以下示例:

{
  "message": "Approval expected in 2 days"
}

取消权益

如果用户决定取消其权益,您将收到一条 Pub/Sub 通知。与更改方案类似,实际取消可能会在当前结算周期结束时生效。

通知格式如下:

{
  "eventId": "...",
  // If the entitlement is cancelled at the end of the month,
  // eventType is ENTITLEMENT_PENDING_CANCELLATION
  "eventType": "ENTITLEMENT_CANCELLED",
  "entitlement": {
    "id": "ENTITLEMENT_ID",
    "cancellationDate": "...",
    "updateTime": "..."
  },
}

删除权益

如果用户发出直接请求,或者离开 Google 平台,则用户的权益会被取消并删除,并且其帐号也会被删除。 为了保护用户的隐私,您必须在收到通知后从服务器中删除用户的数据。

在用户权益被取消以及用户帐号被删除后,您会收到类似以下内容的通知:

{
  "eventId": "...",
  "eventType": "ENTITLEMENT_DELETED",
  "entitlement": {
    "id": "ENTITLEMENT_ID",
    "updateTime": "...",
  },
}
{
  "eventId": "...",
  "eventType": "ACCOUNT_DELETED",
  "account": {
    "id": "USER_ACCOUNT_ID",
    "updateTime": "...",
  },
}

帐号任务的事件类型列表

以下是您的应用可能在 Pub/Sub 消息中收到的 eventType 列表:

eventType说明
ACCOUNT_CREATION_REQUESTED已弃用
ACCOUNT_ACTIVE表示已创建客户帐号。
ACCOUNT_DELETED表示该客户的帐号已从 Google Cloud 系统中删除。
ENTITLEMENT_CREATION_REQUESTED表示客户选择了您的一个定价方案。
ENTITLEMENT_ACTIVE表示客户选择的方案现在已经生效。
ENTITLEMENT_PLAN_CHANGE_REQUESTED表示客户选择了新方案。
ENTITLEMENT_PLAN_CHANGED表示客户的方案变更已获批准且变更已生效。
ENTITLEMENT_PLAN_CHANGE_CANCELLED表示客户的方案变更已被取消,原因是该方案变更未获批准,或者他们已换回原来的方案。
ENTITLEMENT_PENDING_CANCELLATION表示客户取消了他们的方案,并且取消操作直到结算周期结束为止都处于待处理状态。
ENTITLEMENT_CANCELLATION_REVERTED表示客户的处于待处理状态的取消操作已还原。请注意,取消操作在结束之后不可还原。
ENTITLEMENT_CANCELLED表示客户计划已取消。
ENTITLEMENT_CANCELLING表示客户的方案正在被取消。
ENTITLEMENT_DELETED表示有关客户方案的信息已从 Google Cloud Marketplace 中删除。

(对于基于用量的价格)向 Google 报告使用情况

如果您为解决方案选择基于用量的价格,则必须向 Service Control API 报告应用的使用情况。

您的合作伙伴工程师会创建与您的解决方案对应的服务,并为您的服务帐号提供访问权限以针对该服务报告使用情况。

如需了解 Service Control,请参阅入门指南

创建权益后,您必须使用以下 HTTP GET 请求调用 Partner Procurement API 来检索 usageReportingId

GET v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID

响应包含有关权益的信息,格式如下:

{
  "name": "providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID",
  "provider": "YOUR_PARTNER_ID",
  "account": "USER_ACCOUNT_ID",
  "product": "example-messaging-service",
  "plan": "pro",
  "usageReportingId": "USAGE_REPORTING_ID",
  "state": "ENTITLEMENT_ACTIVATION_REQUESTED",
  "updateTime": "...",
  "createTime": "..."
}

要报告使用情况,您必须首先进行 services.check API 调用,以检查服务的配置。在响应中,如果 checkErrors[] 对象为空,请进行 services.report API 调用以发送使用情况报告。

使用情况报告是一个 Operation,其中包含价格指标的 MetricValueSetOperation 还包含 consumerId 字段,该字段设置为权益中的 USAGE_REPORTING_ID

以下举例说明了 example-messaging-service 的使用情况报告,该报告会发送有关客户正在使用的存储的信息:

POST https://servicecontrol.googleapis.com/v1/services/example-messaging-service.gcpmarketplace.example.com:report
{
  "operations": [{
    "operationId": "1234-example-operation-id-4567",
    "operationName": "Hourly Usage Report",
    "consumerId": "USAGE_REPORTING_ID",
    "startTime": "2019-02-06T12:00:00Z",
    "endTime": "2019-02-06T13:00:00Z",
    "metricValueSets": [{
      "metricName": "example-messaging-service/UsageInGiB",
      "metricValues": [{ "int64Value": "150" }]
    }]
  }]
}

您必须按小时报告应用的使用情况。验证用量的 startTimeendTime 是否正确。如果用户的服务已在 startTime 之前停用,则services.check API 会在 checkErrors[] 对象中发送错误,并且不会向客户收取该时段的费用。

如果 services.check API 返回以下一个或多个错误,我们建议您停止向客户提供服务,除非错误得到解决:

  • SERVICE_NOT_ACTIVATED
  • BILLING_DISABLED
  • PROJECT_DELETED