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

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

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

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

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

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

Примечание. Начиная с 31 октября 2022 г. индексируемый текст можно будет показывать во фрагментах результатов, и это повлияет на результаты поиска в большем количестве мест, включая Cloud Search и наложение поиска на Диске и Gmail.

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

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

При указании indexableText также имейте в виду:

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

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

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

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

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

Конкретно:

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

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

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

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

Важно: Миниатюры становятся недействительными каждый раз при изменении содержимого файла. При предоставлении миниатюр важно загружать новые миниатюры каждый раз при изменении содержимого. Изменения метаданных не делают миниатюры недействительными.

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

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

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

Вернуть конкретную миниатюру

В следующем примере кода показан запрос метода files.get с несколькими полями в качестве параметра запроса для возврата метаданных thumbnailLink для определенного файла. Дополнительные сведения см. в разделе Возврат определенных полей для файла .

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

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

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

Вернуть список миниатюр

В следующем примере кода показан запрос метода files.list с несколькими полями в качестве параметра запроса, возвращающий метаданные thumbnailLink для списка файлов. Дополнительную информацию см. в разделе Поиск файлов и папок .

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

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

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