واجهة برمجة تطبيقات مشاركة خطة بيانات الجوّال من 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 لإرسال إشعار منخفض الرصيد إلى المستخدم.

تحديد المستخدمين المعنيين

تحتاج "هيئة حماية البيانات" إلى طريقة لتحديد المستخدمين الذين يمكن إرسال بياناتهم إلى "إطار الشفافية والموافقة". يتوقع GTAF تلقي تحديثات للمستخدمين التاليين:

1. أرقام CPID النشطة: المستخدمون الذين لديهم أرقام CPID نشطة. إلى أن تكون معرّفات CPID التي تم إنشاؤها من خلال نقطة نهاية CPID صالحة، يجب أن ترسل "هيئة حماية البيانات" آخر الأخبار حول خطة بيانات المستخدمين. إذا تم ضبط العنوان Accept-Language في وقت إنشاء معرّف CPID، يجب أن تكون السلاسل البشرية القابلة للقراءة في حالة خطة البيانات بهذه اللغة.
2. رموز MSISDN المسجَّلة: لعرض التطبيقات التي يمكنها الوصول إلى MSISDN، سيسجّل GTAF معرّف MSISDN مع "تعديل بنود معالجة البيانات" كما هو موضّح في قسم msisdn للتسجيل في واجهة برمجة تطبيقات وكيل خطة البيانات. بعد تسجيل MSISDN، يجب أن ترسل "هيئة حماية البيانات" آخر الأخبار حول خطة بيانات المستخدِم إلى أن تنتهي صلاحية التسجيل.

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

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

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

يمكن للتطبيقات أن تتلقّى معلومات عن حالة خطة البيانات بطريقتين:

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

تفاعل GTAF-DPA

تستخدم "تعديل بنود معالجة البيانات" طلب 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

{
  "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 في القسم المرجعي.

في حال نجاح الطلب، سيعرض 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/operator/12345/PlanStatuses?userKey=abcdef

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

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