Google 移动流量套餐共享 API

动机

借助 Google 移动流量套餐共享 API，运营商可以向 GTAF 发送有关用户（以用户密钥标识）流量套餐的信息。在本页中，我们概述了可以将这些更新推送到 GTAF 并由此推送到 Google 应用的机制。该 API 目前允许 DPA 将数据计划状态发送到 GTAF，以供 Google 客户端使用。

身份验证

向 GTAF 发出的所有流量套餐共享 API 请求都必须使用 Google Cloud OAuth2 服务器进行身份验证。此类请求必须已在 ISP 门户中针对 DPA 所代表 ASN 的服务帐号进行身份验证。请参阅适用于服务帐号的 Google Cloud OAuth 2.0，了解如何将 OAuth 用于 Google Cloud 服务帐号。

流量套餐更新

目前，Google 移动流量套餐共享 API 允许运营商分享关于其流量套餐的更新：

  • 流量套餐状态：捕获用户的流量套餐的当前状态。例如，如果用户的数据流量已用尽，运营商可以向 GTAF 推送流量套餐状态更新，然后 GTAF 可以使用该更新向用户发送套餐状态通知。

API 说明

图 3. 当 DPA 与 GTAF 共享流量套餐状态时，发生 GTAF-DPA 互动。

应用可以通过以下两种方式之一接收与 GTAF 共享的数据方案状态信息：

  1. UE 调用 GTAF 以获取流量套餐状态信息：
    1. 运营商的 DPA 使用 Data Plan Sharing API 将用户的数据计划状态推送到 GTAF。GTAF 会存储计划状态及其关联的用户密钥，直至运营商指定的到期时间。
    2. 在 UE 上运行的 Google 应用使用 Google 内部 API 请求流量套餐状态信息。应用的请求中会包含用户密钥。
    3. 如果应用可以使用缓存的流量套餐状态，则 GTAF 会使用用户密钥查找用户的流量套餐状态。然后，GTAF 会将此状态返回给应用。
  2. GTAF 会将流量套餐状态信息推送给 UE：
    1. 如适用，来自运营商的数据计划状态会直接推送到 UE。具体而言，推送的方案状态用于更新 Google Play 服务中移动流量套餐模块的设备缓存。

共享流量套餐状态

DPA 使用 HTTPS POST 创建和更新现有方案状态条目，以便用户使用客户端。目前，GTAF 支持将 mobiledataplan 和 youtube 作为有效的客户端标识符。以下是针对 ASN 12345 和用户密钥 abcdef 与 youtube 客户端共享 GTAF 计划信息的运营商的示例请求：

发布 https://mobiledataplansharing.googleapis.com/v1/operators/12345/clients/youtube/users/abcdef/planStatus

请求正文是 PlanStatus 的实例。

{
  "plans": [{
    "planName": "ACME1",
    "planId": "1",
    "planCategory": "PREPAID",
    "expirationTime": "2017-01-29T01:00:03.14159Z", // req.
    "planModules": [{
      "moduleName": "Giga Plan", // req.
      "trafficCategories": ["GENERIC"],
      "expirationTime": "2017-01-29T01:00:03.14159Z", // req.
      "overUsagePolicy": "BLOCKED",
      "maxRateKbps": "1500",
      "description": "1GB for a month", // req.
      "coarseBalanceLevel": "HIGH_QUOTA"
    }]
  }],
  "planInfoPerClient": {
    "youtube": {
      "rateLimitedStreaming": {
        "maxMediaRateKbps": 569
      }
    }
  },
  "languageCode": "en-US", // req.
  "expireTime": "2018-06-14T08:41:27-07:00", // req.
  "updateTime": "2018-06-07T07:41:22-07:00", // req.
  "title": "Prepaid Plan"
}

如果请求成功，GTAF 将返回 HTTP 响应代码 200，如果向用户发送了任何通知，推送的 planStatus 条目中将包含一个通知条目。如果 GTAF 发现请求存在问题，将返回 400-499 范围内的 HTTP 状态代码。如果 GTAF 因 GTAF 故障而无法完成请求，GTAF 将返回 500-599 范围内的 HTTP 代码。收到 500-599 范围内的响应的请求会被视为可重试请求，收到 400-499 范围内的响应的请求通常不可重试。错误案例详细说明了 GTAF 的错误响应。

推送默认客户端的计划状态

GTAF 支持以下调用，其中运营商会推送计划状态，而无需指定可以使用它的客户端。在这种情况下，我们会假定套餐状态适用于 mobiledataplan 客户端，并且运营商打算向用户发送通知。请求正文是 PlanStatus 的实例

POST https://mobiledataplansharing.googleapis.com/v1/operators/12345/planStatuses?userKey=abcdef

国际化

为了支持国际化，DPA 必须知道用户的首选语言，即使来自 GTAF 的直接请求也不例外。要解决此问题，向 CPID 端点发送的请求可以包含 Accept-Language 标头，具体取决于客户端对用户语言偏好设置的访问权限。如果包含该标头，在 DPA 使用 MDP API 发送的更新中，人类可读的字符串必须使用 CPID 请求中提供的设置。

DPA 可以在收到来自 GTAF 的 Accept-Language 标头请求时更新用户语言偏好设置，并使用更新后的用户偏好设置来确定将来向 GTAF 发出的语言代码。

DPA 必须使用 languageCode 指定用户可见字符串所使用的语言。GTAF 使用此方法构建向用户显示的标题和通知正文。