Di chuyển từ API SOAP Ad Manager

API SOAP Ad Manager 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 API Ad Manager (Beta). Tuy nhiên, các phiên bản API SOAP của Ad Manager được hỗ trợ cho chu kỳ hoạt động thông thường. Để biết thêm thông tin, hãy xem Lịch ngừng sử dụng của API SOAP Ad Manager.

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

Học

Các phương thức dịch vụ API SOAP Ad Manager 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 một thực thể. Bảng sau đây cho thấy một ví dụ về mối 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 API Ad Manager (Beta), bạn có thể sử dụng thông tin xác thực API SOAP Ad Manager hiện có hoặc tạo thông tin xác thực mới. Với cả hai tuỳ chọn, trước tiên, bạn phải bật API Ad Manager trong dự án Google Cloud. Để biết thêm thông tin, hãy xem phần Xác thực.

Nếu bạn đang sử dụng thư viện ứng dụng, hãy thiết lập thông tin xác thực 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 xác thực Ứng dụng đã cài đặt, hãy tạo một tệp JSON ở đị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 mới hoặc hiện có của ứng dụng.

  • REFRESH_TOKEN: Mã thông báo làm mới mới hoặc hiện có.

Linux hoặc macOS 

export GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

Windows 

set GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

Tìm hiểu sự khác biệt giữa các bộ lọc

Ngôn ngữ truy vấn của API Ad Manager (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ạ các 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à thay thế mệnh đề ORDER BY và LIMIT bằng các trường riêng biệt:

API SOAP của Ad Manager 

<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 (Thử nghiệm)

Đị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 các điểm khác biệt về cú pháp sau đây so với API SOAP 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à chuỗi tìm kiếm thuần tuý, 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à giá trị cố định

    // 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 API SOAP Ad Manager

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

    Ad Manager API (Beta)

    // 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ả giá trị phải được cùng dòng.

  • Hằng chuỗi chứa dấu cách phải được gói trong dấu ngoặc kép, ví dụ: "Foo bar". Bạn không thể sử dụng dấu ngoặc đơn để gói các giá trị cố định kiểu chuỗi.

Xoá mệnh đề thứ tự

Bạn không bắt buộc phải chỉ định thứ tự sắp xếp trong Ad Manager API (Thử nghiệm). 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 đề ORDER BY PQL và đặt trường orderBy:

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

Di chuyển từ độ dời 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ì mệnh đề LIMIT và OFFSET để phân trang qua các tập hợ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 API SOAP Ad Manager, việc bỏ qua kích thước trang sẽ không trả về toàn bộ tập hợp kết quả. Thay vào đó, phương thức danh sách 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ư API SOAP Ad Manager, API Ad Manager (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ả nào khác hay không.

Mặc dù không bắt buộc phải có độ dời để phân trang, nhưng bạn có thể sử dụng trường skip để phân luồng. Khi tạo nhiều luồng, hãy sử 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