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

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

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

אימות

כל בקשות ה-API לשיתוף נתונים ב-GTAF צריכות לעבור אימות באמצעות שרת Google Cloud OAuth2. הבקשות צריכות להיות מאומתות כחשבון שירות שנכלל בפורטל ה-ISP עבור ה-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 מבקשת מידע על סטטוס תוכנית הנתונים באמצעות API פנימי של Google. הבקשה כוללת את מפתח המשתמש שבבקשה.
   3. אם האפליקציה יכולה להשתמש בסטטוס של חבילת נתונים ששמורה במטמון, GTAF משתמש במפתח המשתמש כדי לחפש את סטטוס תוכנית הנתונים של המשתמש. לאחר מכן, GTAF מחזיר את הסטטוס הזה לאפליקציה.
2. GTAF שולח את פרטי הסטטוס של תוכנית הנתונים ל-UE:
   1. כאשר זה רלוונטי, סטטוס תוכנית הנתונים שמתקבל מהמפעיל מועבר ישירות ישירות אל ה-UE. באופן ספציפי, הסטטוס של התוכנית בדחיפה משמש לעדכון המטמון במכשיר של מודול חבילת הגלישה בשירותי Google Play.

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

הרשות להגנה על מידע (DPA) משתמשת ב-HTTPS POST כדי ליצור ולעדכן רשומה קיימת של סטטוס התוכנית, כדי שהלקוח יוכל להשתמש בה. כרגע GTAF תומך ב-mobiledataplan וב-youtube כמזהי לקוח חוקיים. לפניכם בקשה לדוגמה לאופרטור עם הרשאות שיתוף מסוג 12345 ו-user key 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 מתואר בקטע העזר.

אם הבקשה תתקבל בהצלחה, GTAF יחזיר את הקוד 200 של HTTP ואת הרשומה 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 עשויה לכלול כותרת Get-Language בהתאם ללקוחות בעלי גישה להעדפות שפת המשתמש. אם הכותרת כוללת את המחרוזות האנושיות הניתנות לקריאה בעדכונים שנשלחים על ידי ה-DPA באמצעות ה-MDP API, יש להשתמש בהגדרות שצוינו בבקשת ה-CPID.

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

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