목록 응답 필터링

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 (=) 리소스 필드 값이 지정된 값과 동일합니다.

예: entityStatus="ENTITY_STATUS_ACTIVE"
LESS THAN OR EQUAL TO (<=) 리소스 필드 값이 지정된 값보다 작거나 같습니다. 날짜 또는 날짜/시간을 비교할 때 자주 사용됩니다.

예: updateTime<="2023-04-01T12:00:00Z"
GREATER THAN OR EQUAL TO (>=) 리소스 필드 값이 지정된 값보다 크거나 같습니다. 날짜 또는 날짜/시간을 비교할 때 자주 사용됩니다.

예: updateTime>="2023-03-01T12:00:00Z"
HAS (:) 리소스 필드 값에 지정된 값이 포함되어 있습니다. 리소스 필드가 문자열인 경우 지정된 값이 기존 하위 문자열인지 확인합니다. 리소스 필드가 배열인 경우 배열에 지정된 값이 포함되어 있는지 확인합니다.

예: lineItemIds:"1234"

매개변수 설명의 필드에 연산자가 지정되지 않은 경우 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")