Google 移动流量套餐共享 API

设计初衷

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

身份验证

向 GTAF 发出的所有数据流量方案共享 API 请求都必须使用 Google Cloud OAuth2 服务器进行身份验证。请求必须以服务账号的身份进行身份验证，该服务账号已在 ISP 门户中针对 DPA 所代表的 ASN 列入许可名单。如需查看有关如何将 OAuth 与 Google Cloud 服务账号搭配使用的文档，请参阅适用于服务账号的 Google Cloud OAuth 2.0。

流量套餐更新

目前，Google 移动流量套餐共享 API 允许运营商共享有关用户流量套餐的更新：

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

识别相关用户

DPA 需要一种方法来确定要将哪些用户的数据发送到 GTAF。GTAF 预计会收到以下用户的更新：

  1. 有效 CPID：具有有效 CPID 的用户。在 CPID 端点生成的 CPID 有效之前，DPA 应发送有关用户数据流量套餐的更新。如果在创建 CPID 时设置了 Accept-Language 标头，则数据计划状态中的人类可读字符串必须采用该语言。
  2. 已注册的 MSISDN：为了向有权访问 MSISDN 的应用提供服务，GTAF 会按照数据流量方案代理 API 的 MSISDN 注册部分中所述，向 DPA 注册 MSISDN。注册 MSISDN 后，DPA 应发送有关用户数据流量套餐的更新，直到注册过期。

API 说明

共享数据流量方案状态

图 3. 当 DPA 与 GTAF 共享数据流量方案状态时，GTAF-DPA 之间的互动。

应用可以通过以下两种方式接收流量方案状态信息：

  1. UE 调用 GTAF 以获取数据流量套餐状态信息：
    1. 运营商的 DPA 使用数据流量方案共享 API 将用户的数据流量方案状态推送到 GTAF。GTAF 会存储方案状态及其关联的用户密钥。
    2. 在 UE 上运行的 Google 应用使用 Google 内部 API 请求流量方案状态信息。应用在其请求中包含用户密钥。
    3. 如果应用可以使用缓存的数据流量方案状态，则 GTAF 会使用用户密钥来查找用户的数据流量方案状态。然后，GTAF 会将此状态返回给 UE。
  2. GTAF 将流量方案状态信息推送到 UE：
    1. 在相关情况下，从运营商处收到的流量套餐状态会直接推送给 UE。

GTAF-DPA 互动

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

POST https://mobiledataplansharing.googleapis.com/v1/operators/12345/clients/youtube/users/abcdef/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 因自身故障而无法完成请求，则会返回 500-599 范围内的 HTTP 代码。收到 500-599 范围内的响应的请求被视为可重试，而收到 400-499 范围内的响应的请求通常不可重试。

针对默认客户端的方案状态推送

GTAF 继续支持以下调用，其中方案状态由运营商推送，但未指定可使用该方案的客户。在这种情况下，我们假设方案状态是针对 mobiledataplan 客户端的，并且运营商打算向用户发送通知。对于每个客户端用例和默认客户端用例，请求正文是相同的。

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

国际化

为了支持国际化，即使没有来自 GTAF 的直接请求，DPA 也必须知道用户的首选语言。为了解决此问题，对 CPID 端点的请求可以包含 Accept-Language 标头。如果包含此标头，则 DPA 使用 MDP API 发送的更新中的人类可读字符串必须使用 CPID 请求中提供的设置。