当用户选择某个文件并点击 Google 云端硬盘界面的“打开方式”菜单项时,Google 云端硬盘会将用户重定向到配置 Google 云端硬盘界面集成中定义的相应应用的打开网址。
如果您在配置云端硬盘界面集成时勾选了“导入”框,用户可以选择应用专属文件和 Google Workspace 文件的组合来打开。配置云端硬盘界面集成时,应用专属文件在“默认 MIME 类型”和“默认文件扩展名”字段中定义,而 Google Workspace 文件在“辅助 MIME 类型”和“辅助文件扩展名”字段中定义。
对于用户想要打开的每个文件,云端硬盘会根据您定义的默认 MIME 类型和次要 MIME 类型检查 MIME 类型:
对于在“默认 MIME 类型”字段中定义的 MIME 类型,系统会将文件 ID 传递给您的应用。如需了解如何处理应用专属文件,请参阅处理应用专属文档的打开网址。
对于“辅助 MIME 类型”字段中定义的 MIME 类型,Google 云端硬盘界面会显示一个对话框,询问用户要将 Google Workspace 文件转换为哪种文件类型。例如,如果您在云端硬盘界面中选择了一个 Google 文档文件,并且“辅助 MIME 类型”字段建议您的应用支持 text/plain 或 application/pdf,则云端硬盘界面会询问用户是否要转换为纯文本或 PDF。
如需了解如何处理 Google Workspace 文件,请参阅处理 Google Workspace 文档的打开网址。 如需查看 Google Workspace 文档和 MIME 类型转换格式的列表,请参阅 Google Workspace 文档的导出 MIME 类型。
处理特定于应用的文档的打开网址
如配置 Google 云端硬盘界面集成中所述,您的应用会收到包含相关信息的模板变量,以便应用打开文件。您的应用会在 state
参数中收到一组默认的模板变量。特定于应用的“打开网址”操作的默认 state
信息为:
{
"ids": ["ID"],
"resourceKeys":{"RESOURCE_KEYS":"RESOURCE_KEYS"},
"action":"open",
"userId":"USER_ID"
}
此输出包括以下值:
- ID:父文件夹的 ID。
- RESOURCE_KEYS:一个 JSON 字典,其中包含映射到相应资源键的文件 ID。
open
:正在执行的操作。使用开放网址时,该值为open
。- USER_ID:唯一标识用户的个人资料 ID。
您的应用必须按照以下步骤对该请求采取行动:
- 验证
action
字段的值是否为open
,以及ids
字段是否存在。 - 使用
userId
值为用户创建新会话。如需详细了解已登录用户,请参阅用户和新事件。 - 使用
files.get
方法检查权限、提取文件元数据,并使用ID
值下载文件内容。 - 如果请求中设置了
resourceKeys
,则设置X-Goog-Drive-Resource-Keys
请求标头。如需详细了解资源密钥,请参阅使用资源密钥访问通过链接共享的文件。
state
参数经过网址编码,因此您的应用必须处理转义字符并将其解析为 JSON。
处理 Google Workspace 文档的打开网址
如配置云端硬盘界面集成中所述,您的应用会在 state
参数中收到一组默认的模板变量。Google Workspace 开放网址的默认 state
信息为:
{
"exportIds": ["ID"],
"resourceKeys":{"RESOURCE_KEYS":"RESOURCE_KEYS"},
"action":"open",
"userId":"USER_ID"
}
此输出包括以下值:
- EXPORT_ID:正在导出的文件 ID 的英文逗号分隔列表(仅在打开内置 Google 文档时使用)。
- RESOURCE_KEYS:一个 JSON 字典,其中包含映射到相应资源键的文件 ID。
open
:正在执行的操作。使用开放网址时,该值为open
。- USER_ID:用于标识用户的个人资料 ID。
您的应用必须按照以下步骤对该请求采取行动:
通过检测
state
字段中的open
值和exportIds
字段的存在情况,验证这是否是打开文件的请求。使用
files.get
方法检查权限、提取文件元数据,并使用EXPORT_ID
值确定 MIME 类型。使用
files.export
方法转换文件内容。以下代码示例展示了如何将 Google Workspace 文档导出为所请求的 MIME 类型。如果请求中设置了
resourceKey
,则设置X-Goog-Drive-Resource-Keys
请求标头。如需详细了解资源密钥,请参阅使用资源密钥访问通过链接共享的文件。Java
Python
Node.js
PHP
将转换后的文件显示为只读文件,或显示一个对话框,让用户将文件另存为新文件类型。
state
参数经过网址编码,因此您的应用必须处理转义字符并将其解析为 JSON。
用户和新事件
Google 云端硬盘应用应将所有“打开方式”事件视为潜在的登录事件。部分用户可能拥有多个账号,因此 state
参数中的用户 ID 可能与当前会话不匹配。如果 state
参数中的用户 ID 与当前会话不匹配,请结束应用的当前会话,并以所请求的用户身份登录。
相关主题
除了从 Google 云端硬盘界面打开应用之外,应用还可以显示文件选择器,以便从应用内选择内容。如需了解详情,请参阅 Google 选择器。