Lập phiên bản

API REST của Ad Manager có cả hai 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 REST của Ad Manager không có tần suất phát hành thường xuyên cho Major của Google. 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 tính năng mới và bản sửa lỗi được phát hành thay thế cho phiên bản Major API (API Chính) hiện tại. Ứng dụng phải xử lý các trường không xác định trong các phản hồi của API.

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

Khả năng tương thích ngược được duy trì cho những thay đổi trong 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 bản phát hành trước đó sẽ biên dịch so với 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 những thay đổi đó có được xem xét không tương thích ngược.

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

Đối tượng

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 tin nhắn con 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 tắc 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 một giá trị enum Có
Xoá một 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ị. 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 bị ngừng cung cấp

Nếu một tính năng sản phẩm bị ngừng cung cấp, các trường tương ứng sẽ được đánh dấu là không được dùng nữa và có thể trả về giá trị mặc định phù hợp về mặt 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,
}