تحديد الإصدارات

تحتوي واجهة برمجة تطبيقات مدير الإعلانات REST على كل من إصدارات الإصدار الرئيسي الإصدارات الموجودة في مكانها ومتوافقة مع الإصدارات القديمة إلى الإصدار الرئيسي الحالي.

يمكن وضع علامة على الخدمات والطرق والحقول على أنها متوقفة في أي وقت وداخل على الرغم من ذلك، ستظل الإصدارات الرئيسية (مثل الإصدار 1) متوافقة حتى الإصدار الرئيسي تم إنهاء العمل به.

إصدارات الإصدارات الرئيسية

إصدار الإصدار الرئيسي هو إصدار غير متوافق مع الإصدارات القديمة تغييرات واجهة برمجة التطبيقات. ستتم تسمية هذه الإصدارات باسم نقاط نهاية مختلفة لواجهة برمجة التطبيقات. تتوافق الإصدارات الرئيسية السابقة مع فترة نقل البيانات.

لا توفّر واجهة برمجة تطبيقات REST في "مدير إعلانات Google" وتيرة منتظمة لإصدار التطبيقات الرئيسية مماثلة. لن يتم طرح الإصدارات الرئيسية الجديدة إلا عند الضرورة.

الإصدارات الحالية

تم طرح تغييرات متوافقة مع الأنظمة القديمة، بما في ذلك ميزات جديدة وإصلاحات للأخطاء. محل إصدار واجهة برمجة التطبيقات الرئيسية الحالي. يجب أن يتعامل العملاء مع الحقول غير المعروفة في ردود واجهة برمجة التطبيقات.

التوافق مع الأنظمة القديمة

يتم الحفاظ على التوافق مع الأنظمة القديمة للتغييرات في الإصدار الرئيسي. يتم تعريف التوافق على النحو التالي:

  1. التوافق مع المصدر: الرمز المكتوب مقابل مجموعات إصدار سابق مقابل إصدار أحدث، وتعمل بنجاح مع إصدار أحدث ومكتبة البرامج.

  2. توافق الأسلاك: رمز تمت كتابته وفقًا لإصدار سابق يتصل بشكل صحيح مع خادم أحدث. بعبارة أخرى، لا تُعد المدخلات فقط والمخرجات متوافقة، ولكن توقعات التسلسل والإلغاء تابع للمطابقة.

  3. التوافق الدلالي: يستمر الرمز المكتوب مقابل إصدار سابق يحصلون على ما يتوقعه المطورون المعقولون.

تسرد الجداول التالية أنواع تغييرات واجهة برمجة التطبيقات وما إذا تم أخذها في الاعتبار متوافقة مع الأنظمة القديمة.

الخدمات

نوع التغيير متوافقة مع الأنظمة القديمة
إضافة خدمة جديدة نعم
إزالة خدمة لا

الطُرق

نوع التغيير متوافقة مع الأنظمة القديمة
إضافة طريقة جديدة نعم
إزالة طريقة لا
تغيير طلب طريقة أو نوع ردّها لا

أغراض

نوع التغيير متوافقة مع الأنظمة القديمة
إضافة حقل مطلوب لا
إضافة حقل اختياري نعم
نقل حقل إلى رسالة فرعية أو خارجها لا
تغيير حقل من "مطلوب" إلى "اختياري" نعم
تغيير حقل من اختياري إلى مطلوب لا
إزالة قيد غير قابل للتغيير نعم
إضافة قيد غير قابل للتغيير لا

عمليات التعداد

نوع التغيير متوافقة مع الأنظمة القديمة
إضافة قيمة تعداد نعم
إزالة قيمة تعداد لا

سلوك الحقل الذي تم إيقافه

حقول الاستبدال

بالنسبة إلى الحقول التي يتوفّر لها بديل، ستتم تعبئة كلا الحقلَين عندما يكون ذلك ممكنًا. وعند التحديث، يمكن ضبط أيّ من الحقلَين. تضمين كلا الحقلين في تحديث ينتج عن الطلب خطأ 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,
}