Bộ lọc

API REST của Ad Manager hỗ trợ lọc trên các phương thức List. Cú pháp chuỗi bộ lọc được định nghĩa 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ý có chứa Hoa Kỳ (mã mục tiêu địa lý 2480)
lineItems.displayName = "*_interstitial"	Liệt kê những 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.
Quy trình này sẽ do thư viện ứng dụng xử lý tự động.

Các từ ngữ

Giá trị thuần tuý (ví dụ: 42, Hugo) là giá trị cần so khớp. Các văn bản chỉ xuất hiện một mình sẽ bị 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 cân nhắc so khớp trên phương thức list. Tính năng này tương đương với chức năng tìm kiếm chung trong giao diện người dùng Ad Manager nhưng trong phạm vi một loại tài nguyên duy nhất.

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

Toán tử logic

API REST của Ad Manager 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. Các 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 là đúng.
OR	a OR b OR c	Đúng nếu bất kỳ giá trị nào trong số a, b, c 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 REST của Ad Manager cung cấp các toán tử đơn nhất NOT và -. Các thông số này có thể sử dụng 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 REST của 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 là đú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"	"True" nếu a được sắp xếp theo từ vựng sau "foo".
<=	a <= "foo"	"True" nếu a là "foo" hoặc đặt theo từ vựng trước nó.
>=	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; phía bên phải chỉ chấp nhận các toán tử logic và giá trị cố định.

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

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

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

Ký tự đại diện

Khi so sánh các chuỗi để đảm bảo tính bằng, API REST của Ad Manager hỗ trợ ký tự đại diện bằng ký tự *.

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

Toán tử truyền tải

API REST của Ad Manager hỗ trợ toán tử ., cho biết rằng hoạt động truyền tải thông qua một tin nhắn, bản đồ hoặc cấu trúc.

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

Truyền tải đượ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ền tải.

Lưu ý quan trọng: Bạn không được sử dụng toán tử . để truyền 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 REST của Ad Manager hỗ trợ toán tử :, có nghĩa là "có". Bạn có thể sử dụng đối tượng này với các bộ sưu tập (các trường hoặc bản đồ lặp lại), thông điệp và Chuỗi cũng như các hành vi hơi khác nhau trong từng trường hợp.

Truy vấn các trường chuỗi để kiểm tra xem chuỗi đó có chứa chuỗi con phù hợ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 các trường lặp lại để xem cấu trúc lặp lại có chứa phần tử phù hợp hay không:

Ví dụ:	Ý nghĩa
r:42	Đúng nếu r chứa 42.
r.foo:42	"True" nếu r chứa 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 một trường lặp lại cho một giá trị. Ví dụ: e.0.foo = 42 và e[0].foo = 42 là không bộ lọc hợp lệ.

Bản đồ, cấu trúc và thông báo có thể truy vấn sự hiện diện của một trường trên 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 truyền tải thông điệp, một trường chỉ được coi là xuất hiện nếu có giá trị không phải là giá trị mặc định.

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

Ngoài những nội dung đượ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 các truy vấn bộ lọc.

Đặt

API REST của Ad Manager hỗ trợ tính năng đặt hàng trên các phương thức List. Cú pháp cho các trường orderBy là danh sách các 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ự khoảng trắng 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.

Bạn sẽ chỉ định các trường phụ bằng toán tử truyền tải. Ví dụ: foo.bar hoặc address.street.