Google Sheets

可用性: 核心标准 Plus Pro Enterprise Flex 自托管 Enterprise PyAirbyte
支持级别: Airbyte
连接器版本: 0.12.18 (上次更新 4 天前)
同步成功率
使用率
定义 ID: 71607ba1-c0ac-4799-8049-7f4b90dd50f7

此页面包含 Google Sheets 来源连接器的设置指南和参考信息。

信息

Google Sheets 来源连接器从单个 Google Sheets 电子表格中提取数据。电子表格中的每个工作表都可以同步。要同步多个电子表格，请使用我们的 Google Drive 连接器或在您的 Airbyte 实例中设置多个 Google Sheets 来源连接器。不会访问 Google Drive 中的其他文件。

先决条件

电子表格链接 - 您要同步的 Google 电子表格的链接。

对于 Airbyte Cloud 具有对电子表格访问权限的 Google Workspace 用户

对于 Airbyte 开源版
一个 GCP 项目
在您的 GCP 项目中启用 Google Sheets API
具有访问您要复制的电子表格权限的服务帐户密钥

设置指南

Google Sheets 来源连接器支持通过 OAuth 或服务帐户密钥身份验证进行身份验证。

步骤 1：设置 Google Sheets

对于 Airbyte Cloud

我们强烈建议使用 OAuth，因为它大大简化了设置过程，并允许您直接从 Airbyte UI 进行身份验证。

对于 Airbyte 开源版

我们建议使用服务帐户密钥身份验证。请按照以下步骤创建服务帐户、生成密钥并启用 Google Sheets API。

注意

如果您希望使用 OAuth 进行 Airbyte 开源 的身份验证，可以按照 Google 的 OAuth 说明创建身份验证应用程序。请务必将范围设置为 https://www.googleapis.com/auth/spreadsheets.readonly。您需要为连接器设置获取客户端 ID、客户端密钥和刷新令牌。

设置服务帐户密钥

创建服务帐户

在您的 Google Cloud 控制台中打开服务帐户页面。
选择现有项目，或创建一个新项目。
在页面顶部，单击 + 创建服务帐户。
输入服务帐户的名称和描述，然后单击 创建并继续。
在 服务帐户权限 下，选择授予服务帐户的角色，然后单击继续。我们建议 查看者 角色。

生成密钥

转到 API 控制台/凭据页面，然后单击您刚刚创建的服务帐户的电子邮件地址。
在密钥选项卡中，单击 + 添加密钥，然后单击 创建新密钥。
选择JSON 作为密钥类型。这将生成并下载您将用于身份验证的 JSON 密钥文件。点击继续。

启用 Google Sheets API

转到 API 控制台/库页面。
确保您已从顶部选择正确的项目。
找到并选择 Google Sheets API。
单击启用。

如果您的电子表格可以被拥有其链接的任何人查看，则无需进一步操作。如果不是，为您的服务帐户授予访问您的电子表格的权限。

在 Airbyte 中设置 Google Sheets 连接器

对于 Airbyte Cloud：

登录到您的 Airbyte Cloud 账户。
点击“来源”，然后点击“+ 新来源”。
在设置来源页面上，从来源类型下拉菜单中选择 Google Sheets。
输入 Google Sheets 连接器的名称。

对于 Airbyte 开源：

导航到 Airbyte 开源仪表板。
点击“来源”，然后点击“+ 新来源”。
在设置来源页面上，从来源类型下拉菜单中选择 Google Sheets。
输入 Google Sheets 连接器的名称。

选择您的身份验证方法

对于 Airbyte Cloud：（推荐） 从身份验证下拉菜单中选择 通过 Google 身份验证（OAuth），单击 使用 Google 登录，然后完成身份验证流程。
对于 Airbyte 开源：（推荐） 从下拉菜单中选择 服务帐户密钥身份验证，并以 JSON 格式输入您的 Google Cloud 服务帐户密钥

  {
    "type": "service_account",
    "project_id": "YOUR_PROJECT_ID",
    "private_key_id": "YOUR_PRIVATE_KEY",
    ...
  }

要通过 OAuth 身份验证您的 Google 帐户，请从下拉菜单中选择 通过 Google 身份验证（OAuth），并输入您的 Google 应用程序的客户端 ID、客户端密钥和刷新令牌。

对于 电子表格链接，输入 Google 电子表格的链接。要获取链接，请转到您要同步的 Google 电子表格，单击右上角的共享，然后单击 复制链接。

对于 批处理大小，输入一个整数，该整数表示处理 Google Sheet 时的批处理大小。默认值为 1000000。批处理大小是一个整数，表示每次发送到 Google Sheets API 的行批处理大小。行批处理大小意味着从 google sheet 处理多少行，例如默认值 1000000 将处理行 2-1000002，然后 1000003-2000003，依此类推。根据 Google Sheets API 限制文档，可以每分钟发送最多 300 个请求，但每个单独的请求必须在 180 秒内处理完毕，否则请求将返回超时错误。鉴于此信息，请在确定 batch_size 值时考虑网络速度和 google sheet 的列数。

(可选) 您可以启用 将列名转换为符合 SQL 标准的格式 选项。启用此选项将允许连接器将列名转换为标准化的、SQL 友好的格式。例如，列名 Café Earnings 2022 将转换为 cafe_earnings_2022。如果您目标是基于 SQL 的目的地（例如 Postgres、MySQL），我们建议启用此选项。默认设置为 false。
点击 Set up source 并等待测试完成。

配置选项

流名称覆盖（重命名工作表/流名称）

Google Sheets 连接器允许您选择性地重命名在 Airbyte 和您的目的地中显示的工作表（选项卡名称）。如果您的工作表名称不够描述性、包含特殊字符或您希望跨来源标准化命名，这将很有用。

工作原理

您可以提供一个覆盖列表，每个覆盖指定一个 source_stream_name（您的电子表格中工作表/选项卡的精确名称）和一个 custom_stream_name（您希望它在 Airbyte 和您的目的地中显示的名称）。
如果您的电子表格中找不到 source_stream_name，它将被忽略并使用默认名称。
此功能仅影响流（工作表/选项卡）名称，不影响字段/列名称。
如果您想重命名字段或列名称，可以在连接创建后使用 Airbyte 映射功能来执行此操作。请参阅 Airbyte 文档，了解有关如何使用映射的更多详细信息。
重命名操作发生在任何其他名称转换或清理选项之前。

示例

假设您的电子表格包含名为 Sheet1、2024 Q1 和 Summary 的工作表。您希望将它们重命名为 sales_data、q1_2024，并保持 Summary 不变。您将配置

[
  { "source_stream_name": "Sheet1", "custom_stream_name": "sales_data" },
  { "source_stream_name": "2024 Q1", "custom_stream_name": "q1_2024" }
]

发现后，Airbyte 中的流将被命名为 sales_data、q1_2024 和 Summary。

如何配置

在 Airbyte UI 中，将您的覆盖项添加到 流名称覆盖 字段，作为对象数组。
如果您不想重命名任何流，请将此字段留空。
添加或更改流名称覆盖后，在 Airbyte 中刷新您的模式，以使新的流名称生效。
覆盖的流将默认使用同步模式：完全刷新（追加），不支持主键。如果您想使用主键和去重，请在您的连接设置中将同步模式更新为“完全刷新 | 覆盖 + 去重”。

Google Sheets 连接器列名称转换

Google Sheets 连接器提供选项来自定义电子表格中的列名称如何转换为符合 SQL 规范。这些设置可以在设置连接器时在 Airbyte UI 中配置。

1. 将列名称转换为符合 SQL 规范的格式

描述：启用后，此选项会将列名称转换为与 SQL 数据库兼容的格式（例如，小写，将空格替换为下划线）。这是启用任何列名称转换所需的首要开关。
默认值：关闭

2. 其他转换选项

以下选项允许您微调列名称转换过程。只有在启用“将列名称转换为符合 SQL 规范的格式”时，它们才会生效。

删除前导和尾随下划线
- 描述：删除列名称中的前导和尾随下划线。请注意，如果禁用“允许前导数字”，则对于以数字开头的列名称，前导下划线将被保留。
- 示例:
  - 输入：" EXAMPLE Domain "
  - 输出："example_domain"
- 默认值：关闭
组合数字-单词对
- 描述：将相邻的数字和单词组合成一个单独的标记，不使用分隔符。
- 示例:
  - 输入："50th Percentile"
  - 输出："50th_percentile"（如果启用“允许前导数字”）
  - 输出："_50th_percentile"（如果禁用“允许前导数字”）
- 默认值：关闭
删除所有特殊字符
- 描述：删除所有特殊字符（例如，*、?、!、$、%、(、)）的列名称。
- 示例:
  - 输入："Example ID*"
  - 输出："example_id"
- 默认值：关闭
组合字母-数字对
- 描述：将相邻的字母和数字组合成一个单独的标记，不使用分隔符。
- 示例:
  - 输入："Q3 2023"
  - 输出："q3_2023"
- 默认值：关闭
允许前导数字
- 描述：允许列名称以数字开头。如果禁用，则会在以数字开头的列名称前添加前导下划线。
- 示例:
  - 输入："50th Percentile"
  - 输出："50_th_percentile"（如果启用）
  - 输出："_50_th_percentile"（如果禁用）
- 默认值：关闭

其他详细信息

所有转换后的列名称都将转换为小写。
多个空格或特殊字符将被合并或删除，而不是替换为多个下划线。
仅使用单个下划线分隔标记。
结果始终对 SQL 友好且易于阅读。

这些选项提供了灵活性，可以根据您的特定数据库要求调整列名称转换。在配置 Google Sheets 连接器时，根据需要在 Airbyte UI 中进行调整。

标题去重

Google Sheets 连接器会自动处理重复的列标题，方法是将单元格位置附加到每个重复的标题名称，以创建唯一的字段名称。这确保即使您的电子表格包含重复的标题名称，所有列都能正确同步。

工作原理

检测到重复标题时，连接器会将 _<cell_position> 附加到每个重复的标题名称
单元格位置遵循标准的 Google Sheet 命名约定（例如，A1、B1、C1 等）
这创建了唯一的字段名称，同时保留了原始标题文本

示例

如果您的电子表格在 C 列和 Q 列（位置 C1 和 Q1）中都有名为 stats 的标题，则连接器将创建两个不同的字段

stats_C1（对于位置 C1 的列）
stats_Q1（对于位置 Q1 的列）

这确保了来自两列的数据都被正确捕获并同步到您的目标，并清楚地标识了每个字段代表哪个列。

支持的同步模式

Google Sheets 来源连接器支持以下同步模式

支持的流

所选电子表格中的每个工作表都作为单独的流同步。工作表中的每个选定列都作为字符串字段同步。

Airbyte 仅支持复制 Grid 工作表。

数据类型映射

所选电子表格中的每个工作表都作为单独的流同步。工作表中的每个选定列都作为字符串字段同步。

Airbyte 仅支持复制 Grid 工作表。

集成类型	Airbyte 类型	备注
任意类型	`字符串`

限制和故障排除

展开以查看有关 Google Sheets 连接器限制和故障排除的详细信息。

连接器限制

速率限制

Google API 速率限制为

每个项目每分钟 300 次读取请求
每个用户每分钟 60 次请求

Airbyte 将请求批量处理到 API，以便有效地提取数据并遵守这些速率限制。我们建议不要使用相同的用户或服务帐户用于超过 3 个 Google Sheets 来源连接器实例，以确保高速传输。

故障排除

如果您的工作表完全为空（没有标题行）或已删除，Airbyte 不会删除目标中的表。如果发生这种情况，同步日志将包含一条消息，说明在同步整个电子表格时跳过了该工作表。
如果电子表格不是 Google Sheets 文件，连接器设置将失败。如果该文件另存为或导入为其他文件类型，设置可能会失败。
请查看我们的 Airbyte 论坛，了解 Google Sheets 来源连接器的常见故障排除问题。

参考

配置字段参考

字段

类型

属性名称

对象

credentials

字符串

spreadsheet_id

布尔值

allow_leading_numbers

整数

batch_size

布尔值

combine_letter_number_pairs

布尔值

combine_number_word_pairs

布尔值

names_conversion

布尔值

read_empty_header_columns

布尔值

删除前导和尾随下划线

布尔值

remove_special_characters

array<object>

stream_name_overrides

变更日志

展开以查看

版本	日期	拉取请求	主题
0.12.18	2026-01-20	71904	更新依赖项
0.12.17	2026-01-14	71703	更新依赖项
0.12.16	2025-12-18	70510	更新依赖项
0.12.15	2025-12-03	69848	添加可选标志以读取带有空标题的列
0.12.14	2025-11-25	70029	更新依赖项
0.12.13	2025-11-18	69396	更新依赖项
0.12.12	2025-10-29	68759	更新依赖项
0.12.11	2025-10-21	68254	更新依赖项
0.12.10	2025-10-16	67531	添加错误处理，以处理导致 500 响应的表格中的意外数据。
0.12.9	2025-10-14	67876	更新依赖项
0.12.8	2025-10-07	67395	更新依赖项
0.12.7	2025-09-30	65383	更新依赖项
0.12.6	2025-09-16	66012	更新到 CDK v7
0.12.5	2025-08-09	64633	更新依赖项
0.12.4	2025-08-02	64179	更新依赖项
0.12.3	2025-07-26	63822	更新依赖项
0.12.2	2025-07-22	63334	功能：去重标题
0.12.1	2025-07-19	55490	更新依赖项
0.12.0	2025-07-15	63305	将发布候选版本 0.12.0-rc.2 提升到主版本。
0.12.0-rc.2	2025-07-11	62931	修复：处理 SchmemaMatchingExtractor 中意外的 `propeties_to_match`
0.12.0-rc.1	2025-07-02	62456	功能：将连接器迁移到仅限清单格式
0.11.0	2025-06-11	61489	功能：添加流名称覆盖选项
0.10.0	2025-06-09	60836	功能：添加在使用将列名称转换为符合 SQL 规范的格式 (names_conversion) 时添加额外的清理标志
0.9.6	2025-05-22	60874	在单个工作表上对 429 错误使用自定义回退策略
0.9.5	2025-05-13	60259	修复启用 `names_conversion` 时列名称中使用的空格
0.9.4	2025-03-01	54989	更新依赖项
0.9.3	2025-02-22	54434	更新依赖项
0.9.2	2025-02-15	53720	更新依赖项
0.9.1	2025-02-08	51696	更新依赖项
0.9.0	2025-02-04	53154	将发布候选版本 0.9.0-rc.3 提升到主版本。
0.9.0-rc.3	2025-01-31	52682	修复流名称类型
0.9.0-rc.2	2025-01-31	52671	修复工作表 ID 编码
0.9.0-rc.1	2025-01-30	50843	迁移到低代码
0.8.5	2025-01-11	44270	从这个版本开始，Docker 镜像现在是 rootless。请注意，此版本和未来的版本将与 Airbyte 版本早于 0.64 不兼容
0.8.4	2024-12-09	48835	实施集成测试
0.7.4	2024-09-09	45108	Google Sheets API 错误现在会导致同步失败
0.7.3	2024-08-12	43921	更新依赖项
0.7.2	2024-08-10	43544	更新依赖项
0.7.1	2024-08-03	43290	更新依赖项
0.7.0	2024-08-02	42975	迁移到 CDK v4.3.0
0.6.3	2024-07-27	42826	更新依赖项
0.6.2	2024-07-22	41993	避免将速率限制视为成功的同步
0.6.1	2024-07-20	42376	更新依赖项
0.6.0	2024-07-17	42071	迁移到 CDK v3.9.0
0.5.11	2024-07-13	41527	更新依赖项
0.5.10	2024-07-09	41273	更新依赖项
0.5.9	2024-07-06	41005	更新依赖项
0.5.8	2024-06-28	40587	将已弃用的 AirbyteLogger 替换为 logging.Logger
0.5.7	2024-06-25	40560	在发现期间捕获身份验证错误并引发配置错误
0.5.6	2024-06-26	40533	更新依赖项
0.5.5	2024-06-25	40505	更新依赖项
0.5.4	2024-06-22	40129	更新依赖项
0.5.3	2024-06-06	39225	［autopull］将基础镜像升级到 v1.2.2
0.5.2	2024-06-02	38851	至少每流发送一次状态消息
0.5.1	2024-04-11	35404	添加 `row_batch_size` 参数以更精细地控制读取记录
0.5.0	2024-03-26	36515	解决 poetry 依赖冲突，将记录计数添加到状态消息
0.4.0	2024-03-19	36267	将 airbyte-cdk 版本固定到 `^0`
0.3.17	2024-02-29	35722	添加逻辑以发出流状态
0.3.16	2024-02-12	35136	修复 `pyproject.toml` 中的许可证。
0.3.15	2024-02-07	34944	使用 Poetry 管理依赖项。
0.3.14	2024-01-23	34437	修复标题单元格过滤
0.3.13	2024-01-19	34376	修复名称转换
0.3.12	2023-12-14	33414	为 airbyte-lib 准备
0.3.11	2023-10-19	31599	基础镜像迁移：移除 Dockerfile 并使用 python-connector-base 镜像
0.3.10	2023-09-27	30487	修复由于速率限制而导致增加批处理大小时跳过行的问题。
0.3.9	2023-09-25	30749	性能测试 - 在 docker 镜像中包含 socat 二进制文件
0.3.8	2023-09-25	30747	性能测试 - 在 docker 镜像中包含 socat 二进制文件
0.3.7	2023-08-25	29826	删除规范中的行批处理大小，并在出现速率限制时添加自动增加此值
0.3.6	2023-08-16	29491	更新到最新的 CDK
0.3.5	2023-08-16	29427	在出现 429 错误时添加停止读取
0.3.4	2023-05-15	29453	更新规范描述
0.3.3	2023-08-10	29327	添加用户友好的错误消息，用于在发现期间出现 404 和 403 错误
0.3.2	2023-08-09	29246	添加检查，在读取时跳过已修改的工作表
0.3.1	2023-07-06	28033	修复了多个报告的漏洞（共 25 个），CVE-2022-37434、CVE-2022-42898
0.3.0	2023-06-26	27738	许可证更新：Elv2
0.2.39	2023-05-31	26833	删除 authSpecification，转而使用 advancedAuth 在规范中
0.2.38	2023-05-16	26097	重构配置错误
0.2.37	2023-02-21	23292	跳过非网格工作表。
0.2.36	2023-02-21	23272	优雅地处理空工作表。
0.2.35	2023-02-23	23057	规范化列名称
0.2.34	2023-02-15	23071	将最小电子表格 ID 大小更改为 20 个字符
0.2.33	2023-02-13	23278	处理身份验证错误
0.2.32	2023-02-13	22884	不要使用 http 电子表格。
0.2.31	2022-10-09	19574	撤销“将 row_id 添加到行并用作主键”
0.2.30	2022-10-09	19215	将 row_id 添加到行并用作主键
0.2.21	2022-10-04	15591	清理 AirbyteStream 的实例化
0.2.20	2022-10-10	17766	修复解析电子表格 ID 时的空指针异常。
0.2.19	2022-09-29	17410	使用最新的 CDK。
0.2.18	2022-09-28	17326	迁移到每个流的状态。
0.2.17	2022-08-03	15107	在连接器规范中公开行批处理大小
0.2.16	2022-07-07	13729	改进配置字段描述
0.2.15	2022-06-02	13446	重试导致服务器错误请求
0.2.13	2022-05-06	12685	更新 CDK 到 v0.1.56，以便在出现未捕获异常时发出 `AirbyeTraceMessage`
0.2.12	2022-04-20	12230	更新连接器以使用 `spec.yaml`
0.2.11	2022-04-13	11977	将剩余的打印语句替换为 airbyte 日志记录器
0.2.10	2022-03-25	11404	允许使用电子表格链接/URL 代替电子表格 ID
0.2.9	2022-01-25	9208	更新标题和描述
0.2.7	2021-09-27	8470	迁移到 CDK
0.2.6	2021-09-27	6354	支持通过 Oauth webflow 连接
0.2.5	2021-09-12	5972	通过添加受支持的同步模式到 Stream 初始化来修复 full_refresh 测试
0.2.4	2021-08-05	5233	修复仅包含图表的表格列表时的错误
0.2.3	2021-06-09	3973	为 Kubernetes 支持添加 AIRBYTE_ENTRYPOINT
0.2.2	2021-04-20	2994	格式规范
0.2.1	2021-04-03	2726	修复基础连接器版本控制
0.2.0	2021-03-09	2238	协议允许未来/未知的属性
0.1.7	2021-01-21	1762	修复大型电子表格问题
0.1.6	2021-01-27	1668	采用连接器最佳实践
0.1.5	2020-12-30	1438	实现退避机制
0.1.4	2020-11-30	1046	添加使用索引 YAML 文件的连接器

先决条件​

设置指南​

步骤 1：设置 Google Sheets​

设置服务帐户密钥​

创建服务帐户​

生成密钥​

启用 Google Sheets API​

在 Airbyte 中设置 Google Sheets 连接器​

对于 Airbyte Cloud：​

对于 Airbyte 开源：​

配置选项​

流名称覆盖（重命名工作表/流名称）​

工作原理​

示例​

如何配置​

Google Sheets 连接器列名称转换​

1. 将列名称转换为符合 SQL 规范的格式​

2. 其他转换选项​

其他详细信息​

标题去重​

工作原理​

示例​

支持的同步模式​

支持的流​

数据类型映射​

限制和故障排除​

连接器限制​

速率限制​

故障排除​

参考​

配置字段参考

变更日志​

先决条件

设置指南

步骤 1：设置 Google Sheets

设置服务帐户密钥

创建服务帐户

生成密钥

启用 Google Sheets API

在 Airbyte 中设置 Google Sheets 连接器

对于 Airbyte Cloud：

对于 Airbyte 开源：

配置选项

流名称覆盖（重命名工作表/流名称）

工作原理

示例

如何配置

Google Sheets 连接器列名称转换

1. 将列名称转换为符合 SQL 规范的格式

2. 其他转换选项

其他详细信息

标题去重

工作原理

示例

支持的同步模式

支持的流

数据类型映射

限制和故障排除

连接器限制

速率限制

故障排除

参考

变更日志