ניהול גרסאות

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

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

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

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

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

גרסאות קיימות

פורסמו שינויים שתואמים לאחור, כולל תכונות חדשות ותיקוני באגים אותה לגרסה הנוכחית של ה-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,
}