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

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

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

אימות

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

תיאור API

ב-GTAF נעשה שימוש במפתח משתמש, שמזהה מנוי למפעיל, בתגובה לשאילתות DPA של האופרטור. כש-GTAF שולח שאילתה לגבי הרשות להגנה על מידע (DPA) מטעם אפליקציות עם גישה ל-MSISSDN, ייתכן ש-MATAF ישתמש ב-MSISSDN. ברמה גבוהה, ה-API של תוכנית הנתונים המוצעים מורכב מהרכיבים הבאים:

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

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

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

אינטראקציה עם GTAF-DPA

אינטראקציה עם GTAF-DPA

איור 4. אפשר להתקשר ולקבל בקשות לתוכניות נתוני משתמשים.

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

  1. הלקוח מבקש סטטוס של חבילת נתונים ו/או מידע אחר על ידי קריאה ל-Google API פרטי. הלקוח כולל את מפתח המשתמש בבקשה אל GTAF.
  2. GTAF משתמש במפתח משתמש ובמזהה לקוח כדי להריץ שאילתה ב-DPA של האופרטור. מזהי הלקוחות הנתמכים הם 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 פונה אליו בשם DPA מזוהה באמצעות 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)כדי ליצור מודל למקרה שבו מודול של התוכנית משותף בין אפליקציות מרובות (למשל 500 MB למשחק ולמוזיקה). ה-PMTC הבאים מוגדרים מראש: 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 פונה אליו בשם DPA מזוהה באמצעות CLIENT_ID. בהתאם להסכם שבין הלקוח ל-Google, הרשות להגנה על מידע (DPA) יכולה להתאים אישית את התגובה ל-GTAF. הפרמטר האופציונלי להקשר הוא ההקשר שבו הבקשה נשלחת. בדרך כלל זוהי מחרוזת שהאפליקציה מעבירה לאופרטור דרך GTAF.

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

{
    "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 Services. זאת כדי להבטיח חוויית משתמש טובה למשתמשים ב-Google Play Services.

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

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

רכישת נתונים

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

בקשת עסקה

כאשר היא מקבלת בקשה מלקוח, 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 גרועה של בקשה, המודיעה ל-GTAF שמזהה התוכנית שנרכש אינו חוקי.
  • הרשות להגנה על מידע (DPA) מחזירה קוד שגיאה 402 של תשלום נדרש, המציין ש-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 SHELA יקבל את ההנחה שהתוכנית הופעלה.

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) תחזיר שגיאה במקרים הבאים:

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

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

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

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

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

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

POST DPA_URL/הרשמה

גוף הבקשה יהיה מופע של 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 SHOULD ישלח עדכונים אל תוכנית הנתונים של המשתמש עד לתאריך expirationTime.

אם מתרחשת שגיאה, יש להחזיר שגיאה Response:

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

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

ממשק API למעקב

בתרחישי שימוש מסוימים, כדי לעקוב אחרי הרשות להגנה על מידע (DPA), נדרשים התקשרות של GPAF. בתרחישי השימוש האלה, הגדרנו ממשק API למעקב.

הגדרת API

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

DPA_URL/dpaStatus

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

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

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

התנהגות DPA

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

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

התנהגות GTAF

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

מקרי שגיאה

אם מדובר בשגיאה, הרשות להגנה על מידע (DPA) אמורה להחזיר קוד מצב HTTP התואם לאחד מהבאים:

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

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

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

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

אחרת, הרשות להגנה על מידע (DPA) החזירה אישור 200. חשוב לנו לציין שהערכים של cause משמשים לכל התגובות.

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

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

אם הארגון להגנה על מידע (DPA) אינו תומך בשפה שהמשתמש ביקש, הוא יכול להשתמש בשפת ברירת מחדל ולהשתמש בשדה LanguageCode כדי לציין את הבחירה שלו.