跳到主要内容

配置 Google Sheets 数据源

最近更新 2026/10/05

Google Sheets 数据源用于通过离线同步读取 Google 表格中的数据，并写入平台内置数仓。本文介绍 Google 端的授权准备、数据源配置、同步方案创建和任务流挂载。

使用限制与准备事项​

开始配置前，请确认以下限制和前置条件：

  • Google Sheets 仅支持作为数据来源，不支持作为数据去向，也不会回写 Google 表格。
  • 系统会依据 Google Sheets 顶部显示的列标（A、B、C 等），自动添加 col_ 前缀生成来源字段名。例如，A 列生成 col_A，B 列生成 col_B。所有来源字段的类型均为字符串，请在字段映射时按目标表要求转换或调整字段。
  • 需准备一个可创建 Google Cloud 项目、服务账号和 JSON 密钥的 Google 账号，并有权限将目标 Google 表格共享给服务账号。
  • 平台运行环境需能访问 Google Sheets API 和 Google Drive API。
环境配置方式适用场景配置要求
不区分环境开发环境与生产环境共用同一个服务账号上传一份 JSON 密钥即可
独立环境配置开发环境与生产环境使用不同服务账号分别上传密钥；两个账号都需能访问同名的 Google 表格和工作表
提示

独立环境配置下，配置和预览使用开发环境凭证，生产任务使用生产环境凭证。请提前检查两个环境中的表格名称、工作表名称和共享权限。

在 Google Cloud 和 Google Sheets 中完成授权​

Google Sheets 数据源使用服务账号进行服务端认证，无需配置 OAuth 同意屏幕、客户端 ID、回调地址或全域委派。

  1. 创建或选择 Google Cloud 项目。进入 Google Cloud Console，选择已有项目或新建项目。
  2. 启用所需 API。在 API 和服务 > API 库 中分别搜索并启用 Google Sheets API 和 Google Drive API。前者用于读取单元格数据，后者用于发现表格和读取文件元数据。
  3. 创建服务账号。进入 IAM 和管理 > 服务账号，创建一个专用于读取 Google Sheets 的服务账号。当前接入无需为服务账号授予项目 Owner、Editor 或 Drive Admin 等宽泛角色。
  4. 创建 JSON 密钥。打开该服务账号的 密钥 页，选择 添加密钥 > 创建新密钥 > JSON，下载并妥善保存密钥文件。
  5. 共享目标表格。打开需要读取的 Google 表格，点击右上角 共享，输入 JSON 文件中的 client_email，权限选择 查看者，然后完成共享。

给服务账号授予目标 Google 表格的查看权限。

在 Google Sheets 中将服务账号添加为“查看者”

每个需要读取的表格都必须直接共享给服务账号，或通过父文件夹继承访问权限。仅启用 API 不会自动赋予表格访问权限。

警告

Service Account JSON 包含敏感凭证，请勿将密钥提交到代码仓库、日志、群聊或工单；如密钥泄露，请在 Google Cloud 中立即停用或删除并重新生成。

如果无法创建密钥，请联系 Google Cloud 管理员检查组织策略 iam.disableServiceAccountKeyCreation。如果无法向 iam.gserviceaccount.com 地址共享表格，请联系 Google Workspace 管理员检查 Drive 外部共享策略。

创建 Google Sheets 数据源​

  1. 进入 数据开发平台 > 集成 > 数据源，点击 新增数据源。
  2. 选择 GoogleSheets，填写数据源名称和备注。
  3. 选择 不区分环境 或 独立环境配置。独立环境配置需要分别完成开发环境和生产环境的配置。
  4. 在 Service Account JSON 中上传 Google Cloud 下载的原始 .json 文件。
  5. 点击 连通性测试。显示 可连通 后，点击 完成。

上传 Service Account JSON，并确认连通性测试结果为“可连通”。

上传服务账号 JSON 并完成连通性测试
配置项说明
Service Account JSON上传 Google Cloud 下载的原始 JSON 密钥文件，平台会自动完成校验。
不区分环境开发环境和生产环境共用当前密钥
独立环境配置分别维护开发环境和生产环境密钥，两个环境均需单独通过连通性测试

编辑已保存的数据源时，页面只显示脱敏后的服务账号邮箱，不会回显私钥。如需更换密钥，请重新上传新的 JSON 文件并再次测试连接。

创建离线同步方案​

  1. 进入 数据开发平台 > 集成 > 离线同步，点击 创建集成方案。
  2. 在 数据来源 中选择 GoogleSheets 及已创建的数据源。
  3. 依次选择要读取的 Google 表格 和其中的 工作表。列表中仅展示当前服务账号有权访问的内容。
  4. 填写 列范围。范围只包含列字母，例如 A:F、F:F 或 AA:ZZZ；系统会自动转换为大写。
  5. 展开 文件读取规则，根据表格内容设置 跳过表头。开启后从第 2 行开始读取，关闭后从第 1 行开始读取。
  6. 点击来源数据预览，确认选定范围、行数和数据内容符合预期。

选择表格、工作表和列范围后，通过来源数据预览检查读取结果。

配置读取范围并预览来源数据
提示

列范围不包含行号或工作表名称。A1:F、A:F50000、工作表1!A:F 和起始列大于结束列的 F:A 均为无效格式。

独立环境配置下，生产执行会使用生产环境服务账号查找同名 Google 表格和工作表。若名称重复、缺失或未授权，生产任务可能失败。

字段映射与同步验证​

完成数据来源配置后，选择平台内置数仓中的目标表，并建立字段映射。Google Sheets 字段按列字母生成，例如 A 列对应 col_A、B 列对应 col_B，类型均为字符串。

  1. 在 数据去向 中选择或创建目标表，并按业务需要设置写入方式。
  2. 在 字段映射 中将来源字段映射到目标字段；目标字段类型不一致时，先完成必要的类型转换。
  3. 填写方案名称、负责人和备注后保存。
  4. 点击 手动执行，在执行记录中确认任务成功，再到目标表核对行数、字段顺序和数据内容。
现象检查项
连通性测试失败确认上传的是完整的服务账号 JSON，密钥未被停用或删除，并已启用 Google Sheets API 和 Google Drive API
找不到目标 Google 表格确认表格已共享给 JSON 中的 client_email，权限至少为“查看者”
找不到工作表确认工作表未被删除；独立环境下检查生产账号是否能访问同名表格和工作表
列范围报错只填写列字母并检查起始列不大于结束列；确认范围未超出工作表可读取范围
提示 429 或请求限流稍后重试，并检查 Google API 配额和任务并发

挂载到任务流​

手动验证成功后，可将离线同步方案挂载到任务流，按调度周期自动执行。

  1. 打开已保存的离线同步方案，点击 挂载到任务流。
  2. 选择目标任务流。
  3. 填写节点名，选择执行模式，并按需设置负责人和备注。节点类型和集成方案会自动带出。
  4. 点击 创建节点并挂载。挂载成功后，可点击 前往任务流 检查节点位置和上下游依赖。
  5. 保存任务流并完成发布；生产调度将使用生产环境的数据源配置。

如需更换同步方案或数据源，请先评估现有任务流依赖，并在修改后重新执行一次验证。

这篇文档对你有帮助吗？
本页内容