设计初衷
借助 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 预计会收到以下用户的更新:
- 有效 CPID:具有有效 CPID 的用户。在 CPID 端点生成的 CPID 有效之前,DPA 应发送有关用户数据流量套餐的更新。如果在创建 CPID 时设置了
Accept-Language
标头,则数据计划状态中的人类可读字符串必须采用该语言。 - 已注册的 MSISDN:为了向有权访问 MSISDN 的应用提供服务,GTAF 会按照数据流量方案代理 API 的 MSISDN 注册部分中所述,向 DPA 注册 MSISDN。注册 MSISDN 后,DPA 应发送有关用户数据流量套餐的更新,直到注册过期。
API 说明
共享数据流量方案状态
图 3. 当 DPA 与 GTAF 共享数据流量方案状态时,GTAF-DPA 之间的互动。
应用可以通过以下两种方式接收流量方案状态信息:
- UE 调用 GTAF 以获取数据流量套餐状态信息:
- 运营商的 DPA 使用数据流量方案共享 API 将用户的数据流量方案状态推送到 GTAF。GTAF 会存储方案状态及其关联的用户密钥。
- 在 UE 上运行的 Google 应用使用 Google 内部 API 请求流量方案状态信息。应用在其请求中包含用户密钥。
- 如果应用可以使用缓存的数据流量方案状态,则 GTAF 会使用用户密钥来查找用户的数据流量方案状态。然后,GTAF 会将此状态返回给 UE。
- GTAF 将流量方案状态信息推送到 UE:
- 在相关情况下,从运营商处收到的流量套餐状态会直接推送给 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 请求中提供的设置。