نسخه سازی

Ad Manager REST API هم نسخه‌های اصلی را نام‌گذاری کرده است و هم نسخه‌های درجا سازگار با نسخه اصلی فعلی.

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

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

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

Ad Manager REST API سرعت انتشار معمولی برای نسخه های اصلی ندارد. نسخه های اصلی جدید فقط در صورت لزوم منتشر می شوند.

انتشار در محل

تغییرات سازگار با عقب از جمله ویژگی‌های جدید و رفع اشکال در نسخه اصلی 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 می شود:

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