二、支持的能力
| 能力 | 支持情况 | 说明 |
| 数据源版本 | 不涉及 | 托管服务，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 | 任务级配置项，详见 任务参数说明 |
完整数据源能力对照参见 支持的数据源与读取能力。
三、支持的文件格式
| 格式 | 说明 |
| TXT | 文这篇件，需声明字段名与字段类型 |
| CSV | 逗号分隔文件，支持自定义字段分隔符 |
| JSON | 按 key 解析为字段，嵌套结构按 JSON 字符串整体保留 |
| Parquet | 列式存储格式，自动解析文件自带 schema |
| ORC | 优化行列存储格式，自动解析文件自带 schema |
四、使用限制
| 限制项 | 说明 |
| 链路方向 | 当前仅支持作为来源端读取，不支持作为目标端写入 |
| 认证方式 | 仅支持 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；不支持 ${} | 否 | — |
注意：说明：
十六、最佳实践
| 实践 | 建议 |
| 密钥最小化 | 使用 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、文件是否被压缩且压缩格式选择正确、对象的存储类型是否为尚未解冻的归档存储。
20、Q：任务报「路径下无文件」或「文件不存在」？
A：周期调度中源端目录暂时为空属常见情况。在该任务的 S3 读取节点高级参数中添加 ignoreDirEmpty=TRUE、ignoreFileNotFound=TRUE 即可跳过；文件传输模式下需同步空文件时追加 transEmpFile=TRUE。
21、Q：增量同步后目标端出现重复数据？
A：增量以文件为粒度筛选，文件被覆盖重写后会整体重新同步。建议源端按日期分区写入、不做原地覆盖，并在目标端按分区做幂等处理。
22、Q：源端删除的文件，目标端为什么没有被删除？
A：增量同步不感知文件删除，源端删除不会触发目标端删除。如需同步删除，请在目标端自行维护清理逻辑。
23、Q：读取性能不佳或任务内存溢出？
A：优先检查文件路径是否使用了通配符、单目录下文件数是否过多，建议改为精确分区路径并将大目录拆分为多个任务；同时避免配置多个行分隔符与不必要的 Quote character。
24、相关文档
·添加数据源连接
·数据源连通性测试
·支持的数据源与读取能力