配置云端硬盘界面集成

如需在用户创建或打开文件时在 Google 云端硬盘中显示您的应用，您必须先设置云端硬盘界面 (UI) 集成。您还需要进行配置，才能在 Google Workspace Marketplace 中列出您的应用。

启用 Drive API

在使用 Google API 之前，您必须先在 Google Cloud 项目中启用它们。您可以在单个 Google Cloud 项目中启用一个或多个 API。

如需开始与 Google 云端硬盘界面集成，您必须启用 Drive API。这样您就可以使用 API 和界面集成功能了。

• 在 Google Cloud 控制台中，启用 Google Drive API。

  启用 API

设置云端硬盘界面集成

1. 在 Google API 控制台中，依次前往菜单 > API 和服务 > 已启用的 API 和服务。

   前往“已启用的 API 和服务”

2. 在“API 和服务”信息中心底部，点击 Google Drive API。系统随即会显示 Google Drive API 配置页面。
3. 选择云端硬盘界面集成标签页。
4. （可选）在应用名称字段中输入一个名称。应用名称会显示在云端硬盘设置的“管理应用”标签页中，供用户查看。
5. （可选）在简短说明字段中输入简短的一行说明。简短说明会显示在云端硬盘设置的“管理应用”标签页中。
6. （可选）在详细说明字段中输入完整说明。

7. 上传一个或多个应用图标，以便在用户关联的云端硬盘应用列表中以及“打开方式”上下文菜单中显示这些图标。图标应为 PNG 格式，且具有透明背景。图标最多可能需要 24 小时才会显示在云端硬盘中。

   注意： 文档图标已弃用。您的应用图标会显示在快捷方式和第三方快捷方式文件旁边。对于其他文件类型，系统会使用一组标准图标。

8. 如需使用云端硬盘界面的“打开方式”菜单项，请在打开网址字段中输入应用的网址。此网址由“打开方式”上下文菜单使用。

   • 此网址必须包含完全限定域名；localhost 不起作用。
   • 此网址应可供应用的预期用户访问。 如果您有多个应用版本，例如一个用于公开发布，另一个用于向部分用户限制性发布，则每个版本都应使用唯一的网址。然后，您可以为每个版本创建不同的应用配置。
   • 您必须先验证此网址的所有权，然后才能在 Google Workspace Marketplace 中列出您的应用。
   • 默认情况下，系统会将 state 查询参数附加到此网址，以将数据从 Google 云端硬盘界面传递到您的应用。如需了解 state 参数的内容，请参阅state 参数。
   警告： 自动显示 OAuth 2.0 权限请求页面的选项已被弃用。请勿勾选此复选框。应用必须启动所有授权请求。

9. （可选）在默认 MIME 类型和默认文件扩展名字段中输入默认 MIME 类型和文件扩展名。默认 MIME 类型和文件扩展名表示您的应用专门用于打开的文件。例如，您的应用可能会打开用于分层和编辑图片的内置格式。仅包含标准媒体类型，并确保它们没有拼写错误。如果您的应用仅打开快捷方式或第三方快捷方式文件，您可以将 MIME 类型留空。

10. （可选）在辅助 MIME 类型和辅助文件扩展名字段中输入辅助 MIME 类型和文件扩展名。次要 MIME 类型和文件扩展名表示您的应用可以打开的文件，但并非特定于您的应用。例如，您的应用可能是可以打开 PNG 和 JPG 图片的图片编辑应用。仅包含标准媒体类型，并确保它们没有拼写错误。如果您的应用仅打开快捷方式或第三方快捷方式文件，您可以将 MIME 类型留空。

    注意： 如果用户安装了多个可以打开文件的云端硬盘应用，系统会使用最近安装的应用，直到用户选择其他应用为止。

11. 如需使用云端硬盘界面中的“新建”按钮并让用户使用您的应用创建文件，请选中创建文件复选框。系统会显示新网址和可选的文档名称字段。

    • 此网址必须包含完全限定域名；localhost 不起作用。
    • 您必须先验证此网址的所有权，然后才能在 Google Workspace Marketplace 中列出您的应用。
    • 默认情况下，系统会将 state 查询参数附加到此网址，以将数据从 Google 云端硬盘界面传递到您的应用。如需了解 state 参数的内容，请参阅state 参数。

12. 在新网址字段中输入网址。“新建”按钮使用此网址将用户重定向到您的应用。

    注意： 将“文档名称”字段留空。此字段不再使用。

13. （可选）如果您希望应用打开 Google Workspace 支持的文件，请勾选导入复选框。

14. （可选）如果您的应用必须管理共享云端硬盘中的文件，请勾选支持共享云端硬盘复选框。如需详细了解如何在应用中支持共享云端硬盘，请参阅实现共享云端硬盘支持。

15. 点击提交。

请求 drive.install 范围

如需允许应用显示为“打开方式”或“新建”菜单中的一个选项，请请求 https://www.googleapis.com/auth/drive.install 范围以与云端硬盘界面集成。当用户请求此范围时，会收到类似于以下内容的对话框：

图 1. 使用云端硬盘界面范围时的安装对话框。

如需详细了解您可以为云端硬盘应用请求的范围以及如何请求这些范围，请参阅 API 专属授权和身份验证信息。

注意： 如果您将云端硬盘应用发布到 Google Workspace Marketplace，用户和网域管理员可以直接从 Google Workspace Marketplace 搜索并安装该应用。

state 参数

默认情况下，系统会在“打开网址”和“新建网址”中附加 state 参数，以便将数据从云端硬盘界面传递到您的应用。此参数包含一个 JSON 编码的字符串，其中包含模板变量以及有关向您的应用发出的请求的数据。包含的变量取决于所使用的网址类型（“打开网址”或“新建网址”）：

模板变量	说明	网址应用
{ids}	以英文逗号分隔的正在打开的文件 ID 列表。	打开网址
{exportIds}	正在导出的文件 ID 的英文逗号分隔列表（仅在打开内置 Google 文档时使用）。	打开网址
{resourceKeys}	一个 JSON 字典，其中包含映射到相应资源键的文件 ID。	打开网址
{folderId}	父文件夹的 ID。	“新建”网址
{folderResourceKey}	父文件夹的资源键。	“新建”网址
{userId}	用于标识用户的个人资料 ID。	打开网址和新网址
{action}	正在执行的操作。使用“打开网址”时，该值为 open；使用“新网址”时，该值为 create。	打开网址和新网址

state 参数经过网址编码，因此您的应用必须处理转义字符并将其解析为 JSON。应用可以检测 state 参数中的 create 值，以验证创建文件的请求。

JSON 格式的新网址状态信息示例

新网址的 state 信息为：

{
  "action":"create",
  "folderId":"FOLDER_ID",
  "folderResourceKey":"FOLDER_RESOURCE_KEY",
  "userId":"USER_ID"
}

JSON 格式的“打开网址”状态信息示例

“打开网址”的 state 信息为：

{
  "ids": ["ID"],
  "resourceKeys":{"RESOURCE_KEYS":"RESOURCE_KEYS"},
  "action":"open",
  "userId":"USER_ID"
}

ID 和资源密钥用于提取文件元数据和下载文件内容。应用获得文件 ID 和访问令牌后，便可以检查权限、提取文件元数据并下载文件内容，如 files.get 方法中所述。

注意： 所有应用（包括通过快捷方式和第三方快捷方式打开文件的应用）都应调用 files.get 方法来检查用户对文档的权限。应用应在只读用户打开无法编辑或保存的文件时发出警告，而不是让他们花费时间进行编辑，然后在保存时显示错误。

相关主题

已安装的应用必须能够创建、管理和打开从云端硬盘界面启动的操作。如需了解详情，请参阅与 Google 云端硬盘界面的“新建”按钮集成或与 Google 云端硬盘界面的“打开方式”上下文菜单集成。