Возвращать определенные поля

В этом документе объясняется, как использовать параметр fields в Google Drive.

Чтобы получить именно те поля, которые вам нужны, и повысить производительность, используйте системный параметр fields в вызове метода.

Для получения информации о других системных параметрах, применимых к Drive API, см. раздел «Альтернативные системные параметры» .

Как работает параметр fields

Параметр fields использует FieldMask для фильтрации ответа. Маски полей используются для указания подмножества полей, которые должен вернуть запрос. Использование маски поля — это хорошая практика проектирования, позволяющая избежать запроса лишних данных, что, в свою очередь, помогает избежать лишнего времени обработки.

Если параметр fields не указан, сервер возвращает набор полей по умолчанию, специфичных для данного метода. Например, метод list ресурса files возвращает только поля kind , id , name и mimeType . Метод get ресурса permissions возвращает другой набор полей по умолчанию.

Для всех методов ресурсов about , comments (кроме delete ) и replies (кроме delete ) необходимо задать параметр fields . Эти методы не возвращают набор полей по умолчанию.

После обработки сервером корректного запроса, включающего параметр fields , он возвращает код состояния HTTP 200 OK вместе с запрошенными данными. Если параметр fields содержит ошибку или является недопустимым, сервер возвращает код состояния HTTP 400 Bad Request вместе с сообщением об ошибке, указывающим на некорректность выбора полей. Например, files.list(fields='files(id,capabilities,canAddChildren)') приводит к ошибке "Недопустимый выбор поля canAddChildren". Правильный параметр fields для этого примера — files.list(fields='files(id,capabilities/canAddChildren)') .

Чтобы определить, какие поля можно вернуть с помощью параметра fields , посетите страницу документации ресурса, к которому вы обращаетесь. Например, чтобы узнать, какие поля можно вернуть для файла, обратитесь к документации ресурса files . Для получения более подробной информации о поисковых запросах, специфичных для файлов, см. раздел «Поисковые запросы и операторы» .

Правила форматирования параметров полей

Формат значения параметра запроса fields в общих чертах основан на синтаксисе XPath. Ниже приведены правила форматирования параметра fields . Все эти правила используют примеры, относящиеся к методу files.get .

• Для выбора нескольких полей, например, 'name, mimeType' , используйте список, разделенный запятыми.

• Используйте a/b для выбора поля b , вложенного в поле a , например 'capabilities/canDownload' . Дополнительную информацию см. в разделе «Получение полей вложенного ресурса» .

• Используйте подселектор для запроса набора определенных подполей массивов или объектов, заключая выражения в скобки "()". Например, 'permissions(id)' возвращает только идентификатор разрешения для каждого элемента в массиве permissions.

• Чтобы получить все поля объекта, используйте звездочку ( * ) в качестве подстановочного знака при выборе полей. Например, 'permissions/permissionDetails/*' выбирает все доступные поля сведений о разрешении для каждого разрешения. Обратите внимание, что использование подстановочного знака может негативно сказаться на производительности запроса.

• Невозможно выбрать отдельные элементы карты, если их ключи содержат специальные символы (например, косые черты / или точки . ). Например, попытка выбрать определенный ключ формата экспорта в exportLinks с помощью fields=exportLinks/application/pdf приводит к ошибке HTTP 400 Bad Request , поскольку анализатор пути интерпретирует / как разделитель вложенных свойств. Чтобы получить пары ключ-значение со специальными символами в ключах, запросите всю карту целиком (например, fields=exportLinks ) и отфильтруйте результаты на стороне клиента.

GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=name,starred,shared

{
  "name": "File1",
  "starred": false,
  "shared": true
  }
}

Получение полей вложенного ресурса

Когда поле ссылается на другой ресурс, вы можете указать, какие поля вложенного ресурса следует получить.

Например, чтобы получить поле role (вложенный ресурс) ресурса permissions , используйте любой из следующих вариантов:

• permissions.get with fields=role .
• permissions.get с fields=* для отображения всех полей permissions .
• files.get с fields=permissions(role) или fields=permissions/role .
• files.get с fields=permissions , чтобы отобразить все поля permissions .
• changes.list with fields=changes(file(permissions(role))) .

Для получения нескольких полей используйте список, разделенный запятыми. Например, files.list with fields=files(id,name,createdTime,modifiedTime,size) .

Для указания вложенных полей внутри вложенных массивов или объектов используйте вложенные скобки. Например, чтобы вывести список файлов с их идентификатором, именем и данными вложенного владельца (отображаемое имя и адрес электронной почты), а также получить токен следующей страницы для пагинации: files.list with fields=nextPageToken,files(id,name,owners(displayName,emailAddress)) .

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"
    }
  ]
}

Альтернативные параметры системы

Параметры запроса, применяемые ко всем операциям API Google Drive, описаны в разделе «Системные параметры» .

Связанные темы

• Устранение ошибок
• Устранение неполадок аутентификации и авторизации
• Повышение производительности