การกำหนดเวอร์ชัน

Ad Manager API มีทั้งชื่อรุ่นหลักและ รุ่นในตัวที่เข้ากันได้แบบย้อนหลังกับเวอร์ชันหลักปัจจุบัน

บริการ เมธอด และฟิลด์ต่างๆ อาจได้รับการทําเครื่องหมายว่าเลิกใช้งานได้ทุกเมื่อภายในเวอร์ชันหลัก (เช่น v1) แต่ระบบจะยังคงรองรับบริการเหล่านั้นจนกว่าเวอร์ชันหลักดังกล่าวจะหยุดให้บริการ

เวอร์ชันหลักที่เผยแพร่

รุ่นเวอร์ชันหลักคือรุ่นที่มีความเข้ากันได้แบบย้อนหลัง การเปลี่ยนแปลง API เวอร์ชันเหล่านี้จะมีชื่อและปลายทาง API ที่แตกต่างกัน ระบบจะรองรับเวอร์ชันหลักก่อนหน้าในช่วงการย้ายข้อมูล

Ad Manager API ไม่มีช่วงเวลาการเผยแพร่ที่แน่นอนสำหรับเวอร์ชันหลัก ระบบจะเผยแพร่เวอร์ชันหลักใหม่เมื่อจำเป็นเท่านั้น

การเผยแพร่ในสถานที่

เปิดตัวการเปลี่ยนแปลงที่เข้ากันได้แบบย้อนหลัง รวมถึงฟีเจอร์ใหม่และการแก้ไขข้อบกพร่อง แทน Major API เวอร์ชันปัจจุบัน ไคลเอ็นต์ต้องจัดการช่องที่ไม่รู้จักในการตอบกลับของ API

ความเข้ากันได้แบบย้อนหลัง

ระบบจะยังคงรักษาความเข้ากันได้แบบย้อนหลังสำหรับการเปลี่ยนแปลงภายในเวอร์ชันหลัก ความเข้ากันได้มีดังนี้

  1. ความเข้ากันได้ของซอร์สโค้ด: โค้ดที่เขียนขึ้นสำหรับรุ่นก่อนหน้าจะคอมไพล์กับรุ่นที่ใหม่กว่า และทำงานร่วมกับไลบรารีไคลเอ็นต์เวอร์ชันใหม่ได้สําเร็จ

  2. ความเข้ากันได้ของสาย: โค้ดที่เขียนเทียบกับรุ่นก่อนหน้า สื่อสารกับเซิร์ฟเวอร์รุ่นใหม่ได้อย่างถูกต้อง กล่าวคือ ไม่ใช่แค่อินพุต และเอาต์พุตที่เข้ากันได้ แต่ความคาดหวังของการทำให้เป็นอนุกรมและดีซีเรียลไลซ์ จับคู่ต่อไป

  3. ความสามารถในการใช้งานร่วมกันของความหมาย: โค้ดที่เขียนโดยเทียบกับเวอร์ชันก่อนหน้าจะยังคงอยู่ ได้รับสิ่งที่นักพัฒนาซอฟต์แวร์ สมเหตุสมผลมากที่สุดคาดหวัง

ตารางต่อไปนี้แสดงประเภทการเปลี่ยนแปลง API และระบุว่าเข้ากันได้แบบย้อนหลังหรือไม่

บริการ

ประเภทการเปลี่ยนแปลง ใช้งานกับเครื่องรุ่นเก่าได้
เพิ่มบริการใหม่ ใช่
นำบริการออก ไม่ได้

เมธอด

ประเภทการเปลี่ยนแปลง ใช้งานกับเครื่องรุ่นเก่าได้
เพิ่มวิธีการใหม่ ใช่
นำวิธีการออก ไม่ได้
เปลี่ยนประเภทคำขอหรือประเภทการตอบกลับของเมธอด ไม่ได้

วัตถุ

ประเภทการเปลี่ยนแปลง เข้ากันได้แบบย้อนหลัง
เพิ่มช่องที่ต้องกรอก ไม่ได้
เพิ่มช่องที่ไม่บังคับ ใช่
การย้ายช่องเข้าหรือออกจากข้อความย่อย ไม่ได้
เปลี่ยนช่องจากต้องระบุเป็นไม่บังคับ ใช่
เปลี่ยนช่องจากไม่บังคับเป็นต้องระบุ ไม่ได้
นำข้อจำกัดแบบแก้ไขไม่ได้ออก ใช่
เพิ่มข้อจํากัดแบบแก้ไขไม่ได้ ไม่ได้

การแจกแจง

ประเภทการเปลี่ยนแปลง ใช้งานกับเครื่องรุ่นเก่าได้
เพิ่มค่า enum ใช่
นำค่า enum ออก ไม่ได้

ลักษณะการทำงานของช่องที่เลิกใช้งาน

ฟิลด์การเปลี่ยนทดแทน

สําหรับช่องที่มีฟิลด์เปลี่ยนทดแทน ระบบจะป้อนข้อมูลในทั้ง 2 ช่องเมื่อเป็นไปได้ เมื่ออัปเดต คุณจะตั้งค่าช่องใดช่องหนึ่งได้ รวมทั้ง 2 ช่องไว้ในการอัปเดต ทำให้เกิดข้อผิดพลาด INVALID_ARGUMENT

ลองพิจารณาสคีมาต่อไปนี้

{
  // The cost of this Foo in micros.
  // Deprecated: Use `cost` instead.
  "costMicros": number,

  // The cost of this Foo.
  "cost": {
    object (Money)
  }
}

การตอบกลับการอ่านจะป้อนข้อมูลทั้ง 2 ช่องด้วยค่าที่เทียบเท่ากัน ดังนี้

{
  "costMicros": 1250000,
  "cost": {
    "currencyCode": "USD",
    "units": "1",
    "nanos": 250000000
  }
}

คำขออัปเดตสามารถตั้งค่าค่าใดค่าหนึ่งได้ การรวมทั้ง 2 ช่องจะทำให้เกิดข้อผิดพลาด 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,
}