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

Data Plan Agent API

目的

概要で説明したように、オペレーターがサポートするユースケースに応じて、DPA は Google Mobile Data Plan Sharing API と Data Plan Agent API の組み合わせを実装する必要があります。このドキュメントでは、Google がユーザーのモバイルデータプランを特定し、プランに関する情報を取得して、データプランを購入するために使用する Data Plan Agent API について説明します。

認証

GTAF が呼び出す前に、DPA は GTAF を認証する必要があります。オペレーターのオンボーディングプロセスの一環として、DPA SSL 証明書の有効性を確認します。現在、相互認証には OAuth2 の使用が必須となっています。GTAF が DPA で認証する方法の詳細については、データプランエージェントの認証をご覧ください。

国際化

DPA への GTAF リクエストには、人が読める文字列（プランの説明など）の言語を示す Accept-Language ヘッダーが含まれます。また、DPA レスポンス（PlanStatus、PlanOffers）には、値が BCP-47 言語コード（例: "en-US"）。

DPA がユーザーのリクエストした言語をサポートしていない場合は、デフォルトの言語を使用し、languageCode フィールドを使用して選択した言語を示すことができます。

API の説明

GTAF は、通信事業者の DPA をクエリする際に、通信事業者の加入者を識別するユーザーキーを使用します。GTAF が MSISDN にアクセスできるアプリに代わって DPA にクエリを実行する場合、GTAF は MSISDN を使用しても構いません。大まかに表現すると、提案された Data Plan Agent API は次のコンポーネントで構成されています。

ユーザーのデータプランのステータスをクエリするメカニズム。
ユーザーのデータプランの提案について DPA にクエリを行うメカニズム。
ユーザーのデータプランを変更するメカニズム（新しいプランの購入など）。
ユーザーに通知を送信するために使用できる CPID を共有するメカニズム。
サービスに登録するかどうかに関するユーザーの選択を共有するメカニズム。

このドキュメントの残りの部分では、これらの各 API コンポーネントについて詳しく説明します。明示的に記載されていない限り、すべての通信は HTTPS 経由で行われなければなりません（有効な DPA SSL 証明書を使用）。サポートされる実際の機能に応じて、オペレーターはこれらの API コンポーネントのすべてまたはサブセットを実装することを選択できます。

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

図 4. ユーザーのデータプラン情報をリクエストして受け取るためのコールフロー。

図 4 は、ユーザーのデータプランのステータスやその他のデータプラン情報についてクライアントが問い合わせる際のコールフローを示しています。この呼び出しフローは、UE のクライアントによってトリガーされた API 呼び出しで共有されます。

クライアントは、非公開の Google API を呼び出して、データプランのステータスやその他の情報をリクエストします。クライアントは、GTAF へのリクエストにユーザーキーを含めます。
GTAF は、ユーザーキーとクライアント識別子を使用して、事業者の DPA をクエリします。サポートされているクライアント ID は mobiledataplan と youtube です。DPA は、これらのクライアント ID のいずれかを含む呼び出しを受信した場合、クライアントが使用できるプラン情報を返さなければなりません。
GTAF はリクエストされた情報をクライアントに返し、DPA で指定された有効期限までプラン情報をキャッシュに保存します。

図 4 のステップ 1 と 3 は非公開の Google API であるため、これ以上の説明は省略します。ステップ 2 は、後述する公開 API です。DPA は、GTAF からこれらの API 呼び出しを処理する際に、Cache-Control: no-cache HTTP ヘッダーを尊重しなければなりません。

データプランのステータスのクエリ

GTAF は、プランのステータスを取得するために次の HTTP リクエストを発行します。

GET DPA_URL/{userKey}/planStatus?key_type={CPID,MSISDN}&client_id=CLIENT_ID

GTAF が DPA に連絡するクライアントは、CLIENT_ID を使用して識別されます。Google クライアントとオペレーター間の契約に応じて、DPA は GTAF へのレスポンスをカスタマイズできます。成功した場合、DPA は PlanStatus を表すレスポンス本文とともに HTTP 200 OK を返さなければなりません。エラーが発生した場合の想定されるレスポンスについては、エラーケースをご覧ください。

{
  "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"
    }]
  }],
  "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"
  "planInfoPerClient": {
    "youtube": {
      "rateLimitedStreaming": {
        "maxMediaRateKbps": 256
      }
    }
  }
}

後払いプランの場合、expirationTime はプランの定期購入日（データ残高が更新/再読み込みされる日）でなければなりません。

各プランモジュールには複数のプランモジュールトラフィックカテゴリを含めることができます（PMTCs)。複数のアプリでプランモジュールが共有されるケースをモデル化するため（例: ゲームと音楽の場合は 500 MB）。次の PMTC は事前定義されています。GENERIC, VIDEO, VIDEO_BROWSING, VIDEO_OFFLINE, MUSIC, GAMING, SOCIAL and MESSAGING. オペレーターは、個々の Google チームに連絡して、さまざまな Google アプリケーションに関連するトラフィックカテゴリのセットとそのセマンティクスについて合意することが想定されています。

プランの提案をクエリする

GTAF は、次の HTTP リクエストを発行して、携帯通信会社からプランの提案を取得します。

GET DPA_URL/{userKey}/planOffer?key_type={CPID,MSISDN}&client_id=CLIENT_ID&context={purchaseContext}

GTAF が DPA に連絡するクライアントは、CLIENT_ID を使用して識別されます。Google クライアントとオペレーター間の契約に応じて、DPA は GTAF へのレスポンスをカスタマイズできます。省略可能なコンテキストパラメータは、リクエストが作成されるアプリのコンテキストを提供します。通常、これはアプリケーションが GTAF を介してオペレーターに渡す文字列です。

成功した場合、DPA は PlanOffer を表すレスポンス本文とともに HTTP 200 OK を返さなければなりません。エラーが発生した場合の想定されるレスポンスについては、エラーケースをご覧ください。

{
    "offers": [
      {
        "planName": "ACME Red", // req.
        "planId": "turbulent1", // req.
        "planDescription": "Unlimited Videos for 30 days.", // req.
        "promoMessage": "Binge watch videos.",
        "languageCode": "en_US", // req.
        "overusagePolicy": "BLOCKED",
        "cost": { // req.
          "currencyCode": "INR",
          "units": "300",
          "nanos": 0
        },
        "duration": "2592000s",
        "offerContext": "YouTube",
        "trafficCategories": ["VIDEO"],
        "quotaBytes": "9223372036850",
        "filterTags": ["repurchase", "all"]
      }
    ],
    "filters" : [
      {
        "tag": "repurchase",
        "displayText": "REPURCHASE PLANS"
      },
      {
        "tag": "all",
        "displayText": "ALL PLANS"
      }
    ]
    "expireTime": "2019-03-04T00:06:07Z" // req.
}

offers 配列内のデータプランの順序によって、ユーザーにデータプランが表示される順序が決まることがあります。また、UI などの制限により、アプリが x プランのみを表示でき、レスポンスに y > x プランのみが含まれている場合、最初の x プランのみを表示しなければなりません。オファーをクエリするアプリが Google Play 開発者サービスの一部であるモバイルデータプランモジュールの場合、GTAF は最大 50 個のプランのみを共有します。これは、Google Play サービスのユーザーに優れたユーザーエクスペリエンスを提供するためです。

アップセル提案には、各プランに付加されたタグの配列である filterTags という省略可能なパラメータがあります。これらの filterTags はすべて、Filter 内のオブジェクトであるタグと一致する必要があります。Filter は、tuple<tag, displaytext=""> を含む第 1 レベルのオブジェクトです。Filter は、UI にレンダリングされるフィルタの統合リストです。ユーザーは DisplayText をクリックしてフィルタできます。displayText に対応するタグは、特典のフィルタリングに使用されます。</tag,>

なお、ユーザーに提供された特典の購入リクエストを処理するメカニズムがオペレーターに備わっている必要があります。ユーザーが購入した商品の代金を支払う仕組みは、レスポンスの formOfPayment オプションを使用して GTAF に伝えることができます。

データ購入

購入プラン API は、GTAF が DPA を介してプランを購入する方法を定義します。GTAF は、1 つのデータプランを購入するトランザクションを DPA に開始します。リクエストには、リクエストをトレースし、トランザクションの重複実行を回避するための一意のトランザクション識別子（transactionId）を含めなければなりません。DPA は成功/失敗のレスポンスを返さなければなりません。

Transaction Request

クライアントからリクエストを受信すると、GTAF は DPA に POST リクエストを発行します。リクエストの URL は次のとおりです。

POST DPA_URL/{userKey}/purchasePlan?key_type={CPID,MSISDN}&client_id=CLIENT_ID

ここで、userKey は CPID または MSISDN です。リクエストの本文は TransactionRequest のインスタンスです。これには次のフィールドが含まれます。

{
  "planId": string,         // Id of plan to be purchased. Copied from
                            // offers.planId field returned from a
                            // Upsell Offer request,
                            // if available. (req.).
  "transactionId": string,  // Unique request identifier (req.)
  "offerContext": string,   // Copied from from the
                            // offers.offerContext, if available.
                            // (opt.)
  "callbackUrl": string     // URL that the DPA can call back with response once
                            // it has handled the request.
}

Transaction Response

DPA は、正常に実行された取引またはキューに登録された取引に対してのみ 200-OK レスポンスを生成しなければなりません。エラーが発生した場合の想定されるレスポンスについては、エラーケースをご覧ください。キューに登録されたトランザクションの場合、DPA はトランザクションステータスのみを入力し、レスポンスの他のフィールドは空のままにします。キューに登録されたトランザクションが処理されたら、DPA はレスポンスとともに GTAF を呼び戻さなければなりません。レスポンスの本文は TransactionResponse のインスタンスで、次の詳細が含まれます。

{
  "transactionStatus": "SUCCESS",

  "purchase": {
    "planId": string,               // copied from request. (req.)
    "transactionId": string,        // copied from request. (req.)
    "transactionMessage": string,   // status message. (opt.)
    "confirmationCode": string,     // DPA-generated confirmation code
                                    // for successful transaction. (opt.)
    "planActivationTime" : string,  // Time when plan will be activated,
                                    // in timestamp format. (opt.)
  },

  // walletInfo is populated with the balance left in the user's account.
  "walletBalance": {
    "currencyCode": string,       // 3-letter currency code defined in ISO 4217.
    "units": string,              // Whole units of the currency amount.
    "nanos": number               // Number of nano units of the amount.
  }
}

planActivationTime がない場合、GTAF はプランが有効になっていると見なします。

CPID を登録する

通知をサポートするクライアントが CPID エンドポイントから新しい CPID を取得すると、クライアントの利用規約で GTAF が許可されている場合、クライアントは CPID を GTAF に登録します。クライアントが CPID を GTAF に正常に登録すると、GTAF は次の API 呼び出しを使用して CPID を DPA に登録します。

POST DPA_URL/{userKey}/registerCpid?key_type={CPID,MSISDN}&client_id=CLIENT_ID

userKey は CPID で、サポートされている CLIENT_ID は mobiledataplan のみです。リクエストの本文は RegisterCpidRequest のインスタンスで、CPID を使用して通知を送信できなくなるまでの時間を含んでいます。

{"staleTime": "2017-01-29T01:00:03.14159Z"}

この API は、Google Play 開発者サービスでモバイルデータプランモジュールをサポートしようとしている事業者のみに関連します。ユーザーに確実に通知を送信するために、DPA は各ユーザーの最新の登録済み CPID を保存しても構いません。登録済みの CPID を使用して通知を送信する方法については、CPID の選択をご覧ください。

DPA が CPID をユーザーに関連付け、永続的に保存することに成功した場合、DPA は 200-OK レスポンスを生成します。エラーが発生した場合の想定されるレスポンスについては、エラーケースをご覧ください。

GTAF は、ユーザーの同意設定を携帯通信会社に渡すために、次のリクエストを発行しても構いません。

POST DPA_URL/{userKey}/consent?key_type={CPID,MSISDN}&client_id=CLIENT_ID

ここで、userKey は CPID または MSISDN です。リクエストの本文は SetConsentStatusRequest のインスタンスです。成功すると、レスポンスの本文は空になります。

GTAF から DPA へのすべての呼び出しは、呼び出しを行う Google クライアントの利用規約に準拠します。DPA がサポートするアプリケーションに応じて、この API を実装するかどうかは事業者が決定します。DPA が同意 API の実装を選択する場合、DPA は各ユーザーの最新の同意ステータスを保存しなければなりません。同意ステータス情報の使用方法については、CPID の選択をご覧ください。

成功した場合、DPA は空のレスポンス本文を含む HTTP 200 OK を返さなければなりません。エラーが発生した場合の想定されるレスポンスについては、エラーケースをご覧ください。

Data Plan Agent API コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

目的

認証

国際化