2025년 9월 8일부터 모든 새 광고 항목은 유럽연합 (EU) 정치 광고를 게재할지 여부를 선언해야 합니다. 선언을 제공하지 않는 Display & Video 360 API 및 SDF 업로드는 실패합니다. 통합을 업데이트하여 이 선언을 하는 방법에 대한 자세한 내용은 지원 중단 페이지를 참고하세요.
fields 매개변수의 형식을 지정하는 자세한 방법은 다음 부분에서 다루고 있으며, 그 다음 부분에는 응답에서 정확히 무엇이 반환되는지에 대해 자세히 설명되어 있습니다.
fields 매개변수 구문 요약
fields 요청 매개변수 값의 형식은 대략 XPath 구문을 기반으로 합니다. 지원되는 구문은 아래에 요약되어 있으며 이어지는 섹션에서 추가적인 예시를 확인할 수 있습니다.
여러 필드를 선택하려면 쉼표로 구분된 목록을 사용합니다.
a 필드 내에 중첩된 b 필드를 선택하려면 a/b를 사용하고, b 내에 중첩된 c 필드를 선택하려면 a/b/c를 사용합니다.
배열 또는 객체의 특정 하위 필드 세트를 요청하려면 하위 선택자를 사용하여 표현식을 괄호 '( )'로 묶습니다.
예: fields=advertisers(advertiserId,generalConfig/domainUrl)는 advertisers 배열에 포함된 각 요소의 광고주 ID와 도메인 URL만 반환합니다. 하위 필드를 하나만 지정할 수도 있으며, 이때 fields=advertisers(advertiserId)는 fields=advertisers/advertiserId와 같습니다.
fields 매개변수 사용 방법의 추가 예시
아래 예시에서는 fields 매개변수 값이 응답에 미치는 영향을 설명합니다.
반환받을 필드 지정(또는 필드 선택)
fields 요청 매개변수 값은 쉼표로 구분된 필드 목록이며 각 필드는 응답의 루트를 기준으로 지정됩니다. 따라서 list 작업을 수행하는 경우에는 응답으로 컬렉션이 반환되며, 일반적으로 이 응답에는 리소스 배열이 포함됩니다. 하나의 리소스를 반환하는 작업을 수행하는 경우에는 리소스를 기준으로 필드가 지정됩니다. 선택한 필드가 배열 (또는 배열의 일부)인 경우 서버는 배열의 모든 요소 중에서 선택된 부분을 반환합니다.
다음은 컬렉션 수준의 몇 가지 예입니다.
예
효과
advertisers
advertisers 배열의 모든 요소를 반환하며 각 요소의 모든 필드가 포함되지만 다른 필드는 제외됩니다.
advertisers,nextPageToken
nextPageToken 필드와 advertisers 배열의 모든 요소를 반환합니다.
advertisers/advertiserId
advertisers 배열의 모든 요소에 대해 advertiserId만 반환합니다.
중첩 필드가 반환될 때마다 응답에는 해당 필드가 속한 상위 객체가 포함됩니다.
명시적으로 함께 선택하지 않은 다른 하위 필드는 상위 필드에 포함되지 않습니다.
advertisers/generalConfig/domainUrl
advertisers 배열 아래에 중첩된 generalConfig 객체의 domainUrl 필드를 반환합니다.
다음은 리소스 수준의 몇 가지 예입니다.
예
효과
advertiserId
요청된 리소스의 advertiserId 필드를 반환합니다.
generalConfig/domainUrl
요청된 리소스에서 generalConfig 객체의 domainUrl 필드를 반환합니다.
하위 선택을 사용하여 특정 필드의 일부만 요청합니다.
기본적으로 요청에서 특정 필드를 지정하면 서버에서는 해당하는 객체 또는 배열 요소 전체를 반환합니다. 특정 하위 필드만 포함하는 응답을 지정할 수 있습니다. 아래 예와 같이 '( )' 하위 선택 구문을 사용하면 됩니다.
예
효과
advertisers(advertiserId,generalConfig/domainUrl)
advertisers 배열의 각 요소에 대해 advertiserId 및 generalConfig domainUrl 값만 반환합니다.
부분 응답 처리
서버는 fields 쿼리 매개변수가 포함된 유효한 요청을 처리한 후 요청된 데이터와 함께 HTTP 200 OK 상태 코드를 반환합니다. fields 쿼리 매개변수에 오류가 있거나 매개변수가 유효하지 않은 경우 서버에서는 HTTP 400 Bad Request 상태 코드와 함께 필드 선택에 어떤 문제가 있는지 알려 주는 오류 메시지 (예: "Invalid field selection a/b")를 반환합니다.
[null,null,["최종 업데이트: 2025-07-25(UTC)"],[[["\u003cp\u003eThis document explains how to improve your application's performance by fetching only the necessary data using partial responses.\u003c/p\u003e\n"],["\u003cp\u003ePartial responses are achieved using the \u003ccode\u003efields\u003c/code\u003e parameter in your API requests, letting you specify the desired fields to be returned.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003efields\u003c/code\u003e parameter utilizes a syntax similar to XPath, allowing you to select specific fields, nested fields, and sub-fields within objects and arrays.\u003c/p\u003e\n"],["\u003cp\u003eWhen using the \u003ccode\u003efields\u003c/code\u003e parameter, the server returns a 200 OK status with the requested data or a 400 Bad Request if the parameter is invalid.\u003c/p\u003e\n"],["\u003cp\u003eFor APIs with pagination, combine the \u003ccode\u003efields\u003c/code\u003e parameter with \u003ccode\u003emaxResults\u003c/code\u003e and \u003ccode\u003enextPageToken\u003c/code\u003e to further optimize data retrieval and enhance performance.\u003c/p\u003e\n"]]],["To enhance API call performance, request only necessary data using the `fields` parameter for a partial response. This reduces data transfer, parsing, and storage, optimizing network, CPU, and memory usage. The `fields` parameter specifies desired fields in a comma-separated list, supporting nested field selection with `a/b` and sub-selections using `( )`. The server returns an HTTP 200 OK status with the specified data or 400 Bad Request if there is an error with the parameter.\n"],null,["# Improve Performance\n\nThis document covers some techniques you can use to improve the performance of\nyour application. In some cases, examples from other implemented APIs are used\nto illustrate the ideas presented. However, the same concepts are applicable\nto the Display \\& Video 360 API.\n\nWorking with partial resources\n------------------------------\n\nAnother way to improve the performance of your API calls is to request only\nthe portion of the data that you're interested in. This lets your application\navoid transferring, parsing, and storing unneeded fields, so it can use\nresources such as network, CPU, and memory more efficiently.\n\n### Partial response\n\nBy default, the server sends back the full representation of a resource after\nprocessing requests. For better performance, you can ask the server to send\nonly the fields you really need and get a *partial response* instead.\n\nTo request a partial response, use the `fields` request parameter to specify\nthe fields you want returned. You can use this parameter with any request\nthat returns response data.\n\n#### Example\n\nThe following example shows the use of the `fields` parameter with the\nDisplay \\& Video 360 API.\n\n**Simple request:** This HTTP `GET` request omits the `fields` parameter and\nreturns the full resource. \n\n GET https://displayvideo.googleapis.com/v4/advertisers?partnerId=1\n\n**Full resource response:** The full resource data includes the following\nfields, along with many others that have been omitted for brevity. \n\n 200 OK\n\n {\n \"advertisers\": [\n {\n \"name\": \"advertisers/1\",\n \"advertiserId\": \"1\",\n \"partnerId\": \"1\",\n \"displayName\": \"Example Advertiser 1\",\n \"entityStatus\": \"ENTITY_STATUS_ACTIVE\",\n \"updateTime\": \"2019-01-01T00:00:00.000000Z\",\n \"generalConfig\": {\n \"domainUrl\": \"http://example.com\",\n \"timeZone\": \"America/New_York\",\n \"currencyCode\": \"USD\",\n \"address\": {\n }\n },\n \"adServerConfig\": {\n \"thirdPartyOnlyConfig\": {\n }\n },\n \"creativeConfig\": {\n },\n \"dataAccessConfig\": {\n \"sdfConfig\": {\n \"sdfConfig\": {\n \"version\": \"VERSION_3_1\"\n }\n }\n },\n \"integrationDetails\": {\n }\n },\n {\n \"name\": \"advertisers/2\",\n \"advertiserId\": \"2\",\n \"partnerId\": \"1\",\n \"displayName\": \"Example Advertiser 2\",\n \"entityStatus\": \"ENTITY_STATUS_ACTIVE\",\n \"updateTime\": \"2019-01-01T00:00:00.000000Z\",\n \"generalConfig\": {\n \"domainUrl\": \"http://example.com\",\n \"timeZone\": \"America/New_York\",\n \"currencyCode\": \"USD\",\n \"address\": {\n }\n },\n \"adServerConfig\": {\n \"thirdPartyOnlyConfig\": {\n }\n },\n \"creativeConfig\": {\n },\n \"dataAccessConfig\": {\n \"sdfConfig\": {\n \"sdfConfig\": {\n \"version\": \"VERSION_3_1\"\n }\n }\n },\n \"integrationDetails\": {\n }\n },\n ...\n ],\n \"nextPageToken\": \"...\"\n }\n\n**Request for a partial response:** The following request for this same resource\nuses the `fields` parameter to significantly reduce the amount of data returned. \n\n```text\nGET https://displayvideo.googleapis.com/v4/advertisers?partnerId=1&fields=advertisers(advertiserId,partnerId,displayName)\n```\n\n**Partial response:** In response to the request above, the server sends back a\nresponse that contains a pared-down advertisers array that includes only the\nadvertiser ID, display name, and partner ID property of each advertiser, if\npresent. \n\n 200 OK\n\n {\n \"advertisers\": [\n {\n \"advertiserId\": \"1\",\n \"partnerId\": \"1\",\n \"displayName\": \"Example Advertiser 1\"\n },\n {\n \"advertiserId\": \"2\",\n \"partnerId\": \"1\",\n \"displayName\": \"Example Advertiser 2\"\n },\n ...\n ]\n }\n\nNote that the response is a JSON object that includes only the selected fields\nand their enclosing parent objects.\n\nDetails on how to format the `fields` parameter is covered next, followed by\nmore details about what exactly gets returned in the response.\n\n##### Fields parameter syntax summary\n\nThe format of the `fields` request parameter value is loosely based on XPath\nsyntax. The supported syntax is summarized below, and additional examples are\nprovided in the following section.\n\n- Use a comma-separated list to select multiple fields.\n\n- Use `a/b` to select a field `b` that is nested within field `a`; use `a/b/c`\n to select a field `c` nested within `b`.\n\n- Use a sub-selector to request a set of specific sub-fields of arrays or\n objects by placing expressions in parentheses \"`( )`\".\n\n For example: `fields=advertisers(advertiserId,generalConfig/domainUrl)`\n returns only the advertiser ID and domain URL for each element in the\n advertisers array. You can also specify a single sub-field, where\n `fields=advertisers(advertiserId)` is equivalent to\n `fields=advertisers/advertiserId`.\n\n##### More examples of using the fields parameter\n\nThe examples below include descriptions of how the `fields` parameter value\naffects the response.\n| **Note:** As with all query parameter values, the `fields` parameter value must be URL encoded. For better readability, the examples in this document omit the encoding.\n\nIdentify the fields you want returned, or make *field selections*.\n\n: The `fields` request parameter value is a comma-separated list of fields, and\n each field is specified relative to the root of the response. Thus, if you\n are performing a `list` operation, the response is a collection, and it\n generally includes an array of resources. If you are performing an operation\n that returns a single resource, fields are specified relative to that\n resource. If the field you select is (or is part of) an array, the server\n returns the selected portion of all elements in the array.\n\n Here are some collection-level examples:\n\n | Example | Effect |\n |---------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n | `advertisers` | Returns all elements in the `advertisers` array, including all fields in each element, but no other fields. |\n | `advertisers,nextPageToken` | Returns both the `nextPageToken` field and all elements in the `advertisers` array. |\n | `advertisers/advertiserId` | Returns only the `advertiserId` for all elements in the `advertisers` array. Whenever a nested field is returned, the response includes the enclosing parent objects. The parent fields do not include any other child fields unless they are also selected explicitly. |\n | `advertisers/generalConfig/domainUrl` | Returns the `domainUrl` field for the `generalConfig` object, which itself is nested under the `advertisers` array. |\n\n Here are some resource-level examples:\n\n | Example | Effect |\n |---------------------------|-----------------------------------------------------------------------------------------|\n | `advertiserId` | Returns the `advertiserId` field of the requested resource. |\n | `generalConfig/domainUrl` | Returns the `domainUrl` field for the `generalConfig` object in the requested resource. |\n\nRequest only parts of specific fields using *sub-selections*.\n\n: By default, if your request specifies particular fields, the server returns\n the objects or array elements in their entirety. You can specify a response\n that includes only certain sub-fields. You do this using \"`( )`\"\n sub-selection syntax, as in the example below.\n\n | Example | Effect |\n |-----------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|\n | `advertisers(advertiserId,generalConfig/domainUrl)` | Returns only the values of `advertiserId` and generalConfig `domainUrl` for each element in the `advertisers` array. |\n\n##### Handling partial responses\n\nAfter a server processes a valid request that includes the `fields` query\nparameter, it sends back an HTTP `200 OK` status code, along with the requested\ndata. If the `fields` query parameter has an error or is otherwise invalid, the\nserver returns an HTTP `400 Bad Request` status code, along with an error\nmessage telling you what was wrong with the fields selection (for example,\n`\"Invalid field selection a/b\"`).\n| **Note:** For APIs that support query parameters for data pagination (`maxResults` and `nextPageToken`, for example), use those parameters to reduce the results of each query to a manageable size. Otherwise, the performance gains possible with partial response might not be realized."]]
