Вернуть определенные поля для файла

Чтобы вернуть именно те поля, которые вам нужны, и повысить производительность, используйте параметр запроса 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"
    }
  ]
}