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

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

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

การเปิดตัวเวอร์ชันหลัก

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

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

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

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

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

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

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

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

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