動機
透過 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 隨後就能使用這項資訊，向使用者傳送方案狀態通知。
API 說明
圖 3. DPA 與 GTAF 互動，將資費方案狀態提供給 GTAF。
應用程式可以透過下列兩種方式之一，接收與 GTAF 共用的數據方案狀態資訊：
- UE 會呼叫 GTAF，取得數據方案狀態資訊：
- 電信業者 DPA 會使用 Data Plan Sharing API，將使用者的資費方案狀態推送至 GTAF。GTAF 會儲存方案狀態和相關聯的使用者金鑰，直到電信業者指定的到期時間為止。
- 在 UE 上執行的 Google 應用程式會使用 Google 內部 API，要求取得資料方案狀態資訊。應用程式會在要求中加入使用者金鑰。
- 如果應用程式可以使用快取資料方案狀態，GTAF 會使用使用者金鑰查詢使用者的資料方案狀態。GTAF 接著會將這個狀態傳回應用程式。
- GTAF 會將資料方案狀態資訊推送至 UE：
- 如果適用，系統會直接將從電信業者收到的數據方案狀態推送至 UE。具體來說，推送的方案狀態會用於更新 Google Play 服務中「行動數據方案」模組的裝置端快取。
共用資料方案狀態
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
要求主體是 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 的錯誤回應。
將方案狀態推送至預設用戶端
GTAF 支援下列呼叫，其中方案狀態是由電信業者推送，且未指定可使用方案的用戶端。在本例中，我們假設方案狀態適用於 mobiledataplan 用戶端，且電信業者打算傳送通知給使用者。要求主體是 PlanStatus 的例項
POST https://mobiledataplansharing.googleapis.com/v1/operators/12345/planStatuses?userKey=abcdef
國際化
為支援國際化，即使沒有 GTAF 的直接要求，DPA 也必須知道使用者的偏好語言。如要解決這個問題，視用戶端是否能存取使用者語言偏好設定，對 CPID 端點的要求「可能」會包含 Accept-Language 標頭。如果包含標頭，DPA 使用 MDP API 傳送的更新中，可供人閱讀的字串必須使用 CPID 要求中提供的設定。
當 DPA 收到 GTAF 傳送的要求 (附有 Accept-Language 標頭) 時，DPA「可能」會更新使用者語言偏好設定，並在日後向 GTAF 傳送要求時，使用更新後的使用者偏好設定來判斷語言代碼。
DPA「必須」使用 languageCode 指定使用者可見字串所用的語言。GTAF 會使用這項資訊建構向使用者顯示的通知標題和內文。