预策数据魔方

本文档说明 Open Insight 标准对象从预策哪些接口获取。当前预策连接器以 pull 为主，接口统一通过 YuceClient 访问，PAT/personkey 认证头使用 X-Access-Token。

登录授权

Open Insight 通过 Personal Access Key 访问预策数据魔方。可以通过以下两种方式获取。

方式一：在页面中直接获取

访问预策数据魔方的 Personal Access Token 页面：

https://xxx.yyy.com/#/personal-access-token

将 https://xxx.yyy.com 替换为所在环境的预策数据魔方地址，然后在页面中创建并复制 Personal Access Key。此方式适用于当前部署版本提供该页面的用户。

方式二：通过接口手动获取

如果当前版本没有 Personal Access Token 页面，可以使用已登录会话中的 YCSESSIONID 创建 Personal Access Key：

登录并访问预策数据魔方首页。
打开浏览器开发者工具，进入 应用（Application）→ Cookie → 当前站点域名，找到并复制 YCSESSIONID 的值。
在本地命令行中执行以下请求，将地址和 YCSESSIONID 替换为所在环境的真实值：

curl -X POST 'https://{预策数据魔方地址}/api/personalAccessToken/create?tokenName=CLI&expireDays=365' \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -b 'YCSESSIONID={YCSESSIONID}'

例如：

curl -X POST 'https://xxxxx.yyyy.com/api/personalAccessToken/create?tokenName=cli&expireDays=365' \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -b 'YCSESSIONID=xxxxx'

从接口返回内容中获取 tokenValue

请求成功后，返回内容中的 tokenValue 即为 Personal Access Key。

授权信息安全

YCSESSIONID 和 Personal Access Key 都属于敏感授权信息。推荐在自己的本地命令行中执行请求，不要将真实值粘贴到聊天、文档或日志中；让 Codex 代为执行可能使授权信息经过代码执行中转环境。若信息意外泄露，请尽快撤销或更换。

接口总览

标准对象	Pull 范围	主要预策接口	补充预策接口	说明
`Cluster`	所有 pull	无	无	预策连接器按约定自动创建默认集群，`engineType=starrocks`。
`Table`	`table` / `all`	`POST /asset/retrieveAssets`	`POST /worktable/loadWorkTableDetail`、`POST /worktable/getAllFields`	从资产检索接口分页发现工作表，再拉取工作表详情和字段列表。
`Task`	`task` / `all`	`POST /etlScheduleTaskApi/pageTaskInfo`	`POST /lineage/getLineageDag`	从调度任务分页接口获取任务名称、负责人、调度周期、状态和任务模板信息；上游血缘内联到 `lineage`。
`User`	实时查询	`GET /user/getAllUserNames`	无	分页获取用户，映射为 `user list` 输出。
`Baseline`	实时查询	`POST /pageBaselineInfo`	无	分页获取基线定义，映射为 `baseline list` 输出。
`Dashboard`	实时查询	`GET /site/listReportForm`	`POST /reportForm/loadFormByFormId`、`POST /reportForm/queryFormCards`	通过 `dashboard list/get` 实时读取远端最新仪表盘信息，不写入 `source/`。
`Chart`	实时查询	`POST /reportForm/queryFormCards`	`POST /reportFormItem/getItemById` / `POST /reportFormItem/getCardData`	通过 `chart list/get/query` 实时读取远端最新图表信息和数据，不写入 `source/`。

user list、dashboard list/get、chart list/get/query、subject list/get 和 permission get 是实时查询能力，不属于标准对象 pull，也不写入 cache.yaml 或 source/。

对象明细

Cluster

Cluster 表示预策背后的默认计算引擎。当前不通过预策接口拉取，而是由连接器自动生成：

kind: Cluster
id: cluster.yuce.default
systemId: system.yuce
engineType: starrocks
extensions:
  yuce:
    nodeId: ""

cluster query 通过 POST /analysis/previewDynamicSqlData 执行 SQL。请求体包含：

{
  "dynamicParameterList": [],
  "sql": "select * from fxxb0507"
}

连接器使用 FINANCE_MASTER 应用版本，dynamicParameterList 固定传空数组，SQL 中直接使用表名。响应中的 data.fields 用于生成列名，data.rows[].columns 用于生成结果行。

Table

Table 表示预策工作表。

接口链路：

POST /asset/retrieveAssets
- 参数包含 retrieveType=WORKTABLE、page、size、queryWord。
- 用于分页发现工作表。
- 当前从列表项读取 objectId、tableId 或 id 作为远端表 id。
POST /worktable/loadWorkTableDetail
- 参数包含 tableId。
- 用于获取表名、展示名、负责人、来源类型、资产节点等详情。
POST /worktable/getAllFields
- 参数包含 tableId。
- 用于获取字段列表，映射为标准对象的 columns。
POST /lineage/getLineageDag
- table lineage <node_id> 实时查询数据血缘。
- 参数固定包含 expandType=UP_STREAM、graphType=DATA_LINEAGE、maxLevel（默认 3）、nodeId。
- 默认输出完整 JSON；--format table 会输出 lineageNodes 与 dependencies 两张完整表格。

关键字段映射：

标准字段	预策字段来源
`id`	`{kind}.yuce.{safeToken(remoteId)}` 标准化生成（见 `helpers.objectId`）
`remoteId`	列表项 `objectId`、`tableId`、`id`（取首个非空值）
`title`	详情 `aliasTableName`、`tableAliasName`、`displayName`；兜底列表项 `aliasTableName`、`displayName`、`tableName`、`name`
`owner`	`ownerName`、`creatorName`、`assetNodeVO.ownerName`、`assetNodeVO.creatorName`
`clusterId`	固定写入 `cluster.yuce.default`
`table`	`tableName`、`name`
`tableType`	固定 `table`
`columns[].name`	`fieldName`、`name`、`columnName`、`fieldId`
`columns[].type`	`fieldType`、`type`、`dataType`
`columns[].nullable`	`nullable`
`columns[].description`	`description`、`comment`、`fieldDesc`
`extensions.yuce.sourceType`	`tableSourceTypeEnum`、`sourceType`、`source_type`
`extensions.yuce.assetClass`	`assetClass`
`extensions.yuce.sourceName`	`sourceName`、`source_name`

Task

Task 表示预策调度任务。

接口链路：

POST /etlScheduleTaskApi/pageTaskInfo
- 参数包含 taskName、pageIndex、pageSize。
- 用于分页获取调度任务。
POST /lineage/getLineageDag
- 参数包含 expandType=UPDOWN_STREAM、graphType=TASK、maxLevel、nodeId（等于 taskCode）。
- 用于获取上游血缘，内联写入 lineage。
POST /lineage/getLineageDag
- task lineage <task_id> 实时查询上下游任务血缘。
- 参数固定包含 expandType=UPDOWN_STREAM、graphType=TASK、maxLevel（默认 3）、nodeId（等于 task_id）。
- 默认输出完整 JSON；--format table 会输出 lineageNodes 与 dependencies 两张完整表格。

关键字段映射：

标准字段	预策字段来源
`id`	`{kind}.yuce.{safeToken(remoteId)}` 标准化生成（见 `helpers.objectId`）
`remoteId`	`taskCode`、`task_code`、`id`
`title`	`taskName`、`task_name`
`owner`	`ownerName`、`owner`、`createUser`
`schedule`	`schedulePeriod`、`period`
`status`	`taskStatus`、`status`
`templateCode`	`taskTemplateCode`
`templateName`	`taskTemplateName`
`inputs`	从 `dependencies[].parentNodes` 解析出的上游 `nodeId`，标准化为 `task.yuce.{safeToken(nodeId)}`
`lineage.maxLevel`	pull 参数 `maxLevel`（默认 `1`）
`lineage.upstreamTaskCodes`	从 `dependencies[].parentNodes` 沿父节点图解析
`lineage.lineageNodes`	`POST /lineage/getLineageDag` 返回的 `lineageNodes`
`lineage.dependencies`	`POST /lineage/getLineageDag` 返回的 `dependencies`
`lineage.groups`	`POST /lineage/getLineageDag` 返回的 `groups`
`extensions.yuce.taskCode`	`taskCode`
`extensions.yuce.rawStatus`	`taskStatus`、`status`

User

User 表示预策用户账号。

接口链路：

GET /user/getAllUserNames
- 查询参数包含 page、pageSize。
- 用于分页获取用户。

关键字段映射：

标准字段	预策字段来源
`id`	`user.yuce.{safeToken(remoteId)}` 标准化生成
`remoteId`	`userId`、`user_id`、`id`、`username`、`userName`、字符串记录本身
`title`	`realName`、`nickName`、`displayName`、`userName`、`username`、字符串记录本身
`username`	`username`、`userName`、`name`、字符串记录本身
`name`	`name`
`displayName`	`displayName`、`realName`、`nickName`、`userName`
`email`	`email`、`mail`
`department`	`departmentName`、`department`、`deptName`、`dept`
`status`	`status`、`userStatus`、`enabled`
`extensions.yuce.userId`	标准化前的 `remoteId`
`extensions.yuce.username`	标准化后的 `username`

Baseline

Baseline 表示预策基线定义。

接口链路：

POST /pageBaselineInfo
- 参数包含 current、pageSize。
- 用于分页获取基线列表。

关键字段映射：

标准字段	预策字段来源
`id`	`{kind}.yuce.{safeToken(remoteId)}` 标准化生成（见 `helpers.objectId`）
`remoteId`	`baselineId`、`baseline_id`、`id`、`baselineCode`
`title`	`baselineName`、`baseline_name`、`name`、`title`
`owner`	`ownerName`、`owner`、`createUser`、`creatorName`
`status`	`baselineStatus`、`status`、`baselineStatusType`
`promiseTime`	`promiseTime`、`promise_time`、`targetTime`、`baselineTime`
`taskIds`	`taskCodes`、`taskCodeList`、`relatedTaskCodes`、`taskList` 中的任务编码，标准化为 `task.yuce.{safeToken(taskCode)}`
`extensions.yuce.baselineId`	`baselineId`
`extensions.yuce.taskCodes`	原始任务编码列表

BaselineInstance

BaselineInstance 表示某业务日期下的基线运行实例。不通过本地缓存同步，也不写入本地缓存；openinsight baseline-instance list --date 每次直接查询远端。

接口链路：

POST /pageBaselineInstanceInfo
- 参数包含 current、pageSize、baselineDate、baselineStatusTypeList、completed。
- 用于分页获取指定日期的基线实例。
GET /listBaselineInstanceRelatedTaskInstance
- 查询参数包含 baselineInstanceId。
- 用于获取基线实例关联的调度实例，内联写入 taskInstances。

关键字段映射：

标准字段	预策字段来源
`id`	`baseline-instance.yuce.{safeToken(remoteId)}`
`remoteId`	`baselineInstanceId`、`baseline_instance_id`、`id`、`instanceId`
`title`	`baselineName`、`baseline_name`、`name`、`title`
`baselineId`	`baselineId`、`baseline_id`、`baselineCode`，标准化为 `baseline.yuce.{safeToken(baselineId)}`
`baselineDate`	CLI `--date` 参数
`status`	`baselineStatusType`、`baselineStatus`、`status`
`completed`	`completed`
`promiseTime`	`promiseTime`、`promise_time`、`targetTime`
`actualTime`	`actualTime`、`actual_time`、`finishTime`、`endTime`
`taskInstances`	`GET /listBaselineInstanceRelatedTaskInstance` 返回记录列表
`extensions.yuce.baselineInstanceId`	`baselineInstanceId`
`extensions.yuce.baselineRemoteId`	`baselineId`

Dashboard

Dashboard 表示预策仪表盘。

site get <site_id> 会调用 GET /site/getSite?siteId=<site_id> 读取站点信息和节点树，并递归遍历 siteNodeTreeBO.childList 中 nodeType=2 的节点。每个节点的 nodeContent 会作为仪表盘远端 id 继续查询仪表盘详情，最终在返回 JSON 的 dashboards 字段中保留节点路径、节点 id 和仪表盘详情。

接口链路：

GET /site/listReportForm
- 参数包含 size=2000、keyWord=。
- 用于发现仪表盘列表；如果返回数量达到 2000，会打印结果可能不完整的警告并继续。
POST /reportForm/loadFormByFormId
- 参数包含 formId。
- 用于获取仪表盘详情。
POST /reportForm/queryFormCards
- 参数包含 formId。
- 用于获取仪表盘内卡片列表，并映射为标准对象的 charts 引用。

关键字段映射：

标准字段	预策字段来源
`id`	`{kind}.yuce.{safeToken(remoteId)}` 标准化生成（见 `helpers.objectId`）
`remoteId`	`reportFormId`、`formId`、`dashboardId`、`id`
`title`	详情 `name`、`formName`、`title`；兜底列表 `name`、`formName`、`title`、`reportFormName`
`owner`	`ownerName`、`owner`、`createUser`
`charts`	卡片 `id`、`itemId`、`cardId` 标准化为 `chart.yuce.{safeToken(cardId)}`
`extensions.yuce.siteId`	`siteId`
`extensions.yuce.siteName`	`siteName`、`siteTitle`

Chart

Chart 表示预策仪表盘中的图表卡片。

接口链路：

GET /site/listReportForm
POST /reportForm/queryFormCards
- 前两个接口用于发现所有仪表盘和仪表盘卡片。
POST /reportFormItem/getItemById
- 参数包含 itemId 和 formId。
- 用于获取图表完整配置。当前不会额外传入 version=WORKING。

关键字段映射：

标准字段	预策字段来源
`id`	`{kind}.yuce.{safeToken(remoteId)}` 标准化生成（见 `helpers.objectId`）
`remoteId`	卡片 `id`、`itemId`、`cardId`
`title`	`name`、`itemName`、`cardName`、`title`
`dashboardId`	所属仪表盘 `formId` 标准化为 `dashboard.yuce.{safeToken(formId)}`
`chartType`	`chartType`、`chart_type`，兜底 `cardType`、`itemType`、`type`
`query.sql`	`sqlText`、`sqlContent`、`sql`、`finalSql`、`customSql`、`sqlTemplate`、`placeholderSql`、`sql_text`、`sql_template`
`datasetId`	`srcCollectionId`、`collectionId`、`collection_id`；非 `-1` 时映射为 `dataset.yuce.{safeToken(collectionId)}`
`dimensions`	`dimensions` 中的 `name`、`fieldName`、`fieldId`、`fieldType`、`fieldAlias`、`expression` 等字段标准化为对象数组
`measures`	`metrics`、`measures`，或 `cardDataConfigList[].cardDataConfigElement.fieldConfigList` 中的指标字段标准化为对象数组
`measures[].comparison`	指标字段 `contrastInfo`，用于保留日环比、周同比、月同比、年同比等配置
`measures[].proportion`	指标字段 `proportionCalculateParam`，用于保留列占比、行占比等配置
`measures[].format`	指标字段 `numberFormatConfig`
`filters`	`queryConditionList`、`queryConditions`、`filterConditions`、`conditions` 标准化为对象数组
`extensions.yuce.cardType`	`cardType`、`itemType`、`type`
`extensions.yuce.collectionId`	`srcCollectionId`、`collectionId`、`collection_id`
`extensions.yuce.dashboardRemoteId`	所属仪表盘远端 id
`extensions.yuce.siteId`	所属站点 id

Permission

Permission 查询不映射为本地标准对象，只通过 openinsight permission get 实时读取预策权限接口，并原样输出 JSON。

接口链路：

GET /centralizedAuthorization/getShieldResourceInfo
- --scope function：resourceType=PLATFORM_PERMISSION。
- --scope data：resourceType=DATA。
- --scope dashboard：resourceType=CUBE_SITE_PERMISSION。
- 查询参数包含 authId=<user-id>、authType=<auth-type>。
POST /centralizedAuthorization/getBenchResourceSubNodes
- --scope data-resource 使用该接口。
- 请求体包含 authObjectId=<user-id>、authTargetType=<auth-type>，并固定传 parentId=uaKymyLsPI、resourceShareType=PUBLIC、shieldQueryType=PUBLIC_RESOURCE。

示例：

openinsight permission get --scope function --user-id 0795386429996234
openinsight permission get --scope data-resource --user-id 0795386429996234
openinsight permission get --scope data --user-id 0795386429996234
openinsight permission get --scope dashboard --user-id 0795386429996234

Subject

Subject（指标中心-分析主体）查询不映射为本地标准对象，只通过 openinsight subject list/get 实时读取预策指标中心-分析主体接口。

接口链路：

GET /objectTypeApi/v2/listObjectTypes
- openinsight subject list 使用该接口，输出指标中心-分析主体清单表格。
GET /objectTypeApi/use/v2/loadObjectTypeProperties
- openinsight subject get <object_type_rid> 使用该接口查询属性。
- 查询参数包含 objectTypeRid=<object_type_rid>。
GET /ontologyObjectTypeRelationshipApi/getObjectTypeRelationships
- openinsight subject get <object_type_rid> 使用该接口查询关系。
- 查询参数包含 objectTypeRid=<object_type_rid>。

示例：

openinsight subject list
openinsight subject get Br8I2dsv4F

暂未通过预策接口拉取的标准对象

标准对象	当前状态
`Cluster`	由连接器约定生成默认对象，不从预策业务接口拉取。
`Dataset`	当前没有独立预策 dataset pull。`Chart.datasetId` 仅根据图表配置中的 collection id 生成引用。

Pull 输出位置

标准对象	输出目录
`Cluster`	`source/clusters/*.cluster.yaml`
`Table`	`source/tables/*.table.yaml`
`Task`	`source/tasks/*.task.yaml`
`User`	不写入本地文件，由 `user list` 实时查询
`Baseline`	不写入本地文件，由 `baseline list` 实时查询
`BaselineInstance`	不写入本地文件，由 `baseline-instance list --date` 实时查询
`Dashboard`	不写入本地文件，由 `dashboard list/get` 实时查询
`Chart`	不写入本地文件，由 `chart list/get/query` 实时查询
`Subject`	不写入本地文件，由 `subject list/get` 实时查询

除实时查询对象外，其他对象仅在启用 --save-raw 时写入相同目录下的 *.raw.json。

登录授权​

方式一：在页面中直接获取​

方式二：通过接口手动获取​

接口总览​

对象明细​

Cluster​

Table​

Task​

User​

Baseline​

BaselineInstance​

Dashboard​

Chart​

Permission​

Subject​

暂未通过预策接口拉取的标准对象​

Pull 输出位置​

登录授权

方式一：在页面中直接获取

方式二：通过接口手动获取

接口总览

对象明细

Cluster

Table

Task

User

Baseline

BaselineInstance

Dashboard

Chart

Permission

Subject

暂未通过预策接口拉取的标准对象

Pull 输出位置