2025년 9월 8일부터 모든 새 광고 항목은 유럽연합 (EU) 정치 광고를 게재할지 여부를 선언해야 합니다. 선언을 제공하지 않는 Display & Video 360 API 및 SDF 업로드는 실패합니다. 통합을 업데이트하여 이 선언을 하는 방법에 대한 자세한 내용은
지원 중단 페이지를 참고하세요.
목록 응답 필터링
컬렉션을 사용해 정리하기
내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.
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")
달리 명시되지 않는 한 이 페이지의 콘텐츠에는 Creative Commons Attribution 4.0 라이선스에 따라 라이선스가 부여되며, 코드 샘플에는 Apache 2.0 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 Google Developers 사이트 정책을 참조하세요. 자바는 Oracle 및/또는 Oracle 계열사의 등록 상표입니다.
최종 업데이트: 2025-07-25(UTC)
[null,null,["최종 업데이트: 2025-07-25(UTC)"],[[["\u003cp\u003eOptimize Display & Video 360 API usage by filtering \u003ccode\u003eLIST\u003c/code\u003e method results with the \u003ccode\u003efilter\u003c/code\u003e query parameter to retrieve only necessary data.\u003c/p\u003e\n"],["\u003cp\u003eStructure filter strings using restrictions like \u003ccode\u003e{field} {operator} {value}\u003c/code\u003e, combining them with \u003ccode\u003eAND\u003c/code\u003e or \u003ccode\u003eOR\u003c/code\u003e operators and parentheses for grouping, ensuring the string remains under 500 characters.\u003c/p\u003e\n"],["\u003cp\u003eRefer to each \u003ccode\u003eLIST\u003c/code\u003e method's documentation for filterable fields and supported operators, using comparison operators such as \u003ccode\u003e=\u003c/code\u003e, \u003ccode\u003e<=\u003c/code\u003e, \u003ccode\u003e>=\u003c/code\u003e, and \u003ccode\u003e:\u003c/code\u003e with appropriate values and formats.\u003c/p\u003e\n"],["\u003cp\u003eConstruct complex filter logic by combining restrictions with \u003ccode\u003eAND\u003c/code\u003e for filtering different fields or applying different criteria to the same field, and \u003ccode\u003eOR\u003c/code\u003e for multiple criteria on the same field, adhering to specific guidelines for combining groups.\u003c/p\u003e\n"]]],["The `LIST` method in the Display & Video 360 API uses a `filter` parameter to refine bulk resource retrieval. Filters are strings comprised of restrictions (`{field} {operator} {value}`) combined with `AND` or `OR` operators, and grouped with parentheses. Common operators include `=`, `\u003c=`, `\u003e=`, and `:`. Restrictions on different fields use `AND`, while same-field restrictions use `OR`. Filter strings are limited to 500 characters, and longer logic should be split into multiple requests. The filter strings must be wrapped in quotes.\n"],null,["# Filter list responses\n\nMost services in the Display \\& Video 360 API provide a `LIST` method for bulk retrieval of\nresources. These `LIST` methods usually support filtering results through a\n`filter` query parameter. Use this parameter to optimize your API usage by only\nretrieving what you need.\n\nThis guide shows how to use the `filter` parameter effectively.\n\nFilter structure\n----------------\n\nA `filter` parameter value is a string, consisting of one or more restrictions\nthat can be combined with **`AND`** or **`OR`** operators, and grouped using\nparentheses.\n\nRestrictions are of the form `{field} {operator} {value}`. Here's an\nexample: \n\n entityStatus=\"ENTITY_STATUS_ACTIVE\"\n\nThe filter string length cannot exceed 500 characters. If your filter string\nexceeds 500 characters, do one of the following:\n\n- Split the logic into multiple filter strings, and retrieve the resources using separate `LIST` requests.\n- Remove some of the logic from the filter string, and use it to filter the retrieved resources locally.\n\nWrap restriction values in quotes to ensure logic is properly applied.\n\nURL-encode your filter strings if you are making `LIST` calls directly without\nusing a client library.\n\nSee [Logic between restrictions](#logic) for more details on formatting\nyour queries.\n\nFilterable fields\n-----------------\n\nEach `LIST` method's filterable fields are listed in the method's `filter`\nparameter description. In most cases, you can filter on a subset of a resource's\nstandard fields. In some rare cases, there are additional fields you can use\nonly for filtering.\n\nEach field in the parameter's description supports at least one of the following\ncomparable operators:\n\n| Comparable Operators || |\n|-------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---|\n| **`EQUALS (=)`** | Resource field value is equal to given value. Example: `entityStatus=\"ENTITY_STATUS_ACTIVE\"` |\n| **`LESS THAN OR EQUAL TO (\u003c=)`** | Resource field value is less than or equal to given value. Often used when comparing a date or datetime. Example: `updateTime\u003c=\"2023-04-01T12:00:00Z\"` |\n| **`GREATER THAN OR EQUAL TO (\u003e=)`** | Resource field value is greater than or equal to given value. Often used when comparing a date or datetime. Example: `updateTime\u003e=\"2023-03-01T12:00:00Z\"` |\n| **`HAS (:)`** | Resource field value contains the given value. If the resource field is a string, it will check if the given value is an existing substring. If the resource field is an array, it will check if the array contains the given value. Example: `lineItemIds:\"1234\"` |\n\nIf no operators are specified for the field in the parameter's description, you\ncan only use the `EQUALS (=)` operator. Some fields support multiple operators.\n\nSome filterable fields, such as those for dates and times, require the\ncomparable value to follow a specific format. The format is specified next to\nthe field in the `filter` parameter description.\n\nLogic between restrictions\n--------------------------\n\nYou can combine multiple restrictions to narrow or expand the response from your\n`LIST` request.\n\nYou can usually combine multiple restrictions with **`AND`** and **`OR`**\nlogical operators. Each `LIST` method specifies which operators it supports.\nSome methods only support using a single restriction in the `filter` parameter.\n\nConsider the following restrictions when building filter strings with **`AND`**\nor **`OR`** logical operators:\n| **Note:** The following examples are written using the [`advertisers.lineItems.list`](/display-video/api/reference/rest/current/advertisers.lineItems/list) method's [`filter`](/display-video/api/reference/rest/current/advertisers.lineItems/list#body.QUERY_PARAMETERS.filter) parameter restrictions.\n\n- **`AND`** must be used between restrictions, or groups of restrictions, that filter different fields, or that filter the same field differently. Here are some examples:\n - `updateTime\u003e=\"2023-03-01T12:00:00Z\" AND entityStatus=\"ENTITY_STATUS_ACTIVE\"`\n - `updateTime\u003e=\"2023-03-01T12:00:00Z\" AND updateTime\u003c=\"2023-04-01T12:00:00Z\"\n AND (entityStatus=\"ENTITY_STATUS_ACTIVE\" OR\n entityStatus=\"ENTITY_STATUS_PAUSED\")`\n- **`OR`** must be used between individual restrictions that filter by the same field. Here's an example:\n - `(entityStatus=\"ENTITY_STATUS_ACTIVE\" OR\n entityStatus=\"ENTITY_STATUS_PAUSED\") AND\n (lineItemType=\"LINE_ITEM_TYPE_DISPLAY_DEFAULT\" OR\n lineItemType=\"LINE_ITEM_TYPE_VIDEO_DEFAULT\")`\n- You can't use **`OR`** to combine two groups of restrictions. Use multiple\n `LIST` requests with different filter values instead. For example, use the\n following separate `LIST` requests:\n\n - `(lineItemType=\"LINE_ITEM_TYPE_DISPLAY_DEFAULT\" AND insertionOrderId=\"123\")`\n - `(lineItemType=\"LINE_ITEM_TYPE_VIDEO_DEFAULT\" AND insertionOrderId=\"456\")`\n\n Don't use the **`OR`** operator to combine them:\n\n `(lineItemType=\"LINE_ITEM_TYPE_DISPLAY_DEFAULT\" AND insertionOrderId=\"123\") OR\n (lineItemType=\"LINE_ITEM_TYPE_VIDEO_DEFAULT\" AND insertionOrderId=\"456\")`\n- Parentheses might be implied if you don't use them to group restrictions in a\n filter string. For example, the following filter string:\n\n `updateTime\u003e=\"2023-03-01T12:00:00Z\" AND entityStatus=\"ENTITY_STATUS_ACTIVE\" OR\n entityStatus=\"ENTITY_STATUS_PAUSED\" OR entityStatus=\"ENTITY_STATUS_DRAFT\"`\n\n is interpreted as:\n\n `updateTime\u003e=\"2023-03-01T12:00:00Z\" AND (entityStatus=\"ENTITY_STATUS_ACTIVE\"\n OR entityStatus=\"ENTITY_STATUS_PAUSED\" OR entityStatus=\"ENTITY_STATUS_DRAFT\")`"]]
