Display & Video 360 API의 대부분의 서비스는 리소스를 일괄적으로 가져오는 LIST
메서드를 제공합니다. 이러한 LIST
메서드는 일반적으로 filter
쿼리 매개변수를 통한 결과 필터링을 지원합니다. 이 매개변수를 사용하면 필요한 항목만 검색하여 API 사용을 최적화할 수 있습니다.
이 가이드에서는 filter
매개변수를 효과적으로 사용하는 방법을 보여줍니다.
필터 구조
filter
매개변수 값은 AND
또는 OR
연산자와 결합할 수 있는 하나 이상의 제한사항으로 구성되고 괄호를 사용하여 그룹화될 수 있는 문자열입니다.
제한사항은 {field} {operator} {value}
형식입니다. 예를 들면 다음과 같습니다.
entityStatus="ENTITY_STATUS_ACTIVE"
필터 문자열 길이는 500자(영문 기준) 이하여야 합니다. 필터 문자열이 500자를 초과하면 다음 중 하나를 수행합니다.
- 로직을 여러 필터 문자열로 분할하고 별도의
LIST
요청을 사용하여 리소스를 검색합니다. - 필터 문자열에서 일부 로직을 삭제하고 이를 사용하여 검색된 리소스를 로컬에서 필터링합니다.
로직이 올바르게 적용되도록 제한 값을 따옴표로 묶습니다.
클라이언트 라이브러리를 사용하지 않고 직접 LIST
를 호출하는 경우 필터 문자열을 URL 인코딩합니다.
쿼리 형식 지정에 대한 자세한 내용은 제한 간 논리를 참조하세요.
필터링 가능한 필드
각 LIST
메서드의 필터링 가능한 필드는 메서드의 filter
매개변수 설명에 나열됩니다. 대부분의 경우 리소스 표준 필드의 하위 집합을 필터링할 수 있습니다. 드문 경우지만 필터링에만 사용할 수 있는 추가 필드가 있습니다.
매개변수 설명의 각 필드는 다음과 같은 비교 가능한 연산자 중 하나 이상을 지원합니다.
비슷한 연산자 | ||
---|---|---|
EQUALS (=)
|
리소스 필드 값이 지정된 값과 동일합니다.
예: |
|
LESS THAN OR EQUAL TO (<=)
|
리소스 필드 값이 지정된 값보다 작거나 같습니다. 날짜 또는 날짜/시간을 비교할 때 자주 사용됩니다.
예: |
|
GREATER THAN OR EQUAL TO (>=)
|
리소스 필드 값이 지정된 값보다 크거나 같습니다. 날짜 또는 날짜/시간을 비교할 때 자주 사용됩니다.
예: |
|
HAS (:)
|
리소스 필드 값에 지정된 값이 포함되어 있습니다. 리소스 필드가 문자열인 경우 지정된 값이 기존 하위 문자열인지 확인합니다. 리소스
필드가 배열인 경우 배열에 지정된 값이 포함되어 있는지
확인합니다.
예: |
매개변수 설명의 필드에 연산자가 지정되지 않은 경우 EQUALS (=)
연산자만 사용할 수 있습니다. 일부 필드는 여러 연산자를 지원합니다.
날짜 및 시간 등과 같은 일부 필터링 가능한 필드에는 비교 가능한 값이 특정 형식을 따라야 합니다. 형식은 filter
매개변수 설명의 필드 옆에 지정됩니다.
제한 사이의 로직
여러 제한사항을 결합하여 LIST
요청의 응답 범위를 좁히거나 확장할 수 있습니다.
일반적으로 여러 개의 제한사항을 AND
및 OR
논리 연산자와 결합할 수 있습니다. 각 LIST
메서드는 지원하는 연산자를 지정합니다.
일부 메서드는 filter
매개변수에 단일 제한사항 사용만 지원합니다.
AND
또는 OR
논리 연산자로 필터 문자열을 빌드할 때는 다음 제한사항을 고려하세요.
AND
는 다른 필드를 필터링하거나 동일한 필드를 다르게 필터링하는 제한사항 또는 제한사항 그룹 사이에 사용해야 합니다. 다음은 몇 가지 예입니다.updateTime>="2023-03-01T12:00:00Z" AND entityStatus="ENTITY_STATUS_ACTIVE"
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
요청을 사용하세요. 예를 들어 다음과 같은 별도의LIST
요청을 사용합니다.(lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" AND insertionOrderId="123")
(lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT" AND insertionOrderId="456")
OR
연산자를 사용하여 결합하지 마세요.(lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" AND insertionOrderId="123") OR (lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT" AND insertionOrderId="456")
필터 문자열에서 제한사항을 그룹화하는 데 괄호를 사용하지 않으면 괄호가 함축될 수 있습니다. 예를 들어 다음 필터 문자열은 다음과 같습니다.
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")