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

الحافز

تتيح واجهة برمجة التطبيقات Google Mobile Data Plan Sharing API للمشغّل إرسال معلومات حول خطة بيانات المستخدم (المحدّد من خلال مفتاح المستخدم) إلى GTAF. في هذه الصفحة، نوضّح الآلية التي يمكن من خلالها إرسال هذه التحديثات إلى "إطار عمل Google للتطبيقات" وبالتالي إلى تطبيقات Google. تسمح واجهة برمجة التطبيقات حاليًا لـ DPA بإرسال حالة خطة البيانات إلى 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 هذا التعديل لإرسال إشعار بحالة الخطة إلى المستخدم.

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

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

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

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

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

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

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 غير قابلة لإعادة المحاولة بشكل عام. توضّح حالات الخطأ بالتفصيل الردود التي تتضمّن أخطاء من GTAF.

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

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

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

التدويل

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

يجوز لـ "اتفاقية معالجة البيانات" تعديل إعدادات اللغة المفضّلة للمستخدم عندما تتلقّى طلبًا من "إطار عمل الترجمة العالمي" يتضمّن عنوان Accept-Language، كما يجوز لها استخدام إعدادات المستخدم المعدَّلة لتحديد رمز اللغة في الطلبات المستقبلية إلى "إطار عمل الترجمة العالمي".

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