Чтобы вернуть именно те поля, которые вам нужны, и повысить производительность, используйте параметр запроса fields
в вызове метода.
По умолчанию сервер отправляет обратно набор полей, специфичных для запрашиваемого ресурса. Например, метод files.get
может возвращать только id
, name
и mimeType
для ресурса files
. Метод permissions.get
возвращает другой набор полей по умолчанию для ресурса permissions
.
После того как сервер обрабатывает действительный запрос, включающий параметр запроса 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'
.Используйте
a/b
, чтобы выбрать полеb
, вложенное в полеa
, например'capabilities/canDownload'
. Дополнительные сведения см. в разделе Получение полей вложенного ресурса .Используйте дополнительный селектор, чтобы запросить набор определенных подполей массивов или объектов, помещая выражения в круглые скобки «()». Например,
'permissions(id)'
возвращает только идентификатор разрешения для каждого элемента в массиве разрешений.Чтобы вернуть все поля объекта, используйте звездочку в качестве подстановочного знака при выборе полей. Например,
'permissions/permissionDetails/*'
выбирает все доступные поля сведений о разрешениях для каждого разрешения. Обратите внимание, что использование этого подстановочного знака может привести к снижению производительности запроса.
Показать пример
Запрос
В этом примере мы предоставляем параметр пути к идентификатору файла и несколько полей в качестве параметра запроса в запросе. Ответ возвращает значения полей для идентификатора файла.
GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=name,starred,shared
Ответ
{ "name": "File1", "starred": false, "shared": true } }
Получить поля вложенного ресурса
Если поле ссылается на другой ресурс, вы можете указать, какие поля вложенного ресурса следует извлечь.
Например, чтобы получить поле role
(вложенный ресурс) ресурса permissions
, используйте любой из следующих параметров:
-
permissions.get
сfields=role
илиfields=*
. -
files.get
сfields=permissions(role)
илиfields=permissions/role
. -
files.get
сfields=permissions
чтобы подразумевать все поля вложенного ресурса. -
changes.list
сfields=changes(file(permissions(role)))
.
Чтобы получить несколько полей, используйте список, разделенный запятыми. Например, files.list
с fields=files(id,name,createdTime,modifiedTime,size)
.
Показать пример
Запрос
В этом примере мы предоставляем параметр пути к идентификатору файла и несколько полей, включая определенные поля ресурса вложенных разрешений, в качестве параметра запроса в запросе. Ответ возвращает значения поля для идентификатора файла.
GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=name,starred,shared,permissions(kind,type,role)
Ответ
{ "name": "File1", "starred": false, "shared": true, "permissions": [ { "kind": "drive#permission", "type": "user", "role": "owner" } ] }