필요한 정확한 필드를 반환하고 성능을 개선하려면 메서드 호출에서 fieldssystem parameter를 사용하세요.
이 문서에서는 Google Drive에서 fields 매개변수를 사용하는 방법을 설명합니다.
필드 매개변수의 작동 방식
fields 매개변수는 응답 필터링에 FieldMask를 사용합니다. 필드 마스크는 요청에서 반환해야 하는 필드의 하위 집합을 지정하는 데 사용됩니다. 필드 마스크를 사용하면 불필요한 데이터의 요청을 방지하여 불필요한 처리 시간을 막을 수 있습니다.
fields 매개변수를 지정하지 않으면 서버에서 메서드에 특화된 기본 필드 집합을 반환합니다. 예를 들어 files 메서드의 list 메서드는 kind, id, name, mimeType 필드만 반환합니다. permissions 리소스의 get 메서드는 다른 기본 필드 집합을 반환합니다.
about, comments (delete 제외), replies (delete 제외) 리소스의 모든 메서드에 대해 fields 매개변수를 설정해야 합니다. 이러한 메서드는 기본 필드 집합을 반환하지 않습니다.
서버는 fields 매개변수가 포함된 유효한 요청을 처리한 후 요청된 데이터와 함께 HTTP 200 OK 상태 코드를 반환합니다. 필드 매개변수에 오류가 있거나 매개변수가 유효하지 않은 경우 서버에서는 HTTP 400 Bad Request 상태 코드와 함께 필드 선택에 어떤 문제가 있는지 알려 주는 오류 메시지를 반환합니다. 예를 들어 files.list(fields='files(id,capabilities,canAddChildren)')은 '잘못된 필드 선택 canAddChildren' 오류를 생성합니다. 이 예의 올바른 필드 매개변수는 files.list(fields='files(id,capabilities/canAddChildren)')입니다.
fields 매개변수를 사용하여 반환할 수 있는 필드를 확인하려면 쿼리 중인 리소스의 문서 페이지를 참고하세요. 예를 들어 파일에 대해 반환할 수 있는 필드를 확인하려면 files 리소스 문서를 참고하세요.
파일 관련 검색어에 대한 자세한 내용은 검색어 및 연산자를 참고하세요.
필드 매개변수 형식 규칙
필드 요청 매개변수 값의 형식은 대략 XPath 구문을 기반으로 합니다. 다음은 fields 매개변수의 형식 지정 규칙입니다. 이러한 규칙에서는 모두 files.get 메서드와 관련된 예시를 사용합니다.
쉼표로 구분된 목록을 사용하여 'name,
mimeType'과 같은 여러 필드를 선택합니다.
'capabilities/canDownload'과 같이 a 필드 내에 중첩된 b 필드를 선택하려면 a/b를 사용합니다. 자세한 내용은 중첩된 리소스의 필드 가져오기를 참고하세요.
하위 선택자를 사용하여 표현식을 괄호 '()'로 묶어 배열 또는 객체의 특정 하위 필드 세트를 요청합니다. 예를 들어 'permissions(id)'는 permissions 배열에 포함된 각 요소의 권한 ID만 반환합니다.
객체의 모든 필드를 반환하려면 필드 선택에서 별표 (*)를 와일드 카드로 사용합니다. 예를 들어 'permissions/permissionDetails/*'는 권한별로 사용 가능한 모든 권한 세부정보 필드를 선택합니다. 와일드 카드를 사용하면 요청 성능에 부정적인 영향을 미칠 수 있습니다.
요청
이 예시에서는 파일 ID 경로 매개변수와 여러 필드를 요청의 쿼리 매개변수로 제공합니다. 응답은 파일 ID의 필드 값을 반환합니다.
GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=name,starred,shared
[null,null,["최종 업데이트: 2025-08-04(UTC)"],[],[],null,["# Return specific fields\n\nTo return the exact fields you need, and to improve performance, use the\n`fields` [system\nparameter](https://cloud.google.com/apis/docs/system-parameters#definitions) in\nyour method call.\n\nThis document explains how to use the `fields` parameter in Google Drive.\n\nHow the fields parameter works\n------------------------------\n\nThe `fields` parameter uses a\n[FieldMask](https://protobuf.dev/reference/protobuf/google.protobuf/#field-mask)\nfor response filtering. Field masks are used to specify a subset of fields that\na request should return. Using a field mask is good design practice to make sure\nthat you don't request unnecessary data, which in turn helps avoid unnecessary\nprocessing time.\n\nIf you don't specify the `fields` parameter, the server returns a default set of\nfields specific to the method. For example, the\n[`list`](/workspace/drive/api/reference/rest/v3/files/list) method on the [`files`](/workspace/drive/api/reference/rest/v3/files) method only returns the `kind`, `id`, `name`, and\n`mimeType` fields. The [`get`](/workspace/drive/api/reference/rest/v3/permissions/get) method on the\n[`permissions`](/workspace/drive/api/reference/rest/v3/permissions) resource returns a different set\nof default fields.\n\nFor all methods of the [`about`](/workspace/drive/api/reference/rest/v3/about), [`comments`](/workspace/drive/api/reference/rest/v3/comments) (excluding `delete`), and [`replies`](/workspace/drive/api/reference/rest/v3/replies) (excluding `delete`) resources you *must* set the\n`fields` parameter. These methods don't return a default set of fields.\n\nAfter a server processes a valid request that includes the `fields` parameter,\nit returns an `HTTP 200 OK` status code, along with the requested data. If the\nfields parameter has an error or is otherwise invalid, the server returns an\n`HTTP 400 Bad Request` status code, along with an error message stating what's\nwrong with your fields selection. For example,\n`files.list(fields='files(id,capabilities,canAddChildren)')` yields an error of\n\"Invalid field selection canAddChildren.\" The correct fields parameter for this\nexample is `files.list(fields='files(id,capabilities/canAddChildren)')`.\n\nTo determine the fields you can return using the `fields` parameter, visit the\ndocumentation page of the resource you're querying. For example, to see what\nfields you can return for a file, refer to the `files` resource documentation.\nFor more file-specific query terms, see [Search query terms and operators](/workspace/drive/api/guides/ref-search-terms).\n| **Important:** Use query parameters that support data pagination (such as `maxResults` and `nextPageToken`) to reduce the results of each query to a manageable size. Otherwise, the performance gains possible with a [partial\n| response](/workspace/drive/api/guides/performance#partial) might not be realized.\n\nField parameter format rules\n----------------------------\n\nThe format of the fields request parameter value is loosely based on XPath\nsyntax. The following are formatting rules for the `fields` parameter. All these\nrules use examples related to the `files.get` method.\n\n- Use a comma-separated list to select multiple fields, such as `'name,\n mimeType'`.\n\n- Use `a/b` to select field `b` that's nested within field `a`, such as\n `'capabilities/canDownload'`. For more information, see [Fetch the fields of\n a nested resource](#nested).\n\n- Use a sub-selector to request a set of specific sub-fields of arrays or\n objects by placing expressions in parentheses \"()\". For example,\n `'permissions(id)'` returns only the permission ID for each element in the\n permissions array.\n\n- To return all fields in an object, use an asterisk (`*`) as a wildcard in\n field selections. For example, `'permissions/permissionDetails/*'` selects\n all available permission details fields per permission. Note that using the\n wildcard can lead to negative performance impacts on the request.\n\n**Request**\n\nIn this example, we provide the file ID path parameter and multiple fields as a query parameter in the request. The response returns the field values for the file ID. \n\n```scdoc\nGET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=name,starred,shared\n```\n\n**Response** \n\n```text\n{\n \"name\": \"File1\",\n \"starred\": false,\n \"shared\": true\n }\n}\n```\n\nFetch the fields of a nested resource\n-------------------------------------\n\nWhen a field refers to another resource, you can specify which fields of the\nnested resource should be fetched.\n\nFor example, to retrieve the `role` field (nested resource) of the `permissions`\nresource, use any of the following options:\n\n- `permissions.get` with `fields=role`.\n- `permissions.get` with `fields=*` to show all `permissions` fields.\n- `files.get` with `fields=permissions(role)` or `fields=permissions/role`.\n- `files.get` with `fields=permissions` to show all `permissions` fields.\n- `changes.list` with `fields=changes(file(permissions(role)))`.\n\nTo retrieve multiple fields, use a comma-separated list. For example,\n`files.list` with `fields=files(id,name,createdTime,modifiedTime,size)`. \n**Request**\n\nIn this example, we provide the file ID path parameter and multiple fields, including certain fields of the nested permissions resource, as a query parameter in the request. The response returns the field values for the file ID. \n\n```carbon\nGET https://www.googleapis.com/drive/v3/files/\u003cvar translate=\"no\"\u003eFILE_ID\u003c/var\u003e?fields=name,starred,shared,permissions(kind,type,role)\n```\n\n**Response** \n\n```carbon\n{\n \"name\": \"File1\",\n \"starred\": false,\n \"shared\": true,\n \"permissions\": [\n {\n \"kind\": \"drive#permission\",\n \"type\": \"user\",\n \"role\": \"owner\"\n }\n ]\n}\n```\n\nRelated topics\n--------------\n\n- [Resolve errors](/workspace/drive/api/guides/handle-errors)\n- [Troubleshoot authentication and authorization issues](/workspace/drive/api/troubleshoot-authentication-authorization)\n- [Improve performance](/workspace/drive/api/guides/performance)"]]
