このページは 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 のやり取り。

アプリは、次の 2 つの方法でデータプランのステータス情報を受け取ることができます。

UE は GTAF にデータプランのステータス情報を要求します。
1. 事業者の DPA は、Data Plan Sharing API を使用して、ユーザーのデータプランのステータスを GTAF にプッシュします。GTAF は、プランのステータスと関連するユーザーキーを保存します。
2. UE で実行されている Google アプリケーションが、Google 内部 API を使用してデータプランのステータス情報をリクエストします。アプリケーションはリクエストにユーザーキーを含めます。
3. アプリケーションがキャッシュに保存されたデータプランのステータスを使用できる場合、GTAF はユーザーキーを使用してユーザーのデータプランのステータスを検索します。GTAF はこのステータスを UE に返します。
GTAF はデータプランのステータス情報を UE にプッシュします。
1. 関連する場合、事業者から受信したデータプランのステータスは UE に直接プッシュされます。

GTAF-DPA のインタラクション

DPA は、HTTPS POST を使用して、クライアントで使用されるユーザーの既存のプランステータスエントリを作成および更新します。現在、GTAF は有効なクライアント識別子として mobiledataplan と youtube をサポートしています。以下は、asn 12345 と ユーザーキー abcdef を持つ事業者が、youtube クライアントの GTAF とプラン情報を共有するリクエストの例です。

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 がリクエストを完了できない場合、GTAF は 500 ～ 599 の範囲の HTTP コードを返します。500 ～ 599 の範囲のレスポンスを受信したリクエストは再試行可能と見なされ、400 ～ 499 の範囲のレスポンスを受信したリクエストは通常、再試行できません。

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

GTAF は、使用可能なクライアントを指定せずに、プランのステータスが通信事業者によってプッシュされる次の呼び出しをサポートし続けます。この場合、プランのステータスは mobiledataplan クライアントを対象としており、事業者はユーザーに通知を送信することを想定しています。リクエスト本文は、クライアントごとのユースケースとデフォルトのクライアントユースケースで同じです。

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

国際化

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