OpenCore文档与知识Google Drive

Google Drive Service Account

以 Markdown 格式查看

当组织通过服务身份管理 Google Workspace 访问时，使用此方式。Workspace 管理员负责批准委派和 Scope，OpenCore Admin 负责上传和维护凭据，并在配置连接器时选择或关联该凭据。

前置条件

请使用 Standard 模式，因为连接器和文档索引需要此模式。你需要一个由组织控制的 Google Cloud Project、能够配置 Domain-Wide Delegation 的 Google Workspace 管理员，以及拥有 Drive 内容的 Workspace 组织的 Primary Admin Email。

创建 Service Account

在 Google Cloud Project 中创建 Service Account，并为它创建 JSON Key。请妥善保护密钥，只能通过受保护的 OpenCore Admin 页面上传。

1{
2  "type": "service_account",
3  "project_id": "<google-cloud-project-id>",
4  "client_email": "<service-account>@<project-id>.iam.gserviceaccount.com",
5  "private_key": "<keep-this-secret-and-upload-it-only-in-the-admin-panel>"
6}

请从 Google Cloud 记录 Service Account OAuth client ID。Domain-Wide Delegation 使用的是该 OAuth client ID，而不是 Service Account 邮箱地址。

配置 Domain-Wide Delegation

在 Google Workspace Admin console 中，将 Service Account OAuth client ID 添加到 Domain-Wide Delegation，并且只授权 Google Drive 连接器当前所需的 Scope：

最小 ScopeOpenCore 请求它的原因
https://www.googleapis.com/auth/drive.readonly读取已批准的 Google Drive 内容。
https://www.googleapis.com/auth/drive.metadata.readonly读取用于发现和识别内容的 Google Drive 元数据。
https://www.googleapis.com/auth/admin.directory.group.readonly为权限同步读取 Workspace 群组成员关系。
https://www.googleapis.com/auth/admin.directory.user.readonly为权限同步读取 Workspace 用户。

除非已部署的连接器变更了文档所述要求，请不要添加更广泛的 Scope。Service Account 在访问 Google Workspace 时会模拟所配置的 Primary Admin Email。

将凭据添加到 OpenCore

  1. 以 Admin 身份登录 OpenCore，并打开 文档与知识。
  2. 选择 Google Drive，选择 Service account，并上传 JSON Key。
  3. 输入拥有 Drive 内容的 Google Workspace 组织中管理员或所有者的 Primary Admin Email。
  4. 创建凭据；不要将密钥放入源代码管理、Agent 指令或共享文档。

只有 Admin 可以上传、替换或以其他方式维护 Service Account 凭据。配置连接器时，也由 Admin 选择或关联该 Google 凭据；不要假定该凭据已与其他角色共享。

配置索引范围

Admin 配置连接器时，请选择最小的已批准范围。

区域可用选项
GeneralInclude Everyone’s My Drive 和 Include shared drives。
Specific逗号分隔的多个 Shared Drive URLs、Folder URLs 和 My Drive Emails。被索引的文件夹包含全部子文件夹。
AdvancedSpecific User Emails：仅索引这些用户可访问的文件；以及可选的 Hide domain link-only files。

所选范围和被模拟账号的 Google Drive 权限都会限制连接器可读取的内容。Domain-Wide Delegation 不会取代内容所有者对索引的批准。

验证连接器

使用一个小且有代表性的已批准范围创建连接器，并运行一次索引尝试。在将文档集附加给 Agent 或扩大范围前，请检查尝试结果、已索引文档集，以及报告的跳过文件或错误。

故障排查

症状检查并修正
JSON 类型被拒绝上传 type 为 service_account 的有效 JSON Key，而不是 OAuth Client JSON。
Primary Admin Email 失败输入拥有所选内容的 Google Workspace 组织中一个存在的管理员或所有者邮箱。
Delegation 或 Scope 错误确认 Domain-Wide Delegation 使用 Service Account OAuth client ID，并授权全部四个必需 Scope。
Google Workspace 返回 403确认 Primary Admin Email 具有目录访问权限，且 Service Account 的 Domain-Wide Delegation 已生效。

相关页面