نسخه سازی

رابط برنامه‌نویسی کاربردی مدیریت تبلیغات (Ad Manager API) هم نسخه‌های اصلی (Major Version) و هم نسخه‌های سازگار با نسخه‌های قبلی (Backward Compatibility) را برای نسخه اصلی فعلی نامگذاری کرده است.

سرویس‌ها، متدها و فیلدها می‌توانند در هر زمانی در یک نسخه اصلی (مثلاً نسخه ۱) به عنوان منسوخ‌شده علامت‌گذاری شوند، با این حال، تا زمانی که آن نسخه اصلی منسوخ شود، پشتیبانی از آنها ادامه خواهد داشت.

نسخه‌های اصلی منتشر شده

یک نسخه اصلی (Major) به عنوان نسخه‌ای با تغییرات API ناسازگار با نسخه‌های قبلی تعریف می‌شود. این نسخه‌ها نامگذاری شده و دارای نقاط پایانی API متفاوتی هستند. نسخه‌های اصلی قبلی برای یک دوره مهاجرت پشتیبانی می‌شوند.

رابط برنامه‌نویسی کاربردی مدیریت تبلیغات (Ad Manager API) برای نسخه‌های اصلی (Magic) آهنگ انتشار منظمی ندارد. نسخه‌های اصلی جدید فقط در صورت لزوم منتشر می‌شوند.

نسخه‌های درجا

تغییرات سازگار با نسخه‌های قبلی، شامل ویژگی‌های جدید و رفع اشکالات، در نسخه اصلی API فعلی منتشر می‌شوند. کلاینت‌ها باید فیلدهای ناشناخته را در پاسخ‌های API مدیریت کنند.

سازگاری با نسخه‌های قبلی

سازگاری با نسخه‌های قبلی برای تغییرات در نسخه اصلی حفظ می‌شود. سازگاری به صورت زیر تعریف می‌شود:

  1. سازگاری با منبع: کدی که برای نسخه قبلی نوشته شده است، برای نسخه جدیدتر کامپایل می‌شود و با موفقیت با نسخه جدیدتر کتابخانه کلاینت اجرا می‌شود.

  2. سازگاری با سیم: کدی که برای نسخه قبلی نوشته شده است، به درستی با سرور جدیدتر ارتباط برقرار می‌کند. به عبارت دیگر، نه تنها ورودی‌ها و خروجی‌ها سازگار هستند، بلکه انتظارات سریال‌سازی و حذف سریال‌سازی نیز همچنان مطابقت دارند.

  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 می‌شود:

هزینه میکروس 

// 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,
}