動機
透過 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 預計會收到下列使用者的更新:
- 有效 CPID:擁有有效 CPID 的使用者。在 CPID 端點產生的 CPID 有效之前,DPA「應」傳送使用者資料方案的更新資訊。如果在建立 CPID 時設定了
Accept-Language
標頭,資料方案狀態中的可讀字串就必須使用該語言。 - 已註冊的 MSISDN:如要為可存取 MSISDN 的應用程式提供服務,GTAF 會按照 Data Plan Agent API 的「msisdn 註冊」一節所述,向 DPA 註冊 MSISDN。MSISDN 註冊完成後,DPA 應傳送使用者資料方案的更新資訊,直到註冊到期為止。
API 說明
共用資料方案狀態
圖 3. DPA 與 GTAF 互動,將資費方案狀態提供給 GTAF。
應用程式可以透過下列兩種方式接收數據方案狀態資訊:
- UE 會呼叫 GTAF,取得數據方案狀態資訊:
- 電信業者 DPA 會使用 Data Plan Sharing API,將使用者的資費方案狀態推送至 GTAF。GTAF 會儲存方案狀態和相關聯的使用者金鑰。
- 在 UE 上執行的 Google 應用程式會使用 Google 內部 API,要求取得資料方案狀態資訊。應用程式會在要求中加入使用者金鑰。
- 如果應用程式可以使用快取資料方案狀態,GTAF 會使用使用者金鑰查詢使用者的資料方案狀態。GTAF 隨後會將這個狀態傳回 UE。
- GTAF 會將資料方案狀態資訊推送至 UE:
- 如果適用,從電信業者收到的數據方案狀態會直接推送至 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 要求中提供的設定。