ממשק API לשיתוף תוכניות נתונים לנייד של Google

למה בחרנו לעשות זאת?

‫Google Mobile Data Plan Sharing API מאפשר למפעיל לשלוח מידע על חבילת הגלישה של משתמש (שמזוהה באמצעות מפתח משתמש) אל GTAF. בדף הזה אנחנו מתארים את המנגנון שבאמצעותו אפשר להעביר את העדכונים האלה ל-GTAF וכך לאפליקציות של Google. ה-API מאפשר כרגע ל-DPA לשלוח את סטטוס תוכנית הנתונים ל-GTAF כדי שלקוח Google יוכל להשתמש בו.

אימות

כל הבקשות ל-Data Plan Sharing API אל GTAF חייבות להיות מאומתות באמצעות שרת Google Cloud OAuth2. הבקשות צריכות להיות מאומתות כחשבון שירות שנכלל ברשימת ההיתרים בפורטל ספקי האינטרנט עבור מספר מערכת אוטונומית (ASN) שהסכם ה-DPA מייצג. במאמר Google Cloud OAuth 2.0 for Service Accounts אפשר לקרוא על השימוש ב-OAuth עם חשבונות שירות של Google Cloud.

עדכונים לגבי חבילת גלישה

בשלב הזה, Google Mobile Data Plan Sharing API מאפשר למפעיל לשתף עדכונים לגבי חבילת הגלישה של המשתמש:

• סטטוס תוכנית הגלישה: הסטטוס הנוכחי של תוכנית הגלישה של המשתמש. לדוגמה, אם למשתמש עומדים להסתיים הנתונים בחבילת הגלישה, מפעיל יכול לשלוח עדכון סטטוס של חבילת הגלישה ל-GTAF, ואז GTAF יכול לשלוח למשתמש התראה על יתרה נמוכה.

זיהוי משתמשים רלוונטיים

ה-DPA צריך דרך לקבוע את הנתונים של אילו משתמשים לשלוח ל-GTAF. מערכת GTAF מצפה לקבל עדכונים לגבי המשתמשים הבאים:

1. מזהי CPID פעילים: משתמשים עם מזהי CPID פעילים. עד שהמזהים מסוג CPID שנוצרו על ידי נקודת הקצה של CPID יהיו תקפים, ה-DPA צריך לשלוח עדכונים לגבי תוכנית הנתונים של המשתמש. אם הכותרת Accept-Language הוגדרה בזמן יצירת ה-CPID, המחרוזות שניתנות לקריאה על ידי בני אדם בסטטוס של תוכנית הנתונים חייבות להיות בשפה הזו.
2. מספרי MSISDN רשומים: כדי להציג אפליקציות שיש להן גישה למספר MSISDN, ‏ GTAF ירשום את מספר ה-MSISDN ב-DPA כמו שמתואר בקטע רישום מספר MSISDN ב-API של Data Plan Agent. אחרי שרושמים את מספר ה-MSISDN, ספק ה-DPA צריך לשלוח עדכונים לגבי תוכנית הנתונים של המשתמש עד שתוקף הרישום יפוג.

תיאור ה-API

סטטוס של תוכנית שיתוף נתונים

איור 3. אינטראקציה בין GTAF ל-DPA כש-DPA משתף את סטטוס חבילת הגלישה עם GTAF.

יש שתי דרכים שבהן אפליקציות יכולות לקבל מידע על הסטטוס של חבילת השימוש בנתונים סלולריים:

1. מכשיר ה-UE קורא ל-GTAF כדי לקבל מידע על סטטוס חבילת השימוש בנתונים:
   1. הסכם ה-DPA של המפעיל משתמש ב-Data Plan Sharing API כדי לשלוח את סטטוס חבילת הגלישה של המשתמש ל-GTAF. ב-GTAF מאוחסן סטטוס התוכנית ומפתח המשתמש שמשויך אליה.
   2. אפליקציית Google שפועלת ב-UE מבקשת את המידע על סטטוס חבילת הנתונים באמצעות Google-internal API. האפליקציה כוללת את מפתח המשתמש בבקשה שלה.
   3. אם האפליקציה יכולה להשתמש בסטטוס של תוכנית נתונים שמאוחסן במטמון, GTAF משתמש במפתח המשתמש כדי לחפש את הסטטוס של תוכנית הנתונים של המשתמש. לאחר מכן, GTAF מחזיר את הסטטוס הזה ל-UE.
2. ‫GTAF מעביר מידע על סטטוס תוכנית הנתונים אל ה-UE:
   1. במקרים הרלוונטיים, הסטטוס של תוכנית הנתונים שמתקבל מהמפעיל נשלח ישירות אל ציוד הקצה.

GTAF-DPA Interaction

ה-DPA משתמש ב-HTTPS POST כדי ליצור ולעדכן רשומה קיימת של סטטוס התוכנית עבור משתמש, לשימוש על ידי לקוח. נכון לעכשיו, GTAF תומך ב-mobiledataplan וב-youtube כמזהי לקוח תקינים. זו דוגמה לבקשה של מפעיל עם מספר ASN‏ 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 שנשלח עם ערך של התראות אם נשלחה התראה למשתמש. אם הכלי לניתוח תנועה ב-Google יזהה בעיה בבקשה, הוא יחזיר קוד סטטוס HTTP בטווח 400-499. אם 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 שולח באמצעות ה-API של MDP חייבות להשתמש בהגדרות שסופקו בבקשת ה-CPID.