目的
概要で説明したように、オペレーターが使用を希望するユースケースに応じて、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 言語コード（&ent-en-US" など）。
DPA がユーザーのリクエスト言語をサポートしていない場合は、デフォルトの言語を使用し、languageCode フィールドでその言語を指定します。
API の説明
GTAF は、オペレーターの DPA を照会するときに、オペレーターのサブスクライバーを識別するユーザーキーを使用します。MSISDN にアクセスできるアプリに代わって GTAF が DPA にクエリを送信する場合は、GTAF で MSISDN を使用しても構いません。提案する Data Plan Agent API はおおまかに次のコンポーネントで構成されています。
- ユーザーデータ プランのステータスを照会するメカニズム。
- ユーザーに対してデータプランの特典について DPA にクエリするメカニズム。
- ユーザーのデータプランを変更するメカニズム（新しいプランの購入など）。
- ユーザーへの通知の送信に使用できる CPID を共有するための仕組みです。
- Google のサービスに登録するかどうかのユーザーの選択を共有する仕組み。
以下では、これらの各 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 への応答をカスタマイズできます。成功した場合、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 プランのみが表示されます。GTAF がプランを共有できるのは、特典をクエリするアプリが Google Play 開発者サービスの一部であるモバイルデータ プラン モジュールである場合に限られます。これは、Google Play 開発者サービスのユーザーに優れたユーザー エクスペリエンスを提供するためです。
アップセルのオファーには、各プランに添付されるタグの配列である、オプションのパラメータとして filterTags があります。これらの filterTag はすべて、Filter 内のオブジェクトであるタグと一致する必要があります。Filter は、タプル<tag, displaytext=""> を含む第 1 レベルのオブジェクトです。Filter は、UI にレンダリングされるフィルタの統合リストです。ユーザーは DisplayText をクリックしてフィルタリングできます。displayText に対応するタグは、特典のフィルタリングに使用されます。</tag,>
オペレーターは、ユーザーに拡張された特典の購入リクエストのためのメカニズムを提供しなければなりません。購入に対してユーザーに課金されるメカニズムは、レスポンスで formOfPayment オプションを使用して GTAF に通知できます。
データ購入
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 は、正常に実行されたトランザクションまたはキューに登録されたトランザクションに対してのみ、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 が登録されます。クライアントが 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 がサポートしようとしているアプリケーションに応じて、DPA がこの API を実装するかどうかはオペレータが判断する必要があります。DPA が同意 API を実装することを選択した場合、DPA は各ユーザーの最新の同意ステータスを保存しなければなりません。同意ステータス情報の使用方法については、CPID の選択をご覧ください。
成功した場合、DPA は空のレスポンス本文で HTTP 200 OK を返さなければなりません。エラーが発生した場合の予想される応答については、エラーケースをご覧ください。