> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.alephant.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server.

# Google Drive Service Account

> 配置 Google Workspace Service Account 和 Domain-Wide Delegation，以管理组织的 Google Drive 索引。

当组织通过服务身份管理 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 页面上传。

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

请从 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：

| 最小 Scope                                                         | OpenCore 请求它的原因                |
| ---------------------------------------------------------------- | ------------------------------ |
| `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 配置连接器时，请选择最小的已批准范围。

| 区域       | 可用选项                                                                                 |
| -------- | ------------------------------------------------------------------------------------ |
| General  | **Include Everyone's My Drive** 和 **Include shared drives**。                         |
| Specific | 逗号分隔的多个 **Shared Drive URLs**、**Folder URLs** 和 **My Drive Emails**。被索引的文件夹包含全部子文件夹。 |
| Advanced | **Specific 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 已生效。 |

## 相关页面

* [Google Drive 概览](/opencore/knowledge/google-drive/overview) 对比认证方式和索引范围。
* [Google Drive OAuth](/opencore/knowledge/google-drive/oauth) 指导使用 OAuth App 完成基于浏览器的授权。
* [连接器与索引](/opencore/knowledge/connectors) 说明文档集和索引尝试。