ממשק API של סוכן תוכנית הנתונים

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

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

אימות

לפני ש-GTAF יכול להתקשר, ה-DPA צריך לאמת את GTAF. כחלק מתהליך צירוף המפעיל, נבדוק את התוקף של אישור ה-SSL של DPA. נכון לעכשיו, אנחנו דורשים שימוש ב-OAuth2 לאימות הדדי.

תיאור ה-API

כש-GTAF שולח שאילתה ל-DPA של המפעיל, הוא משתמש במפתח משתמש שמזהה מנוי של המפעיל. כש-GTAF שולח שאילתה ל-DPA בשם אפליקציות שיש להן גישה ל-MSISDN, ‏ GTAF עשוי להשתמש ב-MSISDN. באופן כללי, ה-API של סוכן תוכנית הנתונים המוצע מורכב מהרכיבים הבאים:

  1. מנגנון לשליחת שאילתה לגבי סטטוס תוכנית הנתונים של המשתמש.
  2. מנגנון להפעלת שאילתות ב-DPA כדי לקבל מידע על חבילות נתונים למשתמש.
  3. מנגנון לביצוע שינויים בתוכנית הנתונים של המשתמש (למשל, רכישת תוכנית חדשה).
  4. מנגנון שמאפשר לבדוק אם משתמש עומד בדרישות לרכישת חבילת נתונים מסוימת.
  5. מנגנון שמאפשר ל-GTAF לרשום מספרי MSISDN אצל רשות הגנת המידע.
  6. מנגנון שמאפשר ל-GTAF לוודא ש-DPA נמצא במצב תקין.

בהמשך המסמך מוסבר על כל אחד מרכיבי ה-API האלה. אלא אם צוין אחרת במפורש, כל התקשורת חייבת להתבצע באמצעות HTTPS (עם אישור SSL תקף של DPA). בהתאם לתכונות הספציפיות שנתמכות, יכול להיות שמפעיל יבחר להטמיע את כל רכיבי ה-API האלה או רק חלק מהם.

שליחת שאילתות לגבי הסטטוס של תוכנית נתונים

GTAF-DPA Interaction

GTAF-DPA Interaction

איור 4. תרשים זרימת שיחה לבקשה ולקבלת מידע על תוכנית נתונים של משתמש.

איור 4 מציג את רצף הפעולות שקשורות לשאילתה של לקוח לגבי סטטוס חבילת הגלישה של המשתמש ופרטים נוספים על חבילת הגלישה. תרשים זרימת השיחות הזה משותף לקריאות ל-API שמופעלות על ידי הלקוח ב-UE.

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

שלבים 1 ו-3 באיור 4 הם ממשקי API פרטיים של Google, ולכן לא מתואר מידע נוסף לגביהם. שלב 2 הוא API ציבורי שמתואר בהמשך. ה-DPA חייב להתייחס לכותרת ה-HTTP‏ Cache-Control: no-cache כשמגישים את הקריאות האלה ל-API מ-GTAF.

סטטוס התוכנית

כדי לקבל את סטטוס התוכנית, GTAF שולח את בקשת ה-HTTP הבאה:

GET DPA_URL/{userKey}/planStatus?key_type={CPID,MSISDN}&client_id=CLIENT_ID

הלקוח שבשמו GTAF יוצר קשר עם רשות הגנת המידע מזוהה באמצעות CLIENT_ID. בהתאם להסכם בין לקוח Google לבין הספק, ה-DPA יכול להתאים אישית את התגובה ל-GTAF. פורמט התגובה הוא אובייקט JSON שמייצג 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"
    }]
  }],
  "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"
  "planInfoPerClient": {
    "youtube": {
      "rateLimitedStreaming": {
        "maxMediaRateKbps": 256
      }
    }
  }
}

הבקשה חייבת לכלול כותרת Accept-Language שמציינת את השפה שבה צריכות להיות המחרוזות שניתנות לקריאה על ידי בני אדם (למשל, תיאורי תוכניות).

בתוכניות שמשלמים עליהן בסוף התקופה, expirationTime חייב להיות תאריך החידוש של התוכנית (כלומר, התאריך שבו יתרת הנתונים מתעדכנת או נטענת מחדש).

כל מודול תוכנית עשוי להכיל כמה קטגוריות תנועה של מודול תוכנית (PMTCs)כדי ליצור מודל למקרה שבו מודול תוכנית משותף בין כמה אפליקציות (למשל, ‫500MB (למשחקים ולמוזיקה). הגדרנו מראש את המאפיינים הבאים של תנועת גולשים שניתן למדוד: GENERIC, VIDEO, VIDEO_BROWSING, VIDEO_OFFLINE, MUSIC, GAMING, SOCIAL and MESSAGING. מומלץ שמפעילים יפנו לצוותים שונים ב-Google כדי להגיע להסכמה לגבי קבוצת קטגוריות התנועה והסמנטיקה שלהן שרלוונטיות לאפליקציות שונות של Google.

שאילתות לגבי מבצעים של תוכניות

הכלי GTAF שולח את בקשת ה-HTTP הבאה כדי לקבל הצעות לתוכניות מהספק:

GET DPA_URL/{userKey}/planOffer?key_type={CPID,MSISDN}&client_id=CLIENT_ID&context={purchaseContext}

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

גוף התשובה מכיל מופע של PlanOffer.

{
    "offers": [
      {
        "planName": "ACME Red", // req.
        "planId": "turbulent1", // req.
        "planDescription": "Unlimited Videos for 30 days.", // req.
        "promoMessage": "Binge watch videos.",
        "languageCode": "en_US", // req.
        "overusagePolicy": "BLOCKED",
        "cost": { // req.
          "currencyCode": "INR",
          "units": "300",
          "nanos": 0
        },
        "duration": "2592000s",
        "offerContext": "YouTube",
        "trafficCategories": ["VIDEO"],
        "quotaBytes": "9223372036850"
      }
    ],
    "expireTime": "2019-03-04T00:06:07Z" // req.
}

הסדר של תוכניות הנתונים במערך offers עשוי לקבוע את הסדר שבו תוכניות הנתונים מוצגות למשתמשים. בנוסף, אם האפליקציה יכולה להציג רק x תוכניות בגלל מגבלות בממשק המשתמש או מגבלות אחרות, והתגובה מכילה רק y > x תוכניות, רק x התוכניות הראשונות יוצגו. ‫GTAF משתף עד 10 תוכניות אם האפליקציה שמבצעת שאילתה לגבי מבצעים היא ממשק המשתמש של חבילת גלישה לנייד, שהוא חלק משירותי Google Play. המטרה היא להבטיח חוויית משתמש טובה למשתמשים בשירותי Google Play.

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

הבקשה חייבת לכלול כותרת Accept-Language שמציינת את השפה שבה צריכות להיות המחרוזות שניתנות לקריאה על ידי בני אדם (למשל, תיאורי תוכניות).

רכישת חבילת גלישה

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

Transaction Request

אחרי ש-GTAF מקבל בקשה מלקוח, הוא שולח בקשת POST ל-DPA. כתובת ה-URL של הבקשה היא:

POST DPA_URL/{userKey}/purchasePlan?key_type={CPID,MSISDN}&client_id=CLIENT_ID

כאשר userKey הוא CPID או MSISDN. גוף הבקשה הוא מופע של TransactionRequest שכולל את השדות הבאים:

{
  "planId": string,         // Id of plan to be purchased. Copied from
                            // offers.planId field returned from a
                            // Upsell Offer request,
                            // if available. (req.).
  "transactionId": string,  // Unique request identifier (req.)
  "offerContext": string,   // Copied from from the
                            // offers.offerContext, if available.
                            // (opt.)
  "callbackUrl": string     // URL that the DPA can call back with response once
                            // it has handled the request.
}

תגובה לעסקה

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

  • ה-DPA מחזיר קוד שגיאה 400 BAD REQUEST, שמציין ל-GTAF שמזהה התוכנית שנרכשה לא תקין.
  • ה-DPA מחזיר קוד שגיאה 402 PAYMENT REQUIRED (נדרש תשלום), שמציין ל-GTAF שלמשתמש אין מספיק יתרה כדי להשלים את הרכישה.
  • ה-DPA מחזיר קוד שגיאה 409 CONFLICT, שמציין ל-GTAF שהתוכנית שרוצים לרכוש לא תואמת לשילוב המוצרים הנוכחי של המשתמש. לדוגמה, אם מדיניות תוכנית הנתונים של הספק לא מאפשרת לשלב בין תוכניות בתשלום חודשי לבין תוכניות בתשלום מראש, ניסיון לרכוש תוכנית בתשלום מראש עבור משתמש עם תוכנית בתשלום חודשי יוביל לשגיאה 409 CONFLICT.
  • ה-DPA מחזיר קוד שגיאה 403 FORBIDDEN, שמציין ל-GTAF שהעסקה הנוכחית היא כפילות של עסקה שהונפקה בעבר. ה-DPA צריך להחזיר את הסיבות הבאות לשגיאה בתגובה:
    • אם העסקה הקודמת נכשלה, הסיבה לשגיאה מציינת את הסיבה לכשל.
    • אם העסקה הקודמת בוצעה בהצלחה, הערך הוא DUPLICATE_TRANSACTION.
    • אם העסקה הקודמת עדיין בתור, הערך הוא REQUEST_QUEUED.

ה-DPA יפיק תגובה מסוג 200-OK רק לעסקה שבוצעה בהצלחה או לעסקה שהוכנסה לתור. במקרה של עסקה בתור, ה-DPA ימלא רק את סטטוס העסקה וישאיר את שאר השדות בתגובה ריקים. ה-DPA חייב להתקשר חזרה ל-GTAF עם תשובה אחרי שטרנזקציה שהוכנסה לתור טופלה. גוף התשובה הוא מופע של TransactionResponse שכולל את הפרטים הבאים:

{
  "transactionStatus": "SUCCESS",

  "purchase": {
    "planId": string,               // copied from request. (req.)
    "transactionId": string,        // copied from request. (req.)
    "transactionMessage": string,   // status message. (opt.)
    "confirmationCode": string,     // DPA-generated confirmation code
                                    // for successful transaction. (opt.)
    "planActivationTime" : string,  // Time when plan will be activated,
                                    // in timestamp format. (opt.)
  },

  // walletInfo is populated with the balance left in the user's account.
  "walletBalance": {
    "currencyCode": string,       // 3-letter currency code defined in ISO 4217.
    "units": string,              // Whole units of the currency amount.
    "nanos": number               // Number of nano units of the amount.
  }
}

אם הערך planActivationTime חסר, מערכת GTAF תניח שהתוכנית הופעלה.

יכול להיות ש-GTAF ישלח את הבקשה הבאה כדי להעביר את העדפת הסכמת המשתמשים אל הספק.

POST DPA_URL/{userKey}/consent?key_type={CPID,MSISDN}&client_id=CLIENT_ID

כאשר userKey הוא CPID או MSISDN. גוף הבקשה הוא מופע של SetConsentStatusRequest.

אם הפעולה בוצעה ללא שגיאות, גוף התגובה יהיה ריק.

זכאות

יכול להיות ש-GTAF ישלח את בקשת הזכאות הבאה כדי לבדוק אם משתמש זכאי לרכוש תוכנית.

GET DPA/{userKey}/Eligibility/{planId}?key_type={CPID,MSISDN}

שימו לב ש-planId הוא המזהה הייחודי של המינוי שאפשר להשתמש בו כדי לרכוש את המינוי בשם המשתמש (ראו רכישת נתונים). אם לא מציינים את planId, הספק חייב להחזיר את כל התוכניות שזמינות לרכישה על ידי המשתמש.

במקרה של שגיאה, ה-DPA יחזיר את הסיבות הנפוצות לשגיאות. בנוסף, ה-DPA יחזיר שגיאה במקרים הבאים:

  • ה-DPA מחזיר קוד שגיאה 400 BAD REQUEST, שמציין ל-GTAF ש-planId לא תקין.
  • ה-DPA מחזיר קוד שגיאה 409 CONFLICT, שמציין ש-planId לא תואם לתוכנית הנתונים של המשתמש.

אחרת, הרשות להגנה על מידע תחזיר תשובה 200-OK. המבנה של EligibilityResponse מוצלח הוא:

{
  "eligiblePlans":
  [
   {
    "planId": string,   // Plan identifier. Can be used to
                        // refer to the plan during
                        // offers, etc. (req.)
   }
  ]
}

אם הבקשה כוללת planId, התשובה כוללת רק את התוכנית הזו. אחרת, הרשימה כוללת את כל התוכניות שהמשתמש יכול לרכוש. במקרה שבו planId ריק וה-DPA לא תומך בהחזרת רשימת התוכניות שעומדות בדרישות, הוא חייב להחזיר שגיאה מסוג 400 BAD REQUEST.

נקודת קצה לרישום MSISDN

כדי להציג אפליקציות שיש להן גישה ל-MSISDN, ‏ GTAF ירשום את ה-MSISDN ב-DPA. ה-GTAF רושם את מספר ה-MSISDN רק כשיש אפליקציות שמופעלות על ידי Google Mobile Data Plan Sharing API, שבהן ה-DPA שולח מידע ל-GTAF באמצעות ממשקי Google API. כדי לרשום מספר MSISDN, ‏ GTAF שולח בקשת POST אל ה-DPA:

POST DPA_URL/register

גוף הבקשה יהיה מופע של RegistrationRequest.

{
  "msisdn": "<msisdn_string>"
}

אם הרישום של מספר ה-MSISDN מצליח, ספק ה-DPA חייב להחזיר תגובה מסוג 200 OK, כולל RegistrationResponse. הפורמט של ה-JSON הוא:

{
  // msisdn that was registered.
  "msisdn": "<msisdn_string>",
  // time after which DPA will not send updates to GTAF.
  "expirationTime": string
}

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

אם מתרחשת שגיאה, צריך להחזיר ErrorResponse:

{
    "error": "<error message>",
    "cause": enum(ErrorCause)
}

הרשימה המלאה של ערכי הסיבה האפשריים וקודי סטטוס HTTP לתנאי שגיאה שונים זמינה כאן. בפרט, אם מתקבלת בקשת רישום של מספר MSISDN עבור משתמש שנמצא בנדידה או שלא הסכים לשיתוף מידע על תוכנית הנתונים עם Google, ספק ה-DPA חייב להחזיר קוד סטטוס HTTP‏ 403.

Monitoring API

יש תרחישי שימוש שבהם נדרש GTAF כדי לעקוב אחרי ה-DPA ולזהות כשלים ב-DPA. לתרחישים האלה הגדרנו API למעקב.

הגדרת API

ה-API למעקב צריך להיות זמין באמצעות בקשת HTTP GET בכתובת ה-URL הבאה:

DPA_URL/dpaStatus

אם ה-DPA וכל שרתי הקצה העורפי שלו פועלים בצורה תקינה, ה-DPA אמור להגיב לשאילתה הזו עם קוד הסטטוס 200 של HTTP וגוף תגובה עם מופע של DpaStatus.

{
    "status": enum(DpaStatusEnum),
    "message": "<optional human-readable status description>"
}

אם ה-DPA או אחד מהבקאנדים שלו לא פועלים בצורה תקינה, הוא צריך להגיב עם קוד סטטוס HTTP 500 וגוף תגובה עם מופע של DpaStatus.

התנהגות של DPA

כשמזוהה כשל, ספק ה-DPA צריך להחזיר את הסטטוס 'לא זמין' לכל השאילתות של dpaStatus. בנוסף, עליהם להפסיק לשלוח מידע על חבילות גלישה עם תקופות ארוכות של שמירת נתונים במטמון. יכול להיות שהמערכת תפסיק לשלוח תשובות עם תקופות ארוכות של שמירה במטמון באחת משתי דרכים:

  1. מתחילים להגדיר זמני תפוגה קצרים של מטמון.
  2. להפסיק לשלוח מידע על חבילת הגלישה.

התנהגות של GTAF

הכלי GTAF יבצע מעת לעת בדיקה של dpaStatus. אם המערכת מזהה כשל ב-DPA (על סמך התשובה 'לא זמין'), היא מנקה את המטמון של האופרטור.

סוגי שגיאות

במקרה של שגיאה, ה-DPA צפוי להחזיר קוד סטטוס HTTP שתואם לאחד מהבאים:

  • המשתמש נמצא כרגע בנדידה והשאילתה בנושא DPA מושבתת עבור המשתמש הזה. ה-DPA מחזיר שגיאה מסוג 403.
  • ה-DPA מחזיר קוד שגיאה 404 NOT_FOUND, שמציין ל-GTAF שמפתח המשתמש לא תקין (כלומר, מפתח המשתמש לא קיים).
  • ה-DPA מחזיר קוד שגיאה 410 GONE, שמציין ל-GTAF שהלקוח צריך לקבל מפתח משתמש חדש אם key_type = CPID ותוקף ה-CPID פג.
  • ה-DPA מחזיר קוד שגיאה 501 NOT_IMPLEMENTED, שמציין שהוא לא תומך בקריאה הזו.
  • השירות לא זמין באופן זמני. ה-DPA מחזיר 503 SERVICE UNAVAILABLE עם הכותרת Retry-After שמציינת מתי אפשר לנסות לשלוח בקשה חדשה.
  • ה-DPA מחזיר את קוד השגיאה 500 INTERNAL SERVER ERROR לכל שאר השגיאות שלא צוינו.
  • הרשות להגנה על מידע מחזירה שגיאה 429 TOO_MANY_REQUESTS עם הכותרת Retry-After שמציינת ש-GTAF שולח יותר מדי בקשות לרשות להגנה על מידע.
  • הרשות להגנה על מידע מחזירה שגיאת 409 CONFLICT, שמעידה על כך שאי אפשר להשלים את הבקשה בגלל התנגשות עם המצב הנוכחי של הרשות להגנה על מידע.

בכל מקרי השגיאה, גוף תגובת ה-HTTP חייב לכלול אובייקט JSON עם מידע נוסף על השגיאה. התוכן של תגובת השגיאה חייב להכיל מופע של ErrorResponse.

{
  "error": string,
  "cause": enum(ErrorCause)
}

הערכים של cause שמוגדרים כרגע מפורטים בחלק של ErrorCause בהפניה ל-API.

אחרת, ה-DPA מחזיר 200 OK. חשוב לציין שהערכים האלה של cause משמשים בכל התשובות.

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

בקשות GTAF אל ה-DPA כוללות כותרת Accept-Language שמציינת את השפה שבה צריכים להיות המחרוזות שניתנות לקריאה על ידי בני אדם (לדוגמה, תיאורי תוכניות). בנוסף, תשובות של DPA (‏PlanStatus,‏ PlanOffers) כוללות שדה חובה languageCode, שהערך שלו הוא קוד השפה BCP-47 (לדוגמה, ‫("en-US") של התגובה.

אם ה-DPA לא תומך בשפה שהמשתמש ביקש, הוא יכול להשתמש בשפת ברירת מחדל ולציין את הבחירה שלו בשדה languageCode.