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

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

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

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

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

Ad Manager REST 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
  }
}

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