本文档介绍了在命名文件和处理可编入索引的文本及缩略图等元数据时需要考虑的重要事项。如需插入和检索文件，请参阅 files 资源。
元数据概览
在 Google Drive API 中，files 资源表示元数据。与元数据是子对象的 API 不同，云端硬盘 API 将整个 files 资源视为元数据。您可以通过 files 资源上的 get 或 list 方法直接访问元数据。
默认情况下，get 和 list 方法仅返回部分字段。如需检索特定数据，您必须在请求中定义 fields 系统参数。如果省略，服务器会返回特定于该方法的默认字段子集。例如，list 方法仅返回每个文件的 kind、id、name、mimeType 和 resourceKey 字段。如需返回其他字段，请参阅返回特定字段。
此外，元数据的可见性还取决于用户在文件中的角色。permissions 资源不决定用户对文件或文件夹的允许操作。相反，files 资源包含一个布尔值 capabilities 字段集合。Google 云端硬盘 API 会从与文件或文件夹关联的 permissions 资源中派生出这些 capabilities。如需了解详情，请参阅了解文件功能。
Drive API 提供两个受限的元数据范围：drive.metadata 和 drive.metadata.readonly。drive.metadata 范围允许您查看和管理文件元数据，而 drive.metadata.readonly 范围是只读的。两者都严格禁止访问文件内容。如需了解详情，请参阅选择 Google Drive API 范围。
最后，请务必验证与权限和范围相关的逻辑。例如，用户可能拥有某个文件的完整权限，但如果您的应用仅具有 drive.metadata.readonly 范围，Drive API 将阻止尝试修改或下载该文件的操作。
指定文件名和扩展名
使用 Google Drive API 插入文件时，应用应在 name 属性中指定文件扩展名。例如，插入 JPEG 文件的操作应在元数据中指定类似 "name": "cat.jpg" 的内容。
后续的 GET 响应可以包含只读 fileExtension 属性，该属性填充了 name 属性中最初指定的扩展服务。当 Google 云端硬盘用户请求下载文件时，或者当文件通过同步客户端下载时，云端硬盘会根据名称构建完整的文件名（带扩展名）。如果缺少扩展名，Google 云端硬盘会尝试根据文件的 MIME 类型确定扩展名。
保存可编入索引的文本
当云端硬盘识别出文件类型（包括文本文档、PDF、包含文字的图片和其他常见类型）时，会自动为文档编制索引以供搜索。如果您的应用保存其他类型的文件（例如绘图、视频和快捷方式），您可以在文件的 contentHints.indexableText 字段中提供可编入索引的文本，从而提高文件的可发现性。
可编入索引的文本以 HTML 形式编入索引。如果您保存可编入索引的文本字符串 <section attribute="value1">Here's some text</section>，则“Here's some text”会编入索引，但“value1”不会。因此，将 XML 保存为可编入索引的文本不如保存 HTML 有用。
指定 indexableText 时，另请注意以下几点：
contentHints.indexableText的大小上限为 128 KB。- 捕获您预期用户会搜索的关键术语和概念。
- 请勿尝试按重要性对文本进行排序，因为索引器会高效地为您执行此操作。
- 您的应用应在每次保存时更新可编入索引的文本。
- 确保文本与文件的内容或元数据相关。
最后一点可能看起来很明显，但非常重要。添加热门搜索字词来强制文件显示在搜索结果中并不是一个好主意。这可能会让用户感到沮丧，甚至可能会促使他们删除相应文件。
上传缩略图
云端硬盘会自动为许多常见文件类型（例如 Google 文档、表格和幻灯片）生成缩略图。 缩略图有助于用户更好地识别云端硬盘文件。
对于 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 字段中。
返回特定缩略图
以下代码示例展示了 get 方法请求，其中包含多个字段作为查询参数，用于返回特定文件的 thumbnailLink 元数据。如需了解详情，请参阅返回文件的特定字段。
GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=id,name,mimeType,thumbnailLink
将 FILE_ID 替换为您要查找的文件的 fileId。
如果可用，该请求会返回指向文件缩略图的短期有效网址。该链接通常会持续几个小时。仅当请求应用可以访问文件的内容时，才会填充此字段。如果文件未公开共享，则必须使用凭据请求来获取 thumbnailLink 中返回的网址。
返回缩略图列表
以下代码示例展示了 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)