Google Mobile Data Plan Shared API

動機

透過 Google Mobile Data Plan Sharing API，電信業者可將使用者 (以使用者金鑰識別) 的數據方案資訊傳送至 GTAF。本頁將說明如何透過 GTAF 將這些更新推送至 Google 應用程式。目前，API 允許 DPA 將資料方案狀態傳送至 GTAF，供 Google 用戶端使用。

驗證

所有傳送至 GTAF 的 Data Plan Sharing API 要求，都必須使用 Google Cloud OAuth2 伺服器進行驗證。要求必須以服務帳戶的身分通過驗證，且該帳戶已在 ISP 入口網站中加入許可清單，代表 DPA 的 ASN。如要瞭解如何搭配使用 OAuth 與 Google Cloud 服務帳戶，請參閱「Google Cloud OAuth 2.0 for Service Accounts」。

數據方案更新

目前 Google 行動資費方案共用 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. DPA 與 GTAF 互動，將資費方案狀態提供給 GTAF。

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

  1. UE 會呼叫 GTAF，取得數據方案狀態資訊：
    1. 電信業者 DPA 會使用 Data Plan Sharing 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，使用者金鑰為 abcdef) 提出要求的範例，要求與 GTAF 分享 youtube 用戶端的方案資訊：

POST 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 會傳回 500 到 599 範圍內的 HTTP 代碼。如果要求收到 500 到 599 範圍內的回應，系統會視為可重試，但如果收到 400 到 499 範圍內的回應，通常就無法重試。

將方案狀態推送至預設用戶端

如果電信業者推送方案狀態，但未指定可使用方案的用戶端，GTAF 仍會繼續支援下列呼叫。在本例中，我們假設方案狀態適用於 mobiledataplan 用戶端，且電信業者打算傳送通知給使用者。每個用戶端用途和預設用戶端用途的要求主體相同。

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

國際化

為支援國際化，即使沒有 GTAF 的直接要求，DPA 也必須知道使用者的偏好語言。如要解決這個問題，對 CPID 端點的請求「可能」會包含 Accept-Language 標頭。如果包含標頭，DPA 使用 MDP API 傳送的更新中，使用者可讀取的字串必須使用 CPID 要求中提供的設定。