目的
Google Mobile Data Plan Sharing API を使用すると、オペレーターはユーザーデータキー(ユーザーキーで識別)のデータプランに関する情報を GTAF に送信できます。このページでは、これらの更新を GTAF と Google アプリケーションに push するためのメカニズムの概要を説明します。現在、この API を使用して DPA がデータプランのステータスを GTAF に送信し、Google クライアントで使用できます。
認証
GTAF への Data Plan Sharing API リクエストはすべて、Google Cloud OAuth2 サーバーを使用して認証する必要があります。リクエストは、DPA が表す ASN の ISP ポータルで許可リストに登録されているサービス アカウントとして認証する必要があります。Google Cloud サービス アカウントで OAuth を使用する方法については、サービス アカウント向け Google Cloud OAuth 2.0 をご覧ください。
データプランの更新
現在、Google Mobile Data Plan Sharing API を使用すると、オペレーターはユーザーのデータプランに関する最新情報を共有できます。
- データプランのステータス: ユーザーのデータプランの現在のステータスをキャプチャします。たとえば、ユーザーがデータを使い切った場合、データプランのステータスの更新を GTAF に push できます。これにより、GTAF でプランのステータスの通知をユーザーに送信できます。
API の説明
図 3. DPA がデータプランのステータスを GTAF と共有する際の GTAF-DPA の操作
アプリケーションは、次の 2 つの方法のいずれかで、GTAF と共有されているデータプランのステータス情報を受信できます。
- UE は、GTAF を呼び出してデータプランのステータス情報を取得します。
- オペレーターの DPA は、Data Plan Sharing API を使用してユーザーのデータプランのステータスを GTAF に push します。GTAF は、オペレーターが指定した有効期限まで、プランのステータスとそれに関連するユーザーキーを保存します。
- UE で実行されている Google アプリケーションは、Google 内部 API を使用してデータプランのステータス情報をリクエストします。アプリケーションのリクエストにユーザーキーが含まれている。
- アプリがキャッシュされたデータプランのステータスを使用できる場合、GTAF はユーザーキーを使用してユーザーのデータプランのステータスを検索します。GTAF はこのステータスをアプリに返します。
- GTAF は、データプランのステータス情報を UE に push します。
- 該当する場合、オペレーターから受信したデータプランのステータスは UE に直接プッシュされます。特に、プッシュされたプランのステータスは、Google Play 開発者サービスのモバイルデータ プラン モジュールのオンデバイス キャッシュを更新するために使用されます。
データプランの共有ステータス
DPA は、HTTPS POST を使用して、クライアントが使用する既存のプラン ステータス エントリを作成および更新します。現在 GTAF は、有効なクライアント識別子として mobiledataplan と youtube をサポートしています。asn が 12345 で、ユーザーキー abcdef のプラン情報が youtube クライアントの GTAF と共有されているオペレーターに対するリクエストの例を次に示します。
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 と、ユーザーに通知が送信された場合、push された planStatus エントリに通知エントリを返します。GTAF がリクエストの問題を特定すると、400 ~ 499 の範囲の HTTP ステータス コードが返されます。GTAF の障害により GTAF がリクエストを完了できない場合、GTAF は 500 ~ 599 の範囲の HTTP コードを返します。500 ~ 599 の範囲のレスポンスを受信するリクエストは再試行可能とみなされ、400 ~ 499 の範囲のレスポンスを受信するリクエストは、一般に再試行されません。エラーケースでは、GTAF からのエラー レスポンスについて詳しく説明します。
デフォルト クライアントの Plan ステータス push
GTAF は次の呼び出しをサポートします。この場合、使用できるクライアントを指定せずにオペレーターがプランのステータスをプッシュします。この場合、プランのステータスは mobiledataplan クライアントを対象としており、オペレーターはユーザーへの通知の送信を想定しています。リクエストの本文は PlanStatus のインスタンスです。
POST https://mobiledataplansharing.googleapis.com/v1/operators/12345/planStatuses?userKey=abcdef
国際化
国際化に対応するため、DPA は GTAF から直接リクエストを受け取らない場合でも、ユーザーが使用する言語を把握する必要があります。この問題を解決するために、クライアントがユーザー言語設定にアクセスできるかどうかに応じて、CPID エンドポイントへのリクエストに Accept-Language ヘッダーが含まれても構いません。ヘッダーが含まれている場合、DPA が MDP API を使用して送信する更新に、人が読める形式の文字列を使用する必要があります。この場合、CPID リクエストで指定されている設定を使用する必要があります。
DPA は、Accept-Language ヘッダーを使用して GTAF からリクエストを受け取ったとき、ユーザーの言語設定を更新しても、更新されたユーザー設定を使用して GTAF に対する今後のリクエストで言語コードを決定しても構いません。
DPA は、languageCode を使用して、ユーザーに表示される文字列に使用する言語を指定する必要があります。GTAF は、これを使用して、ユーザーに表示されるタイトルと本文を作成します。