Data Plan Agent API

设计初衷

如概览中所述，根据运营商希望支持的用例，DPA 必须实现 Google 移动数据流量共享 API 和数据流量代理 API 的组合。本文档介绍了 Google 将用于识别用户的移动数据流量套餐、检索有关这些套餐的信息以及购买数据流量套餐的数据流量套餐代理 API。

身份验证

在 GTAF 可以调用之前，DPA 必须对 GTAF 进行身份验证。在运营商的初始配置过程中，我们会检查 DPA SSL 证书的有效性。我们目前要求使用 OAuth2 进行双向身份验证。如需详细了解 GTAF 如何向 DPA 进行身份验证，请参阅数据规划代理身份验证。

国际化

发送给 DPA 的 GTAF 请求包含 Accept-Language 标头，用于指明人类可读字符串（例如方案说明）应采用的语言。此外，DPA 响应（PlanStatus、PlanOffers）包含一个必需的 languageCode 字段，其值为 BCP-47 语言代码（例如，响应的“en-US”）。

如果 DPA 不支持用户请求的语言，则可以使用默认语言，并通过 languageCode 字段指明其选择。

API 说明

在查询运营商的 DPA 时，GTAF 会使用用户密钥（用于标识运营商的订阅者）。当 GTAF 代表有权访问 MSISDN 的应用查询 DPA 时，GTAF 可以使用 MSISDN。从宏观层面来看，提议的数据流量方案代理 API 包含以下组件：

  1. 用于查询用户数据流量套餐状态的机制。
  2. 用于向 DPA 查询用户的数据流量方案优惠的机制。
  3. 用于更改用户数据流量方案（例如购买新方案）的机制。
  4. 用于分享可用于向用户发送通知的 CPID 的机制。
  5. 用于分享用户是否注册我们服务的机制。

本文档的其余部分将详细介绍这些 API 组件。除非另有明确说明，否则所有通信都必须通过 HTTPS（使用有效的 DPA SSL 证书）进行。运营商可以选择实现所有或部分这些 API 组件，具体取决于所支持的实际功能。

GTAF-DPA 互动

GTAF-DPA 互动

图 4. 用于请求和接收用户数据流量方案信息的调用流程。

图 4 展示了与客户端查询用户的数据流量套餐状态和其他数据流量套餐信息相关的调用流程。此调用流程适用于由 UE 上的客户端触发的 API 调用。

  1. 客户端通过调用私有 Google API 请求流量方案状态和/或其他信息。客户端在向 GTAF 发送的请求中包含用户密钥。
  2. GTAF 使用用户密钥和客户端标识符来查询运营商的 DPA。支持的客户端标识符为 mobiledataplan 和 youtube。当 DPA 收到包含这些客户端标识符之一的调用时，必须使用客户端可用的方案信息进行响应。
  3. GTAF 会将所请求的信息返回给客户端，并且 GTAF 会缓存方案信息，直到 DPA 指定的过期时间为止。

图 4 中的步骤 1 和 3 是专用 Google API，因此不再进一步说明。步骤 2 是下文所述的公共 API。DPA 在通过 GTAF 处理这些 API 调用时，必须遵循 Cache-Control: no-cache HTTP 标头。

查询数据流量套餐状态

GTAF 会发出以下 HTTP 请求来获取方案状态：

GET DPA_URL/{userKey}/planStatus?key_type={CPID,MSISDN}&client_id=CLIENT_ID

GTAF 代表其与 DPA 联系的客户端使用 CLIENT_ID 进行标识。根据 Google 客户与运营商之间的协议，DPA 可以自定义对 GTAF 的响应。如果成功，DPA 必须返回 HTTP 200 OK，并附带表示 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"
    }]
  }],
  "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"
  "planInfoPerClient": {
    "youtube": {
      "rateLimitedStreaming": {
        "maxMediaRateKbps": 256
      }
    }
  }
}

对于后付费方案，expirationTime 必须是方案的周期性日期（即数据余额刷新/重新加载的日期）。

每个计划模块可能包含多个计划模块流量类别（PMTCs)，用于对多个应用共享一个计划模块的情况进行建模，例如，500 MB（游戏和音乐）。以下 PMTC 是预定义的：GENERIC, VIDEO, VIDEO_BROWSING, VIDEO_OFFLINE, MUSIC, GAMING, SOCIAL and MESSAGING. 预计运营商会联系各个 Google 团队，就与不同 Google 应用相关的流量类别及其语义达成一致。

查询方案优惠

GTAF 会发出以下 HTTP 请求，以从运营商处获取方案优惠：

GET DPA_URL/{userKey}/planOffer?key_type={CPID,MSISDN}&client_id=CLIENT_ID&context={purchaseContext}

GTAF 代表其与 DPA 联系的客户端使用 CLIENT_ID 进行标识。根据 Google 客户与运营商之间的协议，DPA 可以自定义对 GTAF 的响应。可选的 context 参数提供发出请求的应用上下文。通常，这是应用通过 GTAF 传递给运营商的字符串。

如果成功，DPA 必须返回 HTTP 200 OK，并附带表示 PlanOffer 的响应正文。如需了解出现错误时的预期响应，请参阅错误情况。

{
    "offers": [
      {
        "planName": "ACME Red", // req.
        "planId": "turbulent1", // req.
        "planDescription": "Unlimited Videos for 30 days.", // req.
        "promoMessage": "Binge watch videos.",
        "languageCode": "en_US", // req.
        "overusagePolicy": "BLOCKED",
        "cost": { // req.
          "currencyCode": "INR",
          "units": "300",
          "nanos": 0
        },
        "duration": "2592000s",
        "offerContext": "YouTube",
        "trafficCategories": ["VIDEO"],
        "quotaBytes": "9223372036850",
        "filterTags": ["repurchase", "all"]
      }
    ],
    "filters" : [
      {
        "tag": "repurchase",
        "displayText": "REPURCHASE PLANS"
      },
      {
        "tag": "all",
        "displayText": "ALL PLANS"
      }
    ]
    "expireTime": "2019-03-04T00:06:07Z" // req.
}

offers 数组中数据方案的顺序可能会决定向用户呈现数据方案的顺序。此外，如果应用由于界面或其他限制只能显示 x 个方案，而响应包含 y > x 个方案，则只能显示前 x 个方案。如果查询优惠的应用是 Google Play 服务的一部分（即“移动数据流量方案”模块），则 GTAF 最多只会分享 50 个方案。这是为了确保 Google Play 服务用户获得良好的用户体验。

追加销售优惠将 filterTags 作为可选参数，该参数是附加到每个方案的标记数组。所有这些 filterTags 都应与 Filter 内的对象 tag 相匹配。Filter 是一个第一级对象，包含元组<tag, displaytext="">。Filter 是将在界面上呈现的过滤条件整合列表。用户可以通过点击 DisplayText 进行过滤。与 displayText 对应的标记用于过滤优惠。</tag,>

请注意，运营商必须具备一种机制来满足向用户提供的任何优惠的购买请求。用户购买任何商品时所用的付款机制可以通过响应中的 formOfPayment 选项与 GTAF 进行通信。

数据购买

购买方案 API 定义了 GTAF 如何通过 DPA 购买方案。GTAF 会发起交易，以便向 DPA 购买一个流量套餐。请求应包含唯一的交易标识符 (transactionId)，以跟踪请求并避免重复执行交易。DPA 必须返回成功/失败响应。

交易请求

一旦收到来自客户端的请求，GTAF 就会向 DPA 发出 POST 请求。请求的网址为：

POST DPA_URL/{userKey}/purchasePlan?key_type={CPID,MSISDN}&client_id=CLIENT_ID

其中，userKey 是 CPID 或 MSISDN。请求正文是 TransactionRequest 的实例，包含以下字段：

{
  "planId": string,         // Id of plan to be purchased. Copied from
                            // offers.planId field returned from a
                            // Upsell Offer request,
                            // if available. (req.).
  "transactionId": string,  // Unique request identifier (req.)
  "offerContext": string,   // Copied from from the
                            // offers.offerContext, if available.
                            // (opt.)
  "callbackUrl": string     // URL that the DPA can call back with response once
                            // it has handled the request.
}

交易响应

DPA 仅应针对成功执行的交易或已加入队列的交易生成 200-OK 响应。如需了解出现错误时的预期响应，请参阅错误情况。如果交易已排队，DPA 应仅填充交易状态，并将响应中的其他字段留空。DPA 必须在处理完排队的交易后，通过响应回调 GTAF。响应正文是 TransactionResponse 的实例，其中包含以下详细信息：

{
  "transactionStatus": "SUCCESS",

  "purchase": {
    "planId": string,               // copied from request. (req.)
    "transactionId": string,        // copied from request. (req.)
    "transactionMessage": string,   // status message. (opt.)
    "confirmationCode": string,     // DPA-generated confirmation code
                                    // for successful transaction. (opt.)
    "planActivationTime" : string,  // Time when plan will be activated,
                                    // in timestamp format. (opt.)
  },

  // walletInfo is populated with the balance left in the user's account.
  "walletBalance": {
    "currencyCode": string,       // 3-letter currency code defined in ISO 4217.
    "units": string,              // Whole units of the currency amount.
    "nanos": number               // Number of nano units of the amount.
  }
}

如果缺少 planActivationTime，GTAF 应假定相应方案已激活。

注册 CPID

当支持通知的客户端从 CPID 端点获取新的 CPID 时，如果客户端条款允许 GTAF 这样做，则会将该 CPID 注册到 GTAF。如果客户端成功将 CPID 注册到 GTAF，则 GTAF 将使用以下 API 调用将该 CPID 注册到 DPA：

POST DPA_URL/{userKey}/registerCpid?key_type={CPID,MSISDN}&client_id=CLIENT_ID

其中，userKey 是 CPID，唯一受支持的 CLIENT_ID 是 mobiledataplan。请求正文是 RegisterCpidRequest 的实例，包含 CPID 无法再用于发送通知的时间，如下所示：

{"staleTime": "2017-01-29T01:00:03.14159Z"}

此 API 仅适用于希望在 Google Play 服务中支持移动数据流量方案模块的运营商。为了可靠地向用户发送通知，DPA 可以存储每个用户的最新注册 CPID。如需了解如何使用注册的 CPID 发送通知，请参阅选择 CPID。

如果 DPA 成功将 CPID 与用户相关联并持久存储，则应生成 200-OK 响应。如需了解出现错误时的预期响应，请参阅错误情况。

GTAF 可能会发出以下请求，以将用户同意偏好传递给运营商。

POST DPA_URL/{userKey}/consent?key_type={CPID,MSISDN}&client_id=CLIENT_ID

其中，userKey 是 CPID 或 MSISDN。请求正文是 SetConsentStatusRequest 的实例。如果成功，则响应正文应为空。

从 GTAF 到 DPA 的每次调用都遵循发出调用的 Google 客户端的服务条款。DPA 是否实现此 API 取决于 DPA 希望支持的应用。如果 DPA 选择实现意见征求 API，则必须存储每位用户的最新意见征求状态。如需有关如何使用意见征求状态信息的指南，请参阅选择 CPID。

如果成功，DPA 必须返回 HTTP 200 OK，且响应正文为空。如需了解出现错误时的预期响应，请参阅错误情形。