fields 매개변수의 형식을 지정하는 자세한 방법은 다음 부분에서 다루고 있으며, 그 다음 부분에는 응답에서 정확히 무엇이 반환되는지에 대해 자세히 설명되어 있습니다.
fields 매개변수 구문 요약
fields 요청 매개변수의 값 형식은 대략 XPath 구문을 기반으로 합니다. 지원되는 구문은 아래에 요약되어 있으며 이어지는 섹션에서 추가적인 예시를 확인할 수 있습니다.
여러 필드를 선택하려면 쉼표로 구분된 목록을 사용합니다.
a 필드 내에 중첩된 b 필드를 선택하려면 a/b를 사용하고, b 내에 중첩된 c 필드를 선택하려면 a/b/c를 사용합니다.
예외:data: { ... }와 같이 응답이 data 객체 내에 중첩되도록 'data' 래퍼를 사용하는 API 응답의 경우 fields 사양에 'data'를 포함하지 마세요. 필드를 지정할 때 data/a/b와 같이 data 객체를 포함하면 오류가 발생합니다. 대신 fields를 a/b와 같이 지정하세요.
배열 또는 객체의 특정 하위 필드 세트를 요청하려면 하위 선택자를 사용하여 표현식을 괄호 '( )'로 묶습니다.
예: fields=items(id,author/email)는 items 배열에 포함된 각 요소의 항목 ID와 작성자 이메일만 반환합니다. 하위 필드를 하나만 지정할 수도 있으며, 이때 fields=items(id)는 fields=items/id와 같습니다.
필요한 경우 필드 선택 구문에 와일드 카드를 사용합니다.
예: fields=items/pagemap/*는 페이지 지도 내의 모든 객체를 선택합니다.
fields 매개변수 사용 방법의 추가 예시
아래 예시에서는 fields 매개변수 값이 응답에 미치는 영향을 설명합니다.
참고: 모든 쿼리 매개변수 값과 마찬가지로 fields 매개변수 값도 URL로 인코딩되어야 합니다. 이 문서의 예시에는 보기 쉽도록 인코딩이 생략되어 있습니다.
반환받을 필드 지정(또는 필드 선택)
fields 요청 매개변수 값은 쉼표로 구분된 필드 목록이며 각 필드는 응답의 루트를 기준으로 지정됩니다. 따라서 list 작업을 수행하는 경우에는 응답으로 컬렉션이 반환되며, 일반적으로 이 응답에는 리소스 배열이 포함됩니다. 하나의 리소스를 반환하는 작업을 수행하는 경우에는 리소스를 기준으로 필드가 지정됩니다. 선택한 필드가 배열(또는 배열의 일부)인 경우 서버에서는 배열의 모든 요소 중에서 선택된 부분을 반환합니다.
다음은 컬렉션 수준의 몇 가지 예시입니다.
예시
효과
items
items 배열의 모든 요소를 반환하며 각 요소의 모든 필드가 포함되지만 다른 필드는 제외됩니다.
etag,items
etag 필드 및 items 배열의 모든 요소를 반환합니다.
items/title
items 배열에 포함된 모든 요소의 title 필드만 반환합니다.
중첩 필드가 반환되는 경우 응답에는 항상 해당 필드가 속한 상위 객체가 포함됩니다. 명시적으로 함께 선택하지 않은 다른 하위 필드는 상위 필드에 포함되지 않습니다.
context/facets/label
context 객체 아래에 중첩된 facets 배열의 모든 구성원에 대해 label 필드만 반환합니다.
items/pagemap/*/title
items 배열의 각 요소에 대해 pagemap의 하위 항목인 모든 객체의 title 필드(있는 경우)만 반환합니다.
다음은 리소스 수준의 몇 가지 예시입니다.
예시
효과
title
요청된 리소스의 title 필드를 반환합니다.
author/uri
요청된 리소스에서 author 객체의 uri 하위 필드를 반환합니다.
links/*/href
links의 하위 요소인 모든 객체의 href 필드를 반환합니다.
하위 선택을 사용하여 특정 필드의 일부만 요청
기본적으로 요청에서 특정 필드를 지정하면 서버에서는 해당하는 객체 또는 배열 요소 전체를 반환합니다. 하지만 특정 하위 필드만 포함하는 응답을 지정할 수도 있습니다. 아래 예시와 같이 '( )' 하위 선택 구문을 사용하면 됩니다.
예
효과
items(title,author/uri)
items 배열에 포함된 각 요소에 대해 title 및 author의 uri 값만 반환합니다.
부분 응답 처리
서버는 fields 쿼리 매개변수가 포함된 유효한 요청을 처리한 후 요청된 데이터와 함께 HTTP 200 OK 상태 코드를 반환합니다. fields 쿼리 매개변수에 오류가 있거나 매개변수가 유효하지 않은 경우 서버에서는 HTTP 400 Bad Request 상태 코드와 함께 필드 선택에 어떤 문제가 있는지 알려 주는 오류 메시지(예: "Invalid field selection a/b")를 반환합니다.
다음은 위 소개 섹션에 나와 있는 부분 응답의 예입니다. 요청에서는 fields 매개변수를 사용하여 반환할 필드를 지정합니다.
참고: 데이터 페이지 나누기를 위한 쿼리 매개변수(예: maxResults 및 nextPageToken)를 지원하는 API의 경우 이러한 매개변수를 사용하여 각 쿼리의 결과를 관리 가능한 크기로 줄이세요. 그러지 않으면 부분 응답을 사용해도 성능이 개선되지 않을 수 있습니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-09-04(UTC)"],[],[],null,["# Improve performance\n\nThis document covers some techniques you can use to improve the performance of your application. In some cases, examples from other APIs or generic APIs are used to illustrate the ideas presented. However, the same concepts are applicable to the Resource Manager API.\n\nCompression using gzip\n----------------------\n\nAn easy and convenient way to reduce the bandwidth needed for each request is to enable gzip compression. Although this requires additional CPU time to uncompress the results, the trade-off with network costs usually makes it very worthwhile.\n\nIn order to receive a gzip-encoded response you must do two things: Set an `Accept-Encoding` header, and modify your user agent to contain the string `gzip`. Here is an example of properly formed HTTP headers for enabling gzip compression: \n\n```perl6\nAccept-Encoding: gzip\nUser-Agent: my program (gzip)\n```\n\nWorking with partial resources\n------------------------------\n\nAnother way to improve the performance of your API calls is by requesting only the portion of the data that you're interested in. This lets your application avoid transferring, parsing, and storing unneeded fields, so it can use resources including network, CPU, and memory more efficiently.\n\n### Partial response\n\nBy default, the server sends back the full representation of a resource after processing requests. For better performance, you can ask the server to send only the fields you really need and get a *partial response* instead.\n\nTo request a partial response, use the `fields` request parameter to specify the fields you want returned. You can use this parameter with any request that returns response data.\n\n#### Example\n\nThe following example shows the use of the `fields` parameter with a generic (fictional) \"Demo\" API.\n\n**Simple request:** This HTTP `GET` request omits the `fields` parameter and returns the full resource. \n\n```\nhttps://www.googleapis.com/demo/v1\n```\n\n**Full resource response:** The full resource data includes the following fields, along with many others that have been omitted for brevity. \n\n```text\n{\n \"kind\": \"demo\",\n ...\n \"items\": [\n {\n \"title\": \"First title\",\n \"comment\": \"First comment.\",\n \"characteristics\": {\n \"length\": \"short\",\n \"accuracy\": \"high\",\n \"followers\": [\"Jo\", \"Will\"],\n },\n \"status\": \"active\",\n ...\n },\n {\n \"title\": \"Second title\",\n \"comment\": \"Second comment.\",\n \"characteristics\": {\n \"length\": \"long\",\n \"accuracy\": \"medium\"\n \"followers\": [ ],\n },\n \"status\": \"pending\",\n ...\n },\n ...\n ]\n}\n```\n\n**Request for a partial response:** The following request for this same resource uses the `fields` parameter to significantly reduce the amount of data returned. \n\n```\nhttps://www.googleapis.com/demo/v1?fields=kind,items(title,characteristics/length)\n```\n\n**Partial response:** In response to the request above, the server sends back a response that contains only the kind information along with a pared-down items array that includes only HTML title and length characteristic information in each item. \n\n```\n200 OK\n``` \n\n```text\n{\n \"kind\": \"demo\",\n \"items\": [{\n \"title\": \"First title\",\n \"characteristics\": {\n \"length\": \"short\"\n }\n }, {\n \"title\": \"Second title\",\n \"characteristics\": {\n \"length\": \"long\"\n }\n },\n ...\n ]\n}\n```\n\nNote that the response is a JSON object that includes only the selected fields and their enclosing parent objects.\n\nDetails on how to format the `fields` parameter is covered next, followed by more 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 syntax. The supported syntax is summarized below, and additional examples are provided in the following section.\n\n- Use a comma-separated list to select multiple fields.\n- Use `a/b` to select a field `b` that is nested within field `a`; use `a/b/c` to select a field `c` nested within `b`. \n\n **Exception:** For API responses that use \"data\" wrappers, where the response is nested within a `data` object that looks like `data: { ... }`, do not include \"`data`\" in the `fields` specification. Including the data object with a fields specification like `data/a/b` causes an error. Instead, just use a `fields` specification like `a/b`.\n- Use a sub-selector to request a set of specific sub-fields of arrays or objects by placing expressions in parentheses \"`( )`\".\n\n For example: `fields=items(id,author/email)` returns only the item ID and author's email for each element in the items array. You can also specify a single sub-field, where `fields=items(id)` is equivalent to `fields=items/id`.\n- Use wildcards in field selections, if needed. For example: `fields=items/pagemap/*` selects all objects in a pagemap.\n\n#### More examples of using the fields parameter\n\nThe examples below include descriptions of how the `fields` parameter value affects the response.\n\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: The `fields` request parameter value is a comma-separated list of fields, and each field is specified relative to the root of the response. Thus, if you are performing a list operation, the response is a collection, and it generally includes an array of resources. If you are performing an operation that returns a single resource, fields are specified relative to that resource. If the field you select is (or is part of) an array, the server returns the selected portion of all elements in the array. \n\n \u003cbr /\u003e\n\n\n Here are some collection-level examples: \n\n\n \u003cbr /\u003e\n\n\n Here are some resource-level examples: \n\n\nRequest only parts of specific fields using sub-selections.\n: By default, if your request specifies particular fields, the server returns the objects or array elements in their entirety. You can specify a response that includes only certain sub-fields. You do this using \"`( )`\" sub-selection syntax, as in the example below.\n\n\n\u003cbr /\u003e\n\n#### Handling partial responses\n\nAfter a server processes a valid request that includes the `fields` query parameter, it sends back an HTTP `200 OK` status code, along with the requested data. If the `fields` query parameter has an error or is otherwise invalid, the server returns an HTTP `400 Bad Request` status code, along with an error message telling the user what was wrong with their fields selection (for example, `\"Invalid field selection a/b\"`).\n\nHere is the partial response example shown in the [introductory section](#partial-response) above. The request uses the `fields` parameter to specify which fields to return. \n\n```\nhttps://www.googleapis.com/demo/v1?fields=kind,items(title,characteristics/length)\n```\n\nThe partial response looks like this: \n\n```\n200 OK\n``` \n\n```text\n{\n \"kind\": \"demo\",\n \"items\": [{\n \"title\": \"First title\",\n \"characteristics\": {\n \"length\": \"short\"\n }\n }, {\n \"title\": \"Second title\",\n \"characteristics\": {\n \"length\": \"long\"\n }\n },\n ...\n ]\n}\n```\n\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.\n\n\u003cbr /\u003e"]]
