创建和管理文件

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

创建文件

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

创建文件时，该方法会返回 files 资源。系统会为该文件指定 kind 的 drive.file、id、name“未命名”以及 mimeType 的 application/octet-stream。The uploadType 会标记为必需，但默认值为 media，因此您实际上不必 提供它。

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

使用 fields 参数

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

文件所有权

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

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

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

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

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

生成要与文件搭配使用的 ID

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

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

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

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

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

请注意，除了 application/vnd.google-apps.drive-sdk 和 application/vnd.google-apps.folder MIME 类型之外，创建 Google Workspace 文件不支持预先生成的 ID。同样，引用转换为 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 范围。

限制和注意事项

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

  • 权限：

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

  • 文件管理：

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

以下是一些您可以尝试的后续步骤：