필터 구문 및 사용법 나열

이 가이드에서는 목록 필터 구문과 다양한 리소스 유형을 필터링하는 방법을 설명합니다.

일부 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}

작업은 다음 순서로 실행됩니다.

1. NOT
2. OR
3. 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로 취급됩니다.	1234.567 -789.0123
정수	소수점이 없는 숫자, 기호('-')가 있거나 없는 모든 숫자는 정수로 취급됩니다.	1234 -789

문자열

이 섹션에서는 필터 구문에 문자열 리터럴로 작성할 수 있는 유형을 설명합니다.

참고: 문자열 리터럴은 큰따옴표 (" ")를 사용하거나 따옴표로 묶지 않을 수 있습니다. 작은따옴표는 문자열 리터럴을 나타내는 데 사용할 수 없습니다. 예를 들어 'ABC DEF'와 ABC DEF는 문자열 리터럴이지만 'ABC DEF'는 아닙니다.

유형	정의	예
불리언	대소문자에 관계없이 TRUE 또는 FALSE	TRUE True "true"
열거형	열거형 유형 리터럴의 이름입니다. enum은 대소문자를 구분합니다.	FINALIZED은(는) Finalized과(와) 같지 않습니다.
문자열	UTF-8 인코딩 텍스트 또는 7비트 ASCII 텍스트를 포함하는 문자열. 삽입된 따옴표는 백슬래시로 이스케이프 처리합니다. 공백이 있는 따옴표가 없는 문자열은 공백으로 문자열을 분할한 후 모든 단어 중에서 암시적 'AND'로 처리됩니다.	name = "test \"double quotes\"" name=(ABC DEF)는 name=ABC AND name=DEF와 동일합니다.
타임스탬프	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 리소스 필드를 필터링할 수 있습니다.

1. 필드 식별자 경로를 따라 반복되는 구성요소가 하나만 있음
2. 필드 경로의 마지막 식별자는 스칼라 유형입니다.

중첩되고 반복되는 필드에 대한 필터링은 지원되지 않습니다.

다음 예를 참고하세요.

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 advertiserId = 93641	정수 값 93641이 있는 advertiserId
isSetupComplete = true isSetupComplete:TRUE 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" proposalRevision = 3	displayName 문자열에 동일한 'proposal' 값이 있고 offerRevision이 3과 같습니다.
displayName = "proposal" OR proposalRevision = 3	displayName의 문자열 값이 'proposal'이거나 제안서 Revision이 3입니다.
NOT displayName = "proposal" displayName != "proposal"	displayName은(는) '제안서'와 같지 않습니다.
proposalState = (PROPOSED OR BUYER_ACCEPTED) proposalState = PROPOSED OR proposalState = BUYER_ACCEPTED	proposalState에는 PROPOSED 또는 구매자 수락됨과 같은 열거형 값이 있습니다.
proposalState = (PROPOSED AND BUYER_ACCEPTED) proposalState = (PROPOSED BUYER_ACCEPTED) proposalState = PROPOSED AND proposalState = BUYER_ACCEPTED proposalState = PROPOSED proposalState = 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" OR dealName = "Test2"	dealName은 'Test1'과 같거나 'Test2'와 같습니다.
dealName:*	dealName is not null.
dealName:"test" dealName:test	dealName에는 'test' 하위 문자열이 포함됩니다.
dealName:("A B") dealName:"A B"	dealName에는 하위 문자열 'A B'가 포함됩니다.
dealName:(A B) dealName:"A" AND dealName:"B"	dealName에는 하위 문자열 'A'와 하위 문자열 'B'가 포함됩니다.
dealName:("A" OR "B" AND "C") dealName:("A" OR "B" "C") dealName:"A" OR dealName:"B" AND dealName:"C" dealName:"A" OR dealName:"B" dealName:"C" (dealName:"A" OR dealName:"B") AND dealName:"C" (dealName:"A" OR dealName:"B") dealName:"C"	dealName이(가) 하위 문자열 'A' 또는 'B'를 포함하며 하위 문자열 'C'도 포함합니다.
dealName:("A B" C) dealName:"A B" AND dealName:"C"	dealName에는 하위 문자열 'A B'와 하위 문자열 'C'가 포함됩니다.
dealName:("A B" OR C D)	dealName은(는) 하위 문자열 'A B' 또는 'C'를 포함하며 하위 문자열 'D'도 포함합니다.
dealName:(NOT "A" B) NOT dealName:"A" AND dealName:"B" (NOT dealName:"A") AND dealName:"B" (NOT dealName:"A") dealName:"B"	dealName은(는) 하위 문자열 'A'를 포함하지 않으며 하위 문자열 'B'도 포함합니다.
dealName:(NOT "A" OR "B") NOT dealName:"A" OR dealName:"B" (NOT dealName:"A") OR dealName:"B"	dealName에 하위 문자열 'A'가 없거나 하위 문자열 'B'가 포함되어 있습니다.