Data Plan Agent API

動機

如總覽所述，視電信業者想支援的用途而定，DPA 必須實作 Google Mobile Data Plan Sharing API 和 Data Plan Agent API 的組合。本文說明 Google 用來識別使用者行動數據方案、擷取方案資訊及購買數據方案的 Data Plan Agent API。

驗證

GTAF 必須先通過 DPA 驗證，才能呼叫 DPA。在營運商的導入程序中，我們會檢查 DPA SSL 憑證的有效性。我們目前「要求」使用 OAuth2 進行相互驗證。如要瞭解 GTAF 如何向 DPA 驗證自身，請參閱「Data Plan Agent Authentication」。

國際化

傳送至 DPA 的 GTAF 要求會包含 Accept-Language 標頭，指出可讀字串 (例如方案說明) 應使用的語言。此外，DPA 回應 (PlanStatus、PlanOffers) 包含必要欄位 languageCode，其值為 BCP-47 語言代碼 (例如 「en-US」) 的回應。

如果 DPA 不支援使用者要求的語言，可以改用預設語言，並使用 languageCode 欄位指出所選語言。

API 說明

GTAF 查詢電信業者 DPA 時，會使用使用者金鑰來識別電信業者的訂閱者。如果應用程式有權存取 MSISDN，GTAF 代表應用程式查詢 DPA 時「可能」會使用 MSISDN。從高階層面來看，建議的 Data Plan Agent 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 會使用使用者金鑰和用戶端 ID 查詢電信業者的 DPA。支援的用戶端 ID 為 mobiledataplan 和 youtube。 當 DPA 收到含有其中一個用戶端 ID 的呼叫時，必須回覆用戶端可使用的方案資訊。
  3. 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 代表的客戶會使用 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 代表的客戶會使用 CLIENT_ID 識別。視 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 陣列中的資料方案順序「可能」會決定向使用者顯示資料方案的順序。此外，如果應用程式因 UI 或其他限制只能顯示 x 個方案，且回應只包含 y > x 個方案，則只能顯示前 x 個方案。如果查詢優惠的應用程式是 Google Play 服務的行動數據方案模組，GTAF 最多只會分享 50 個方案。這是為了確保 Google Play 服務使用者享有良好的使用體驗。

加購優惠的 filterTags 是選用參數，也就是附加至各方案的標記陣列。所有這些 filterTags 都應與 Filter 內的物件標記相符。Filter 是第一層物件，包含元組<tag, displaytext="">。Filter 是篩選器的合併清單，將在 UI 上顯示。使用者可以點選 DisplayText 進行篩選。系統會使用與 displayText 相對應的標記來篩選方案。</tag,>

請注意，營運商「必須」具備機制，可滿足向使用者提出的任何購買要求。使用者購買商品時的收費機制，可透過回應中的 formOfPayment 選項傳達給 GTAF。

購買數據

購買方案 API 定義 GTAF 如何透過 DPA 購買方案。GTAF 會啟動交易，向 DPA 購買一項數據方案。要求「必須」包含專屬交易 ID (transactionId)，以追蹤要求並避免重複執行交易。資料保護主管機關「必須」回覆成功/失敗回應。

交易要求

收到用戶端的要求後，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 這麼做，系統就會向 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"}

只有想在 Google Play 服務中支援行動數據方案模組的電信業者，才需要使用這項 API。為確保能穩定地傳送通知給使用者，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 選擇導入 Consent API，則「必須」儲存每位使用者的最新同意聲明狀態。如需如何使用同意聲明狀態資訊的指引，請參閱「選擇 CPID」一文。

如果成功，DPA 必須傳回 HTTP 200 OK，且回應主體為空白。如需發生錯誤時的預期回應，請參閱「錯誤案例」。