ניהול גרסאות

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

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

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

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

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

גרסאות שמתפרסמות במקום

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

תאימות לאחור

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

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

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

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

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

שירותים

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

Methods

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

אובייקטים

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

ערכי ספירה

סוג השינוי תאימות לאחור
הוספה של ערך 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,
}