Как добавить настраиваемые свойства файла

Специальные свойства файлов – это пары "ключ-значение", которые используются для хранения специальных метаданных файлов Google Диска (например, тегов), идентификаторов из других хранилищ данных, информации, которой обмениваются приложения для рабочих процессов, и т. д. Например, вы можете добавить свойства ко всем документам, созданным отделом продаж в первом квартале.

Чтобы добавить свойства, видимые всем приложениям, используйте поле properties ресурса files. Чтобы добавить свойства, доступные только вашему приложению, используйте поле appProperties ресурса files.

Свойства также можно использовать в поисковых выражениях.

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

Drive API v3

"appProperties": {
  "additionalID": "ID",
}

Drive API v2

{
  'key':        'additionalID',
  'value':      'ID',
  'visibility': 'PRIVATE'
}

Работа со специальными свойствами файлов

В этом разделе объясняется, как выполнять некоторые задачи, связанные со свойствами пользовательских файлов, которые влияют на все приложения.

Как добавить или изменить специальные свойства файла

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

PATCH https://www.googleapis.com/drive/v3/files/FILE_ID
 
{
  "properties": {
    "name": "wrench",
    "mass": "1.3kg",
    "count": "3"
  }
}

Вы также можете добавить к файлу дополнительное свойство, используя расширенный сервис Диска в Google Apps Script. Подробнее о добавлении дополнительных параметров…

Получайте или перечисляйте специальные свойства файлов.

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

GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=properties

Ответ состоит из объекта properties, который содержит набор пар "ключ-значение".

{
  "properties": {
    "name": "wrench",
    "mass": "1.3kg",
    "count": "3"
  }
}

Удаление пользовательских свойств файлов

Чтобы удалить значения свойств, видимые для всех приложений, используйте метод files.update, чтобы задать для поля properties ресурса files значение null.

PATCH https://www.googleapis.com/drive/v3/files/FILE_ID
 
{
  "name": null
}

Чтобы посмотреть изменения, вызовите метод files.get и получите объект properties для файла.

{
  "properties": {
    "mass": "1.3kg",
    "count": "3"
  }
}

Ограничения для специальных свойств файлов

Для дополнительных параметров действуют следующие ограничения:

  • Максимальное количество дополнительных параметров в файле – 100 (из всех источников).
  • Максимум 30 общедоступных свойств на файл (из всех источников).
  • Максимум 30 частных свойств на файл из любого приложения.
  • Максимальный размер строки свойства – 124 байта (включая ключ и значение) в кодировке UTF-8. Например, если ключ свойства состоит из 10 символов, то значение может содержать не более 114 символов. Аналогично, если для значения свойства требуется 100 символов, то для ключа можно использовать до 24 символов.

Дополнительную информацию вы найдете в ресурсе files. Для Drive API версии 2 ознакомьтесь с ресурсом properties.

Доступ к закрытым настраиваемым свойствам файлов

Получить доступ к закрытым свойствам можно только с помощью поля appProperties через аутентифицированный запрос, в котором используется токен доступа, полученный с помощью идентификатора клиента OAuth 2.0. Вы не можете использовать ключ API для получения частных свойств.