واجهة برمجة تطبيقات مشاركة خطة بيانات الجوّال من Google

الحافز

تسمح واجهة برمجة التطبيقات Google Play Data Shared Share API لمشغّل بإرسال معلومات حول خطة بيانات المستخدمين (المحدّدة من خلال مفتاح مستخدم) إلى GTAF. في هذه الصفحة، نوضّح الآلية التي يمكن من خلالها إرسال هذه التحديثات إلى GTAF، وبالتالي إلى تطبيقات Google. تسمح واجهة برمجة التطبيقات حاليًا لـ "هيئة حماية البيانات" إرسال حالة خطة البيانات إلى "GTAF" ليستهلكها عميل Google.

المصادقة

يجب مصادقة جميع طلبات واجهة برمجة التطبيقات لمشاركة البيانات في خطة البيانات إلى GTAF باستخدام خادم Google Cloud OAuth2. يجب مصادقة الطلبات كحساب خدمة تمت إضافته إلى القائمة البيضاء في بوابة مزوّد خدمة الإنترنت لاسم شبكة ASN التي تمثلها هيئة حماية البيانات. راجِع Google Cloud OAuth 2.0 لحسابات الخدمة للاطّلاع على مستندات حول كيفية استخدام OAuth مع حسابات خدمة Google Cloud.

التعديلات على خطط البيانات

في الوقت الحالي، تسمح واجهة برمجة التطبيقات Google Play Data Data Shared API لمشغّل بمشاركة آخر الأخبار حول خطة بيانات المستخدم:

  • حالة خطة البيانات: تسجِّل الحالة الحالية لخطة بيانات المستخدم. على سبيل المثال، إذا نفدت بيانات المستخدم، يمكن لمشغّل إرسال تحديث حالة خطة البيانات إلى GTAF الذي يمكن استخدامه بعد ذلك من خلال GTAF لإرسال إشعار حالة الخطة إلى المستخدم.

وصف واجهة برمجة التطبيقات

الشكل 3. التفاعل مع "هيئة حماية البيانات" (GAAF) و"تعديل بنود معالجة البيانات" (DAP) عندما تشارك "هيئة حماية البيانات" حالة خطة البيانات مع "GTAF".

يمكن للتطبيقات تلقي معلومات حالة خطة البيانات التي تتم مشاركتها مع GTAF بإحدى طريقتين:

  1. تطلب UE من أجل GTAF للحصول على معلومات حالة خطة البيانات:
    1. تستخدم "تعديل بنود معالجة البيانات" الخاص بعامل التشغيل واجهة برمجة التطبيقات لمشاركة بيانات البيانات من أجل إرسال حالة خطة بيانات المستخدمين إلى "GTAF". يخزّن معرّف إعلانات Google (GTAF) حالة الخطة ومفتاح المستخدم المرتبط بها حتى وقت انتهاء الصلاحية الذي يحدّده عامل التشغيل.
    2. يطلب تطبيق Google الذي يتم تشغيله على UE معلومات حالة خطة البيانات باستخدام واجهة برمجة تطبيقات داخلية في Google. يتضمّن التطبيق مفتاح المستخدم في طلبه.
    3. إذا كان يمكن للتطبيق استخدام حالة خطة البيانات المخزّنة مؤقتًا، سيستخدم GTAF مفتاح المستخدم للبحث عن حالة خطة بيانات المستخدم. يعرض GTAF بعد ذلك هذه الحالة على التطبيق.
  2. يرسل نظام GTAF معلومات حالة خطة البيانات إلى UE:
    1. عندما يكون ذلك ملائمًا، يتم إرسال حالة خطة البيانات التي تم استلامها من عامل التشغيل مباشرةً إلى UE. وبشكل خاص، يتم استخدام حالة الخطة المُرسَلة لتعديل ذاكرة التخزين المؤقت على الجهاز لوحدة خطة بيانات الجوّال في خدمات Google Play.

مشاركة حالة خطة البيانات

تستخدم "تعديل بنود معالجة البيانات" طلب HTTP POST لإنشاء وتحديث إدخال حالة الخطة الحالية كي يتمكن المستخدم من استخدامها. يدعم GTAF حاليًا mobiledataPlan وyoutube كمعرّفات عميل صالحة. في ما يلي مثال على طلب عامل تشغيل يتضمّن مشاركة Asn 12345 وuser key abcdef لمعلومات خطة الخطة مع GTAF لعميل youtube:

POST https://mobiledataPlansharing.googleapis.com/v1/operator/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"
}

في حال نجاح الطلب، سيعرض GTAF رمز استجابة HTTP 200 وإدخال PlanStatus الذي تم إرساله مع إدخال إشعارات في حال إرسال أي إشعار إلى المستخدم. إذا اكتشف GTAF مشكلة في الطلب، سيعرض رمز حالة HTTP في النطاق 400-499. إذا تعذّر على GTAF إكمال طلب بسبب خطأ في GTAF، سيعرض GTAF رمز HTTP في النطاق 500-599. تعتبر الطلبات التي تتلقى استجابة في النطاق 500-599 قابلة لإعادة المحاولة، والطلبات التي تتلقى ردًا في النطاق 400-499 لا يمكن بشكل عام إعادة المحاولة. توضّح حالات الخطأ استجابة الخطأ من GTAF بالتفصيل.

إرسال حالة الخطة للعميل التلقائي

يتيح GTAF الاستدعاء التالي حيث يدفع عامل التشغيل حالة الخطة بدون تحديد البرنامج الذي يمكن استخدامه له. في هذه الحالة، نفترض أنّ حالة الخطة مخصّصة لبرنامج mobiledataPlan، ويعتزم المشغّل إرسال إشعار إلى المستخدم. نص الطلب هو مثال PlanStatus

POST https://mobiledataPlansharing.googleapis.com/v1/operator/12345/PlanStatuses?userKey=abcdef

التوافق مع أسواق عالمية

لدعم النشر على نطاق عالمي، يجب أن تعرف "هيئة حماية البيانات" اللغة المفضّلة للمستخدم حتى بدون طلب مباشر من "إطار عمل الشفافية والموافقة". لحل هذه المشكلة، قد يتضمّن طلب نقطة نهاية CPID عنوانًا باللغة المقبولة بناءً على وصول العملاء إلى الإعدادات المفضّلة للغة المستخدم. إذا تم تضمين الرأس، يجب أن تستخدم السلاسل البشرية التي يمكن قراءتها في التحديثات التي ترسلها "هيئة حماية البيانات" باستخدام واجهة برمجة التطبيقات MDP للإعدادات التي تم تقديمها في طلب CPID.

وستعمل "هيئة حماية البيانات" على تعديل الإعدادات المفضّلة المتعلّقة بلغة المستخدم عندما يتلقّى طلبًا من "إطار عمل العلامات" (GTAF) باستخدام عنوان قبول اللغة واستخدام الإعدادات المفضّلة المعدَّلة للمستخدم لتحديد رمز اللغة في الطلبات المستقبلية الموجّهة إلى "إطار عمل Google Play".

يجب أن تحدّد "هيئة حماية البيانات" اللغة المستخدَمة للسلاسل المرئية للمستخدم باستخدام languageCode. يستخدم GTAF هذا لإنشاء عنوان ونص الإشعارات التي يتم عرضها للمستخدم.