创建和管理文件

本指南介绍了如何使用 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 字段。如需返回其他字段，请参阅返回特定字段。

文件所有权

使用 Drive API 创建文件时，所有权取决于应用使用的身份验证凭据，具体如下：

  • 用户账号 (OAuth 2.0)：如果应用代表用户进行身份验证，则该用户将成为文件所有者。然后，该文件会位于其“我的云端硬盘”文件夹或指定文件夹中。它会消耗其存储空间配额。

  • 服务账号：如果应用使用服务账号进行身份验证，则服务账号是文件所有者。然后，该文件会存储在服务账号的专用云端硬盘存储空间中。除非明确共享，否则文件不会显示在其他云端硬盘存储空间账号中。 如果服务账号被删除，其拥有的所有文件都会立即被删除。

    如果您使用的是服务账号，但希望特定用户账号拥有某个文件，请使用全网域授权。这样一来，服务账号就可以模拟用户并代表用户创建文件。如需了解详情，请参阅向服务账号进行全网域授权。

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

生成 ID 以用于文件

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

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

您还可以指定可以使用 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 可能会导致超出云端硬盘 API 配额限制。如需了解详情，请参阅使用限制。

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