Data Plan Agent API

动机

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

身份验证

GTAF 必须先调用 GTAF，然后才能对其进行调用。在运营商新手入门流程期间，我们将检查 DPA SSL 证书的有效性。目前，我们要求使用 OAuth2 进行双向身份验证。如需详细了解 GTAF 如何使用 DPA 对自身进行身份验证，请参阅流量套餐代理身份验证。

国际化

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

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

API 说明

GTAF 在查询运营商的 DPA 时使用用户密钥来识别运营商的用户。当 GTAF 代表有权访问 MSISDN 的应用查询 DPA 时，GTAF 可以使用 MSISDN。概括来讲，建议的 Data Plan Agent API 包含以下组件：

1. 查询用户流量套餐状态的机制。
2. 查询 DPA 以获取用户的流量套餐方案的机制。
3. 更改用户的流量套餐（例如，购买新的套餐）的机制。
4. 共享 CPID 的机制，可用于向用户发送通知。
5. 供用户选择是否注册我们的服务的机制。

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

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。从 GTAF 调用这些 API 时，DPA 必须遵循 Cache-Control: no-cache HTTP 标头。

查询流量套餐状态

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

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

您可以使用 CLIENT_ID 来标识 GTAF 联系 DPA 的客户端。根据 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}

您可以使用 CLIENT_ID 来标识 GTAF 联系 DPA 的客户端。根据 Google 客户端与运营商之间的协议，DPA 可以自定义对 GTAF 的响应。可选的上下文参数提供发出请求的应用上下文。通常，这是应用通过 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 服务的用户提供良好的用户体验。

追加销售优惠提供了 filterTag 作为可选参数，这是附加到每个方案的一系列代码。所有这些 filterTag 都应该与作为过滤器内部对象的标记匹配。Filter 是包含元组标记、displaytext="&gt>的第一级对象。Filter 是将在界面中呈现的过滤器的综合列表。用户可以通过点击 DisplayText 进行过滤。与 displayText 对应的标记用于过滤优惠。/lt,/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 必须返回响应。响应正文是 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 将使用以下 API 调用向 DPA 注册 CPID：

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 与用户相关联并永久存储该 DPA，则 DPA 应生成 200-OK 响应。如需了解出现错误时的预期响应，请参阅错误案例。

征得用户同意

GTAF 可以发出以下请求，以将用户意见征求偏好设置传递给运营商。

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

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

从 GTAF 到 DPA 的每次调用都遵循发出调用的 Google 客户端的服务条款。根据 DPA 想要支持的应用，由运营商决定 DPA 是否实现此 API。如果 DPA 确实选择实现意见征求 API，则 DPA 必须存储每个用户的最新意见征求状态。如需了解如何使用意见征求状态信息，请参阅选择 CPID。

如果成功，DPA 必须返回 HTTP 200 OK，且响应正文为空。请参阅错误案例，了解错误情况下的预期响应。