list 메서드는 설정된 유형의 여러 리소스를 가져옵니다. filter 쿼리 매개변수를 사용하면 검색된 리소스가 충족해야 하는 기준을 지정할 수 있습니다.
필터 구조
filter 매개변수 값은 문자열입니다. 이러한 문자열은 하나 이상의 기준으로 구성됩니다. 기준은 AND 또는 OR 연산자로 조인됩니다.
단일 기준의 형식은 {field} {operator} {value}입니다. 예를 들면 다음과 같습니다.
entityStatus="ENTITY_STATUS_ACTIVE"
필터 문자열은 500자로 제한됩니다. 문자열이 너무 긴 경우:
- 로직을 별도의 문자열로 나눕니다. 각 필터 문자열로
list호출 결과를 결합하여 하나의 목록을 만듭니다. - 필터 문자열에서 기준을 삭제합니다. 삭제된 기준을 사용하여 검색된 리소스를 로컬로 필터링합니다.
기준 값을 따옴표로 묶습니다.
API를 직접 호출할 때 필터 문자열이 URL에서 사용할 수 있도록 인코딩되어 있는지 확인합니다.
필터 문자열 구조에 관한 자세한 내용은 조인 기준 섹션을 참고하세요.
필터 기준
각 목록 메서드는 특정 필터 기준을 지원합니다. 메서드의 filter 매개변수에 대한 설명에는 이러한 기준이 나열되어 있습니다. 필터 기준은 가져온 리소스의 필드의 하위 집합인 경우가 많습니다.
각 기준은 하나 이상의 연산자를 지원합니다.
| 비교 가능한 연산자 | |
|---|---|
EQUALS (=)
|
필드가 지정된 값과 같습니다. 예: |
LESS THAN OR EQUAL TO (<=)
|
필드가 지정된 값보다 작거나 같습니다. 날짜 또는 datetime으로 필터링하는 데 자주 사용됩니다. 예: |
GREATER THAN OR EQUAL TO (>=)
|
필드가 지정된 값보다 크거나 같습니다. 날짜 또는 datetime으로 필터링하는 데 자주 사용됩니다. 예: |
HAS (:)
|
필드에 지정된 값이 포함되어 있습니다. 필드가 문자열인 경우 지정된 값이 하위 문자열인지 확인합니다. 필드가 배열인 경우 배열에서 지정된 값을 확인합니다. 예: |
기준에서 연산자를 지정하지 않으면 EQUALS (=)만 지원됩니다.
기준에 특별한 형식이 필요한지 표시됩니다.
조인 기준
여러 기준을 결합하여 list 대답을 추가로 제한합니다.
논리 연산자 AND 및 OR로 기준을 결합합니다. 각 list 메서드는 지원되는 항목을 지정합니다. 일부 메서드는 기준이 하나인 필터만 지원합니다.
여러 기준을 사용할 때는 다음 한도를 고려하세요.
| 제한사항 및 예 | |
|---|---|
AND는 서로 다른 필드를 필터링하거나 동일한 필드를 다르게 필터링하는 제한사항 또는 제한사항 그룹을 결합해야 합니다.
|
updateTime>="2023-03-01T12:00:00Z" AND updateTime<="2023-04-01T12:00:00Z" AND (entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED")
|
OR은 동일한 필드로 필터링하는 개별 제한사항을 결합해야 합니다.
|
(entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED") AND (lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" OR lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT")
|
OR는 두 그룹의 제한을 결합할 수 없습니다. 대신 필터 값이 다른 list 요청을 여러 개 사용하세요.
|
다음 두 필터 문자열은 별도의 요청에서 사용해야 하며 OR 연산자를 사용하여 결합할 수 없습니다.
|
| 괄호가 포함되지 않더라도 제한사항을 그룹화하는 데 괄호가 사용될 수 있습니다. |
필터 문자열 updateTime>="2023-03-01T12:00:00Z" AND entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED" OR entityStatus="ENTITY_STATUS_DRAFT"는 updateTime>="2023-03-01T12:00:00Z" AND (entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED" OR entityStatus="ENTITY_STATUS_DRAFT")로 해석됩니다.
|