ממשק 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 יכול לשלוח התראה למשתמש לגבי סטטוס התוכנית.

תיאור ה-API

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

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

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

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

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

שליחת סטטוס התוכנית ללקוח ברירת המחדל

פרוטוקול GTAF תומך בקריאה הבאה, שבה המפעיל מעביר את סטטוס התוכנית בלי לציין את הלקוח שאפשר להשתמש בה עבורו. במקרה הזה, אנחנו מניחים שסטטוס התוכנית מיועד ללקוח mobiledataplan והמפעיל מתכוון לשלוח התראה למשתמש. גוף הבקשה הוא מופע של PlanStatus

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

אינטרנציונליזציה

כדי לתמוך בבינאום, ה-DPA צריך לדעת את שפת ברירת המחדל של המשתמש גם ללא בקשה ישירה מ-GTAF. כדי לפתור את הבעיה הזו, יכול להיות שהבקשה לנקודת הקצה של CPID תכלול כותרת Accept-Language, בהתאם לגישת הלקוחות להעדפות השפה של המשתמש. אם הכותרת כלולה, מחרוזות שניתנות לקריאה על ידי בני אדם בעדכונים שספק ה-DPA שולח באמצעות MDP API חייבות להשתמש בהגדרות שסופקו בבקשת ה-CPID.

ה-DPA עשוי לעדכן את העדפות השפה של המשתמשים כשהוא מקבל בקשה מ-GTAF עם כותרת Accept-Language, ולהשתמש בהעדפות המשתמשים המעודכנות כדי לקבוע את קוד השפה בבקשות עתידיות ל-GTAF.

בהסכם בנושא עיבוד נתונים צריך לציין את השפה שבה מוצגות מחרוזות למשתמשים באמצעות languageCode. הכלי GTAF משתמש בזה כדי ליצור את הכותרת ואת גוף ההודעות שמוצגות למשתמש.