元数据查询 API
本页接口均以 METADATA_BASE_URL=https://<host>/metadata 为 Base 地址；应用系统辅助接口使用 BASE_BASE_URL=https://<host>/base。
适用于数据门户、开发平台和数据字典同步：先定位应用系统及数据源，再检索对象并读取详情、字段和历史。以下列出完整服务路径。
核心接口
| 方法与路径 | 用途 | 关键输入 |
|---|---|---|
POST /base/modelCategory/getModelCategories | 获取应用系统 | 无 Body 要求；返回数组，使用 categoryId、categoryName |
POST /base/modelCategory/getModelCategoryById | 查询指定应用系统 | Query：categoryId（Long，必填） |
POST /metadata/models/fromre/page | 分页查询采集数据源 | Body：categoryId（Long）、modelName、currentPage、pageSize；Query：showLogicalModel（Boolean，默认 false） |
GET /metadata/models/{modelId}/schemas | 查询数据源的 Schema | Path：modelId（Long，必填）；返回字符串数组 |
POST /metadata/entities/searchMetadata | 按范围查询表、字段等对象 | Body：modelIds、schemas、types、keyword、currentPage、pageSize |
GET /metadata/entities/{objectId}/get | 获取对象定义 | Path：objectId（Long，必填） |
GET /metadata/entities/{objectId}/columns | 获取表的字段定义 | Path：表 objectId（Long）；Query 可用 keyword |
GET /metadata/entities/{objectId}/history | 查询对象变化版本 | Path：objectId（Long，必填） |
POST /metadata/dataReport/search | 分页查询报表 | Body：keyword、path（String 数组）、currentPage、pageSize |
GET /metadata/dataReport/{dataReportId} | 查询报表定义及关联信息 | Path：dataReportId（Long，必填） |
搜索条件
modelIds 是 Long 数组；schemas 是 String 数组；types 是对象类型数组，常用值包括 TABLE、COLUMN、VIEW、STORED_PROCEDURE、FUNCTION。文件、API 及元模型还涉及 SHARE_FILE、API、META_MODEL 和 typeIds；应按目标元模型的实际类型定义传入，不能把所有自定义对象都当作关系表。
{
"currentPage": 1,
"pageSize": 20,
"modelIds": [1001],
"schemas": ["demo_sales"],
"types": ["TABLE", "VIEW"],
"keyword": "customer"
}1001 和 demo_sales 是虚构范围，必须替换。响应包含 totalItems、currentPage、pageSize 和 content。每条搜索记录包含 id、name、type、definition、path 等字段，使用 id 继续查询对象详情。不要用显示名称作为跨系统唯一键。
对象和字段的主要返回字段
| 返回字段 | 用途 |
|---|---|
objectId、modelId、schema、typeId | 确认来源、粒度和类型 |
physicalName、logicalName、definition | 物理名称、业务名称和说明 |
domains、standardCodes、tags | 关联标准、标准代码和标签，实际返回视对象而定 |
owner、udps、properties | 负责人、扩展属性及技术属性 |
字段的 type、notNull、defaultValue、ordinal | 数据类型、非空、默认值和位置 |
字段精度在当前 Schema 中拼作 percision，适配时保留实际字段名，不擅自改成 precision。历史返回包含 version、createTime、changeHistory 以及来源信息，用于发现结构或语义变化，不等于源数据库数据变更日志。
根据来源选择查询路径
- 数据源逆向得到的表、字段、过程和函数从数据集对象查询；元模型实例按其实际类型查询。
- DDM 物理/逻辑数据字典和 DDL 文件被逆向后，查询形成的表字段元数据；不按文件附件检索这些结构。
- 文件存储服务器采集的文件才按文件对象处理。
- BI 采集报表和自定义报表统一走报表查询。报表返回可包含
relatedTable、path和url，保留实际来源与关联标识。
采集及查询口径详见元数据管理。元数据详情、资产目录详情和业务数据样例是不同接口。本指南不把 /entities/data/sample 作为默认集成调用。
场景：同步企业数据字典
- 获取应用系统和授权数据源，建立外部系统标识与
categoryId、modelId的映射。 - 按数据源、Schema 和对象类型分页检索，读取对象详情和字段。
- 保存对象标识、业务语义、技术属性、标准关联和同步时间。
- 后续按对象历史及本地快照比对变化；如果接口未提供适用的增量游标，采用受控分页扫描及差异比较。
- 对本轮未返回的对象，先排除权限变化、采集失败和分页不完整，再判断是否下线。
实际对接仍需用客户自己的对象做样本验收，并记录目标部署的分页、权限和错误结构。
采集任务：创建、调度和执行
采集任务是元数据从数据源进入 DAM 的控制面。数据源创建与任务调度分开管理：创建数据源不会替代任务配置，任务执行前还要确认账号权限、插件和 Schema 范围。
| 方法与路径 | 用途 | 关键输入 |
|---|---|---|
POST /metadata/jobs/createJob | 创建采集或同步任务 | DatablauJobDescriptor：name、typeName、boundResourceId、boundResourceType、runCycle、schedule、parameters、disabled、@class |
POST /metadata/jobs/startJob | 立即启动任务 | Query 使用定义中的 任务ID（Long），Body 为任务参数字符串；调用前确认网关是否保留中文参数名 |
POST /metadata/jobs/stopJob | 停止运行中的任务 | 任务标识及参数格式同目标定义 |
POST /metadata/jobs/enableJob / disableJob | 启用或停用计划任务 | 任务标识 |
POST /metadata/jobs/rescheduleJob | 修改调度 | Query 使用定义中的 任务ID，Body 为调度参数 |
POST /metadata/jobs/query/jobs/byDto | 按条件查询任务 | name、type、status、resourceId、jobId、runCycle、创建者和时间范围等 |
POST /metadata/jobs/query/jobResults/byCriteria | 查询执行结果 | 任务、实例、状态和时间条件 |
POST /metadata/jobs/query/jobEvents/byCriteria | 查询执行事件 | 任务实例、事件类型和时间条件 |
POST /metadata/simplejobs/status | 查询简单任务状态 | Query：jobId（Long） |
创建任务的最小结构示例（标识为占位符）：
{
"name": "metadata-sync-demo",
"typeName": "META_DATA_SYNC",
"boundResourceId": 1001,
"boundResourceType": "MODEL",
"runCycle": "CRON",
"schedule": "0 0 2 * * ?",
"parameters": {},
"disabled": false,
"@class": "com.datablau.job.dto.DatablauJobDescriptor"
}@class、typeName、调度表达式和任务 ID 参数名属于当前接口契约的敏感部分，升级或网关转换后必须重新从 Swagger 确认。启动超时后先查询实例和结果，再决定是否重试，避免重复采集。
模型比对与 DDM 协作
DDM 设计模型可作为目标结构，DAM 采集到的数据库元数据作为基线。典型流程是：将数据库结构逆向到 DDM → 在 DDM 修改逻辑名称、描述或结构 → 执行比对 → 审核差异 → 将获批结果更新回 DAM 或数据库。
| 方法与路径 | 用途 |
|---|---|
GET /metadata/models/{modelId}/compareMappings | 查询可用的模型映射 |
GET /metadata/models/{modelId}/{modelVersionId}/compareResult/{mappingId}/{ddmModelId}/{ddmModelVersionId} | 获取指定 DDM 版本与采集模型的差异 |
GET /metadata/models/{modelId}/{modelVersionId}/compareResultFile/{mappingId}/{ddmModelId}/{ddmModelVersionId} | 导出比对结果文件 |
GET /metadata/models/{modelId}/{mappingId}/compareResultHistory | 查询历史比对记录 |
POST /metadata/models/{modelId}/{modelVersionId}/updateCompareResultFile | 按审核后的比对文件更新结果 |
POST /metadata/models/model/{baseModelId}/compare/{targetModelId} | 比较两个模型 |
POST /metadata/models/model/{baseModelId}/compare/{targetModelId}/download | 下载模型比对报告 |
比对接口只产生差异和更新依据，不代替 DDM 的审批和发布流程。正式同步前保存模型版本、映射关系、差异报告和回滚快照。
受控更新与批量语义维护
当治理结果需要回写 DAM 时，可评估以下接口。它们会改变元数据或生成导出任务，必须先在测试范围确认权限、字段覆盖规则和失败处理，再用于批量集成。
| 方法与路径 | 关键契约 | 使用注意 |
|---|---|---|
PUT /metadata/entities/{dataObjectId}/summary | Path：dataObjectId（Long）；JSON Body 为 DataObjectDto，定义明确要求“修改的完整对象” | 适用于经确认的对象语义维护；不能当作只传 logicalName 的局部 PATCH |
POST /metadata/models/{modelId}/exportAsync | Path：modelId；Query 可用 tableIds、tagIds（String）、isSimple；JSON Body 为 DataObjectExportDto，含 schemas 等范围 | 返回 String，需确认实际任务标识及下载结果流程，不能当作已下载 Excel |
POST /metadata/models/{modelId}/updateMetadata/{ignoreError} | Path：modelId（Long）、ignoreError（Boolean）；请求含二进制 file | 使用同环境导出的模板维护逻辑名称、描述、标签及标准关联，具体可更新列以模板为准 |
更新单个对象时，先读取当前完整对象并保存更新前快照，再修改获准字段，按接口要求提交并回读校验。详情中的 writable 可用于提示当前状态，但实际写权限仍由服务端判断。不得用空对象或省略字段试探覆盖语义；并发修改前重新读取并核对差异。
批量维护建议沿用“导出—补全—导入—检查结果”的业务流程，保留对象标识、模板列和失败行。ignoreError 的实际部分成功策略需要联调，不能简单解释为保证整批原子提交。
当前导入定义将二进制文件声明在 application/json 中，和常见文件上传媒体类型不一致；异步导出/导入的响应也只声明 String，未完整给出后续状态与下载关联。正式集成前应由服务方确认实际上传方式、任务体系和结果下载接口，不提供猜测的可执行上传命令。没有确认 API 契约时，可先按元数据批量维护在产品页面完成该操作。