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

الحافز

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

المصادقة

يجب مصادقة جميع طلبات Data Plan Sharing API الموجّهة إلى GTAF باستخدام خادم Google Cloud OAuth2. يجب أن تتم مصادقة الطلبات كحساب خدمة تمت إضافته إلى القائمة البيضاء في بوابة موفّر خدمة الإنترنت لرقم نظام مستقل (ASN) الذي تمثّله اتفاقية معالجة البيانات. راجِع بروتوكول OAuth 2.0 من Google Cloud لحسابات الخدمة للاطّلاع على مستندات حول كيفية استخدام بروتوكول OAuth مع حسابات خدمة Google Cloud.

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

تسمح واجهة برمجة التطبيقات Google Mobile Data Plan Sharing API حاليًا لمشغّل شبكة الجوّال بمشاركة تحديثات حول خطة بيانات المستخدم:

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

تحديد المستخدمين ذوي الصلة

يحتاج "مزوّد منصة البيانات" إلى طريقة لتحديد بيانات المستخدمين التي سيتم إرسالها إلى GTAF. يتوقّع GTAF تلقّي إشعارات بشأن المستخدمين التاليين:

1. معرّفات المحتوى الشريك النشطة: المستخدمون الذين لديهم معرّفات محتوى شريك نشطة إلى أن تصبح معرّفات CPID التي تم إنشاؤها بواسطة نقطة نهاية CPID صالحة، يجب أن يرسل DPA تعديلات بشأن خطة بيانات المستخدم. إذا تم ضبط عنوان Accept-Language عند إنشاء CPID، يجب أن تكون السلاسل القابلة للقراءة البشرية في حالة خطة البيانات بتلك اللغة.
2. أرقام MSISDN المسجّلة: لعرض التطبيقات التي يمكنها الوصول إلى رقم MSISDN، ستسجّل GTAF رقم MSISDN لدى DPA كما هو موضّح في قسم تسجيل رقم MSISDN ضمن Data Plan Agent API. بعد تسجيل رقم MSISDN، على DPA إرسال إشعارات بشأن خطة بيانات المستخدم إلى أن تنتهي صلاحية التسجيل.

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

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

الشكل 3. تفاعل GTAF-DPA عندما تشارك DPA حالة خطة البيانات مع GTAF

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

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

التفاعل بين إطار عمل تقييم التهديدات العالمية (GTAF) واتفاقية معالجة البيانات (DPA)

تستخدم DPA طلب HTTPS POST لإنشاء وتعديل إدخال حالة خطة حالية ليستخدمه العميل. تتيح GTAF حاليًا استخدام mobiledataplan وyoutube كمعرّفات صالحة للعملاء. في ما يلي مثال على طلب من مشغّل لديه رقم نظام مستقل 12345 ومفتاح مستخدم abcdef يشارك معلومات الخطة مع GTAF لعميل youtube:

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. في حال تضمين العنوان، يجب أن تستخدم السلاسل القابلة للقراءة في التحديثات التي يرسلها "مزوّد بيانات الاعتماد" باستخدام واجهة برمجة تطبيقات MDP الإعدادات المتوفّرة في طلب CPID.