Добавить пользовательские свойства файла

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

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

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

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

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

{
  '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 Drive в 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 частных объектов недвижимости.
• В кодировке UTF-8 максимальный размер строки свойства (включая ключ и значение) составляет 124 байта. Например, свойство с ключом длиной 10 символов может содержать в значении не более 114 символов. Аналогично, свойство, для значения которого требуется 100 символов, может использовать до 24 символов для ключа.

Для получения дополнительной информации см. раздел « files . Для Drive API v2 см. раздел « properties .

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

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