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 就能向使用者傳送低餘額通知。

識別相關使用者

DPA 需要決定哪些使用者要傳送哪些資料給 GTAF。GTAF 預期會收到下列使用者的更新：

  1. 有效的 CPID：具備有效 CPID 的使用者。在 CPID 端點產生的 CPID 之前，DPA 應傳送關於使用者數據方案的最新資訊。如果您在建立 CPID 時設定了 Accept-Language 標頭，則資料方案狀態中的使用者可理解字串「必須」以該語言呈現。
  2. 已註冊 MSISDN：如要提供可存取 MSISDN 的應用程式，GTAF 會使用 Data Plan Agent API 的 msisdn 註冊一節，向 DPA 註冊 MSISDN。註冊 MSISDN 後，DPA 應傳送關於使用者資料方案的最新資訊，直到註冊到期為止。

API 說明

共用數據方案狀態

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

應用程式可透過兩種方式接收數據方案狀態資訊：

  1. UE 會呼叫 GTAF 以取得數據方案狀態資訊：
    1. 業者 DPA 會使用 Data Plan Shared API，將使用者的資料方案狀態推送至 GTAF。GTAF 會儲存方案狀態及其相關聯的使用者金鑰。
    2. 在 UE 上執行的 Google 應用程式使用 Google 內部 API 要求數據方案狀態資訊。應用程式會在要求中加入使用者金鑰。
    3. 如果應用程式可以使用快取資料方案狀態，GTAF 會使用使用者金鑰來查詢使用者的數據方案狀態。接著，GTAF 會將此狀態傳回 UE。
  2. GTAF 可將數據方案狀態推送到 UE：
    1. 在適用情況下，系統會將運算子接收的資料方案狀態直接推送到 UE。

GTAF-DPA 互動

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

{
  "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 會繼續支援以下呼叫，其中業者會推送方案狀態，但並未指定可使用的用戶端。在本範例中，我們假設方案狀態適用於 mobiledataplan 用戶端，且業者打算傳送通知給使用者。每個用戶端用途和預設用戶端用途的要求主體都相同。

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

國際化

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