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

تتضمّن واجهة برمجة التطبيقات الخاصة بـ "إدارة إعلانات Google" إصدارات رئيسية تحمل أسماء وإصدارات متوافقة مع الإصدارات السابقة في مكانها للإصدار الرئيسي الحالي.

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

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

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

لا تتوفّر وتيرة إصدار منتظمة للإصدارات الرئيسية من Ad Manager API. لن يتم طرح إصدارات رئيسية جديدة إلا عند الضرورة.

الإصدارات الموضعية

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

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

يتم الحفاظ على التوافق مع الإصدارات السابقة للتغييرات التي يتم إجراؤها ضمن رقم الإصدار الرئيسي. يتم تعريف التوافق على النحو التالي:

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