概述
Amazon S3（Simple Storage Service）是 AWS 提供的对象存储服务，适用于存放任意类型的数据文件。DataBuddy 数据接入支持将 Amazon S3 作为来源端，读取其中的文件做离线同步。本文介绍 Amazon S3 数据源的连接配置、能力支持范围、任务配置参数与常见问题。
支持的能力
能力 | 支持情况 | 说明 |
数据源版本 | 不涉及 | 托管服务，REST API 仅有唯一版本，创建数据源时无需选择版本 |
离线同步（读 / 写） | ✓ / - | 支持读取桶内文件作为离线同步任务的源端；DataBuddy 数据源仅支持接入读取，不支持写入 |
实时同步（读 / 写） | - / - | 不支持以 Amazon S3 作为实时同步任务的数据端 |
直连分析（读 / 写） | - / - | 不支持通过直连分析查询 Amazon S3 |
认证方式 | Access Key ID / Secret Access Key | 仅支持静态密钥，不支持临时安全凭据（Session Token）与 IAM Role 认证 |
支持的文件格式 | TXT / CSV / JSON / Parquet / ORC | |
支持的压缩格式 | none / deflate / gzip / bzip2 / lz4 / snappy |
支持的文件格式
使用限制
限制项 | 说明 |
链路方向 | 当前仅支持作为来源端读取，不支持作为目标端写入 |
认证方式 | 仅支持 Access Key ID / Secret Access Key（静态密钥），不支持临时安全凭据（Session Token）与 IAM Role 认证 |
传输协议 | 强制 HTTPS，不提供 HTTP 选项；Endpoint 填写 http:// 或缺省协议时会自动校正为 https:// |
增量语义 | 增量以文件为粒度，不感知文件内的行级新增、更新、删除，也不感知文件删除 |
文件定位 | 文件路径须包含桶名（ s3a://bucket_name/path/），不支持对象目录树浏览与文件采样预览 |
存储类型 | 归档存储、深度归档存储类型的对象需先解冻后才能读取 |
Schema 一致性 | 同一任务读取的所有文件视为同一张逻辑表，须适配同一套 schema；schema 不一致的记录进入脏数据处理链路 |
前提条件
获取访问密钥
在 AWS 控制台 IAM 中创建用户并生成 Access Key ID 与 Secret Access Key，为该用户授予目标桶的
s3:GetObject 与 s3:ListBucket 权限。建议使用 IAM 子用户密钥并遵循最小权限原则，仅授予任务所需桶与前缀的读取权限，避免使用根账号密钥。网络与环境准备
确认 DataBuddy 执行资源与 Amazon S3 的服务端点之间网络连通；跨公网读取时请评估链路稳定性与流量成本。
待读取对象的存储类型为标准存储；归档存储与深度归档存储需先完成解冻。
创建数据源的步骤
1. 登录 DataBuddy 控制台。
2. 在顶部切换到目标地域和 Workspace。
3. 进入 数据集成 > 数据源管理（或 平台管理 > 数据源管理）。
4. 点击 添加数据源，选择 Amazon S3。
5. 填写连接配置与认证信息，详见 数据源配置。
6. 点击 连通性测试（参见 数据源连通性测试）。
7. 测试通过后点击保存或保存 & 创建任务。
支持的配置列表及详细说明
数据源配置
以下为数据源级配置，作用于引用该连接的所有任务。
参数 | 说明 | 是否必填 | 默认值 |
数据源名称 | 数据源在工作空间内的唯一标识 | 是 | — |
描述 | 数据源的用途说明，便于团队协作识别 | 否 | — |
Endpoint | S3 服务端点，如 https://s3.us-east-1.amazonaws.com；必须为 https:// 前缀，输入 http:// 或缺省协议时自动校正；支持填写 S3 兼容存储的端点 | 是 | — |
Region | 桶所在地域，如 us-east-1；由 Endpoint 自动推断并回填，允许手工修改 | 是 | 由 Endpoint 推断 |
Access Key ID | AWS 访问密钥 ID | 是 | — |
Secret Access Key | AWS 访问密钥，加密存储，保存后不再展示明文 | 是 | — |
凭据托管 | 开启后从凭据管理系统获取密钥，需凭据处于生效状态 | 否 | 关闭 |
存储桶 Bucket | 默认存储桶；任务级文件路径可指定其他桶，需同一凭据具备对应权限 | 是 | — |
数据源权限 | 项目共享 / 仅个人和管理员 | 是 | 项目共享 |
网络方式 | 公网 / 私网，复用现有网络通道与资源组 | 是 | 公网 |
编辑数据源时，除数据源名称与所属项目外均可编辑，密钥字段需重新输入。
任务配置
以下为任务级配置，仅作用于当前任务的 S3 读取节点。配置链路：选择连接 → 同步范围 → 同步方式 → 文件路径 → 文件类型 → 格式参数 → 字段配置 → 高级参数。
同步范围
模式 | 行为 |
全量 | 同步文件路径下的所有文件，无状态、可重复运行 |
增量 | 同步文件路径下「上周期计划调度时间 ~ 本周期计划调度时间」之间更新的文件，按对象的最后修改时间（Last Modified）比对 |
可选值：
全量 / 增量，默认 全量。增量的生效约束：
同步范围仅对目录形式的文件路径生效；路径指向具体文件时不生效，按该文件同步。
调试运行时，增量退化为同步路径下的所有文件。
时间口径以 S3 对象的最后修改时间为准，统一按 UTC 比对后换算到调度时区。
说明：
增量以文件为粒度，不感知文件内的行级变更，也不感知文件删除。若文件被覆盖重写，该文件会整体重新同步，可能产生重复数据，建议配合按日期分区的目录结构使用。
增量时间窗口配置
选择增量同步后，可在文件路径下配置增量时间窗口：
参数 | 说明 | 是否必填 | 默认值 |
增量开始时间 | 时间窗口起点，仅筛选最后修改时间 ≥ 该时间的文件 | 是 | 上周期计划调度时间 |
增量结束时间 | 时间窗口终点，仅筛选最后修改时间 < 该时间的文件 | 是 | 本周期计划调度时间 |
支持填写调度时间参数，格式为
${yyyyMMddHHmmss} 或 ${yyyy-MM-dd HH:mm:ss}。缺省取值即为「上周期计划调度时间 ~ 本周期计划调度时间」，无需手工填写。
时间与 S3 对象的最后修改时间（Last Modified）比对时，统一按 UTC 口径换算。
同步方式
模式 | 行为 |
数据同步 | 解析结构化文件内容，按字段映射写入目标端，需配置文件类型与格式参数 |
文件传输 | 不解析文件内容，整体搬迁文件，可用于非结构化数据 |
可选值：
数据同步 / 文件传输，默认 数据同步。选择文件传输时，格式参数与字段配置不再展示。任务参数说明
参数 | 说明 | 是否必填 | 默认值 |
数据连接 | 已配置的 Amazon S3 数据源，展示连接名称与 Endpoint、桶摘要 | 是 | — |
文件路径 | 须包含桶名，如 s3a://bucket_name/path/；支持 * 通配符；支持递归读取子目录 | 是 | — |
文件类型 | TXT / CSV / JSON / ORC / PARQUET | 是 | TXT |
字段分隔符 | 仅 TXT、CSV 在数据同步模式下可见；不支持 ${} | 条件必填 | , |
行分隔符 | 仅 TXT、CSV 在数据同步模式下可见；最多配置 3 个；不填时按运行环境默认（Linux \\n，Windows \\r\\n）；不支持 ${} | 否 | — |
编码 | utf8 / gbk | 是 | utf8 |
压缩格式 | none / deflate / gzip / bzip2 / lz4 / snappy | 是 | none |
Quote character | 无配置 / 双引号 " / 单引号 '，将引号内内容作为完整值读取 | 否 | 无配置 |
跳过表头 | 是否跳过文件首行；勾选后可从首行表头自动生成字段名 | 是 | 否 |
空值转换 | 读取时将指定字符串转为 NULL；不支持 ${} | 否 | — |
说明：
文件路径中使用通配符会在列举对象时带来额外的性能与内存开销，建议优先使用精确的分区目录路径，或将大目录按分区拆分为多个任务。
字段分隔符不支持
${}，因为 ${a} 会被识别为调度参数。最佳实践
实践 | 建议 |
密钥最小化 | 使用 IAM 子用户密钥，仅授予目标桶与前缀的 s3:GetObject、s3:ListBucket 权限 |
目录规划 | 按日期分区组织目录，配合增量同步缩小每次扫描范围 |
路径写法 | 优先使用精确的分区目录路径，减少通配符使用；大规模目录（十万级以上文件）按分区拆分为多个任务 |
格式校验 | 通过调试运行验证分隔符、编码、表头、Quote character 等参数是否符合预期 |
空分区处理 | 周期调度中出现空分区目录时，配置 ignoreDirEmpty=TRUE、ignoreFileNotFound=TRUE 跳过 |
网络打通 | 确保执行资源与 S3 端点网络连通，跨公网场景评估链路稳定性与流量成本 |
常见问题
Q：认证失败（Access Denied）？
A：检查 Access Key ID 与 Secret Access Key 是否正确，并确认该密钥具备目标桶的
s3:GetObject、s3:ListBucket 权限；同时确认 Region 与桶实际所在地域一致。Q：读取不到文件？
A：依次确认：文件路径是否包含桶名（
s3a://bucket_name/...）、前缀是否匹配对象 Key、文件是否被压缩且压缩格式选择正确、对象的存储类型是否为尚未解冻的归档存储。Q：任务报「路径下无文件」或「文件不存在」？
A：周期调度中源端目录暂时为空属常见情况。在该任务的 S3 读取节点高级参数中添加
ignoreDirEmpty=TRUE、ignoreFileNotFound=TRUE 即可跳过；文件传输模式下需同步空文件时追加 transEmpFile=TRUE。Q：增量同步后目标端出现重复数据？
A：增量以文件为粒度筛选，文件被覆盖重写后会整体重新同步。建议源端按日期分区写入、不做原地覆盖，并在目标端按分区做幂等处理。
Q：源端删除的文件，目标端为什么没有被删除？
A：增量同步不感知文件删除，源端删除不会触发目标端删除。如需同步删除，请在目标端自行维护清理逻辑。
Q：读取性能不佳或任务内存溢出？
A：优先检查文件路径是否使用了通配符、单目录下文件数是否过多，建议改为精确分区路径并将大目录拆分为多个任务；同时避免配置多个行分隔符与不必要的 Quote character。
