Google Mobile Data Plan Shared API

動機

Google Mobile Data Plan Shared API 可讓營運人員將關於使用者 (可透過使用者金鑰識別) 的數據方案傳送至 GTAF。本頁概略說明將更新推送至 GTAF 及由 Google 應用程式使用的機制。這個 API 目前可讓 DPA 將數據方案狀態傳送至 GTAF，供 Google 用戶端使用。

驗證

向 GTAF 提出的所有 Data Plan Shared API 要求都必須透過 Google Cloud OAuth2 伺服器進行驗證。這些要求必須做為服務帳戶在 ISP 入口網站中加入許可清單，以供 DPA 代表的 ASN。如要瞭解如何將 OAuth 與 Google Cloud 服務帳戶搭配使用，請參閱服務帳戶的 Google Cloud OAuth 2.0一文。

數據方案更新

目前 Google Mobile Data Plan Shared API 可讓營運人員分享使用者數據方案的相關更新：

  • 數據方案狀態：擷取使用者數據方案的目前狀態。舉例來說，如果使用者耗盡資料，運算子就可以將數據方案狀態更新推送到 GTAF，接著 GTAF 就能將該方案狀態通知通知給使用者。

API 說明

圖 3. 當資料保護主管機關與 GTAF 分享數據方案狀態時，GTAF-DPA 的互動情形。

應用程式可透過下列兩種方式接收與 GTAF 共用的資料方案狀態資訊：

  1. UE 會呼叫 GTAF 以取得數據方案狀態資訊：
    1. 業者 DPA 會使用 Data Plan Shared API，將使用者的資料方案狀態推送至 GTAF。GTAF 會儲存方案狀態及其相關聯的使用者金鑰，直到業者指定的到期時間為止。
    2. 在 UE 上執行的 Google 應用程式使用 Google 內部 API 要求數據方案狀態資訊。應用程式會在要求中加入使用者金鑰。
    3. 如果應用程式可以使用快取資料方案狀態，GTAF 會使用使用者金鑰來查詢使用者的數據方案狀態。GTAF 接著將這個狀態傳回應用程式。
  2. GTAF 可將數據方案狀態推送到 UE：
    1. 在適用情況下，系統會將運算子接收的資料方案狀態直接推送到 UE。特別是，推送方案的狀態是用來更新 Google Play 服務中行動數據方案模組的裝置快取。

共用數據方案狀態

DPA 會使用 HTTPS POST 建立並更新現有方案的狀態項目，以供使用者使用。目前 GTAF 支援 mobiledataplan 和 youtube 做為有效用戶端 ID。以下示範如何向 Asn 12345 和 user key abcdef 與 GTAF 的 YouTube 用戶端分享方案資訊的運算子要求：

貼文 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 因 GTAF 錯誤而無法完成要求，GTAF 會傳回 500-599 範圍內的 HTTP 代碼。收到 500-599 回應內回應的要求會視為可重試，而 400 到 499 範圍內收到回應的要求通常無法重試。錯誤案例 詳細說明瞭 GTAF 的錯誤回應。

推送預設用戶端的方案狀態

GTAF 支援以下呼叫，其中電信業者會推送方案狀態，且並未指定可使用的用戶端。在這個案例中，我們假設方案狀態適用於 mobiledataplan 用戶端，且運算子打算傳送通知給使用者。要求主體是 PlanStatus 的執行個體

訊息 https://mobiledataplansharing.googleapis.com/v1/operators/12345/planStatuses?userKey=abcdef

國際化

為了支援國際化，DPA 必須知道使用者偏好的語言，甚至不需要來自 GTAF 的直接要求。如要解決這個問題，傳送至 CPID 端點的要求可能會「接受」接受語言標頭，視用戶端存取使用者語言偏好設定而定。如果包含標頭，則 DPA 使用 MDP API 傳送的更新內容中包含使用者可理解的字串，必須使用 CPID 要求中提供的設定。

當 GTA 收到含 Accept-Language 標頭的要求時，DPA 可能會更新使用者的語言偏好設定，並在日後針對 GTAF 的請求中，使用更新後的使用者偏好設定來判斷語言代碼。

DPA 「必須」使用 languageCode 指定使用者可見字串的語言。GTAF 會使用這個值建構要顯示給使用者的標題和內文。