このページは 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 を使用する必要があります。

API の説明

GTAF は、オペレーターの DPA を照会するときに、オペレーターのサブスクライバーを識別するユーザーキーを使用します。MSISDN にアクセスできるアプリに代わって GTAF が DPA にクエリを送信する場合は、GTAF で MSISDN を使用しても構いません。提案する Data Plan Agent API はおおまかに次のコンポーネントで構成されています。

ユーザーデータプランのステータスを照会するメカニズム。
ユーザーに対してデータプランの特典について DPA にクエリするメカニズム。
ユーザーのデータプランを変更するメカニズム（新しいプランの購入など）。
ユーザーが特定のデータプランを購入できるかどうかを確認するメカニズム。
GTAF が MSISDN を DPA に登録するための仕組みです。
DPA が正常な状態であるかどうかを検証する GTAF のメカニズム。

以下では、これらの各 API コンポーネントについて詳しく説明します。特に明記されていない限り、すべての通信は HTTPS を介して（有効な DPA SSL 証明書を使用して）行われる必要があります。サポートされている実際の機能に応じて、オペレーターはこれらの API コンポーネントの一部またはすべてを実装しても構いません。

データプランのステータスを照会する

GTAF-DPA インタラクション

図 4. 通話データフローをリクエストして受け取れます。

図 4 は、ユーザーのデータプランのステータスとその他のデータプラン情報をクエリするクライアントに関連付けられた呼び出しフローを示しています。この呼び出しフローは、UE のクライアントによってトリガーされた API 呼び出しに対して共有されます。

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

図 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 への応答をカスタマイズできます。レスポンスの形式は、PlanStatus を表す JSON オブジェクトです。

{
  "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
      }
    }
  }
}

リクエストには、人が読める文字列（プランの説明など）の言語を示す Accept-Language ヘッダーが含まれなければなりません。

後払いプランの場合、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 を通じてアプリケーションがオペレータに渡す文字列です。

レスポンスの本文には PlanOffer のインスタンスが含まれます。

{
    "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"
      }
    ],
    "expireTime": "2019-03-04T00:06:07Z" // req.
}

offers 配列のデータプランの順序は、データプランがユーザーに表示される順序を決定しても構いません。さらに、UI またはその他の制限により、アプリが x プランのみを提示でき、レスポンスに y > x プランが含まれている場合、最初の x プランのみが表示されます。GTAF は、特典をクエリするアプリが Google Play 開発者サービスの一部であるモバイルデータプラン UI の場合、最大 10 個のプランのみを共有します。これは、Google Play 開発者サービスのユーザーに優れたユーザーエクスペリエンスを提供するためです。

offerInfo 内の文字列は、ユーザーがクーポンの詳細を確認できるようにすることを目的としています。また、アプリ内からさらに多くのクーポンを受け取らないようにする方法も含まれています。こうしたフィールドがある理由は、一部の演算子はアプリ内購入を許可する際にエンドユーザーの同意を必要としないため、ユーザーがオプトアウトするためのメカニズムを必要とするためです。オペレーターは、ユーザーに拡張された特典の購入リクエストのためのメカニズムを提供しなければなりません。購入に対してユーザーに課金されるメカニズムは、レスポンスで formOfPayment オプションを使用して GTAF に通知できます。

リクエストには、人が読める文字列（プランの説明など）の言語を示す Accept-Language ヘッダーが含まれなければなりません。

データ購入

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

取引リクエスト

GTAF は、クライアントからのリクエストを受信すると、POST リクエストを DPA に発行します。リクエストの 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.
}

トランザクションの応答

エラーの場合、DPA は一般的なエラーの原因を返す必要があります。さらに、次のエラーコードは失敗したトランザクションの結果を表します。

DPA は、購入済みのプラン ID が無効であることを示す 400 BAD REQUEST エラーコードを返します。
DPA は、402 PAYMENT REQUIRED エラーコードを返します。これは、ユーザーが購入を完了するのに十分な残高がないことを GTAF に対して示すものです。
DPA は、購入対象のプランがユーザーの現在のプロダクト構成と互換性がないことを示す 409 CONFLICT エラーコードを返します。たとえば、オペレーターのデータプランのポリシーで、プリペイドプランとプリペイドプランの混在が許可されていない場合、後払いユーザーのプリペイドプランを購入しようとすると 409 CONFLICT エラーが発生します。
DPA は、現在のトランザクションが以前に発行されたトランザクションの重複であることを示す 403 FORBIDDEN エラーコードを返します。DPA は、それに応じて次のエラー原因を返すべきです。
- 前のトランザクションが失敗した場合は、エラーの原因を示すエラーの原因になります。
- 前のトランザクションが成功した場合は、DUPLICATE_TRANSACTION。
- 前のトランザクションがまだキューに入っている場合は、REQUEST_QUEUED となります。

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 は、プランが有効になっているものと想定します。

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

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

userKey は、CPID または MSISDN です。リクエストの本文は SetConsentStatusRequest のインスタンスです。

成功すると、レスポンスの本文は空になります。

対象条件

GTAF は、ユーザーがプランを購入できるかどうかを確認するために、次の利用資格リクエストを発行しても構いません。

GET DPA/{userKey}/Eligibility/{planId}?key_type={CPID,MSISDN}

planId は、ユーザーに代わってプランを購入するために使用できるプランの一意の識別子です（データ購入をご覧ください）。planId が指定されていない場合、DPA は、ユーザーが購入可能なすべてのプランを返さなければなりません。

エラーの場合、DPA は一般的なエラーの原因を返す必要があります。さらに、DPA は、次のエラーケースでエラーを返す必要があります。

DPA は 400 BAD REQUEST エラーコードを返し、planId が無効であることを GTAF に知らせます。
DPA は、planId がユーザーのデータプランと互換性がないことを示す 409 CONFLICT エラーコードを返します。

それ以外の場合、DPA は 200 OK レスポンスを返す必要があります。EligibleResponse の成功のフォーマットは次のとおりです。

{
  "eligiblePlans":
  [
   {
    "planId": string,   // Plan identifier. Can be used to
                        // refer to the plan during
                        // offers, etc. (req.)
   }
  ]
}

リクエストに planId が含まれている場合、レスポンスにはそのプランのみが含まれます。それ以外の場合、このリストにはユーザーが購入できるすべてのプランが含まれます。planId が空で、DPA が有効なプランのリストを返すことをサポートしていない場合は、400 BAD REQUEST エラーを返さなければなりません。

MSISDN 登録エンドポイント

MSISDN にアクセスできるアプリを提供するため、GTAF では MSISDN を DPA に登録します。GTAF は、Google Mobile Data Plan Sharing API によってアプリケーションが実行される場合にのみ MSISDN を登録します。DPA は Google API を使用して GTAF に情報を送信します。MSISDN を登録するには、GTAF が POST リクエストを DPA に送信します。

POST DPA_URL/登録

リクエストの本文は RegistrationRequest のインスタンスになります。

{
  "msisdn": "<msisdn_string>"
}

MSISDN の登録が成功した場合、DPA は RegistrationResponse を含む 200 OK レスポンスを返す必要があります。JSON の形式は次のとおりです。

{
  // msisdn that was registered.
  "msisdn": "<msisdn_string>",
  // time after which DPA will not send updates to GTAF.
  "expirationTime": string
}

DPA は、expirationTime が経過するまで、ユーザーのデータプランに関する最新情報を GTAF に送信すべきです。

エラーが発生した場合は、ErrorResponse が返されます。

{
    "error": "<error message>",
    "cause": enum(ErrorCause)
}

さまざまなエラー条件と考えられる原因と HTTP のステータスコードの完全なリストについては、こちらをご覧ください。特に、ローミングを行っているユーザー、またはデータプラン情報を Google と共有していないユーザーに対して MSISDN 登録リクエストを受け取った場合、DPA は HTTP ステータスコード 403 を返さなければなりません。

Monitoring API

一部のユースケースでは、GTAF で DPA をモニタリングし、DPA の失敗を検出する必要があります。これらのユースケースに対応するために、Monitoring API を定義しました。

API の定義

Monitoring API は、次の URL の HTTP GET リクエストで使用できるようにする必要があります。

DPA_URL/dpaStatus

DPA とそのすべてのバックエンドが正しく動作している場合、DPA はこのクエリに応答するために、HTTP ステータスコード 200 と、DpaStatus のインスタンスを含むレスポンスの本文を返します。

{
    "status": enum(DpaStatusEnum),
    "message": "<optional human-readable status description>"
}

DPA またはそのバックエンドのいずれかが正常に機能していない場合は、HTTP ステータスコード 500 と、DpaStatus のインスタンスを含むレスポンスの本文を返します。

DPA の動作

障害が検出されると、DPA はすべての dpaStatus クエリに対して「UNAVAILABLE」のステータスを返す必要があります。また、長いキャッシュ期間を伴うデータプラン情報の送信も停止する必要があります。キャッシュ保存期間が長いレスポンスの送信を停止するには、次の 2 つの方法があります。

キャッシュの有効期限を短く設定します。
データプラン情報の送信を中止します。

GTAF の動作

GTAF は、dpaStatus を定期的にポーリングします。「UNAVAILABLE」のレスポンスで DPA の障害が検出されると、オペレーターのキャッシュがクリアされます。

エラーケース

エラーの場合、DPA は次のいずれかに対応する HTTP ステータスコードを返します。

このユーザーはローミング中です。このユーザーの DPA クエリは無効になっています。DPA が 403 エラーを返します。
DPA は、ユーザーキー（存在しないユーザーキー）が無効であることを 404 NOT_FOUND エラーコードとして GTAF に返します。
DPA は 410 GONE エラーコードを返します。key_type = CPID で CPID が期限切れになった場合、クライアントは新しいユーザーキーを取得するよう GTAF に指示します。
DPA は、この呼び出しがサポートされていないことを示す 501 NOT_IMPLEMENTED エラーコードを返します。
サービスを一時的に利用できません。DPA は、503 SERVICE UNAVAILABLE を返します。この Retry-After ヘッダーは新しいリクエストを試行できるタイミングを示します。
DPA は、その他の不明なエラーについては 500 INTERNAL SERVER ERROR エラーコードを返します。
DPA は、429 TOO_MANY_REQUESTS エラーと Retry-After ヘッダーを返し、GTAF から DPA へのリクエストが多すぎることを示します。
DPA は、409 CONFLICT エラーを返します。これは、DPA の現在の状態との競合が原因でリクエストを完了できないことを示しています。

すべてのエラーケースで、HTTP レスポンスの本文には、エラーに関する詳細情報を含む JSON オブジェクトを含める必要があります。エラーレスポンスの本文には ErrorResponse のインスタンスが含まれなければなりません。

{
  "error": string,
  "cause": enum(ErrorCause)
}

現在定義されている cause 値は、ErrorCause API リファレンスの一部としてリストされます。

それ以外の場合は、DPA から 200 OK が返されます。これらの cause 値はすべてのレスポンスに使用されます。

国際化

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

DPA がユーザーのリクエスト言語をサポートしていない場合は、デフォルトの言語を使用し、languageCode フィールドでその言語を指定します。