Google Drive

目前存在一个持续性问题，且默认的 Google DVC 应用受到影响。如果你看到“此应用已被屏蔽”的提示，请查看此工单获取临时解决方案和更多详情。

要开始使用 Google Drive 远程存储，你只需使用有效的 URL 格式将其添加即可。然后使用任何需要连接到它的 DVC 命令（例如，在已有跟踪数据后执行 dvc pull 或 dvc push）。例如：

$ dvc add data
...
$ dvc remote add --default myremote \
                           gdrive://0AIac4JZqHhKmUk9PDA/dvcstore
$ dvc remote modify myremote gdrive_acknowledge_abuse true
$ dvc push
Your browser has been opened to visit:

    https://accounts.google.com/o/oauth2/auth...

Authentication successful.

详见授权说明。

有关配置参数的完整列表，请参见配置参数。

DVC 默认验证 Google Drive 文件

默认情况下，GDrive 远程存储不被视为“受信任”。这意味着此类存储会启用 verify 参数，因此 DVC 在下载文件时（例如执行 dvc pull）会重新计算文件哈希值，以确保文件未被修改。

DVC 使用 Google Drive API 将你的 DVC 项目数据与此类远程存储进行同步，因此会受到某些使用限制和配额的约束，默认情况下这些限制与其它 GDrive 远程存储用户共享。对于高频使用场景，强烈建议使用自定义 Google Cloud 项目进行连接，以便你自己掌控这些限制。

拥有自己的 GC 项目后，还可以使用服务账号来自动化需要建立 GDrive 远程连接的任务（例如 CI/CD）。

请注意我们的 Google API 隐私政策。

URL 格式

有几种不同的方式可以构建适用于不同用途的 GDrive 远程 URL，例如根目录下的文件夹或子文件夹、非你账户拥有的共享文件夹等。URL 由一个基础部分和一个可选的路径组成，指向一个已存在的文件夹，即 gdrive://<base>/path/to/folder。其中 base 可以是以下之一：

文件夹 ID（推荐）—— 每个 Google Drive 文件夹的唯一标识符，包括共享文件夹和共享盘*（这两者只能通过 ID 引用）。

⚠️ 目标文件夹应明确共享给特定用户（或用户组），他们才能在 DVC 中使用它。“任何人可通过链接访问”无法保证正常工作。
```
$ dvc remote add myremote gdrive://0AIac4JZqHhKmUk9PDA
```
或
```
$ dvc remote add myremote \
                      gdrive://0AIac4JZqHhKmUk9PDA/Data/text
```
上面的 0AIac4JZqHhKmUk9PDA 即为文件夹 ID，可在浏览器地址栏中找到，例如 https://drive.google.com/drive/folders/0AIac4JZqHhKmUk9PDA。

* 注意共享盘的存储和上传限制。
root —— 表示你的顶级 Google Drive 文件夹（“我的云端硬盘”）。

⚠️ 仅适用于个人使用，因为如果共享以此方式配置的远程存储，会导致每个用户使用 DVC 时尝试在各自的 Google Drive 之间同步数据。
```
$ dvc remote add myremote gdrive://root/dvcstore
```
我们不建议单独使用 gdrive://root，因为它通常还用于其他多种用途，使用 DVC 向此处推送数据可能会导致混乱。
appDataFolder —— 特殊的隐藏文件夹（每位用户唯一），专用于存储应用程序特定的数据。这是防止通过 Google Drive 网页界面意外删除远程存储数据的好选择。

⚠️ 仅适用于个人使用。
```
$ dvc remote add myremote gdrive://appDataFolder
```

使用自定义 Google Cloud 项目（推荐）

可选：按照以下步骤创建您自己的 Google Cloud 项目，并为您的 GDrive 远程存储生成 OAuth 凭据，以连接到 Google Drive。我们强烈建议在重度使用或高级需求场景下采用此方式，原因如下：

您可以自主控制 Google API 的使用限制，并在需要时向 Google 申请提高配额。
可在需要时确保最佳的数据传输性能。
使用服务账号执行自动化任务（例如 CI/CD）只能通过此方式实现。

DVC 使用 Google Drive API 来连接您的 Google Drive。这需要一个启用了 Drive API 访问权限的 Google Cloud 项目，以及其对应的 OAuth 凭据（客户端 ID 和 客户端密钥）。

登录 Google API Console。

请确认您使用的是预期的 Google 账号（右上角）。
选择或创建一个用于 DVC 远程连接的项目。
从左侧边栏进入 APIs & Services 的 Dashboard 页面，点击 + 启用 API 和服务。在 API 库中查找并选择“Google Drive API”，然后点击启用按钮。
返回左侧边栏的 APIs & Services，选择 OAuth 同意屏幕。选择一个 用户类型 并点击创建。在下一个页面中，输入一个 应用名称，例如“DVC remote storage”，然后向下滚动到底部并点击保存。
在左侧边栏中选择凭据，点击 创建凭据 下拉菜单，选择 OAuth 客户端 ID。选择 桌面应用 类型，使用默认客户端名称点击创建。
此时应会显示新生成的 客户端 ID 和 客户端密钥，您也可以随时回到凭据页面重新获取它们。

✅ 在团队内部共享 客户端 ID 和 客户端密钥 通常是安全的。这些凭据仅用于生成后续需要访问的授权 URL，以便连接到 Google Drive。

最后，使用 dvc remote modify 命令设置凭据（针对每个 GDrive 远程存储），例如：

$ dvc remote modify myremote gdrive_client_id 'client-id'
$ dvc remote modify myremote gdrive_client_secret 'client-secret'

请注意，Google Drive API 的使用限制/配额是按项目客户端计算的，可在 OAuth 同意屏幕中查看。在共享凭据时请注意这一点，否则可能会超出限制。

授权

本节介绍简单的身份验证方式，即让 DVC 代表用户账户访问 GDrive。这种方式非常适合本地运行 DVC 等场景。如果需要自动化操作（例如 CI/CD），我们建议改用使用服务账号。

首次使用 GDrive 远程存储时，例如首次尝试 dvc push 跟踪的数据，DVC 会提示您访问一个特殊的 Google 认证网页。您需要在此处登录具有访问目标 GDrive URL 权限的 Google 账户。认证流程将要求您授予 DVC 所需的权限，并生成一个验证码，供 DVC 完成连接使用。成功后，必要的凭据将被全局缓存，例如在 macOS 上的 ~/Library/Caches/pydrive2fs/{gdrive_client_id}/default.json（参见 gdrive_user_credentials_file），下次 DVC 需要时将自动使用。

为防止他人未经授权访问您的 Google Drive，请勿与他人共享这些凭据。每个团队成员都应单独完成此流程。

如果多个 GDrive 远程存储使用相同的客户端 ID，默认情况下它们将共享同一组缓存的凭据。如需隔离它们，可为不同的远程存储使用自定义的配置文件名称：

$ dvc remote modify --local myremote profile myprofile

您还可以为每个远程存储覆盖缓存凭据文件的位置，例如将其放在主目录中：

$ dvc remote modify myremote --local \
      gdrive_user_credentials_file ~/.gdrive/myremote-credentials.json

如果该文件位于 Git 仓库中，请将其视为机密信息，切勿提交。建议将其添加到 .gitignore 文件中以确保安全。

若要更改已认证的用户或解决令牌相关的错误，可以删除用户凭据文件并重新进行授权。

另外，可以通过设置 GDRIVE_CREDENTIALS_DATA 在 CI/CD 系统、生产环境、只读文件系统等场景中传递用户凭据。该变量的内容应为 JSON 格式的字符串，格式与上述凭据文件相同，通常通过相同的认证流程获取。如果设置了 GDRIVE_CREDENTIALS_DATA，则忽略 gdrive_user_credentials_file 的值（即使已提供）。

如果运行 dvc push 或 dvc pull 命令时出现错误提示 “此文件已被识别为恶意软件或垃圾内容，无法下载”，请检查是否已设置 gdrive_acknowledge_abuse 选项：

$ dvc remote modify myremote gdrive_acknowledge_abuse true

请注意我们的 Google API 隐私政策。

使用服务账户

服务账户是与您的 GCP 项目关联的 Google 账户，而非特定用户。它适用于代码需要独立访问数据的场景，例如在 Compute Engine 中运行、自动化 CI/CD 等，无需交互式用户 OAuth 认证。

Google 服务账户有其自身的使用限制，若频繁结合 dvc push、dvc pull 等命令使用，可能会超出限制。对于高频率使用，建议依赖委托机制。

这需要您拥有自己的 GC 项目，如上所述。

要创建服务账号，请在左侧边栏中导航至IAM & Admin，然后选择服务账号（Service Accounts）。点击+ 创建服务账号，输入服务账号名称，例如“我的 DVC 项目”，并可选地提供自定义的服务账号 ID和描述。接着点击创建并继续。你可以跳过接下来的两个可选部分。点击完成，你将返回到概览页面。选择你的服务账号，进入密钥（Keys）标签页。在添加密钥下拉菜单中选择创建新密钥，选择JSON格式，然后点击创建。将生成的.json密钥文件下载并保存到安全位置。

⚠️ 请注意不要随意与他人分享该密钥文件。
配置远程存储以使用该服务账号，并指定密钥文件的位置：
```
$ dvc remote modify myremote gdrive_use_service_account true
$ dvc remote modify myremote --local \
              gdrive_service_account_json_file_path path/to/file.json
```
或者，可以通过设置GDRIVE_CREDENTIALS_DATA环境变量，在 CI/CD 系统、生产环境、只读文件系统等场景中传递服务账号密钥。该变量的内容应为一个字符串，其 JSON 格式需与上述密钥文件中的内容一致。如果同时提供了此变量和gdrive_service_account_json_file_path，则优先使用GDRIVE_CREDENTIALS_DATA，而忽略gdrive_service_account_json_file_path。
将你希望使用的 Google Drive 文件夹共享给该服务账号。进入 Google Drive 文件夹的共享设置，将服务账号作为编辑者（具有读写权限）或查看者（仅读权限）添加进去：

委托

委托可用于克服与 Google 服务账号相关的配额限制。

所需的OAuth 范围（scope）为https://www.googleapis.com/auth/drive。

还必须使用关联用户的个人邮箱来配置远程存储：

$ dvc remote modify myremote gdrive_service_account_user_email \
              example_adress@some_google_domain.com

配置参数

如果以下参数包含敏感用户信息，请使用 --local 选项添加，以确保它们被写入 Git 忽略的配置文件中。

url - 远程位置。参见有效 URL 格式。

$ dvc remote modify myremote url \
                    gdrive://0AIac4JZqHhKmUk9PDA/dvcstore

gdrive_client_id - 使用自定义 Google Client 项目时用于 OAuth 2.0 认证的客户端 ID。还需配合使用gdrive_client_secret。
```
$ dvc remote modify myremote gdrive_client_id 'client-id'
```
gdrive_client_secret - 使用自定义 Google Client 项目时用于 OAuth 2.0 认证的客户端密钥。还需配合使用gdrive_client_id。
```
$ dvc remote modify myremote gdrive_client_secret 'client-secret'
```
profile - 用于缓存 OAuth 凭据的文件基名。当多个 GDrive 远程使用相同的gdrive_client_id时，有助于避免使用错误的凭据。默认值为default。
```
$ dvc remote modify --local myremote profile myprofile
```
gdrive_user_credentials_file - 指定用于缓存 OAuth 凭据的文件路径。默认路径为$CACHE_HOME/pydrive2fs/{gdrive_client_id}/default.json（除非指定了profile）。其中CACHE_HOME在各平台上的位置如下：

macOS Linux（典型） Windows
~/Library/Caches ~/.cache %CSIDL_LOCAL_APPDATA%
```
$ dvc remote modify myremote \
      gdrive_user_credentials_file path/to/mycredentials.json
```
详见授权说明。
gdrive_trash_only - 配置dvc gc将远程文件移入回收站而非永久删除。默认值为false，表示“删除”。对于共享磁盘/文件夹特别有用，因为在这些场景中可能不具备删除权限。
```
$ dvc remote modify myremote gdrive_trash_only true
```
gdrive_acknowledge_abuse - 确认下载潜在滥用文件的风险。任何被识别为此类的文件（如恶意软件、个人信息等）只能由其所有者下载（需启用此参数）。
```
$ dvc remote modify myremote gdrive_acknowledge_abuse true
```

macOS	Linux（典型）	Windows
`~/Library/Caches`	`~/.cache`	`%CSIDL_LOCAL_APPDATA%`

对于服务账号

服务账号是与您的 GCP 项目关联的 Google 账号，而不是特定用户。更多信息请参阅使用服务账号。

gdrive_use_service_account - 使用服务账号进行身份验证。请确保该服务账号对远程 url 中的文件结构具有所需的读/写权限。
```
$ dvc remote modify myremote gdrive_use_service_account true
```

gdrive_service_account_json_file_path - 指向 Google 项目的服务账号 .json 密钥文件（凭据）的路径。

$ dvc remote modify --local myremote \
                    gdrive_service_account_json_file_path \
                    path/to/file.json

gdrive_service_account_user_email - 如有需要，可以将用户账号的权限委派给服务账号。
```
$ dvc remote modify myremote \
                    gdrive_service_account_user_email 'myemail-addr'
```
⚠️ DVC 需要以下 OAuth 范围：
- https://www.googleapis.com/auth/drive
- https://www.googleapis.com/auth/drive.appdata