이 가이드에서는 목록 필터 구문과 다양한 리소스 유형을 필터링하는 방법을 설명합니다.
일부 API 메서드는 필터를 허용하여 응답에서 반환되는 리소스를 제한할 수 있습니다.
요약
이 섹션에서는 목록 필터 구문 구조를 간략하게 설명합니다.
필터는
expression
가 포함된 문자열입니다.expression
는 여러 비교의 부울 조합입니다.expression = ["NOT"] comparison { ("AND" | "OR") ["NOT"] comparison } expression = ( expression )
comparison
는 리소스 필드를 값과 일치시킵니다. 일반적인 비교 연산자를 모두 사용할 수 있습니다.comparison = name OP value OP = "<=" | "<" | ">=" | ">" | "!=" | "=" | ":"
has
연산자인 콜론 (:
)은 문자열과 반복되는 필드에 사용할 수 있습니다. 자세한 내용은 연산자 있음 섹션을 참고하세요.필터에 다음 유형의 값을 사용할 수 있습니다.
- 숫자
- 문자열
- 괄호로 묶인 표현식
value = number| string | "*" | "(" expression ")"
문자열은 다음을 나타낼 수 있습니다.
- 임의 텍스트
- 부울
- enum 값
- 타임스탬프
부울 표현식
expression = ["NOT"|"-"] comparison {["AND" | "OR"] ["NOT"|"-"] comparison}
작업은 다음 순서로 실행됩니다.
NOT
OR
AND
예를 들어 다음 표현식은 동일합니다.
a OR NOT b AND NOT c OR d
(a OR (NOT b)) AND ((NOT c) OR d)
비교 사이에 AND
연산자를 생략할 수 있습니다. 예를 들어 다음 필터는 동일합니다.
c=d AND e=f
c=d e=f
NOT
대신 하이픈 (-
)을 사용할 수 있습니다. 하이픈 (-
)과 다음 비교 연산자 사이에는 공백이 없어야 합니다. 예를 들어 다음 필터는 동일합니다.
NOT e=f
-e=f
비교
이 섹션에서는 다음과 같은 "name OP value"
비교를 설명합니다.
comparison = name OP value
어디서
OP = "<=" | "<" | ">=" | ">" | "!=" | "=" | ":"
name = identifier { "." identifier }
identifier = unquoted_text
value = number | string | "*" | "(" expression ")"
비교의 왼쪽은 API 리소스 필드의 경로 이름입니다.
이름은 마침표 (.
)로 연결된 일련의 리소스 식별자로 구성됩니다. 각 필드 식별자 뒤에는 해당 필드의 다음 수준 이름이 옵니다. 예를 들어, 다른 복잡한 필드 tool
를 가진 복잡한 필드 item
와 shape
라는 필드가 있는 리소스를 가정해 보겠습니다. 이 리소스의 필터에서는 이름이 item.tool.shape
인 도형을 참조합니다.
오른쪽은 일반적으로 필드 유형으로 변환되어 비교되는 스칼라 값입니다. 자세한 내용은 값 리터럴 유형 섹션을 참조하세요.
비교의 오른쪽은 리터럴 값 또는 리터럴 값만 포함된 불리언 표현식의 괄호로 묶인 불리언 조합으로 표현될 수도 있습니다 (앞에 NOT
가 포함되거나 포함되지 않음). 왼쪽 이름과 비교 연산자가 각 값에 적용됩니다. 예를 들어 다음 필터는 동일합니다.
deal.name = ("test 1" OR "test 2")
deal.name = "test 1" OR deal.name = "test 2"
다음은 동등한 두 필터에 대한 더 복잡한 또 다른 예입니다.
deal.name = ("test 1" OR "test 2" AND (NOT "test3" OR "test4"))
(deal.name = "test 1" OR deal.name = "test 2") AND ( (NOT deal.name = "test3") OR deal.name = "test4")
값 리터럴 유형
비교 연산자의 오른쪽 값은 숫자 리터럴과 문자열 리터럴로 분류할 수 있습니다.
숫자
이 섹션에서는 숫자 리터럴의 표현에 대해 설명합니다.
유형 | 정의 | 예 |
---|---|---|
2루타 | 기호 ('-')가 있든 없든, 소수점이 포함된 모든 숫자는 Double로 취급됩니다. |
|
정수 | 소수점이 없는 숫자, 기호('-')가 있거나 없는 모든 숫자는 정수로 취급됩니다. |
|
문자열
이 섹션에서는 필터 구문에 문자열 리터럴로 작성할 수 있는 유형을 설명합니다.
유형 | 정의 | 예 |
---|---|---|
불리언 | 대소문자에 관계없이 TRUE 또는 FALSE |
|
열거형 | 열거형 유형 리터럴의 이름입니다. enum은 대소문자를 구분합니다. |
FINALIZED 은(는) Finalized 과(와) 같지 않습니다.
|
문자열 | UTF-8 인코딩 텍스트 또는 7비트 ASCII 텍스트를 포함하는 문자열. 삽입된 따옴표는 백슬래시로 이스케이프 처리합니다. 공백이 있는 따옴표가 없는 문자열은 공백으로 문자열을 분할한 후 모든 단어 중에서 암시적 'AND'로 처리됩니다. |
|
타임스탬프 | ISO8601 표준 형식의 문자열입니다. |
"2014-10-02T15:01:23.045Z"
|
비교 연산자
비교 연산자는 다음과 같습니다.
- 이하:
"<="
- 미만:
"<"
- 이상:
">="
- 초과:
">"
- 같지 않음:
"!="
- 같음:
"="
- 포함:
":"
이러한 연산자는 Double, Integer, Boolean, Enum 및 Timestamp 값 유형에 적용됩니다.
연산자 있음
다음 필드의 특수 작업에 HAS
연산자 (:
)를 사용할 수 있습니다.
- 하위 문자열
HAS
연산자가 문자열 열의 값을 문자열과 비교하는 데 사용되는 경우 이 연산자는 하위 문자열 연산 역할을 합니다. 예를 들어name:"abcd"
는name
가"abcd"
가 포함된 문자열인 모든 인스턴스를 반환합니다.- 존재 여부 확인
HAS
연산자를 특수 문자*
와 함께 사용하면HAS
연산자는 null이 아닌 값을 확인합니다. 예를 들어name:*
는name
가 null, 누락 또는 정의되지 않은 모든 인스턴스를 반환합니다.- 문자열이 아닌 값에
HAS
연산자를 사용하면EQUALS
(=
) 연산자와 동일하게 작동합니다. 예를 들어isCompleted:true
는isCompleted = true
와 같은 방식으로 동작합니다. - 반복되는 입력란
다음 사항이 true인 경우
HAS
(:
) 연산자를 사용하여 반복되는 API 리소스 필드를 필터링할 수 있습니다.- 필드 식별자 경로를 따라 반복되는 구성요소가 하나만 있음
- 필드 경로의 마지막 식별자는 스칼라 유형입니다.
중첩되고 반복되는 필드에 대한 필터링은 지원되지 않습니다.
다음 예를 참고하세요.
item
에는"red"
,"blue"
,"yellow"
와 같은 문자열 값이 포함된colors
필드가 있습니다.item.colors:("red")
는colors
필드에"red"
값이 있는 모든 항목을 반환합니다.item.colors:("red" "yellow")
는colors
필드에"red"
와"yellow"
가 모두 있는 모든 항목을 반환합니다.item.colors:("red" OR "yellow")
는colors
필드에"red"
또는"yellow"
가 있는 모든 항목을 반환합니다.
item
에는 스칼라 필드shape
가 있는 복합 객체인 반복되는tools
필드도 있습니다. 이 객체의 값은"square"
또는"round"
입니다.item.tools.shape:("square")
는"square"
모양 도구가 있는 모든 항목을 반환합니다.item.tools.shape:("square" "round")
는"square"
모양 도구와"round"
모양 도구가 모두 있는 항목을 모두 반환합니다.item.tools.shape:("square" OR "round")
는"square"
도형 도구 또는"round"
도형 도구가 있는 모든 항목을 반환합니다.
채워지지 않은 중첩 필드
중첩 필드는 루트 수준 필드의 하위 필드입니다. 예를 들어 item.tools.shape
의 shape
는 items.tools
의 중첩 필드입니다.
루트 수준 필드의 기본값은 false입니다. 중첩 필드는 기본적으로 채워지지 않습니다.
채워지지 않은 중첩 필드가 있는 객체는 제외 필터 (!=
)로 반환되지 않습니다.
다음 예를 참고하세요.
item.tools
에는 값을 "SMALL"
, "MEDIUM"
또는 "LARGE"
로 설정할 수 있는 size
enum이 있습니다.
다음 항목이 있는 경우:
{
"name": "item1",
"tools": {
"size": "MEDIUM"
}
},
{
"name": "item2",
"tools": {
"size": "LARGE"
}
},
{
"name": "item3"
}
네거티브 필터 "tools.size != SMALL"
로 items.list
를 호출하면 다음이 반환됩니다.
{
"items": [
{
"name": "item1",
"tools": {
"size": "MEDIUM"
}
},
{
"name": "item2",
"tools": {
"size": "LARGE"
}
}
]
}
item3
에 item.tools.size
가 설정되지 않았으므로 음수 필터는 item3
객체를 반환하지 않습니다.
예
예 | 설명 |
---|---|
externalDealId = "123456789" |
문자열 값 '123456789'가 포함된 externalDealId |
advertiserId:93641 |
정수 값 93641이 있는 advertiserId |
isSetupComplete = true |
isSetupComplete 이(가) TRUE와 같습니다. |
updateTime > "2018-02-14T11:09:19.378Z" |
updateTime 이 2018년 2월 14일 11:09:19.378(UTC) 이후입니다. |
displayName = "proposal" AND proposalRevision = 3 |
displayName 문자열에 동일한 'proposal' 값이 있고 offerRevision이 3과 같습니다. |
displayName = "proposal" OR proposalRevision = 3 |
displayName 의 문자열 값이 'proposal'이거나 제안서 Revision이 3입니다. |
NOT displayName = "proposal" |
displayName 은(는) '제안서'와 같지 않습니다. |
proposalState = (PROPOSED OR BUYER_ACCEPTED) |
proposalState 에는 PROPOSED 또는 구매자 수락됨과 같은 열거형 값이 있습니다. |
proposalState = (PROPOSED AND BUYER_ACCEPTED) |
proposalState 에 PROPOSED AND BUYER_AcceptedED와 동일한 열거형 값이 있습니다. |
dealName = Test Deal |
INVALID 표현식 |
dealName = "Test Deal" |
dealName 은 '테스트 거래'와 같습니다. |
dealName = (Test Deal) |
dealName 는 'Test'와 같고 'Deal'과도 동일합니다. |
dealName = ("Test1" OR "Test2") |
dealName 은 'Test1'과 같거나 'Test2'와 같습니다. |
dealName:* |
dealName is not null. |
dealName:"test" |
dealName 에는 'test' 하위 문자열이 포함됩니다. |
dealName:("A B") |
dealName 에는 하위 문자열 'A B'가 포함됩니다. |
dealName:(A B) |
dealName 에는 하위 문자열 'A'와 하위 문자열 'B'가 포함됩니다. |
dealName:("A" OR "B" AND "C") |
dealName 이(가) 하위 문자열 'A' 또는 'B'를 포함하며 하위 문자열 'C'도 포함합니다. |
dealName:("A B" C) |
dealName 에는 하위 문자열 'A B'와 하위 문자열 'C'가 포함됩니다. |
dealName:("A B" OR C D) |
dealName 은(는) 하위 문자열 'A B' 또는 'C'를 포함하며 하위 문자열 'D'도 포함합니다. |
dealName:(NOT "A" B) |
dealName 은(는) 하위 문자열 'A'를 포함하지 않으며 하위 문자열 'B'도 포함합니다. |
dealName:(NOT "A" OR "B") |
dealName 에 하위 문자열 'A'가 없거나 하위 문자열 'B'가 포함되어 있습니다. |