主题
目录
资源说明
目录定义
目录是衡石系统内为方便用户管理应用及应用下的资源而设定的系统功能，展示为树形结构，通过该功能可实现业务区域划分、资源与资源使用权限的集中管理
目录结构说明
| 字段 | 类型 | 描述 |
|---|---|---|
| id | BIGINT | 目录id |
| title | STRING | 目录标题 |
| parentId | BIGINT | 父目录id |
| area | STRING | 目录所在区域: PERSONAL_AREA 、PUBLIC_AREA 、 DATA_MART 、 APP_MART、SUBJECT_AREA |
| options | OBJECT | 目录配置信息 |
| options.rootType | STRING | 区域级根节点的类型: PUBLIC_ROOT_FOLDER 、PERSONAL_ROOT_FOLDER |
| options.childrenOrder | ARRAY | 子目录排序 |
| options.appOrder | ARRAY | 目录内应用排序 |
| updatedAt | DATETIME | 目录最后更新时间 |
| updatedBy | DATETIME | 目录最后修改者的userId |
| createdAt | DATETIME | 目录创建时间 |
| updatedBy | DATETIME | 目录最后修改者的userId |
| tenantId | LONG | 租户id |
| idPath | ARRAY | 路径id |
区域说明
| 状态值 | 意义 |
|---|---|
| PERSONAL_AREA | 个人区，用户私有(3.0版本未实现目录功能) |
| PUBLIC_AREA | 共享区，该区域属于系统公有区域，所有被赋予目录权限的系统内用户均可管理/编辑/读取 |
| DATA_MART | 数据集市，与共享区性质相同，区别在于该区域目录下的应用内，只能创建数据集，供其他区域使用 |
| APP_MART | 应用集市-个人空间,即发布区(3.0版本未实现目录功能) |
| SYSTEM_PORTAL | 应用集市-团队空间,即发布区(3.0版本未实现目录功能) |
| SUBJECT_AREA | 主题域,它是数据集市里管理指标的区域 |
目录/应用授权说明
| 状态值 | 意义 |
|---|---|
| read | 查看者：可查看目录/应用及目录下的资源 |
| read|write | 编辑者：拥有目录的编辑者权限时,可在目录下创建、查看、修改目录/应用 |
| admin|read|write | 管理者：除拥有编辑者权限外，还可管理目录/应用为其他用户赋予/删除权限 |
| admin|read\ | 租户使用者：平台方授权资源给租户时的角色，可管理目录/应用为租户内其他用户赋予权限 |
目录权限说明
- 四个公用目录区: DATA_MART,PUBLIC_AREA,SYSTEM_PORTAL,SUBJECT_AREA存在超管用户，超管用户用有该区域内所有资源的所有权限，其角色分别为: DATA_MART(系统管理+数据管理) ,PUBLIC_AREA(系统管理+数据管理),SYSTEM_PORTAL(系统管理+数据分析),SUBJECT_AREA(系统管理+指标管理)
- 普通用户的权限范围：若用户拥有某目录的某项权限，则同时拥有该目录下子目录与资源的对应权限，以最大权限为准
接口说明
创建目录
- 创建者需要同时拥有
数据管理员和系统管理员角色 或 拥有上层任意父目录的编辑者权限 - 区域根目录由系统默认生成，因此用户创建的目录
parent_id不可为空
请求URL
http
POST /api/folders HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...请求参数
Request Body 参数
| 字段 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
| title | STRING | 是 | 目录名称 |
| parentId | BIGINT | 是 | 父目录id |
返回对象的格式说明
| 字段 | 类型 | 说明 |
|---|---|---|
| version | STRING | 当前系统版本哈希值 |
| data | OBJECT | 每种目录的共同结构见目录结构说明。 |
接口示例1: 创建目录
http
POST /api/folders HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...
// Request Body:
{
"title": "test",
"parentId": 1
}http
HTTP/1.1 200 Ok
Content-Type: application/json
{
"version": "version@9a5e106#6730f0d",
"code": 0,
"msg": "success",
"data": {
"id": 2,
"parentId": 1,
"title": "test",
"createdBy": 1,
"createdAt": "2019-12-08 23:35:54",
"updatedBy": 1,
"updatedAt": "2019-12-08 23:35:54",
"area": "PUBLIC_AREA"
}
}修改(移动)目录
- 修改者需要同时拥有
数据管理员和系统管理员角色 或 拥有上层任意父目录的编辑者权限 - 移动目录需遵循以下规则:
1、区域根目录不可移动 2、目录不可跨区域移动 3、移动目录需要用户同时拥有被移动目录和目标目录的
编辑者权限 4、若移动目录需要保留权限配置,则用户需拥有目标目录的管理者权限
请求URL
http
PUT /api/folders/{folderId} HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...请求参数
Request Body 参数
| 字段 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
| title | STRING | 否 | 目录名称 |
| parentId | BIGINT | 否 | 父目录id(移动操作时表示目标目录id) |
| keepAuthConfig | BOOL | 否 | 是否保留权限配置(默认为true) |
返回对象的格式说明
| 字段 | 类型 | 说明 |
|---|---|---|
| version | STRING | 当前系统版本哈希值 |
| data | OBJECT | 每种目录的共同结构见目录结构说明。 |
接口示例1: 修改/移动目录
http
PUT /api/folders/{folderId} HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...
// Request Body:
{
"title": "test",
"parentId": 3,
"keepAuthConfig":false
}http
HTTP/1.1 200 Ok
Content-Type: application/json
{
"version": "version@9a5e106#6730f0d",
"code": 0,
"msg": "success",
"data": {
"id": 2,
"parentId": 3,
"title": "test",
"createdBy": 1,
"createdAt": "2019-12-08 23:35:54",
"updatedBy": 1,
"updatedAt": "2019-12-08 23:35:54",
"area": "PUBLIC_AREA"
}
}删除目录
- 修改者需要同时拥有
数据管理员和系统管理员角色 或 拥有上层任意父目录的编辑者权限 - 区域根目录不可删除
- 为防止误操作，只能删除空目录(目录下无子目录或应用)
请求URL
http
DELETE /api/folders/{folderId} HTTP/1.1
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...请求参数
无
返回对象的格式说明
| 字段 | 类型 | 说明 |
|---|---|---|
| version | STRING | 当前系统版本哈希值 |
| data | OBJECT | 每种目录的共同结构见目录结构说明。 |
接口示例1: 删除目录
http
DELETE /api/folders/{folderId}` HTTP/1.1http
HTTP/1.1 200 Ok
Content-Type: application/json
{
"version": "version@9a5e106#6730f0d",
"code": 0,
"msg": "success"
}根据id获取目录
- 修改者需要同时拥有
数据管理员和系统管理员角色 或 拥有上层任意父目录的查看者权限 - 返回值中包含被查询目录下一级的子目录和app(children/apps),以及被查询目录所有父目录的id和title(parents)
请求URL
http
GET /api/folders/{folderId} HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...请求参数
无
返回对象的格式说明
| 字段 | 类型 | 说明 |
|---|---|---|
| version | STRING | 当前系统版本哈希值 |
| data | OBJECT | 每种目录的共同结构见目录结构说明。 |
接口示例1: 根据id获取目录
http
GET /api/folders/{folderId}` HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...http
HTTP/1.1 200 Ok
Content-Type: application/json
{
"version": "version@9a5e106#6730f0d",
"code": 0,
"msg": "success",
"data": {
"id": 3,
"parentId": 2,
"title": "b",
"options": {},
"createdBy": 1,
"createdAt": "2019-12-01 21:24:24",
"updatedBy": 3,
"updatedAt": "2019-12-04 18:15:18",
"visible": true,
"children": [
{"id":4,"title":"c"},
{"id":5,"title":"d"}
],
"parents": [
{"id":1,"title":"root"}
{"id":2,"title":"a"}
]
"area": "PUBLIC_AREA",
"apps": [
{
"id": 2,
"title": "app2",
"cover": "",
"options": {},
"createdBy": 1,
"createdAt": "2019-12-01 21:08:36",
"updatedBy": 1,
"updatedAt": "2019-12-01 21:08:36",
"visible": true,
"isDelete": false,
"isPublish": false,
"hsVersion": 0,
"publicPublish": false,
"publish": false
}
],
"delete": false
}
}获取目录列表
- 修改者需要同时拥有
数据管理员和系统管理员角色 或 拥有上层任意父目录的查看者权限 - 返回结果为当前用户在指定区域，有权限查看的所有目录的树形结构，并包含各目录下的应用
- 同时拥有
数据管理员和系统管理员角色的用户，可看到指定区域下的所有目录信息
请求URL
http
GET /api/folders HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...请求参数
URL 参数
| 字段 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
| area | STRING | 否 | 指定查询区域,默认为 PUBLIC_AREA |
| targetAppId | LONG | 否 | 查询可见数据源时传递的当前appId |
| orderBy | STRING | 否 | 排序字段，默认为updated_at |
| orderType | STRING | 否 | 排序方式，默认为desc |
| action | STRING | 否 | 查询当前用户拥有特定权限的目录，如:read |
| targetFolderCreatorId | LONG | 否 | 查询特定用户创建的目录，仅在PERSONAL_AREA可用 |
| needDetails | LONG | 否 | 是否需要查询目录的详细信息 |
| queryAppTree | BOOL | 否 | 是否要查询目录下的应用信息,默认为 true |
| needAppChildren | BOOL | 否 | 是否需要查询应用内的子对象：仪表盘,容器,图表,数据集，默认为 true （queryAppTree = true 时生效） |
| queryDataset | BOOL | 否 | 是否需要返回应用内的数据集，默认为 true （queryAppTree != false 与 needAppChildren = true 时生效） |
| queryDashboard | BOOL | 否 | 是否需要返回应用内的仪表盘，默认为 true （queryAppTree != false 与 needAppChildren = true 时生效） |
| queryChart | BOOL | 否 | 是否需要返回应用内的图表，默认为 false （queryAppTree != false 与 needAppChildren = true 与 queryDashboard = true 时生效） |
| onlyApps | BOOL | 否 | 是否仅返回应用信息以及应用下子对象的列表，默认为 false （queryAppTree = true 时生效） |
返回对象的格式说明
| 字段 | 类型 | 说明 |
|---|---|---|
| version | STRING | 当前系统版本哈希值 |
| data | OBJECT | 每种目录的共同结构见目录结构说明。 |
接口示例1: 仅获取应用信息列表
http
GET /api/folders?area=PERSONAL_AREA&queryAppTree=true&queryChart=true&needDetails=false&needAppChildren=true&queryDataset=true&queryDashboard=true&onlyApps=true HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...http
HTTP/1.1 200 Ok
Content-Type: application/json
{
"version": "5.3-SNAPSHOT@@git.commit.id.abbrev@#993daa9",
"code": 0,
"msg": "success",
"data": [
{
"id": 89,
"title": "分析应用20240403120002",
"createdBy": 2,
"folderId": 0,
"area": "PERSONAL_AREA",
"type": "ANALYTIC_APP",
"isCollaborated": false,
"dashboardHash": [
{
"id": 1
}
],
"action": "read|admin|write",
"authRole": "ADMINISTRATOR",
"dashboardList": [
{
"id": 1,
"title": "新建仪表盘20240403120019",
"appId": 89,
"charts": [
{
"id": 2,
"title": "新建探索",
"appId": 89
}
]
}
],
"datasetList": [
{
"id": 1,
"title": "china_map_area",
"appId": 89
}
],
"refreshEntityGroup": "APP_REFRESH",
"refreshExecDetail": {
"jobClass": "com.hengshi.nangaparbat.schedulejob.AppDatasetRefreshJob",
"jobParams": {
"app": 89
},
"retryTimes": 1
},
"execDetail": {
"jobClass": "com.hengshi.nangaparbat.schedulejob.AppEmailJob",
"jobParams": {
"app": 89
},
"retryTimes": 1
},
"entityGroup": "APP_EMAIL",
"entityKey": "89"
}
],
"chartDataStartTimeMillis": 0
}接口示例2: 获取目录与应用
http
GET /api/folders?area=PERSONAL_AREA&queryAppTree=true&queryChart=true&needAppChildren=true&onlyApps=false HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...http
HTTP/1.1 200 Ok
Content-Type: application/json
{
"version": "5.3-SNAPSHOT@@git.commit.id.abbrev@#993daa9",
"code": 0,
"msg": "success",
"data": [
{
"id": 0,
"title": "personal_area_root_folder",
"area": "PERSONAL_AREA",
"children": [
{
"id": 47,
"parentId": 0,
"title": "仪表盘复制",
"createdBy": 2,
"area": "PERSONAL_AREA",
"idPath": [
0
],
"children": [],
"apps": [
{
"id": 330,
"title": "查询应用 -个人区",
"createdBy": 2,
"folderId": 47,
"area": "PERSONAL_AREA",
"type": "QUERY_APP",
"isCollaborated": false,
"dashboardHash": [
{
"id": 6
},
{
"id": 5
},
{
"id": 2
}
],
"action": "read|admin|write",
"authRole": "ADMINISTRATOR",
"dashboardList": [
{
"id": 6,
"title": "页面C(1)",
"appId": 330
}
],
"datasetList": [],
"refreshEntityGroup": "APP_REFRESH",
"refreshExecDetail": {
"jobClass": "com.hengshi.nangaparbat.schedulejob.AppDatasetRefreshJob",
"jobParams": {
"app": 330
},
"retryTimes": 1
},
"execDetail": {
"jobClass": "com.hengshi.nangaparbat.schedulejob.AppEmailJob",
"jobParams": {
"app": 330
},
"retryTimes": 1
},
"entityGroup": "APP_EMAIL",
"entityKey": "330"
}
]
}
],
"action": "read|admin|write",
"authRole": "ADMINISTRATOR",
"isCollaborated": false
}
],
"chartDataStartTimeMillis": 0
}接口示例3: 仅获取目录信息
http
GET /api/folders?area=PERSONAL_AREA&queryAppTree=false&queryChart=true&needAppChildren=true HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...http
HTTP/1.1 200 Ok
Content-Type: application/json
{
"version": "5.3-SNAPSHOT@@git.commit.id.abbrev@#993daa9",
"code": 0,
"msg": "success",
"data": [
{
"id": 0,
"title": "personal_area_root_folder",
"area": "PERSONAL_AREA",
"children": [
{
"id": 31,
"parentId": 0,
"title": "json array",
"createdBy": 2,
"area": "PERSONAL_AREA",
"idPath": [
0
],
"children": [
{
"id": 34,
"parentId": 31,
"title": "array folder1",
"createdBy": 2,
"area": "PERSONAL_AREA",
"idPath": [
0,
31
],
"children": [
{
"id": 35,
"parentId": 34,
"title": "array folder2",
"createdBy": 2,
"area": "PERSONAL_AREA",
"idPath": [
0,
31,
34
],
"children": [],
"apps": [],
"action": "read|admin|write",
"authRole": "ADMINISTRATOR",
"isCollaborated": true
}
],
"apps": [],
"action": "read|admin|write",
"authRole": "ADMINISTRATOR",
"isCollaborated": true
}
],
"apps": [],
"action": "read|admin|write",
"authRole": "ADMINISTRATOR",
"isCollaborated": false
},
{
"id": 26,
"parentId": 0,
"title": "性能测试",
"createdBy": 2,
"area": "PERSONAL_AREA",
"idPath": [
0
],
"children": [],
"apps": [],
"action": "read|admin|write",
"authRole": "ADMINISTRATOR",
"isCollaborated": false
},
{
"id": 19,
"parentId": 0,
"title": "外面1",
"createdBy": 2,
"area": "PERSONAL_AREA",
"idPath": [
0
],
"children": [
{
"id": 20,
"parentId": 19,
"title": "外面2",
"createdBy": 2,
"area": "PERSONAL_AREA",
"idPath": [
0,
19
],
"children": [],
"apps": [],
"action": "read|admin|write",
"authRole": "ADMINISTRATOR",
"isCollaborated": true
}
],
"apps": [],
"action": "read|admin|write",
"authRole": "ADMINISTRATOR",
"isCollaborated": false
}
],
"apps": [],
"action": "read|admin|write",
"authRole": "ADMINISTRATOR",
"isCollaborated": false
}
],
"chartDataStartTimeMillis": 0
}查询指定文件夹下的应用
查询用户指定的文件夹下的应用列表。
请求URL
http
GET /api/folders/{folderId}/apps HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...请求参数
URL 参数
| 字段 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
| recursive | BOOL | 否 | 是否递归到子文件夹，默认是 false，需要递归到子文件夹，需要设置为 true |
| orderBy | String | 否 | 排序字段，默认为updated_at，字段名采用下划线命名规则 |
| orderType | String | 否 | 排序规则，默认是 desc；需要升序，需要设置为 asc |
| queryDataset | BOOL | 否 | 是否需要返回应用内的数据集，默认为 true |
| queryDashboard | BOOL | 否 | 是否需要返回应用内的仪表盘，默认为 true |
| queryChart | BOOL | 否 | 是否需要返回应用内的图表，默认为 false |
| portalViewFirst | BOOL | 否 | 门户视图的应用只返回门户，默认为 true |
返回对象的格式说明
接口示例1
http
GET http://localhost:9981/api/folders/2/apps?recursive=true&orderBy=last_accessed_at&orderType=asc&portalViewFirst=true HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...http
HTTP/1.1 200 Ok
Content-Type: application/json
{
"version": "6.0-SNAPSHOT@f5180d2#0178b43",
"code": 0,
"msg": "success",
"data": [
{
"id": 504,
"title": "使用like过滤",
"cover": "",
"options": {
"dashboardsOrder": [
1,
2
],
"publishConfig": {
"zoomInPermitted": false,
"showDetailPermitted": false,
"downloadPermitted": false,
"augmentedAnalysisPermitted": false,
"publishTitle": "使用like过滤",
"publisher": "trial",
"totalPages": {},
"duplicatedPermitted": false,
"publisherDisplayConfig": {
"id": 2,
"type": "user",
"name": "trial"
},
"targetFolderId": 2,
"foldersTitle": [
"公共空间"
],
"displayPublisher": true,
"gradientColor": [
"#BED0F4",
"#4E6CA2"
],
"defaultView": "dashboard"
},
"enableAppRule": false,
"enableRuleStrictValidate": true,
"dataAppDetails": [],
"enableDataAppAllocate": true,
"availableDataApps": [],
"tenantConfig": {},
"resultCacheInterval": 3600
},
"createdBy": 2,
"createdAt": "2024-09-27 11:56:31",
"updatedBy": 2,
"updatedAt": "2024-09-27 11:56:40",
"visible": true,
"isDelete": false,
"isPublish": true,
"isBackup": false,
"publishHash": "EB6A701E7FCADE74D3AAE9EBAF091D2F1",
"publishedBy": 490,
"folderId": 2,
"area": "SYSTEM_PORTAL",
"dataMode": "APP_MODE",
"type": "ANALYTIC_APP",
"publishState": false,
"hideDatasets": [],
"defaultDataset": 12,
"status": "RUNNING",
"dashboardHash": [
{
"id": 2,
"hash": "EB2FF36CF25005311F67339595B8751D9"
},
{
"id": 1,
"hash": "EA28F8DB6E55268EACA9438FC7DA59CFA"
}
],
"action": "read|admin",
"authRole": "TENANT",
"dashboardList": [
{
"id": 2,
"title": "新建仪表盘20240924183337",
"appId": 504,
"chartIds": [
2
],
"hash": "EB2FF36CF25005311F67339595B8751D9",
"updatedAt": "2024-09-27 11:56:32"
},
{
"id": 1,
"title": "新建仪表盘20240923141255",
"appId": 504,
"chartIds": [
1
],
"hash": "EA28F8DB6E55268EACA9438FC7DA59CFA",
"updatedAt": "2024-09-27 11:56:32"
}
],
"datasetList": [
{
"id": 12,
"title": "hello",
"appId": 504
},
{
"id": 11,
"title": "advancedcal2",
"appId": 504
}
]
}
]
}根据ID触发业务指标主题下的业务指标分词向量化
触发后任务在执行记录中可以查看进度和日志。
请求URL
http
GET /api/folders/{subjectId}/tokenize HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...请求参数
URL 参数
| 字段 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
| subjectId | INTEGER | 是 | 业务指标主题的 id |
返回对象的格式说明
| 字段 | 类型 | 说明 |
|---|---|---|
| version | STRING | 当前系统版本哈希值 |
参考示例
http
GET /api/folders/5132/tokenize HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...http
HTTP/1.1 200 Ok
Content-Type: application/json
{
"version": "version@9a5e106#6730f0d",
"code": 0,
"msg": "success"
}