Data Plan Agent API, Data Plan Agent API

انگیزه

همانطور که در نمای کلی ذکر شد، بسته به موارد استفاده ای که اپراتور می خواهد پشتیبانی کند، DPA باید ترکیبی از Google Mobile Data Plan Sharing API و Data Plan Agent API را پیاده سازی کند. این سند، Data Plan Agent API را توصیف می‌کند که Google از آن برای شناسایی طرح‌های داده تلفن همراه کاربر، بازیابی اطلاعات مربوط به این طرح‌ها و خرید طرح‌های داده استفاده می‌کند.

احراز هویت

قبل از اینکه GTAF بتواند تماس بگیرد، DPA باید GTAF را احراز هویت کند. به عنوان بخشی از فرآیند ورود اپراتور، ما اعتبار گواهینامه DPA SSL را بررسی خواهیم کرد. ما در حال حاضر به استفاده از OAuth2 برای احراز هویت متقابل نیاز داریم.

توضیحات API

GTAF هنگام پرس و جو از DPA اپراتور از کلید کاربر استفاده می کند که مشترک اپراتور را شناسایی می کند. وقتی GTAF از طرف برنامه هایی که به MSISDN دسترسی دارند از DPA درخواست می کند، GTAF ممکن است از MSISDN استفاده کند. در سطح بالایی، Data Plan Agent API پیشنهادی شامل اجزای زیر است:

  1. مکانیزم برای استعلام وضعیت طرح داده های کاربر.
  2. مکانیسمی برای پرس و جو از DPA برای ارائه طرح داده به کاربر.
  3. مکانیزم ایجاد تغییرات در طرح داده کاربر (به عنوان مثال، خرید یک طرح جدید).
  4. مکانیزمی برای تأیید اینکه آیا کاربر واجد شرایط خرید یک طرح داده خاص است یا خیر.
  5. مکانیسم GTAF برای ثبت MSISDN در DPA.
  6. مکانیسم GTAF برای تأیید اینکه آیا DPA در وضعیت سالمی است یا خیر.

بقیه این سند در مورد هر یک از این مؤلفه های API توضیح می دهد. مگر اینکه صریحاً ذکر شده باشد، همه ارتباطات باید از طریق HTTPS (با یک گواهی معتبر DPA SSL) انجام شوند. بسته به ویژگی‌های واقعی که پشتیبانی می‌شوند، یک اپراتور ممکن است تمام یا زیرمجموعه‌ای از این مؤلفه‌های API را پیاده‌سازی کند.

استعلام وضعیت طرح داده

تعامل GTAF-DPA

GTAF-DPA Interaction

شکل 4. جریان تماس برای درخواست و دریافت اطلاعات طرح داده کاربر.

شکل 4 جریان تماس مرتبط با مشتری را نشان می دهد که در مورد وضعیت طرح داده کاربر و سایر اطلاعات طرح داده پرس و جو می کند. این جریان تماس برای تماس‌های API ایجاد شده توسط مشتری در UE به اشتراک گذاشته می‌شود.

  1. مشتری با تماس با یک Google API خصوصی، وضعیت طرح داده و/یا سایر اطلاعات را درخواست می‌کند. کلاینت شامل کلید کاربر در درخواست GTAF می شود.
  2. GTAF از کلید کاربر و شناسه کلاینت برای پرس و جو از DPA اپراتور استفاده می کند. شناسه های مشتری پشتیبانی شده mobiledataplan و youtube هستند. هنگامی که DPA تماسی با یکی از این شناسه های مشتری دریافت می کند، باید با اطلاعات طرحی که می تواند توسط مشتری استفاده شود پاسخ دهد.
  3. GTAF اطلاعات درخواستی را به مشتری برمی گرداند و اطلاعات طرح توسط GTAF تا زمان انقضا مشخص شده توسط DPA ذخیره می شود.

مراحل 1 و 3 در شکل 4 APIهای Google خصوصی هستند و بنابراین بیشتر توضیح داده نشده اند. مرحله 2 یک API عمومی است که در ادامه توضیح داده می شود. هنگامی که این تماس‌های API از GTAF ارائه می‌شود، DPA باید به هدر HTTP Cache-Control: no-cache احترام بگذارد.

وضعیت طرح

GTAF برای دریافت وضعیت طرح درخواست HTTP زیر را صادر می کند:

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

سرویس گیرنده ای که GTAF از طرف آن با DPA تماس می گیرد با استفاده از CLIENT_ID شناسایی می شود. بسته به توافق بین مشتری Google و شرکت مخابراتی، DPA می تواند پاسخ به GTAF را سفارشی کند. قالب پاسخ یک شی JSON است که یک 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"
    }]
  }],
  "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 مگابایت برای بازی و موسیقی) مدل کند. 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 ممکن است ترتیب ارائه طرح(های) داده به کاربران را تعیین کند. علاوه بر این، اگر برنامه به دلیل رابط کاربری یا محدودیت‌های دیگر بتواند فقط x پلان را ارائه دهد و پاسخ شامل طرح‌های y > x باشد، تنها برنامه‌های x اول باید ارائه شوند. اگر برنامه درخواستی پیشنهادات، رابط کاربری Mobile Data Plan باشد که بخشی از خدمات Google Play است، GTAF تنها تا 10 طرح را به اشتراک می گذارد. این برای اطمینان از تجربه کاربری خوب برای کاربران خدمات Google Play است.

رشته‌های موجود در offerInfo به این منظور در نظر گرفته شده‌اند که به کاربر اجازه می‌دهند اطلاعات بیشتری در مورد پیشنهاد داشته باشند، و همچنین شامل راهی برای انصراف از دریافت پیشنهادات بیشتر از داخل برنامه‌ها می‌شوند. دلیل داشتن این فیلدها این است که برخی از اپراتورها برای اجازه دادن به خریدهای درون برنامه ای به رضایت کاربر نهایی نیاز ندارند، بلکه به مکانیزمی برای انصراف کاربران نیاز دارند. توجه داشته باشید که اپراتور باید مکانیزمی برای انجام درخواست خرید برای هر پیشنهاد ارائه شده به کاربر داشته باشد. با استفاده از گزینه formOfPayment در پاسخ می توان مکانیزمی را که از طریق آن کاربر برای هر خریدی هزینه دریافت می کند، با GTAF ارتباط برقرار کرد.

این درخواست باید شامل یک سرصفحه Accept-Language باشد که زبانی را که رشته های قابل خواندن توسط انسان (مثلاً توضیحات طرح) باید به آن باشد را نشان می دهد.

خرید داده

API طرح خرید نحوه خرید GTAF را از طریق DPA تعریف می کند. GTAF تراکنش را برای خرید یک طرح داده به DPA آغاز می کند. درخواست باید شامل یک شناسه تراکنش منحصر به فرد (transactionId) برای ردیابی درخواست ها و جلوگیری از اجرای تراکنش های تکراری باشد. DPA باید با پاسخ موفقیت/شکست پاسخ دهد.

درخواست معامله

هنگامی که یک درخواست از یک مشتری دریافت کرد، GTAF یک درخواست POST را به DPA ارسال می کند. آدرس درخواست این است:

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 کد خطای 400 BAD REQUEST را برمی گرداند که نشان می دهد شناسه طرح خریداری شده نامعتبر است.
  • DPA کد خطای 402 PAYMENT REQUIRED را برمی گرداند که به GTAF نشان می دهد که کاربر موجودی کافی برای تکمیل خرید ندارد.
  • DPA یک کد خطای CONFLICT 409 را برمی گرداند که به GTAF نشان می دهد که طرحی که باید خریداری شود با ترکیب محصول فعلی کاربر ناسازگار است. برای مثال، اگر خط‌مشی طرح داده‌های اپراتور ترکیب طرح‌های پس‌پرداخت و پیش‌پرداخت را مجاز نمی‌داند، تلاش برای خرید یک طرح پیش‌پرداخت برای کاربر پس‌پرداخت منجر به خطای CONFLICT 409 می‌شود.
  • DPA یک کد خطای 403 FORBIDDEN را برمی گرداند که به GTAF نشان می دهد که تراکنش فعلی تکراری از تراکنش صادر شده قبلی است. 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 را برمی گرداند که به GTAF نشان می دهد که planId نامعتبر است.
  • DPA یک کد خطای CONFLICT 409 را برمی گرداند که نشان می دهد planId با طرح داده کاربر ناسازگار است.

در غیر این صورت، DPA باید یک پاسخ 200-OK را برگرداند. قالب یک EligibilityResponse موفق به این صورت است:

{
  "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 MSISDN را فقط زمانی ثبت می‌کند که برنامه‌هایی وجود داشته باشند که توسط Google Mobile Data Plan Sharing API ارائه می‌شوند، که در آن DPA اطلاعات را با استفاده از Google API به GTAF ارسال می‌کند. برای ثبت MSISDN، GTAF یک درخواست POST به DPA می دهد:

POST DPA_URL/ثبت نام

بدنه درخواست نمونه ای از RegistrationRequest خواهد بود.

{
  "msisdn": "<msisdn_string>"
}

اگر ثبت MSISDN موفقیت آمیز باشد، DPA باید یک پاسخ OK 200 شامل RegistrationResponse را برگرداند. فرمت JSON این است:

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

سپس DPA باید به‌روزرسانی‌های مربوط به طرح داده‌های کاربر را تا زمان انقضا به GTAF ارسال کند.

اگر خطایی رخ دهد، یک ErrorResponse باید برگردانده شود:

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

لیست کامل مقادیر علت احتمالی و کدهای وضعیت HTTP برای شرایط خطای مختلف در اینجا موجود است. به ویژه، اگر درخواست ثبت MSISDN برای کاربری دریافت شود که در رومینگ است یا اشتراک‌گذاری اطلاعات طرح داده با Google را انتخاب نکرده است، DPA باید کد وضعیت HTTP 403 را برگرداند.

API مانیتورینگ

برخی موارد استفاده به GTAF برای نظارت بر DPA و شناسایی خرابی های DPA نیاز دارند. برای آن موارد استفاده، ما یک API نظارتی تعریف کرده‌ایم.

تعریف API

API نظارت باید از طریق درخواست HTTP GET در URL زیر در دسترس باشد:

DPA_URL/dpaStatus

اگر DPA و همه پشتیبان‌های آن به درستی کار می‌کنند، DPA باید با کد وضعیت HTTP 200 و یک بدنه پاسخ که نمونه‌ای از DpaStatus را دارد به این درخواست پاسخ دهد.

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

اگر DPA یا هر یک از پشتیبان‌های آن به درستی کار نمی‌کنند، باید با کد وضعیت HTTP 500 و یک بدنه پاسخ که نمونه‌ای از DpaStatus را دارد، پاسخ دهد.

رفتار DPA

هنگامی که یک شکست شناسایی شد، DPA باید وضعیت "UNAVAILABLE" را برای همه جستارهای dpaStatus برگرداند. علاوه بر این، باید ارسال اطلاعات طرح داده با دوره های کش طولانی را متوقف کند. ممکن است ارسال پاسخ‌هایی با دوره‌های کش طولانی را به یکی از دو روش متوقف کند:

  1. شروع به تنظیم زمان انقضای حافظه پنهان کوتاه کنید.
  2. ارسال اطلاعات طرح داده را به طور کامل متوقف کنید.

رفتار GTAF

GTAF به صورت دوره ای dpaStatus را نظرسنجی می کند. وقتی خرابی DPA را تشخیص داد (بر اساس پاسخ "UNAVAILABLE")، حافظه پنهان خود را برای اپراتور پاک می کند.

موارد خطا

در صورت بروز خطا، انتظار می رود DPA یک کد وضعیت HTTP مربوط به یکی از موارد زیر را برگرداند:

  • کاربر در حال حاضر در رومینگ است و پرس و جو DPA برای این کاربر غیرفعال است. DPA یک خطای 403 برمی گرداند.
  • DPA یک کد خطای 404 NOT_FOUND را برمی گرداند که به GTAF نشان می دهد که کلید کاربر نامعتبر است (یعنی کلید کاربری موجود نیست).
  • DPA یک کد خطای 410 GONE را برمی‌گرداند که به GTAF نشان می‌دهد که اگر key_type = CPID و CPID منقضی شده باشد، مشتری باید یک کلید کاربری جدید دریافت کند.
  • DPA کد خطای 501 NOT_IMPLEMENTED را برمی‌گرداند که نشان می‌دهد از این تماس پشتیبانی نمی‌کند.
  • سرویس موقتا در دسترس نیست. DPA یک SERVICE 503 NAVAILABLE را با هدر Retry-After برمی گرداند که نشان می دهد چه زمانی می توان درخواست جدیدی را انجام داد.
  • DPA یک کد خطای 500 INTERNAL SERVER ERROR را برای تمام خطاهای نامشخص دیگر برمی گرداند.
  • DPA یک خطای 429 TOO_MANY_REQUESTS را با هدر Retry-After برمی گرداند که نشان می دهد GTAF درخواست های زیادی به DPA می کند.
  • DPA یک خطای CONFLICT 409 را برمی‌گرداند که نشان می‌دهد به دلیل تضاد با وضعیت فعلی DPA، درخواست نمی‌تواند تکمیل شود.

در تمام موارد خطا، بدنه پاسخ HTTP باید شامل یک شی JSON با اطلاعات بیشتر در مورد خطا باشد. بدنه پاسخ به خطا باید شامل یک نمونه از ErrorResponse باشد.

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

مقادیر cause تعریف شده در حال حاضر به عنوان بخشی از مرجع ErrorCause API فهرست شده اند.

در غیر این صورت، DPA یک OK 200 برمی گرداند. توجه می کنیم که این مقادیر cause برای همه پاسخ ها استفاده می شود.

بین المللی شدن

درخواست‌های GTAF به DPA شامل یک هدر Accept-Language است که زبانی را نشان می‌دهد که رشته‌های قابل خواندن توسط انسان (مثلاً توضیحات طرح) باید در آن باشد. علاوه بر این، پاسخ‌های DPA (PlanStatus، PlanOffers) شامل یک فیلد زبان کد الزامی است که مقدار آن BCP-47 است. کد زبان (به عنوان مثال، "en-US") پاسخ.

اگر DPA از زبان درخواستی کاربر پشتیبانی نمی کند، می تواند از یک زبان پیش فرض استفاده کند و از قسمت languageCode برای نشان دادن انتخاب خود استفاده کند.