Lập phiên bản

Ad Manager API có cả bản phát hành Phiên bản chính được đặt tên và bản phát hành tại chỗ tương thích ngược với Phiên bản chính hiện tại.

Các dịch vụ, phương thức và trường có thể được đánh dấu là không dùng nữa bất cứ lúc nào trong một phiên bản lớn (ví dụ: v1), tuy nhiên, chúng sẽ vẫn được hỗ trợ cho đến khi phiên bản lớn đó ngừng hoạt động.

Phát hành phiên bản lớn

Bản phát hành phiên bản lớn được xác định là bản phát hành có các thay đổi về API không tương thích ngược. Các bản phát hành này sẽ được đặt tên và có các điểm cuối API khác nhau. Các phiên bản chính trước đó được hỗ trợ trong một khoảng thời gian di chuyển.

API Ad Manager không có nhịp phát hành thường xuyên cho các phiên bản chính. Các phiên bản chính mới sẽ chỉ được phát hành khi cần thiết.

Bản phát hành tại chỗ

Các thay đổi tương thích ngược, bao gồm cả các tính năng mới và bản sửa lỗi, được phát hành tại chỗ cho phiên bản API chính hiện tại. Các ứng dụng phải xử lý các trường không xác định trong phản hồi API.

Khả năng tương thích ngược

Khả năng tương thích ngược được duy trì cho các thay đổi trong một phiên bản chính. Khả năng tương thích được định nghĩa là:

  1. Khả năng tương thích nguồn: Mã được viết dựa trên một bản phát hành trước đó sẽ biên dịch dựa trên một bản phát hành mới hơn và chạy thành công với phiên bản mới hơn của thư viện ứng dụng.

  2. Khả năng tương thích của dây: Mã được viết dựa trên một bản phát hành trước đó giao tiếp chính xác với một máy chủ mới hơn. Nói cách khác, không chỉ các đầu vào và đầu ra tương thích mà các kỳ vọng về việc chuyển đổi tuần tự và chuyển đổi không tuần tự vẫn tiếp tục khớp.

  3. Khả năng tương thích về ngữ nghĩa: Mã được viết dựa trên một phiên bản trước đó vẫn tiếp tục nhận được những gì mà hầu hết các nhà phát triển hợp lý mong đợi.

Các bảng sau đây liệt kê các loại thay đổi đối với API và liệu những thay đổi đó có được coi là tương thích ngược hay không.

Dịch vụ

Loại thay đổi Tương thích ngược
Thêm dịch vụ mới Có
Xoá dịch vụ Không

Phương thức

Loại thay đổi Tương thích ngược
Thêm phương thức mới Có
Xoá một phương thức Không
Thay đổi loại yêu cầu hoặc phản hồi của phương thức Không

Đồ vật

Loại thay đổi Tương thích ngược
Thêm trường bắt buộc Không
Thêm một trường không bắt buộc Có
Di chuyển một trường vào hoặc ra khỏi một thông báo phụ Không
Thay đổi một trường từ bắt buộc thành không bắt buộc Có
Thay đổi một trường từ không bắt buộc thành bắt buộc Không
Xoá quy định hạn chế không thể thay đổi Có
Thêm quy tắc hạn chế không thể thay đổi Không

Bảng liệt kê

Loại thay đổi Tương thích ngược
Thêm một giá trị enum Có
Xoá một giá trị enum Không

Hành vi của trường không dùng nữa

Trường thay thế

Đối với những trường có trường thay thế, cả hai trường sẽ được điền sẵn dữ liệu khi có thể. Khi cập nhật, bạn có thể đặt một trong hai trường. Việc đưa cả hai trường vào một yêu cầu cập nhật sẽ dẫn đến lỗi INVALID_ARGUMENT.

Hãy xem xét giản đồ sau:

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

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

Phản hồi đọc sẽ điền sẵn cả hai trường bằng các giá trị tương đương:

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

Yêu cầu cập nhật có thể đặt một trong hai giá trị. Việc thêm cả hai trường sẽ dẫn đến lỗi INVALID_ARGUMENT:

costMicros 

// Update payload
{
  "costMicros": 1500000
}

// Response payload
{
  "costMicros": 1500000,
  "cost": {
    "currencyCode": "USD",
    "units": "1",
    "nanos": 500000000
  }
}

chi phí 

// Update payload
{
  "cost": {
    "currencyCode": "USD",
    "units": "1",
    "nanos": 500000000
  }
}

// Response payload
{
  "costMicros": 1500000,
  "cost": {
    "currencyCode": "USD",
    "units": "1",
    "nanos": 500000000
  }
}

Cả hai 

// 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."
          }
        ]
      }
    ]
  }
}

Các tính năng đã ngừng hoạt động

Nếu một tính năng sản phẩm bị ngừng hoạt động, các trường tương ứng sẽ được đánh dấu là không dùng nữa và có thể trả về một giá trị mặc định phù hợp về mặt ngữ nghĩa. Bạn có thể bỏ qua các bản cập nhật.

{
  // The salesperson split amount in micros.
  // Deprecated: The Sales Management feature has been deprecated. This field
  // will always be `0`.
  "salespersonSplitMicros": number,
}