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

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

Чтобы вернуть именно те поля, которые вам нужны, и повысить производительность, используйте системный параметр 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 . Подробнее о терминах запроса, специфичных для файлов, см. в разделе «Термины и операторы поискового запроса» .

Важно: Используйте параметры запроса, поддерживающие пагинацию данных (например, maxResults и nextPageToken ), чтобы уменьшить размер результатов каждого запроса до приемлемого размера. В противном случае выигрыш в производительности, возможный при частичном ответе, может быть не реализован.

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

Формат значения параметра запроса fields в некоторой степени основан на синтаксисе 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 .
• permissions.get с fields=* для отображения всех полей permissions .
• files.get с fields=permissions(role) или fields=permissions/role .
• files.get с fields=permissions для отображения всех полей 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"
    }
  ]
}

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

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

Примечание: Квоты для каждого пользователя всегда применяются API Диска, а личность пользователя определяется по токену доступа, переданному в запросе. Параметры quotaUser и userIp можно использовать только для анонимных запросов к общедоступным файлам.

Похожие темы

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