Để thảo luận và đưa ra ý kiến phản hồi về các sản phẩm của chúng tôi, hãy tham gia kênh Discord chính thức của Ad Manager trong máy chủ Cộng đồng quảng cáo và đo lường của Google.

Di chuyển từ API SOAP Ad Manager

Ad Manager SOAP API là một API cũ để đọc và ghi dữ liệu Ad Manager cũng như chạy báo cáo. Nếu có thể di chuyển, bạn nên sử dụng Ad Manager API (Beta). Tuy nhiên, các phiên bản Ad Manager SOAP API được hỗ trợ cho vòng đời điển hình của chúng. Để biết thêm thông tin, hãy xem Lịch ngừng sử dụng API SOAP của Ad Manager.

Hướng dẫn sau đây trình bày những điểm khác biệt giữa Ad Manager SOAP API và Ad Manager API (Beta).

Học

Các phương thức dịch vụ API SOAP Ad Manager tiêu chuẩn có các khái niệm tương đương trong API Ad Manager. API Ad Manager cũng có các phương thức để đọc các thực thể đơn lẻ. Bảng sau đây cho thấy một ví dụ về việc liên kết cho các phương thức Order:

Phương thức SOAP	Phương thức REST
`getOrdersByStatement`	`networks.orders.get` `networks.orders.list`

Xác thực

Để xác thực bằng Ad Manager API (Beta), bạn có thể sử dụng thông tin xác thực Ad Manager SOAP API hiện có hoặc tạo thông tin xác thực mới. Với cả hai lựa chọn, trước tiên, bạn phải bật API Ad Manager trong dự án Google Cloud của mình. Để biết thêm thông tin, hãy xem phần Xác thực.

Nếu bạn đang sử dụng một thư viện ứng dụng, hãy thiết lập thông tin đăng nhập mặc định của ứng dụng bằng cách đặt biến môi trường GOOGLE_APPLICATION_CREDENTIALS thành đường dẫn của tệp khoá tài khoản dịch vụ. Để biết thêm thông tin chi tiết, hãy xem phần Cách hoạt động của Thông tin xác thực mặc định của ứng dụng.

Nếu bạn đang sử dụng thông tin đăng nhập của Ứng dụng đã cài đặt, hãy tạo một tệp JSON theo định dạng sau và đặt biến môi trường thành đường dẫn của tệp đó:

{
  "client_id": "CLIENT_ID",
  "client_secret": "CLIENT_SECRET",
  "refresh_token": "REFRESH_TOKEN",
  "type": "authorized_user"
}

Thay thế các giá trị sau:

CLIENT_ID: Mã ứng dụng khách mới hoặc hiện có của bạn.
CLIENT_SECRET: Khoá bí mật của ứng dụng khách mới hoặc hiện có.
REFRESH_TOKEN: Mã làm mới mới hoặc hiện có của bạn.

Linux hoặc macOS

export GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

Windows

set GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

Tìm hiểu những điểm khác biệt về bộ lọc

Ngôn ngữ truy vấn Ad Manager API (Beta) hỗ trợ tất cả các tính năng của Ngôn ngữ truy vấn của nhà xuất bản (PQL), nhưng có sự khác biệt đáng kể về cú pháp.

Ví dụ này về việc liệt kê các đối tượng Order minh hoạ những thay đổi lớn như việc xoá các biến liên kết, toán tử phân biệt chữ hoa chữ thường và việc thay thế các mệnh đề ORDER BY và LIMIT bằng các trường riêng biệt:

Ad Manager SOAP API

<filterStatement>
  <query>WHERE name like "PG_%" and lastModifiedDateTime &gt;= :lastModifiedDateTime ORDER BY id ASC LIMIT 500</query>
  <values>
    <key>lastModifiedDateTime</key>
    <value xmlns:ns2="https://www.google.com/apis/ads/publisher/v202502" xsi:type="ns2:DateTimeValue">
      <value>
        <date>
          <year>2024</year>
          <month>1</month>
          <day>1</day>
        </date>
        <hour>0</hour>
        <minute>0</minute>
        <second>0</second>
        <timeZoneId>America/New_York</timeZoneId>
      </value>
    </value>
  </values>
</filterStatement>

API Ad Manager (Beta)

Định dạng JSON

{
  "filter": "displayName = \"PG_*\" AND updateTime > \"2024-01-01T00:00:00-5:00\"",
  "pageSize": 500,
  "orderBy":  "name"
}

URL được mã hoá

GET https://admanager.googleapis.com/v1/networks/123/orders?filter=displayName+%3D+\"PG_*\"+AND+updateTime+%3E+\"2024-01-01T00%3A00%3A00-5%3A00\"

API Ad Manager (Beta) hỗ trợ tất cả các chức năng của PQL, với những điểm khác biệt sau về cú pháp so với API SOAP của Ad Manager:

Các toán tử AND và OR phân biệt chữ hoa chữ thường trong Ad Manager API (Beta). and và or viết thường được coi là các chuỗi tìm kiếm theo nghĩa đen đơn thuần, một tính năng trong API Ad Manager (Beta) để tìm kiếm trên các trường.

Sử dụng toán tử viết hoa
```
// Matches unarchived Orders where order.notes has the value 'lorem ipsum'.
notes = "lorem ipsum" AND archived = false
```
Chữ thường được coi là ký tự nguyên nghĩa
```
// Matches unarchived Orders where order.notes has the value 'lorem ipsum'
// and any field in the order has the literal value 'and'.
notes = "lorem ipsum" and archived = false
```

Ký tự * là ký tự đại diện để so khớp chuỗi. Ad Manager API (Beta) không hỗ trợ toán tử like.

PQL của Ad Manager SOAP API

// Matches orders where displayName starts with the string 'PG_'
displayName like "PG_%"

Ad Manager API (Thử nghiệm)

// Matches orders where displayName starts with the string 'PG_'
displayName = "PG_*"

Tên trường phải xuất hiện ở bên trái của toán tử so sánh:

Bộ lọc hợp lệ
```
updateTime > "2024-01-01T00:00:00Z"
```
Bộ lọc không hợp lệ
```
"2024-01-01T00:00:00Z" < updateTime
```
Ad Manager API (Beta) không hỗ trợ các biến liên kết. Tất cả các giá trị đều phải được nội tuyến.
Hằng chuỗi chứa dấu cách phải được đặt trong dấu ngoặc kép, chẳng hạn như "Foo bar". Bạn không thể dùng dấu nháy đơn để bao bọc các giá trị chữ cố định.

Xoá mệnh đề order by

Bạn không bắt buộc phải chỉ định thứ tự sắp xếp trong Ad Manager API (Beta). Nếu bạn muốn chỉ định thứ tự sắp xếp cho tập kết quả, hãy xoá mệnh đề PQL ORDER BY và đặt trường orderBy:

GET networks/${NETWORK_CODE}/orders?orderBy=updateTime+desc

Di chuyển từ giá trị bù đắp sang mã thông báo phân trang

Ad Manager API (Beta) sử dụng mã thông báo phân trang thay vì các mệnh đề LIMIT và OFFSET để phân trang qua các tập kết quả lớn.

API Ad Manager (Beta) sử dụng tham số pageSize để kiểm soát kích thước trang. Không giống như mệnh đề LIMIT trong Ad Manager SOAP API, việc bỏ qua kích thước trang không trả về toàn bộ tập kết quả. Thay vào đó, phương thức danh sách sẽ sử dụng kích thước trang mặc định là 50. Ví dụ sau đây đặt pageSize và pageToken làm tham số URL:

# Initial request
GET networks/${NETWORK_CODE}/orders?pageSize=50

# Next page
GET networks/${NETWORK_CODE}/orders?pageSize=50&pageToken=${TOKEN_FROM_INITIAL_REQUEST}

Không giống như Ad Manager SOAP API, Ad Manager API (Beta) có thể trả về ít kết quả hơn kích thước trang được yêu cầu ngay cả khi có các trang bổ sung. Sử dụng trường nextPageToken để xác định xem có kết quả bổ sung hay không.

Mặc dù không bắt buộc phải có độ lệch để phân trang, nhưng bạn có thể sử dụng trường skip để thực hiện đa luồng. Khi sử dụng nhiều luồng, hãy dùng mã thông báo phân trang từ trang đầu tiên để đảm bảo bạn đang đọc từ cùng một tập hợp kết quả:

# First thread
GET networks/${NETWORK_CODE}/orders?pageSize=50&pageToken=${TOKEN_FROM_INITIAL_REQUEST}

# Second thread
GET networks/${NETWORK_CODE}/orders?pageSize=50&pageToken=${TOKEN_FROM_INITIAL_REQUEST}&skip=50

Di chuyển báo cáo

API SOAP chỉ có thể đọc và chạy báo cáo trong công cụ Báo cáo không dùng nữa. Ngược lại, REST API chỉ có thể đọc, ghi và chạy Báo cáo tương tác.

Các công cụ và API báo cáo có không gian mã nhận dạng riêng. Bạn không thể dùng mã nhận dạng của SavedQuery trong SOAP API trong REST API.

Nếu đang sử dụng SavedQuery, bạn có thể di chuyển báo cáo sang Báo cáo tương tác trong giao diện người dùng và tạo mối liên kết giữa hai không gian mã nhận dạng. Để biết thêm thông tin về việc di chuyển báo cáo, hãy xem bài viết Di chuyển báo cáo sang Báo cáo tương tác.

Tìm hiểu sự khác biệt về API

Có một số điểm khác biệt trong cách API SOAP và API REST xử lý các định nghĩa và kết quả báo cáo:

SOAP API tự động thêm một phương diện ID tương ứng vào kết quả khi một báo cáo chỉ yêu cầu NAME. Trong REST API, bạn phải thêm phương diện ID một cách rõ ràng vào ReportDefinition để phương diện đó được đưa vào kết quả.
API SOAP không có các loại chỉ số rõ ràng. REST API xác định một loại dữ liệu, được ghi lại trên giá trị enum Dimension. Xin lưu ý rằng các phương diện ENUM là enum mở. Bạn phải xử lý các giá trị enum mới và không xác định khi phân tích cú pháp kết quả.
SOAP API tách Dimensions và DimensionAttributes. API REST có một enum Dimension hợp nhất chứa cả hai.
SOAP API không có giới hạn về số lượng phương diện. Báo cáo tương tác có giới hạn 10 phương diện trong cả giao diện người dùng và API. Những phương diện được phân tích theo cùng một không gian mã nhận dạng sẽ được tính là một phương diện. Ví dụ: bao gồm ORDER_NAME, ORDER_ID và ORDER_START_DATE chỉ được tính là 1 phương diện khi tính toán giới hạn.