管理文件元数据

本文档介绍了为文件命名以及使用可编入索引的文本和缩略图等元数据时的重要注意事项。如需插入和检索文件,请参阅 files 资源。

指定文件名和扩展名

使用 Google Drive API 插入文件时,应用应在标题属性中指定文件扩展名。例如,插入 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 KB。
  • 捕获您希望用户搜索的关键词语和概念。
  • 请勿尝试按重要性对文本进行排序,因为索引器可以高效地完成排序。
  • 您的应用应在每次保存时更新可编入索引的文本。
  • 请确保文本与文件的内容或元数据相关。

最后一点可能看起来很明显,但很重要。但最好通过添加常用搜索字词来强制文件出现在搜索结果中。这可能会让用户感到沮丧,甚至可能会促使他们删除文件。

上传缩略图

云端硬盘会自动为许多常见文件类型(例如 Google 文档、表格和幻灯片)生成缩略图。缩略图可帮助用户更好地识别云端硬盘文件。

对于云端硬盘无法生成标准缩略图的文件类型,您可以提供应用生成的缩略图。在创建或更新文件期间,通过在 files 资源上设置 contentHints.thumbnail 字段来上传缩略图。

具体而言:

  • contentHints.thumbnail.image 字段设置为网址和文件名安全 base64 编码的图片(请参阅 RFC 4648 第 5 节)。
  • contentHints.thumbnail.mimeType 字段设置为缩略图的相应 MIME 类型。

如果云端硬盘可以根据文件生成缩略图,它会使用自动生成的缩略图,并忽略您可能已上传的任何缩略图。如果它无法生成缩略图,则会使用您提供的缩略图。

缩略图应遵循以下规则:

  • 可以采用 PNG、GIF 或 JPG 格式上传。
  • 建议的宽度为 1600 像素。
  • 最小宽度为 220 像素。
  • 文件大小上限为 2 MB。
  • 每次保存时,您的应用都应对其进行更新。

如需了解详情,请参阅 files 资源。

检索缩略图

您可以检索云端硬盘文件的元数据(包括缩略图)。 缩略图信息存放在 files 资源的 thumbnailLink 字段中。

返回特定缩略图

以下代码示例展示了一个 files.get 方法请求,该请求将多个字段作为查询参数,返回特定文件的 thumbnailLink 元数据。如需了解详情,请参阅返回文件的特定字段

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

FILE_ID 替换为您要查找的文件的 fileId

该请求会向文件缩略图返回一个短时效网址(如果有)。通常情况下,该链接会持续几小时。只有当发出请求的应用可以访问文件的内容时,系统才会填充该字段。如果文件未公开共享,必须使用具有凭据的请求提取 thumbnailLink 中返回的网址。

返回缩略图列表

以下代码示例展示了一个 files.list 方法请求,该请求将多个字段作为查询参数,用于返回文件列表的 thumbnailLink 元数据。如需了解详情,请参阅搜索文件和文件夹

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

如需将搜索结果限制为特定文件类型,请应用查询字符串来设置 MIME 类型。例如,以下代码示例展示了如何将列表限制为 Google 表格文件。如需详细了解 MIME 类型,请参阅 Google Workspace 和 Google 云端硬盘支持的 MIME 类型

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