By default, the server sends back a default set of resource fields specific to
the resource being queried. For example, the files.get
method might only
return the id
, name
, and mimeType
for the files
resource. The
permissions.get()
method returns a different set of default fields for a
permissions
resource.
To return the exact fields you need, and improve performance, use the fields
query parameter in your method call. To determine the fields you can return
using the fields
parameter, visit the documentation page of the resource
you are querying. For example, to see what fields you can return for a file,
refer to the files
resource documentation.
Fetching 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
orfields=*
.files.get
withfields=permissions(role)
orfields=permissions/role
.files.get
withfields=permissions
to imply all fields of the nested resource.changes.list
withfields=changes(file(permissions(role)))
.
Formatting rules for the fields
parameter
The format of the fields request parameter value is loosely based on XPath
syntax. Following are formatting rules for the fields
parameter. All of these
rules use examples related to the files.get
function call.
Use a comma-separated list to select multiple fields, such as
'title, mimeType'
.Use
a/b
to select a fieldb
that is nested within fielda
, such as'labels/starred'
.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.Use an asterisk as a wild card in field selections to return all fields in an object. For example,
'permissions/permissionDetails/*'
selects all available permission details fields per permission. Note that the use of this wildcard can lead to negative performance impact on the request.
After 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 you what was wrong with your fields selection. For example,
files.list(fields='files(id,capabilities/canAddChildre)');
yields an error of "Invalid field selection canAddChildre".