创建和管理文件

本指南介绍了如何使用 Google Drive API 在 Google 云端硬盘中创建和管理文件。

创建文件

如需在云端硬盘中创建不包含任何元数据或内容的文件，请对 files 资源使用不带任何参数的 create 方法。

创建文件时，该方法会返回 files 资源。该文件的 kind 为 drive.file，id 为 name，mimeType 为 application/octet-stream。uploadType 标记为必需，但默认值为 media，因此您实际上不必提供它。

如需详细了解云端硬盘文件限制，请参阅文件和文件夹限制。

使用 fields 参数

如果您想指定要在响应中返回的字段，可以使用 files 资源的任何方法设置 fields system 参数。如果您省略 fields 参数，服务器会返回特定于方法的默认字段集。例如，list 方法仅返回每个文件的 kind、id、name、mimeType 和 resourceKey 字段。如需返回其他字段，请参阅返回特定字段。

生成 ID 以用于文件

files 资源上的 generateIds 方法可让您预先生成唯一的文件 ID，这些 ID 可在 Google 云端硬盘中创建或复制文件和文件夹时使用。如果您需要从应用中控制文件 ID，而不是让 Google 云端硬盘自动分配文件 ID，则此方法非常有用。

您可以使用 count 查询参数设置生成的 ID 数量。如果未设置 count，则默认返回 10 个。您可请求的 ID 数量上限为 1,000。

您还可以指定可以使用 ID 的 space 以及可以使用 ID 的商品的 type。

生成 ID 后，可以通过 id 字段将其传递给 create 或 copy 方法。这可确保创建或复制的文件使用预先确定的 ID。

如果文件成功创建或复制，后续重试会返回 409 Conflict HTTP 状态代码响应，并且不会创建重复文件。

请注意，预生成的 ID 不支持用于创建 Google Workspace 文件，但 application/vnd.google-apps.drive-sdk 和 application/vnd.google-apps.folder MIME 类型除外。同样，我们不支持引用转换为 Google Workspace 文件格式的上传。

创建仅包含元数据的文件

仅包含元数据的文件不包含任何内容。元数据是描述文件的数据（例如 name、mimeType 和 createdTime）。name 等字段与用户无关，对于每个用户来说都相同，而 viewedByMeTime 等字段包含特定于用户的值。

仅包含元数据的文件的一个示例是 MIME 类型为 application/vnd.google-apps.folder 的文件夹。如需了解详情，请参阅创建和填充文件夹。另一个示例是指向云端硬盘上 MIME 类型为 application/vnd.google-apps.shortcut 的另一个文件的快捷方式。如需了解详情，请参阅创建指向云端硬盘文件的快捷方式。

管理缩略图

缩略图有助于用户识别云端硬盘文件。云端硬盘可以自动为常见文件类型生成缩略图，您也可以提供由应用生成的缩略图。如需了解详情，请参阅上传缩略图。

复制现有文件

如需复制文件并应用任何请求的更新，请对 files 资源使用 copy 方法。如需查找要复制的 fileId，请使用 list 方法。

您可以通过补丁语义应用更新，这意味着您可以对资源进行部分修改。您必须在请求中明确设置要修改的字段。未包含在请求中的任何字段都会保留其现有值。如需了解详情，请参阅处理部分资源。

您可以使用 generateIds 方法预先设置复制文件的文件 ID。如需了解详情，请参阅生成要与文件搭配使用的 ID。

请注意，您需要使用适当的 Drive API 范围来授权调用。如需详细了解云端硬盘范围，请参阅选择 Google Drive API 范围。

限制和注意事项

在准备复制文件时，请注意以下限制和注意事项：

  • 权限：

    • files 资源的 DownloadRestrictionsMetadata 对象决定了谁可以复制文件。如需了解详情，请参阅禁止用户下载、打印或复制您的文件。
    • capabilities.canCopy 字段资源用于确定用户是否可以复制文件。如需了解详情，请参阅了解文件功能。
    • 创建副本的用户拥有该副本文件。来源文件的其他共享设置不会被复制。如果副本是在共享文件夹中创建的，则会沿用该文件夹的权限。
    • 复制文件的所有权可能会发生变化，并且复制文件可能不会沿用原始文件的共享设置。可能需要重置这些设置。

  • 文件管理：

    • 某些文件（例如第三方快捷方式）永远无法复制。
    • 您只能将文件复制到一个父文件夹中。不支持指定多个父级。如果未指定 parents 字段，文件会从源文件继承任何可发现的父级。
    • 虽然文件夹也是一种文件，但您无法复制文件夹。 请改为创建目标文件夹，并将现有文件的 parents 字段设置为目标文件夹。然后，您可以删除原始源文件夹。
    • 除非指定了新文件名，否则 copy 方法会生成与原始文件同名的文件。
    • 过度使用 copy 可能会导致您超出 Drive API 配额限制。如需了解详情，请参阅使用限制。

您可以尝试以下几个后续步骤：