ניהול גרסאות

ל-API ל-REST של Ad Manager יש שמות לגרסאות ראשיות וגם גרסאות פנימיות תואמות לאחור לגרסה הראשית הנוכחית.

בכל שלב אפשר לסמן שירותים, שיטות ושדות כשירותים שהוצאו משימוש במסגרת הגרסה הראשית (למשל v1), עם זאת, היא תמשיך להיות נתמכת עד הגרסה הראשית הוצאה משימוש.

הגרסאות הראשיות

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

ל-API ל-REST של Ad Manager אין קצב הפצה קבוע ל-Major גרסאות שונות. גרסאות ראשיות חדשות יושקו רק בעת הצורך.

גרסאות במקום

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

תאימות לאחור

המערכת שומרת על התאימות לאחור לשינויים בתוך הגרסה הראשית. תאימות מוגדרת כך:

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

  2. תאימות להעברה בנקאית: קוד שנכתב ביחס לגרסה קודמת מתקשר כראוי עם שרת חדש יותר. במילים אחרות, לא רק קלט והפלט תואם לפלט, אבל הציפיות מפעולה סריאלית ועלות המרה (deserialization). להמשיך בהתאמה.

  3. תאימות סמנטית: קוד שנכתב ביחס לגרסה קודמת ממשיך כדי לקבל את מה שרוב המפתחים הסבירים יצפו בו.

בטבלאות הבאות מפורטים סוגים של שינויים ב-API והאם הם מביאים בחשבון תאימות לאחור.

שירותים

סוג השינוי תאימות לאחור
הוספת שירות חדש כן
הסרת שירות לא

שיטות

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

אובייקטים

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

ערכים של ספירה

סוג השינוי תאימות לאחור
מוסיפים ערך של enum כן
הסרת ערך של enum לא

התנהגות שדות שהוצאה משימוש

שדות החלפה

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

נבחן את הסכימה הבאה:

{
  // The cost of this Foo in micros.
  // Deprecated: Use `cost` instead.
  "costMicros": number,

  // The cost of this Foo.
  "cost": {
    object (Money)
  }
}

תגובת קריאה מאכלסת ערכים מקבילים בשני השדות:

{
  "costMicros": 1250000,
  "cost": {
    "currencyCode": "USD",
    "units": "1",
    "nanos": 250000000
  }
}

בקשות עדכון יכולות להגדיר כל אחד מהערכים האלה. אם כוללים את שני השדות, שגיאה אחת (INVALID_ARGUMENT):

costMicros 

// Update payload
{
  "costMicros": 1500000
}

// Response payload
{
  "costMicros": 1500000,
  "cost": {
    "currencyCode": "USD",
    "units": "1",
    "nanos": 500000000
  }
}

עלות 

// Update payload
{
  "cost": {
    "currencyCode": "USD",
    "units": "1",
    "nanos": 500000000
  }
}

// Response payload
{
  "costMicros": 1500000,
  "cost": {
    "currencyCode": "USD",
    "units": "1",
    "nanos": 500000000
  }
}

שניהם 

// Update payload
{
  "costMicros": 1250000,
  "cost": {
    "currencyCode": "USD",
    "units": "1",
    "nanos": 500000000
  }
}

// Response payload
{
  "error": {
    "code": 400,
    "message": "Request contains an invalid argument.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "costMicros",
            "description": "Cannot update both costMicros and cost."
          }
        ]
      }
    ]
  }
}

תכונות שיצאו משימוש

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

{
  // The salesperson split amount in micros.
  // Deprecated: The Sales Management feature has been deprecated. This field
  // will always be `0`.
  "salespersonSplitMicros": number,
}