목록 응답 필터링

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")