Bộ lọc

Ad Manager API hỗ trợ lọc theo các phương thức List. Cú pháp chuỗi bộ lọc được xác định chính thức trong ngữ pháp EBNF.

Để bắt đầu, sau đây là một số ví dụ về các trường hợp sử dụng phổ biến.

Ví dụ:	Ý nghĩa
orders.updateTime > "2024-01-01T00:00:00-5:00"	Liệt kê các đơn đặt hàng có updateTime sau ngày 1 tháng 1 năm 2024 theo Múi giờ chuẩn miền Đông
lineItems.targeting.geoTargeting.targetedGeoIds:2840	Liệt kê các mục hàng có tiêu chí nhắm mục tiêu theo địa lý chứa Hoa Kỳ (mã mục tiêu theo địa lý 2480)
lineItems.displayName = "*_interstitial"	Liệt kê các mục hàng có tên hiển thị kết thúc bằng chuỗi _interstitial
orders.displayName = "*video*"	Liệt kê các đơn đặt hàng có tên hiển thị chứa chuỗi video
displayName:"video"	Liệt kê các đơn đặt hàng có tên hiển thị chứa chuỗi video (cú pháp thay thế)

Lưu ý: Bộ lọc phải được mã hoá URL cho các yêu cầu GET. Ví dụ: Chuỗi bộ lọc: orders.updateTime > "2024-01-01T00:00:00-5:00" URL được mã hoá: orders.updateTime%20%3E%20%222024-01-01T00:00:00-5:00%22. Thư viện ứng dụng sẽ tự động xử lý việc này.

Giá trị cố định

Giá trị cố định trần (ví dụ: 42, Hugo) là giá trị cần so khớp. Các giá trị cố định xuất hiện riêng lẻ sẽ được so khớp mờ với tất cả các trường được hỗ trợ trên một tài nguyên. Tài nguyên ghi lại những trường được xem xét để so khớp trên phương thức list. Tính năng này tương đương với tính năng tìm kiếm chung trong giao diện người dùng Ad Manager, nhưng chỉ áp dụng cho một loại tài nguyên.

Chuỗi cố định chứa dấu cách phải được gói trong dấu ngoặc kép (ví dụ: "Foo bar"). Không thể dùng dấu nháy đơn để gói chuỗi cố định.

Toán tử logic

Ad Manager API hỗ trợ các toán tử nhị phân AND và OR.

Thận trọng: Các toán tử này phân biệt chữ hoa chữ thường. Giá trị cố định and và or được coi là Giá trị cố định.

Đơn vị tổ chức	Ví dụ:	Ý nghĩa
AND	a AND b	Đúng nếu a và b đúng.
OR	a OR b OR c	Đúng nếu bất kỳ a, b, c nào là đúng.

Lưu ý: Để khớp với các mẫu lời nói phổ biến, toán tử OR có mức độ ưu tiên cao hơn AND, không giống như trong hầu hết các ngôn ngữ lập trình. Biểu thức a AND b OR c có giá trị là a AND (b OR c). Khi có thể, hãy sử dụng dấu ngoặc đơn rõ ràng để tránh nhầm lẫn.

Toán tử phủ định

API Ad Manager cung cấp các toán tử một ngôi NOT và -. Bạn có thể sử dụng các phương thức này thay thế cho nhau.

Đơn vị tổ chức	Ví dụ:	Ý nghĩa
NOT	NOT a	Đúng nếu a không đúng.
-	-a	Đúng nếu a không đúng.

Toán tử so sánh

API Ad Manager hỗ trợ các toán tử so sánh nhị phân =, !=, <, >, <= và >= cho các trường chuỗi, số, dấu thời gian và thời lượng.

Đơn vị tổ chức	Ví dụ:	Ý nghĩa
=	a = true	Đúng nếu a đúng.
!=	a != 42	Đúng, trừ phi a bằng 42.
<	a < 42	Đúng nếu a là một giá trị số nhỏ hơn 42.
>	a > "foo"	Đúng nếu a được sắp xếp theo thứ tự từ vựng sau "foo".
<=	a <= "foo"	Đúng nếu a là "foo" hoặc theo thứ tự từ vựng trước đó.
>=	a >= 42	Đúng nếu a là một giá trị số từ 42 trở lên.

Lưu ý: Không giống như trong hầu hết các ngôn ngữ lập trình, tên trường phải xuất hiện ở bên trái của toán tử so sánh; bên phải chỉ chấp nhận các giá trị cố định và toán tử logic.

Vì bộ lọc được chấp nhận dưới dạng chuỗi truy vấn, nên quá trình chuyển đổi loại sẽ diễn ra để dịch chuỗi thành giá trị được xác định kiểu phù hợp:

• Chuỗi cần có dấu ngoặc kép. Ví dụ: "Foo bar"
• Enums yêu cầu biểu diễn chuỗi của enum (phân biệt chữ hoa chữ thường).
• Boolean dự kiến các giá trị cố định true và false.
• Số sẽ được biểu thị bằng số nguyên hoặc số thực chuẩn. Đối với số thực, hệ số mũ được hỗ trợ. Ví dụ: 2.997e9
• Thời lượng cần có một giá trị biểu diễn bằng số, theo sau là hậu tố s (dành cho giây). Ví dụ: "20s", "1.2s".
• Dấu thời gian yêu cầu một chuỗi được định dạng RFC-3339. Ví dụ: "2012-04-21T11:30:00-04:00". Hỗ trợ độ lệch UTC.

Thận trọng: Giá trị nhận dạng true, false và null chỉ mang ý nghĩa nội tại khi được sử dụng trong ngữ cảnh của tham chiếu trường đã nhập.

Ký tự đại diện

Khi so sánh các chuỗi để tìm giá trị bằng nhau, API Ad Manager hỗ trợ ký tự đại diện bằng cách sử dụng ký tự *.

Ví dụ:	Ý nghĩa
a = "*.foo"	Đúng nếu a kết thúc bằng ".foo".

Toán tử duyệt qua

API Ad Manager hỗ trợ toán tử ., cho biết việc truy cập thông qua một thông báo, bản đồ hoặc cấu trúc.

Ví dụ:	Ý nghĩa
a.b = true	Đúng nếu a có trường b boolean là true.
a.b > 42	Đúng nếu a có trường b dạng số lớn hơn 42.
a.b.c = "foo"	Đúng nếu a.b có trường c chuỗi là "foo".

Quá trình duyệt được viết bằng tên trường từ tài nguyên. Các dịch vụ riêng lẻ có thể chỉ định một tập hợp con các trường được hỗ trợ để truy cập.

Lưu ý quan trọng: Bạn không thể sử dụng toán tử . để duyệt qua một trường hoặc danh sách lặp lại, ngoại trừ trường hợp sử dụng cụ thể với toán tử :.

Có toán tử

API Ad Manager hỗ trợ toán tử :, có nghĩa là "có". Bạn có thể sử dụng phương thức này với các bộ sưu tập (trường hoặc bản đồ lặp lại), thông báo và Chuỗi, đồng thời phương thức này hoạt động hơi khác nhau trong từng trường hợp.

Truy vấn trường Chuỗi để xem chuỗi có chứa chuỗi con khớp hay không:

Ví dụ:	Ý nghĩa
r.displayName:"_250x250"	Đúng nếu trường Chuỗi r.displayName chứa chuỗi con _250x250.

Truy vấn trường lặp lại để xem cấu trúc lặp lại có chứa phần tử khớp hay không:

Ví dụ:	Ý nghĩa
r:42	Đúng nếu r chứa 42.
r.foo:42	Đúng nếu r chứa một phần tử e sao cho e.foo = 42.

Lưu ý quan trọng: Bộ lọc không thể truy vấn một phần tử cụ thể trên trường lặp lại cho một giá trị. Ví dụ: e.0.foo = 42 và e[0].foo = 42 không phải là bộ lọc hợp lệ.

Bản đồ, cấu trúc và thông báo có thể truy vấn để biết sự hiện diện của một trường trong bản đồ hoặc một giá trị cụ thể:

Ví dụ:	Ý nghĩa
m:foo	Đúng nếu m chứa khoá "foo".
m.foo:*	Đúng nếu m chứa khoá "foo".
m.foo:42	Đúng nếu m.foo là 42.

Khi duyệt qua các thông báo, một trường chỉ được coi là có mặt nếu trường đó có giá trị không phải giá trị mặc định.

Các điểm hạn chế

Ngoài những giới hạn được xác định ở đây, các dịch vụ riêng lẻ có thể chỉ định thêm cấu trúc hoặc giới hạn cho truy vấn bộ lọc.

Đặt

Ad Manager API hỗ trợ việc sắp xếp thứ tự trên các phương thức List. Cú pháp cho các trường orderBy là danh sách tên trường được phân tách bằng dấu phẩy. Ví dụ: "foo,bar".

Thứ tự sắp xếp mặc định là tăng dần. Để chỉ định thứ tự giảm dần cho một trường, hãy thêm hậu tố " desc". Ví dụ: "foo desc, bar".

Các ký tự dấu cách thừa trong cú pháp sẽ bị bỏ qua. Các giá trị "foo, bar desc", " foo , bar desc " và "foo,bar desc" đều tương đương nhau.

Các trường con được chỉ định bằng toán tử duyệt qua. Ví dụ: foo.bar hoặc address.street.