To return the exact fields you need, and to improve performance, use the
fields
system
parameter in your method
call.
The fields
parameter uses a
FieldMask
for response filtering. Field masks are used to specify a subset of fields that
a request should return. Using a field mask is good design practice to make sure
that you don't request unnecessary data, which in turn helps avoid unnecessary
processing time.
By default, the server returns a set of fields specific to the resource being
queried. For example, the get()
method on
the files
resource might only return the
id
, name
, and mimeType
. The
get()
method on the
permissions
resource returns a
different set of default fields.
After a server processes a valid request that includes the fields
parameter,
it returns an HTTP 200 OK
status code, along with the requested data. If the
fields parameter has an error or is otherwise invalid, the server returns an
HTTP 400 Bad Request
status code, along with an error message stating what's
wrong with your fields selection. For example,
files.list(fields='files(id,capabilities,canAddChildren)')
yields an error of
"Invalid field selection canAddChildren." The correct fields parameter for this
example is files.list(fields='files(id,capabilities/canAddChildren)')
.
To determine the fields you can return using the fields
parameter, visit the
documentation page of the resource you're querying. For example, to see what
fields you can return for a file, refer to the files
resource documentation.
Field parameter format rules
The format of the fields request parameter value is loosely based on XPath
syntax. The following are formatting rules for the fields
parameter. All these
rules use examples related to the files.get()
method.
Use a comma-separated list to select multiple fields, such as
'name, mimeType'
.Use
a/b
to select fieldb
that's nested within fielda
, such as'capabilities/canDownload'
. For more information, see Fetch the fields of a nested resource.Use a sub-selector to request a set of specific sub-fields of arrays or objects by placing expressions in parentheses "()". For example,
'permissions(id)'
returns only the permission ID for each element in the permissions array.To return all fields in an object, use an asterisk (
*
) as a wildcard in field selections. For example,'permissions/permissionDetails/*'
selects all available permission details fields per permission. Note that using the wildcard can lead to negative performance impacts on the request.
Show an example
Request
In 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.
GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=name,starred,shared
Response
{ "name": "File1", "starred": false, "shared": true } }
Fetch the fields of a nested resource
When a field refers to another resource, you can specify which fields of the nested resource should be fetched.
For example, to retrieve the role
field (nested resource) of the permissions
resource, use any of the following options:
permissions.get()
withfields=role
.permissions.get()
withfields=*
to show allpermissions
fields.files.get()
withfields=permissions(role)
orfields=permissions/role
.files.get()
withfields=permissions
to show allpermissions
fields.changes.list()
withfields=changes(file(permissions(role)))
.
To retrieve multiple fields, use a comma-separated list. For example,
files.list()
with fields=files(id,name,createdTime,modifiedTime,size)
.
Show an example
Request
In 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.
GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=name,starred,shared,permissions(kind,type,role)
Response
{ "name": "File1", "starred": false, "shared": true, "permissions": [ { "kind": "drive#permission", "type": "user", "role": "owner" } ] }