Управление метаданными файла

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

Обзор метаданных

В API Google Drive ресурс files представляет собой метаданные. В отличие от API, где метаданные являются подобъектом, API Drive рассматривает весь ресурс files как метаданные. Вы можете получить доступ к метаданным напрямую через методы get или list ресурса files .

По умолчанию методы get и list возвращают только частичный набор полей. Для получения конкретных данных необходимо указать системный параметр ` fields в запросе. Если он опущен, сервер возвращает подмножество полей, специфичных для данного метода. Например, метод list возвращает только поля kind , id , name , mimeType и resourceKey для каждого файла. Чтобы возвращать другие поля, см. раздел «Возвращение конкретных полей» .

Кроме того, видимость метаданных зависит от роли пользователя в файле. Ресурс permissions не определяет разрешенные действия пользователя с файлом или папкой. Вместо этого ресурс files содержит набор логических полей capabilities . API Google Drive получает эти capabilities из ресурса permissions , связанного с файлом или папкой. Для получения дополнительной информации см. раздел «Понимание возможностей файлов» .

API Google Drive предлагает два ограниченных диапазона метаданных: drive.metadata и drive.metadata.readonly . Диапазон drive.metadata позволяет просматривать и управлять метаданными файлов, а drive.metadata.readonly — только для чтения. Оба диапазона строго запрещают доступ к содержимому файлов. Для получения дополнительной информации см. раздел «Выбор диапазонов API Google Drive» .

Наконец, всегда проверяйте свою логику в отношении разрешений и областей действия. Например, пользователь может владеть файлом с полными правами доступа, но API Google Диска заблокирует попытки изменить или загрузить этот файл, если ваше приложение имеет только область действия drive.metadata.readonly .

Укажите имена файлов и расширения.

При использовании API Google Drive приложениям следует указывать расширение файла в свойстве ` name . Например, для операции вставки файла JPEG в метаданных следует указать что-то вроде "name": "cat.jpg" .

Последующие ответы GET могут включать свойство fileExtension доступное только для чтения, заполненное расширением, первоначально указанным в свойстве name . Когда пользователь Google Drive запрашивает загрузку файла или когда файл загружается через клиент синхронизации, Drive формирует полное имя файла (с расширением) на основе имени. В случаях, когда расширение отсутствует, Drive пытается определить расширение на основе MIME-типа файла.

Сохранить индексируемый текст

Google Drive автоматически индексирует документы для поиска, когда распознает тип файла, включая текстовые документы, PDF-файлы, изображения с текстом и другие распространенные типы. Если ваше приложение сохраняет другие типы файлов (например, рисунки, видео и ярлыки), вы можете улучшить возможность поиска, указав индексируемый текст в поле contentHints.indexableText файла.

Индексируемый текст индексируется как HTML. Если вы сохраните индексируемую текстовую строку <section attribute="value1">Here's some text</section> , то "Here's some text" будет проиндексировано, а "value1" — нет. Из-за этого сохранение XML в виде индексируемого текста не так полезно, как сохранение HTML.

При указании параметра indexableText также следует учитывать следующее:

  • Ограничение по размеру для contentHints.indexableText составляет 128 КБ.
  • Определите ключевые термины и понятия, которые, как вы ожидаете, будут использоваться пользователем для поиска.
  • Не пытайтесь сортировать текст по степени важности, поскольку индексатор делает это за вас автоматически.
  • Ваше приложение должно обновлять индексируемый текст при каждом сохранении.
  • Убедитесь, что текст связан с содержимым файла или его метаданными.

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

Загрузить миниатюры

Google Диск автоматически создает эскизы для многих распространенных типов файлов, таких как документы Google Docs, таблицы Google Sheets и презентации Google Slides. Эскизы помогают пользователю лучше идентифицировать файлы в Google Диске.

Для типов файлов, для которых Google Drive не может создать стандартную миниатюру, вы можете предоставить изображение миниатюры, сгенерированное вашим приложением. При создании или обновлении файла загрузите миниатюру, установив поле contentHints.thumbnail в ресурсе files .

Конкретно:

  • Установите поле contentHints.thumbnail.image равным URL-адресу и безопасному имени файла изображения в кодировке base64 (см. раздел 5 RFC 4648 ).
  • Установите для поля contentHints.thumbnail.mimeType соответствующий MIME-тип для миниатюры.

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

Миниатюры должны соответствовать следующим правилам:

  • Можно загружать в форматах PNG, GIF или JPG.
  • Рекомендуемая ширина — 1600 пикселей.
  • Минимальная ширина составляет 220 пикселей.
  • Максимальный размер файла составляет 2 МБ.
  • Ваше приложение должно обновлять эти данные при каждом сохранении.

Для получения более подробной информации см. раздел files .

Получить миниатюры

Вы можете получить метаданные, включая эскизы, для файлов Google Drive. Информация об эскизах хранится в поле thumbnailLink ресурса files .

Возвращает конкретное миниатюрное изображение

Приведённый ниже пример кода демонстрирует запрос метода get с несколькими полями в качестве параметра запроса для возврата метаданных thumbnailLink для конкретного файла. Для получения дополнительной информации см. раздел «Возврат определённых полей для файла» .

GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=id,name,mimeType,thumbnailLink

Замените FILE_ID на fileId файла, который вы хотите найти.

Если доступно, запрос возвращает кратковременную ссылку на миниатюру файла. Как правило, ссылка действует несколько часов. Это поле заполняется только тогда, когда запрашивающее приложение может получить доступ к содержимому файла. Если файл не является общедоступным, URL-адрес, возвращаемый в thumbnailLink необходимо получить с помощью запроса с учетными данными .

Возвращает список миниатюр

Приведённый ниже пример кода демонстрирует запрос к методу list с несколькими полями в качестве параметра запроса для возврата метаданных thumbnailLink для списка файлов. Для получения дополнительной информации см. раздел «Поиск файлов и папок» .

GET https://www.googleapis.com/drive/v3/files/?fields=files(id,name,mimeType,thumbnailLink)

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

GET https://www.googleapis.com/drive/v3/files/q=mimeType='application/vnd.google-apps.spreadsheet'&fields=files(id,name,mimeType,thumbnailLink)