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 برای ارسال یک اعلان موجودی کم به کاربر استفاده شود.

شناسایی کاربران مرتبط

DPA به روشی نیاز دارد تا تعیین کند کدام اطلاعات کاربران را به GTAF ارسال کند. GTAF انتظار دارد به‌روزرسانی‌هایی را برای کاربران زیر دریافت کند:

1. Active CPID : کاربران با CPID فعال. تا زمانی که CPIDهایی که توسط نقطه پایانی CPID تولید شده اند معتبر باشند، DPA باید به روز رسانی هایی را درباره طرح داده کاربر ارسال کند. اگر هدر Accept-Language در زمان ایجاد CPID تنظیم شده باشد، رشته های قابل خواندن توسط انسان در وضعیت طرح داده باید در آن زبان باشد.
2. MSISDN های ثبت شده : برای ارائه خدمات به برنامه هایی که به MSISDN دسترسی دارند، GTAF MSISDN را با DPA همانطور که در بخش ثبت msisdn در Data Plan Agent API توضیح داده شده است، ثبت می کند. پس از ثبت MSISDN، DPA باید به‌روزرسانی‌هایی را در مورد طرح داده‌های کاربر ارسال کند تا زمان ثبت نام منقضی شود.

توضیحات API

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

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

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

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

تعامل GTAF-DPA

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

POST https://mobiledataplansharing.googleapis.com/v1/operators/12345/clients/youtube/users/abcdef/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 دریافت می کنند، معمولاً قابل امتحان مجدد نیستند.

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

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

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

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

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