Google Mobile Data Plan Sharing API

انگیزه

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

احراز هویت

همه درخواست‌های Data Plan Sharing API به GTAF باید با استفاده از سرور Google Cloud OAuth2 احراز هویت شوند. درخواست‌ها باید به‌عنوان یک حساب سرویس که در پورتال ISP برای ASN که DPA نمایندگی می‌کند در لیست سفید قرار گرفته است، احراز هویت شوند. برای مستندات مربوط به نحوه استفاده از OAuth با حساب‌های سرویس Google Cloud به Google Cloud OAuth 2.0 برای حساب‌های سرویس مراجعه کنید.

به روز رسانی طرح داده

در حال حاضر Google Mobile Data Plan Sharing API به اپراتور اجازه می‌دهد تا به‌روزرسانی‌های مربوط به طرح داده کاربر را به اشتراک بگذارد:

• وضعیت طرح داده: وضعیت فعلی طرح داده کاربر را ثبت می کند. برای مثال، اگر داده‌های کاربر تمام شود، اپراتور می‌تواند یک به‌روزرسانی وضعیت طرح داده را به GTAF ارسال کند که سپس می‌تواند توسط GTAF برای ارسال اعلان وضعیت طرح به کاربر استفاده شود.

توضیحات API

شکل 3. تعامل GTAF-DPA زمانی که DPA وضعیت طرح داده را با GTAF به اشتراک می گذارد.

برنامه ها می توانند اطلاعات وضعیت طرح داده به اشتراک گذاشته شده با GTAF را به یکی از دو روش دریافت کنند:

1. UE برای اطلاعات وضعیت طرح داده، GTAF را فرا می‌خواند:
   1. DPA اپراتور از Data Plan Sharing API برای انتقال وضعیت طرح داده کاربر به GTAF استفاده می کند. GTAF وضعیت طرح و کلید کاربر مرتبط با آن را تا زمان انقضا مشخص شده توسط اپراتور ذخیره می کند.
   2. برنامه Google در حال اجرا در UE اطلاعات وضعیت طرح داده را با استفاده از API داخلی Google درخواست می کند. برنامه شامل کلید کاربر در درخواست خود است.
   3. اگر برنامه بتواند از وضعیت طرح داده های ذخیره شده استفاده کند، GTAF از کلید کاربر برای جستجوی وضعیت طرح داده کاربر استفاده می کند. سپس GTAF این وضعیت را به برنامه برمی گرداند.
2. GTAF اطلاعات وضعیت طرح داده را به UE منتقل می کند:
   1. در صورت لزوم، وضعیت طرح داده دریافتی از اپراتور مستقیماً به UE منتقل می شود. به طور خاص، وضعیت طرح فشار داده شده برای به روز رسانی حافظه پنهان دستگاه ماژول Mobile Data Plan در خدمات Google Play استفاده می شود.

وضعیت طرح داده به اشتراک گذاری

DPA از HTTPS POST برای ایجاد و به‌روزرسانی یک ورودی وضعیت طرح موجود برای کاربر استفاده می‌کند تا توسط مشتری استفاده شود. در حال حاضر GTAF از mobiledataplan و youtube به عنوان شناسه های مشتری معتبر پشتیبانی می کند. در اینجا یک نمونه درخواست برای اپراتور با asn 12345 و اطلاعات طرح اشتراک گذاری کلید کاربر abcdef با GTAF برای مشتری یوتیوب آورده شده است:

POST https://mobiledataplansharing.googleapis.com/v1/operators/12345/clients/youtube/users/abcdef/planStatus

بدنه درخواست نمونه ای از 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"
}

توجه: فرمت کامل درخواست‌های Google Mobile Data Plan Sharing API در بخش مرجع توضیح داده شده است.

در صورت موفقیت آمیز بودن درخواست، GTAF کد پاسخ HTTP 200 و ورودی planStatus را با یک ورودی اعلان در صورتی که اعلانی برای کاربر ارسال شده باشد، برمی گرداند. اگر GTAF مشکلی را در درخواست شناسایی کند، یک کد وضعیت HTTP در محدوده 400-499 برمی‌گرداند. اگر GTAF به دلیل نقص GTAF نتواند درخواستی را تکمیل کند، GTAF کد HTTP را در محدوده 500-599 برمی گرداند. درخواست هایی که پاسخی در محدوده 500-599 دریافت می کنند، قابل امتحان مجدد هستند و درخواست هایی که پاسخی در محدوده 400-499 دریافت می کنند، معمولاً قابل امتحان مجدد نیستند. Error Cases پاسخ های خطای GTAF را به تفصیل توضیح می دهد.

طرح وضعیت فشار برای مشتری پیش فرض

GTAF از تماس زیر پشتیبانی می کند که در آن وضعیت طرح توسط اپراتور بدون تعیین مشتری برای استفاده از آن تحت فشار قرار می گیرد. در این حالت، ما فرض می کنیم که وضعیت طرح برای مشتری mobiledataplan در نظر گرفته شده است و اپراتور قصد دارد یک اعلان برای کاربر ارسال کند. بدنه درخواست نمونه ای از PlanStatus است

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

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

به منظور پشتیبانی از بین المللی سازی، DPA باید زبان مورد نظر کاربر را حتی بدون درخواست مستقیم GTAF بداند. برای حل این مشکل، درخواست به نقطه پایانی CPID ممکن است بسته به دسترسی مشتری به تنظیمات برگزیده زبان کاربر، یک سرصفحه Accept-Language داشته باشد. اگر هدر گنجانده شده باشد، رشته‌های قابل خواندن توسط انسان در به‌روزرسانی‌هایی که DPA با استفاده از MDP API ارسال می‌کند باید از تنظیمات ارائه‌شده در درخواست CPID استفاده کنند.

DPA ممکن است هنگامی که درخواستی از GTAF با هدر Accept-Language دریافت می کند، ترجیحات زبان کاربر را به روز کند و از تنظیمات به روز شده کاربر برای تعیین کد زبان در درخواست های بعدی به GTAF استفاده کند.

DPA باید زبان مورد استفاده برای رشته های قابل مشاهده کاربر را با استفاده از languageCode مشخص کند. GTAF از این برای ساخت عنوان و بدنه اعلان‌های نمایش داده شده به کاربر استفاده می‌کند.