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

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

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

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

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

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

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

Индексируемый текст индексируется как HTML. Если сохранить индексируемую текстовую строку <section attribute="value1">Here's some text</section> , то строка «Вот текст» будет проиндексирована, а «value1» — нет. Поэтому сохранение 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 Таблиц. Подробнее о типах 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)
,

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

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

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

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

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

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

Индексируемый текст индексируется как HTML. Если сохранить индексируемую текстовую строку <section attribute="value1">Here's some text</section> , то строка «Вот текст» будет проиндексирована, а «value1» — нет. Поэтому сохранение 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 Таблиц. Подробнее о типах 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)