このページは Cloud Translation API によって翻訳されました。

Google Mobile Data Plan Sharing API

目的

Google Mobile Data Plan Sharing API を使用すると、通信事業者はユーザー（ユーザーキーで識別）のデータプランに関する情報を GTAF に送信できます。このページでは、これらのアップデートを GTAF にプッシュし、Google アプリケーションに反映させるメカニズムの概要を説明します。この API を使用すると、DPA はデータプランのステータスを GTAF に送信し、Google クライアントで利用できるようになります。

認証

GTAF への Data Plan Sharing API リクエストはすべて、Google Cloud OAuth2 サーバーを使用して認証する必要があります。リクエストは、DPA が表す ASN の ISP ポータルでホワイトリストに登録されているサービスアカウントとして認証される必要があります。Google Cloud サービスアカウントで OAuth を使用する方法については、Google Cloud サービスアカウントの OAuth 2.0 をご覧ください。

データプランの更新

現在、Google モバイルデータプラン共有 API を使用すると、ユーザーのデータプランに関する最新情報を共有できます。

データプランのステータス: ユーザーのデータプランの現在のステータスを取得します。たとえば、ユーザーのデータ残量が少なくなっている場合、通信事業者はデータプランのステータス更新を GTAF にプッシュできます。GTAF はこの情報を使用して、プランのステータスに関する通知をユーザーに送信できます。

API の説明

図 3. DPA がデータプランのステータスを GTAF と共有する場合の GTAF-DPA のやり取り。

アプリは、GTAF と共有されたデータプランのステータス情報を次のいずれかの方法で受け取ることができます。

UE は GTAF にデータプランのステータス情報を要求します。
1. 事業者の DPA は、Data Plan Sharing API を使用して、ユーザーのデータプランのステータスを GTAF にプッシュします。GTAF は、オペレーターが指定した有効期限まで、プランのステータスと関連するユーザーキーを保存します。
2. UE で実行されている Google アプリケーションが、Google 内部 API を使用してデータプランのステータス情報をリクエストします。アプリケーションはリクエストにユーザーキーを含めます。
3. アプリケーションがキャッシュに保存されたデータプランのステータスを使用できる場合、GTAF はユーザーキーを使用してユーザーのデータプランのステータスを検索します。GTAF はこのステータスをアプリケーションに返します。
GTAF はデータプランのステータス情報を UE にプッシュします。
1. 関連する場合、オペレーターから受信したデータプランのステータスは 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 と、プッシュされた planStatus エントリ（ユーザーに通知が送信された場合は通知エントリを含む）を返します。GTAF がリクエストに問題があると判断した場合、400 ～ 499 の範囲の HTTP ステータスコードを返します。GTAF の障害により GTAF がリクエストを完了できない場合、GTAF は 500 ～ 599 の範囲の HTTP コードを返します。500 ～ 599 の範囲のレスポンスを受信したリクエストは再試行可能と見なされ、400 ～ 499 の範囲のレスポンスを受信したリクエストは通常、再試行できません。エラーケースでは、GTAF からのエラーレスポンスについて詳しく説明します。

デフォルトクライアントのプランステータスプッシュ

GTAF は、使用可能なクライアントを指定せずに、オペレーターがプランのステータスをプッシュする次の呼び出しをサポートしています。この場合、プランのステータスは mobiledataplan クライアントを対象としており、事業者はユーザーに通知を送信することを想定しています。リクエストの本文は PlanStatus のインスタンスです。

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

国際化

国際化をサポートするため、DPA は GTAF からの直接のリクエストがなくても、ユーザーの優先言語を把握する必要があります。この問題を解決するため、クライアントがユーザーの言語設定にアクセスできるかどうかに応じて、CPID エンドポイントへのリクエストに Accept-Language ヘッダーを含めても構いません。ヘッダーが含まれている場合、MDP API を使用して DPA が送信するアップデート内の人間が読める文字列は、CPID リクエストで提供された設定を使用する必要があります。

DPA は、Accept-Language ヘッダーを含む GTAF からのリクエストを受け取った場合、ユーザーの言語設定を更新しても構いません。また、更新されたユーザー設定を使用して、GTAF への今後のリクエストで言語コードを決定しても構いません。

DPA では、languageCode を使用して、ユーザーに表示される文字列に使用される言語を指定しなければなりません。GTAF はこれを使用して、ユーザーに表示される通知のタイトルと本文を作成します。