设计初衷
借助 Google Mobile Data Plan Sharing 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 可以使用该更新向用户发送方案状态通知。
API 说明
图 3. 当 DPA 与 GTAF 共享数据流量方案状态时，GTAF-DPA 之间的互动。
应用可以通过以下两种方式之一接收与 GTAF 共享的流量套餐状态信息：
- UE 调用 GTAF 以获取数据流量套餐状态信息：
- 运营商的 DPA 使用数据流量方案共享 API 将用户的数据流量方案状态推送到 GTAF。在运营商指定的到期时间之前，GTAF 会存储方案状态及其关联的用户密钥。
- 在 UE 上运行的 Google 应用使用 Google 内部 API 请求流量方案状态信息。应用在其请求中包含用户密钥。
- 如果应用可以使用缓存的数据流量方案状态，则 GTAF 会使用用户密钥来查找用户的数据流量方案状态。然后，GTAF 会将此状态返回给应用。
- GTAF 将流量方案状态信息推送到 UE：
- 在相关情况下，从运营商处收到的流量套餐状态会直接推送给 UE。具体而言，推送的方案状态用于更新 Google Play 服务中“移动流量套餐”模块的设备端缓存。
共享数据流量方案状态
DPA 使用 HTTPS POST 为用户创建和更新现有方案状态条目，以供客户端使用。目前，GTAF 支持将 mobiledataplan 和 youtube 用作有效的客户端标识符。以下是一个示例请求，其中包含 ASN 为 12345 的运营商和 用户密钥 abcdef，用于与 GTAF 共享 youtube 客户端的方案信息：
POST 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 因自身故障而无法完成请求，则会返回 500-599 范围内的 HTTP 代码。收到 500-599 范围内的响应的请求被视为可重试，而收到 400-499 范围内的响应的请求通常不可重试。错误情形详细说明了来自 GTAF 的错误响应。
针对默认客户端的方案状态推送
GTAF 支持以下调用，其中方案状态由运营商推送，而无需指定可使用该方案的客户。在这种情况下，我们假设方案状态是针对 mobiledataplan 客户端的，并且运营商打算向用户发送通知。请求正文是 PlanStatus 的实例
POST https://mobiledataplansharing.googleapis.com/v1/operators/12345/planStatuses?userKey=abcdef
国际化
为了支持国际化，即使没有来自 GTAF 的直接请求，DPA 也必须知道用户的首选语言。为了解决此问题，对 CPID 端点的请求可以包含 Accept-Language 标头，具体取决于客户端对用户语言偏好的访问权限。如果包含此标头，则 DPA 使用 MDP API 发送的更新中的人类可读字符串必须使用 CPID 请求中提供的设置。
当 DPA 从 GTAF 收到带有 Accept-Language 标头的请求时，可以更新用户语言偏好设置，并使用更新后的用户偏好设置来确定未来向 GTAF 发出的请求中的语言代码。
DPA 必须使用 languageCode 指定用户可见字符串所用的语言。GTAF 使用此信息来构建向用户显示的通知的标题和正文。