配置 MaxCompute 数据源
MaxCompute 数据源用于通过离线同步读取阿里云 MaxCompute 中的表数据,并写入平台预置仓。本文介绍连接配置、来源 Schema 与分区、字段映射、支持的字段类型,以及同步验证和任务流调度。
使用限制与准备事项
开始配置前,请确认以下事项:
- MaxCompute 仅支持作为数据来源,数据去向为平台预置仓,不支持通过本方案回写 MaxCompute 或直接写入其他外部数据源。
- 准备 MaxCompute 项目的 End Point、项目名称,以及用于接入的 Access Key Id 和 Access Key Secret。
- 接入账号需有权访问该项目、查看表及其元数据,并读取要同步的表或分区。由项目管理员按实际读取范围授予权限,参见 MaxCompute 权限说明。
- 读取自定义 Schema 下的表前,请确认源端 Project 已支持 Schema,并为接入账号授予相应 Schema 及表的访问权限。源端准备方式参见 MaxCompute Schema 操作。
- 若项目启用了下载权限控制,还需按项目要求授予相应的 Tunnel 下载权限,参见 下载权限控制。
- 平台运行环境需能访问所配置的 MaxCompute 服务地址。若项目设置了 IP 白名单,请核对平台服务器的实际出口 IP。
- 提前准备预置仓中的目标表,并核对字段类型和分区定义。创建方式参见 空间表的创建与管理。
| 环境配置方式 | 配置要求 |
|---|---|
| 不区分环境 | 开发环境与生产环境共用一套项目及凭据配置 |
| 独立环境配置 | 分别配置开发环境与生产环境;两套配置均需能够访问方案所选的同名 Schema、表和分区 |
数据预览使用开发环境配置,手动执行使用生产环境配置。请分别核对两套配置的项目、表权限和网络访问。
MaxCompute 的对象层级为 Project > Schema > Table。Project 在数据源连接中配置,Schema 和表在同步方案中选择。同一个 Project 下,不同 Schema 可以有同名表,请结合 Schema 确认读取对象。传统二层 Project 在平台中通过逻辑 default 选择原有表;选择 default 不会将该 Project 升级为支持自定义 Schema 的项目。
请通过安全方式交接 Access Key Secret,避免在截图、日志或公开文档中暴露凭据。更换凭据或调整项目权限后,应重新验证数据源连接及同步方案。
创建 MaxCompute 数据源
- 进入 数据开发平台 > 集成 > 数据源,点击 + 数据源。
- 选择 MaxCompute,点击 下一步,填写数据源名称和备注。
- 选择 不区分环境 或 独立环境配置。独立环境配置需分别填写开发环境和生产环境的信息。
- 填写以下连接参数。在 连通性测试 中点击 测试,确认测试通过后,点击 完成。
| 配置项 | 说明 |
|---|---|
| End Point | MaxCompute 项目所在区域对应的服务地址,请向项目管理员确认 |
| Access Key Id | 接入账号的 AccessKey ID |
| Access Key Secret | 与 AccessKey ID 对应的 AccessKey Secret |
| 项目名称 | 本次读取的 MaxCompute Project 名称,需与接入账号的访问权限一致;此处不填写 Schema 或表名 |
| 高级配置 | 按需填写 JSON 格式的扩展配置;没有额外配置要求时可留空 |
连通性测试通过后,还需在同步方案中加载来源表、预览数据并执行验证,确认表权限、分区范围和实际读取结果。
同一数据源可用于读取该 Project 下有权限访问的不同 Schema;在每个同步方案的 来源表 中分别选择,无需为每个 Schema 重建数据源。
配置 MaxCompute 数据来源
- 进入 数据开发平台 > 集成 > 离线同步,点击 + 集成方案。
- 在 数据来源 中选择 MaxCompute 和已创建的数据源。
- 在 来源表 左侧选择 Schema,再在右侧选择该 Schema 下的数据表。新建方案时,即使只有一个
default,也需先手动选择 Schema。 - 如果来源表为分区表,填写 分区信息 中各分区字段的值。分区值可使用空间参数,不支持通配符;参数说明参见 参数管理。
- 点击 数据预览,核对当前 Schema 下来源表的字段、实际值和读取范围。
- 如需调整批量条数,展开 高级配置 进行设置。
Schema 与表名分别选择。例如,读取 project_a.ods.events 时,数据源中的项目名称为 project_a,来源 Schema 选择 ods,数据表选择 events;不要将完整限定名称填入表名。
| 配置项 | 说明 |
|---|---|
| 数据源名称 | 已在当前空间创建的 MaxCompute 数据源 |
| Schema | 本次读取的 Schema;传统二层 Project 选择 default。如需读取其他 Project,请先核对数据源连接配置及权限 |
| 数据表名称 | 所选 Schema 下的数据表;列表显示表名,分区表带有相应标记 |
| 分区信息 | 来源为分区表时填写各分区值;使用空间参数时,需确认执行时的参数值对应实际存在的分区 |
| 批量条数 | 高级配置项,界面默认值为 1000,可设置范围为 1000–10000 |
切换 Schema 后,原来源表会被清空;切换 Schema 或表时,原分区配置及来源字段映射也会清空。请重新选择表、填写分区并解析字段,核对预览结果和映射。同名表在不同 Schema 下的字段可能不同,不能直接沿用原映射。
来源表新增、删除或修改字段后,也需重新解析并检查映射。编辑已有方案时,请核对回显的 Schema、表及分区,再保存修改。
配置数据去向
在 数据去向 中选择平台 预置仓,再选择目标空间表。若目标表尚未创建,请先前往 库表 按所需字段和分区定义创建,参见 空间表的创建与管理。
| 配置项 | 说明 |
|---|---|
| 目标表 | 接收本次数据的预置仓空间表 |
| 分区信息 | 目标为分区表时,按目标表要求配置分区值;来源分区与目标分区需分别核对 |
| 写入模式 | 选择 插入新数据 或 覆盖写入;界面默认选择覆盖写入,请根据目标数据的保留要求调整 |
执行前,请再次确认目标表、目标分区和写入模式,避免覆盖需要保留的数据。来源表与目标表的字段名可以不同,但需通过字段映射明确对应关系。
字段映射与支持的字段类型
完成来源和去向配置后,在 字段映射 中建立源字段与目标字段的对应关系。可以逐项选择,也可以使用 同名映射 或 同行映射 后逐项核对;一个目标字段只能对应一个来源字段。
映射以当前选定 Schema 和表解析出的字段为准。切换 Schema 或表后,请重新解析字段并建立映射,再核对字段是否受支持。
图中展示的是已有方案的字段对应关系,不表示已通过实时连通性或本次执行验证。
支持的字段类型
MaxCompute 作为数据来源时,支持以下字段类型。字段类型名称不区分大小写,带参数或嵌套结构的字段还需核对完整定义。
| 类型类别 | 支持的 MaxCompute 字段类型 |
|---|---|
| 布尔 | BOOLEAN |
| 整数 | TINYINT、SMALLINT、INT、BIGINT |
| 浮点与定点数 | FLOAT、DOUBLE、DECIMAL |
| 字符串与 JSON | STRING、VARCHAR、CHAR、JSON |
| 日期时间 | DATE、TIMESTAMP、TIMESTAMP_NTZ、DATETIME |
| 复杂类型 | ARRAY、MAP、STRUCT,需核对完整结构 |
不支持 BINARY 及其他未识别的类型。本方案仅支持从 MaxCompute 读取数据,不提供写入 MaxCompute 的字段类型范围。
字段类型使用限制
DECIMAL(p,s)、VARCHAR(n)、CHAR(n)需核对完整精度、小数位数和长度要求。- 日期时间字段需核对实际时间含义、时区及精度要求,不能仅凭基础类型受支持判断结果符合预期。
ARRAY<T>、MAP<K,V>、STRUCT<...>需核对完整元素、键值或字段定义及空值约束;顶层类型受支持不表示任意嵌套结构或元素类型均受支持。- Schema 和分区用于确定读取对象与范围,不改变字段类型的支持条件。来源表结构变化后,请重新解析字段并核对字段对应关系。
- 数据预览能够显示字段,不等于该字段类型已支持同步。请在保存后执行验证,并核对目标表中的实际结果。
同步验证与任务流调度
保存并验证同步结果
- 检查来源 Project、Schema、表和分区,以及目标表和分区、写入模式及字段映射。
- 填写方案名称、负责人和备注,点击 保存。
- 点击 手动执行,按弹窗要求选择执行模式,并核对本次执行的参数值后开始执行。手动执行使用生产环境配置;执行模式不用于切换开发环境与生产环境。
- 在 手动执行记录 中查看执行状态和日志。任务成功后,到目标表核对数据量、字段对应关系,以及数值、时间、复杂类型和空值等样例。
独立环境配置下,开发阶段可以正常加载或预览数据,不代表生产环境凭据和读取权限也已具备。首次执行前,请分别核对两套配置及对应 Project 中的 Schema、表、分区和参数。
挂载到任务流
手动验证通过后,可将方案挂载到任务流,按调度周期执行。
- 打开已保存的方案,点击 挂载到任务流,选择目标任务流;尚未创建时,参见 创建任务流。
- 填写节点名、执行模式、负责人等信息,点击 创建节点并挂载。
- 点击 前往任务流,检查节点及上下游依赖,核对调度所用的来源分区和空间参数。
- 完成 任务流调度设置,保存并 发布任务流。挂载成功不等于节点已经发布上线。
方案挂载到任务流后,不再通过方案详情页手动执行,请从任务流中执行和验证该节点。
常见问题
| 现象 | 检查项 |
|---|---|
| 连通性测试失败 | 核对 End Point、项目名称、AccessKey 及平台服务器的网络访问和 IP 白名单 |
| 连接通过,但 Schema 列表为空或加载失败 | 核对源端 Project 的 Schema 支持状态、账号权限及网络访问;列表加载失败时可刷新重试,不应将失败视为只需选择 default |
| 选定 Schema 后找不到来源表或无法预览 | 确认表位于当前 Schema,核对账号的项目成员身份、Schema、表及元数据读取权限;项目启用下载控制时,还需核对相应下载权限 |
| 同名表的字段或数据与预期不符 | 核对数据源中的 Project 和方案中的 Schema,重新选表、解析字段并检查映射 |
| 分区读取失败或没有数据 | 检查分区是否存在、各分区值是否完整,以及空间参数解析后的实际值 |
| 预览正常,但执行失败 | 核对生产环境配置及其 Project 下是否存在同名 Schema、表和分区,再核对凭据、权限、目标表和参数,并查看本次执行日志 |

