Lập phiên bản

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

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

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

Bản phát hành phiên bản lớn được định nghĩa là một bản phát hành có khả năng tương thích ngược Thay đổi về API. 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 đây được hỗ trợ trong khoảng thời gian di chuyển.

API Ad Manager không có tần suất phát hành thông thường 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.

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. Ứ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ì đối với các thay đổi trong một Phiên bản lớn. Khả năng tương thích được định nghĩa là:

  1. Khả năng tương thích với nguồn: Mã được viết cho một bản phát hành trước đó sẽ biên dịch với 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 Wire: Mã được viết dựa trên bản phát hành trước giao tiếp chính xác với máy chủ mới hơn. Nói cách khác, không chỉ thông tin đầu vào và đầu ra tương thích, nhưng kỳ vọng chuyển đổi tuần tự và huỷ chuyển đổi tuần tự tiếp tục so khớp.

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

Các bảng sau đây liệt kê các loại thay đổi đối với API và liệu các 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á phương thức Không
Thay đổi loại yêu cầu hoặc phản hồi của một 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 trường không bắt buộc Có
Di chuyển một trường vào hoặc ra khỏi 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 trường từ không bắt buộc thành bắt buộc Không
Xoá một 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

Liệt kê

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

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

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 thông tin khi có thể. Khi cập nhật, bạn có thể đặt một trong hai trường. Đưa cả hai trường vào trong bản cập nhật yêu cầu 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 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ị này. Khi đưa cả hai trường này vào, kết quả INVALID_ARGUMENT lỗi:

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 không còn được cung cấp nữa, thì 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ề ngữ nghĩa. Bản cập nhật có thể bỏ qua.

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