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 可以使用该更新向用户发送余额不足的通知。

确定相关用户

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

  1. 有效 CPID：具有有效 CPID 的用户。在 CPID 端点生成的 CPID 有效之前，DPA 应发送有关用户的流量套餐的更新。如果在创建 CPID 时设置了 Accept-Language 标头，则流量套餐状态中便于用户理解的字符串必须使用该语言。
  2. 已注册的 MSISDN：为了提供可以访问 MSISDN 的应用，GTAF 会向 DPA 注册 MSISDN（如 Data Plan Agent API 的 msisdn 注册部分中所述）。注册 MSISDN 后，DPA 应发送有关用户的流量套餐的更新，直至注册到期。

API 说明

共享流量套餐状态

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

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

  1. UE 调用 GTAF 以获取流量套餐状态信息：
    1. 运营商的 DPA 使用 Data Plan Sharing 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 与 youtube 客户端共享 GTAF 计划信息的运营商的示例请求：

发布 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 因 GTAF 故障而无法完成请求，GTAF 将返回 500-599 范围内的 HTTP 代码。收到 500-599 范围内的响应的请求会被视为可重试请求，收到 400-499 范围内的响应的请求通常不可重试。

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

GTAF 继续支持以下调用，其中运营商推送套餐状态，而不指定可以使用该客户端。在本例中，我们假设套餐状态适用于 mobiledataplan 客户端，并且运营商打算向用户发送通知。对于每个客户端用例和默认客户端用例，请求正文都是相同的。

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

国际化

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