Ad Manager REST API는 List 메서드에 관한 필터링을 지원합니다. 필터 문자열 구문은 공식적으로 EBNF 문법에 정의됩니다.
먼저 일반적인 사용 사례의 예를 몇 가지 소개합니다.
| 예 | 의미 |
|---|---|
orders.updateTime > "2024-01-01T00:00:00-5:00" |
2024년 1월 1일 이후 동부 표준시 기준으로 updateTime를 사용한 주문을 나열합니다. |
lineItems.targeting.geoTargeting.targetedGeoIds:2840 |
미국을 포함하는 지역 타겟팅이 있는 광고 항목 나열 (지역 타겟 ID 2480) |
lineItems.displayName = "*_interstitial" |
표시 이름이 _interstitial 문자열로 끝나는 광고 항목을 나열합니다. |
orders.displayName = "*video*" |
표시 이름에 video 문자열이 포함된 주문을 나열합니다. |
displayName:"video" |
표시 이름에 문자열 video (대체 구문)이 포함된 주문을 나열합니다. |
리터럴
기본적인 리터럴 값 (예: 42, Hugo)은 일치시킬 값입니다.
단독으로 표시되는 리터럴은 리소스에서 지원되는 모든 필드와 퍼지 일치됩니다. 리소스는 list 메서드에서 매칭을 위해 고려되는 필드를 문서화합니다. 이 기능은 Ad Manager UI의 전체 검색과
비슷하지만, 단일 리소스 유형으로 범위가 지정됩니다.
공백이 포함된 문자열 리터럴은 큰따옴표로 묶어야 합니다(예: "Foo bar"). 작은따옴표는 문자열 리터럴을 래핑하는 데 사용할 수 없습니다.
논리 연산자
Ad Manager REST API는 바이너리 연산자 AND와 OR를 지원합니다.
| 운영자 | 예 | 의미 |
|---|---|---|
AND |
a AND b |
a 및 b가 true인 경우 true입니다. |
OR |
a OR b OR c |
a, b, c 중 하나라도 true이면 true입니다. |
부정 연산자
Ad Manager REST API는 단항 연산자 NOT 및 -를 제공합니다.
이들은 서로 바꿔서 사용할 수 있습니다.
| 운영자 | 예 | 의미 |
|---|---|---|
NOT |
NOT a |
a가 true가 아닌 경우 true입니다. |
- |
-a |
a가 true가 아닌 경우 true입니다. |
비교 연산자
Ad Manager REST API는 문자열, 숫자, 타임스탬프, 기간 필드에 바이너리 비교 연산자 =, !=, <, >, <=, >=를 지원합니다.
| 운영자 | 예 | 의미 |
|---|---|---|
= |
a = true |
a가 true인 경우 true입니다. |
!= |
a != 42 |
a가 42가 아니면 true입니다. |
< |
a < 42 |
a이 42보다 작은 숫자 값인 경우 true입니다. |
> |
a > "foo" |
a가 어휘순으로 'foo' 뒤에 정렬되면 true입니다. |
<= |
a <= "foo" |
a가 'foo'이거나 그 앞에 어휘순으로 있으면 true입니다. |
>= |
a >= 42 |
a이 42 이상의 숫자 값인 경우 true입니다. |
필터는 쿼리 문자열로 허용되므로 유형 변환이 수행되어 문자열을 적절한 강타입(strongly typed) 값으로 변환합니다.
- 문자열에는 큰따옴표가 필요합니다. 예:
"Foo bar" - enum에는 enum의 문자열 표현 (대소문자 구분)이 필요합니다.
- 불리언에는
true및false리터럴 값이 필요합니다. - 숫자에는 표준 정수 또는 부동 소수점 표현을 사용해야 합니다. 부동 소수점 수의 경우 지수가 지원됩니다. 예:
2.997e9 - 기간은 숫자로 표시된 뒤에
s접미사 (초)를 따라야 합니다. 예:"20s","1.2s" - 타임스탬프에는 RFC-3339 형식의 문자열이 필요합니다.
예를 들면
"2012-04-21T11:30:00-04:00"입니다. UTC 오프셋이 지원됩니다.
와일드 카드
등호 문자열을 비교할 때 Ad Manager REST API는 * 문자를 사용하여 와일드 카드를 지원합니다.
| 예 | 의미 |
|---|---|
a = "*.foo" |
a가 '.foo'로 끝나는 경우 true입니다. |
순회 연산자
Ad Manager REST API는 메시지, 맵 또는 구조체를 통한 순회를 나타내는 . 연산자를 지원합니다.
| 예 | 의미 |
|---|---|
a.b = true |
a에 true인 불리언 b 필드가 있으면 true입니다. |
a.b > 42 |
a에 42보다 큰 숫자 b 필드가 있으면 true입니다. |
a.b.c = "foo" |
a.b에 'foo'인 문자열 c 필드가 있으면 true입니다. |
리소스의 필드 이름을 사용하여 순회가 작성됩니다. 개별 서비스에서는 순회가 지원되는 필드의 하위 집합을 지정할 수 있습니다.
연산자 있음
Ad Manager REST API는 'has'를 의미하는 : 연산자를 지원합니다.
컬렉션 (반복되는 필드 또는 맵), 메시지, 문자열과 함께 사용할 수 있으며 경우에 따라 동작 방식이 약간 다릅니다.
문자열 필드는 문자열에 일치하는 하위 문자열이 포함되어 있는지 쿼리합니다.
| 예 | 의미 |
|---|---|
r.displayName:"_250x250" |
문자열 필드 r.displayName에 _250x250 하위 문자열이 포함되어 있으면 true입니다. |
반복 필드는 반복된 구조에 일치하는 요소가 포함되어 있는지 쿼리합니다.
| 예 | 의미 |
|---|---|
r:42 |
r에 42가 포함되어 있으면 true입니다. |
r.foo:42 |
r에 e.foo = 42와 같은 e 요소가 포함되어 있으면 true입니다. |
맵, 구조체, 메시지는 맵에 필드가 있는지 또는 특정 값을 쿼리할 수 있습니다.
| 예 | 의미 |
|---|---|
m:foo |
m에 키 'foo'가 포함된 경우 true입니다. |
m.foo:* |
m에 키 'foo'가 포함된 경우 true입니다. |
m.foo:42 |
m.foo이 42이면 true입니다. |
메시지를 순회할 때 필드는 기본값이 아닌 값이 있는 경우에만 존재하는 것으로 간주됩니다.
제한사항
개별 서비스는 여기에 정의된 것 외에 필터 쿼리에 대한 추가 구조 또는 제한사항을 지정할 수 있습니다.
주문
Ad Manager REST API는 List 메서드의 정렬을 지원합니다. orderBy 필드의 구문은 쉼표로 구분된 필드 이름 목록입니다. 예를 들면 "foo,bar"입니다.
기본 정렬 순서는 오름차순입니다. 필드를 내림차순으로 지정하려면 " desc" 서픽스를 추가합니다. 예를 들면 "foo desc, bar"입니다.
구문의 중복 공백 문자는 무시됩니다. "foo, bar desc", " foo , bar desc ", "foo,bar desc" 값은 모두 동일합니다.
하위 필드는 순회 연산자로 지정됩니다. 예를 들면 foo.bar 또는 address.street입니다.