@easyv/screen-cli 0.0.0-stage → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +283 -2
- package/bin/easyv-screen.js +2 -0
- package/dist/analyzer.js +130 -0
- package/dist/client.js +168 -0
- package/dist/commands/auth.js +285 -0
- package/dist/commands/component.js +197 -0
- package/dist/commands/data.js +147 -0
- package/dist/commands/debug.js +31 -0
- package/dist/commands/screen.js +199 -0
- package/dist/commands/skills.js +53 -0
- package/dist/config.js +421 -0
- package/dist/debug-query.js +224 -0
- package/dist/index.js +25 -0
- package/dist/output.js +7 -0
- package/package.json +36 -4
- package/skills/easyv-component-dev/SKILL.md +50 -0
- package/skills/easyv-component-dev/references/component-spec.md +123 -0
- package/skills/easyv-screen-build/SKILL.md +40 -0
- package/skills/easyv-screen-data/SKILL.md +53 -0
- package/skills/easyv-screen-debug/SKILL.md +49 -0
- package/skills/easyv-screen-edit/SKILL.md +59 -0
- package/skills/easyv-screen-shared/SKILL.md +32 -0
- package/spec/openapi.v1.yaml +2850 -0
|
@@ -0,0 +1,2850 @@
|
|
|
1
|
+
openapi: 3.1.0
|
|
2
|
+
|
|
3
|
+
info:
|
|
4
|
+
title: EasyV 大屏 OpenAPI
|
|
5
|
+
version: 1.0.0
|
|
6
|
+
description: |
|
|
7
|
+
面向集成方与自动化调用的大屏接口,路径前缀 `/api/easyv/open/v1`。
|
|
8
|
+
与编辑器使用的 `/api/easyv/v5/**` 隔离:这里使用 API Key、标准 HTTP 状态码,以及声明式大屏文档。
|
|
9
|
+
|
|
10
|
+
把本文件导入 Swagger UI、Redoc 或 Apifox 即可按标签查阅。字段含义以本文件为准;
|
|
11
|
+
`openapi/schemas/screen-document.v1.json` 是早期结构草案,画布等运行时字段以本文 `ScreenDocument` 为准。
|
|
12
|
+
|
|
13
|
+
## 怎么读
|
|
14
|
+
|
|
15
|
+
标签按推荐调用顺序排列:
|
|
16
|
+
|
|
17
|
+
1. **元信息**:确认这把 Key 绑定了哪个空间 / 团队、有哪些权限和限制
|
|
18
|
+
2. **分组**:拿到创建大屏所需的 `groupId`
|
|
19
|
+
3. **大屏**:列表、创建、查看元信息
|
|
20
|
+
4. **大屏文档**:读取和修改大屏内容
|
|
21
|
+
5. **组件**:查询某个组件能配哪些字段
|
|
22
|
+
6. **静态资源**:上传图片、音视频、字体,再把返回的 `path` 写入组件
|
|
23
|
+
7. **发布**:生成或关闭分享链接
|
|
24
|
+
8. **版本**、**异步任务**:已挂路由,当前返回 `501 NOT_IMPLEMENTED`
|
|
25
|
+
|
|
26
|
+
每个接口都写了:做什么、需要哪个 scope、参数(位置 / 类型 / 含义 / 约束)、成功响应、本接口会返回的错误码。
|
|
27
|
+
|
|
28
|
+
`x-easyv-status`:`stable` 可按文档接入;`beta` 可用,但写入范围有明确限制;`planned` 调用会得到 501。
|
|
29
|
+
|
|
30
|
+
## 鉴权
|
|
31
|
+
|
|
32
|
+
除特别说明外,所有接口都需要:
|
|
33
|
+
|
|
34
|
+
```http
|
|
35
|
+
Authorization: Bearer <appId>.<secret>
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
- `appId` 形如 `ev_` 加 16 位十六进制;`secret` 只在创建 Key 时展示一次
|
|
39
|
+
- OAuth 访问令牌形如 `oat_`,由授权码流程签发,1 小时过期。校验方式相同:`Authorization: Bearer <token>`
|
|
40
|
+
- 凭证缺失、格式不对、已禁用,返回 `401 UNAUTHORIZED` 或 `401 TOKEN_EXPIRED`
|
|
41
|
+
- 不要传入内部身份头(`op-user-id`、`op-user-role`、`op-account-id`、`space-id`、`team-id`),否则 `400 UNTRUSTED_HEADER`
|
|
42
|
+
|
|
43
|
+
权限有两道闸,两道都要过:
|
|
44
|
+
|
|
45
|
+
| 闸 | 含义 | 不过时 |
|
|
46
|
+
| --- | --- | --- |
|
|
47
|
+
| scope | Key 上声明的操作范围,见各接口 `x-easyv-scope` | `403 SCOPE_FORBIDDEN` |
|
|
48
|
+
| 空间权限 | 与控制台同一套产品权限(能否看大屏、能否编辑、能否分享) | `403 SPACE_PERMISSION_FORBIDDEN` 或 `403 SPACE_PERMISSION_EXPIRED` |
|
|
49
|
+
|
|
50
|
+
## 身份上下文
|
|
51
|
+
|
|
52
|
+
一把 Key 只绑定 **一个空间 + 一个团队**。请求里不要传 `spaceId` / `teamId`,服务端也不会读这两个参数。
|
|
53
|
+
|
|
54
|
+
- 列表、创建都限定在这把 Key 的团队内
|
|
55
|
+
- `groupId` 必须属于该团队,先调 `GET /groups`
|
|
56
|
+
- 访问其他团队的大屏会返回 `404 SCREEN_NOT_FOUND`(不区分「不存在」和「不属于你」)
|
|
57
|
+
- 要操作另一个团队,另建一把 Key
|
|
58
|
+
- `GET /meta` 的 `context` 会回显 `spaceId`、`spaceName`、`teamId`、`teamName`、`appId`、`scopes`
|
|
59
|
+
|
|
60
|
+
## 错误体
|
|
61
|
+
|
|
62
|
+
失败时 HTTP 状态码就是错误类别,正文不是 `{ success: false }` 包装:
|
|
63
|
+
|
|
64
|
+
```json
|
|
65
|
+
{
|
|
66
|
+
"code": "SCREEN_NOT_FOUND",
|
|
67
|
+
"message": "大屏不存在",
|
|
68
|
+
"details": {},
|
|
69
|
+
"requestId": "",
|
|
70
|
+
"traceId": ""
|
|
71
|
+
}
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
- `code`:稳定字符串,用它做分支,不要解析 `message`
|
|
75
|
+
- `details`:可选,结构因错误码而异
|
|
76
|
+
- `requestId`:回传请求头 `x-request-id`;未传则为空字符串
|
|
77
|
+
- `traceId`:有链路追踪时才出现
|
|
78
|
+
- 参数校验失败(类型、长度)一般为 `400`,`code` 为 `BAD_REQUEST`,`message` 为校验文案
|
|
79
|
+
|
|
80
|
+
全部错误码见文末 `Error` schema 的说明。
|
|
81
|
+
|
|
82
|
+
## 并发:revision
|
|
83
|
+
|
|
84
|
+
`revision` 是文档内容的 16 位十六进制摘要,编辑器里的修改也会让它变化。
|
|
85
|
+
|
|
86
|
+
- `GET /screens/{screenId}/document` 的响应体和 `ETag` 响应头都带它(ETag 形如 `"9f2c1ab34de5f607"`)
|
|
87
|
+
- 写文档时用请求头 `If-Match: "9f2c1ab34de5f607"`,或在 `POST /operations` 的 body 里带 `revision`
|
|
88
|
+
- 两者都传时以 `If-Match` 为准;都不传则不做乐观锁
|
|
89
|
+
- 与当前内容不一致:`409 REVISION_CONFLICT`,`details` 含 `expected` 与 `actual`
|
|
90
|
+
|
|
91
|
+
## 大屏文档怎么组织
|
|
92
|
+
|
|
93
|
+
一份文档是「图层树 + 元素表」:
|
|
94
|
+
|
|
95
|
+
- `layers` 只表达层级和顺序。分组节点 `kind` 为 `group`,叶子节点的 `key` 指向 `elements`
|
|
96
|
+
- `elements` 是 `key → 元素`。元素 `kind` 为 `component`(组件)、`panel`(动态面板)或 `container`(组件容器)
|
|
97
|
+
- 面板和容器的每个 `state` 里再嵌一套 `layers` + `elements`
|
|
98
|
+
|
|
99
|
+
**key 规则**(屏幕内唯一,读取时由服务端给出):
|
|
100
|
+
|
|
101
|
+
| 对象 | key |
|
|
102
|
+
| --- | --- |
|
|
103
|
+
| 已有组件 | 优先用创建时写入的自定义 key,否则 `c-<组件 id>` |
|
|
104
|
+
| 分组 | `g-...` |
|
|
105
|
+
| 动态面板 / 引用面板 / 组件容器 / 万能组件 | `p-` / `rp-` / `k-` / `u-` 加内部 id |
|
|
106
|
+
|
|
107
|
+
新增组件时由调用方指定 key(建议 `^[a-z][a-z0-9-]{0,63}$`)。该 key 会记到组件上,**用同一份文档重试不会重复创建**。
|
|
108
|
+
|
|
109
|
+
组件的 `config` 是属性树数组,不是扁平对象。节点用 `name`/`value`(组件)或 `_name`/`_value`(大屏画布)嵌套。
|
|
110
|
+
`GET /components/{module}/schema` 返回的 `fields[].path`(如 `chart.dimension.chartPosition.left`)
|
|
111
|
+
就是这棵树的路径,用来定位要改的节点,不能把 path 直接当成文档字段名。
|
|
112
|
+
|
|
113
|
+
## 文档写入目前支持什么
|
|
114
|
+
|
|
115
|
+
`PUT /screens/{screenId}/document` 与 `POST /screens/{screenId}/operations` 都是 **diff apply**:只落变化,不整屏重建。
|
|
116
|
+
|
|
117
|
+
**会写入:**
|
|
118
|
+
|
|
119
|
+
- `meta.name`
|
|
120
|
+
- 画布 `width`、`height`、`backgroundColor`、`backgroundImage`、`useBackground`、`grid`、`zoom`、`guides`、`globalFilter`
|
|
121
|
+
- 已有组件的 `name`、`config`
|
|
122
|
+
- 新增 `kind: component` 的元素(`layers` 里的位置决定落在根层级还是某个分组内)。
|
|
123
|
+
服务端以组件包的默认配置、事件、动作和默认数据为底,只叠加你给的 `config`、`layout`、`staticData`,
|
|
124
|
+
和编辑器拖入组件的结果一致。`config` 里出现默认配置没有的路径时整单拒绝(`COMPONENT_CONFIG_INVALID`)
|
|
125
|
+
- 删除组件:从 `elements` 和 `layers` 同时去掉,进入回收站
|
|
126
|
+
|
|
127
|
+
**会整单拒绝、不落库**(`400 UNSUPPORTED_CHANGE` 或 `400 UNSUPPORTED_OPERATION`,`details.unsupported` 列出路径或操作名):
|
|
128
|
+
|
|
129
|
+
- 移动已有元素的父节点,或调整同级顺序
|
|
130
|
+
- 新增或删除面板、容器、分组
|
|
131
|
+
- 修改组件的 `module` / `version`
|
|
132
|
+
- 只改 `layout` 不改 `config`(位置在属性树里,直接改 `config`)
|
|
133
|
+
- 修改 `interactions`
|
|
134
|
+
- `operations` 里不在 `DocumentOperation` 列表中的操作
|
|
135
|
+
|
|
136
|
+
规划阶段任一不支持项都会让整单失败。执行阶段删除、新增各自有事务;极端情况下多步写入可能部分生效。用同一份文档重试是安全的。
|
|
137
|
+
|
|
138
|
+
## 一条典型链路
|
|
139
|
+
|
|
140
|
+
1. `GET /meta` 看 `context` 和 `limits`
|
|
141
|
+
2. `GET /groups` 取 `groupId`,`POST /screens` 创建空白大屏
|
|
142
|
+
3. `GET /components` 选组件,`GET /components/{module}/config-fields?keyword=...` 按意图查要改的字段
|
|
143
|
+
4. 需要图片时 `POST /assets`,把返回的 `path` 写进组件 `config`
|
|
144
|
+
5. `GET /screens/{screenId}/document` 拿基线文档和 `revision`
|
|
145
|
+
6. 改完后 `POST /screens/{screenId}/validate` 预检(不落库)
|
|
146
|
+
7. `PUT /screens/{screenId}/document` 或 `POST /screens/{screenId}/operations` 写入,带上 `If-Match`
|
|
147
|
+
8. `PUT /screens/{screenId}/publish` 发布
|
|
148
|
+
|
|
149
|
+
contact:
|
|
150
|
+
name: EasyV Backend
|
|
151
|
+
|
|
152
|
+
servers:
|
|
153
|
+
- url: https://workspace.easyv.cloud/api/easyv/open/v1
|
|
154
|
+
description: 生产
|
|
155
|
+
- url: http://workspace.saas-test.k8s.dtstack.cn/api/easyv/open/v1
|
|
156
|
+
description: 测试
|
|
157
|
+
- url: http://workspace.saas-dev.k8s.dtstack.cn/api/easyv/open/v1
|
|
158
|
+
description: 开发
|
|
159
|
+
- url: http://127.0.0.1:9800/api/easyv/open/v1
|
|
160
|
+
description: 本地
|
|
161
|
+
|
|
162
|
+
security:
|
|
163
|
+
- bearerAuth: []
|
|
164
|
+
|
|
165
|
+
tags:
|
|
166
|
+
- name: 元信息
|
|
167
|
+
description: 调用其它接口之前先看这里。返回 Key 绑定的空间与团队、权限、能力开关和数值限制。
|
|
168
|
+
- name: 分组
|
|
169
|
+
description: 只读。创建大屏和按分组筛选都依赖这里的分组 id。分组的增删改不在本 API 内。
|
|
170
|
+
- name: 大屏
|
|
171
|
+
description: 大屏这条资源的元信息。内容(组件、画布、图层)走「大屏文档」,分享走「发布」。
|
|
172
|
+
- name: 大屏文档
|
|
173
|
+
description: 声明式读写大屏内容。读取拿完整文档;写入用整份文档 diff,或用少量原子操作改名称和组件配置。
|
|
174
|
+
- name: 组件
|
|
175
|
+
description: 组件目录、配置结构,以及上传空间组件包。
|
|
176
|
+
- name: 数据源
|
|
177
|
+
description: 数据源的增删改查。读接口不返回密码。连接测试、表结构和数据预览需要数据源服务。
|
|
178
|
+
- name: 授权
|
|
179
|
+
description: 设备码登录,以及 MCP 使用的 OAuth 2.1 授权码(PKCE、动态客户端注册)。
|
|
180
|
+
- name: 预览
|
|
181
|
+
description: 签发短期只读预览 token,供 CLI 截图。
|
|
182
|
+
- name: 静态资源
|
|
183
|
+
description: 上传组件素材。返回的相对路径写入组件配置或画布背景。
|
|
184
|
+
- name: 发布
|
|
185
|
+
description: 读取、更新或关闭大屏分享。当前只支持普通分享,不生成缓存文件。
|
|
186
|
+
- name: 版本
|
|
187
|
+
description: 整屏快照与回滚。路由已注册,当前版本调用返回 501。
|
|
188
|
+
- name: 异步任务
|
|
189
|
+
description: 长任务查询。路由已注册,当前版本调用返回 501。
|
|
190
|
+
|
|
191
|
+
paths:
|
|
192
|
+
/.well-known/oauth-authorization-server/api/easyv/open/v1:
|
|
193
|
+
get:
|
|
194
|
+
tags: [授权]
|
|
195
|
+
operationId: getOAuthAuthorizationServerMetadata
|
|
196
|
+
summary: OAuth 授权服务器元数据
|
|
197
|
+
description: |
|
|
198
|
+
RFC 8414。issuer 是 `{origin}/api/easyv/open/v1`,因此发现地址是
|
|
199
|
+
`/.well-known/oauth-authorization-server/api/easyv/open/v1`。
|
|
200
|
+
服务内部改写到 `/oauth/authorization-server`。不需要凭证。
|
|
201
|
+
security: []
|
|
202
|
+
responses:
|
|
203
|
+
'200':
|
|
204
|
+
description: 授权服务器元数据
|
|
205
|
+
content:
|
|
206
|
+
application/json:
|
|
207
|
+
schema:
|
|
208
|
+
$ref: '#/components/schemas/OAuthAuthorizationServerMetadata'
|
|
209
|
+
/oauth/register:
|
|
210
|
+
post:
|
|
211
|
+
tags: [授权]
|
|
212
|
+
operationId: registerOAuthClient
|
|
213
|
+
summary: 动态注册 OAuth 客户端
|
|
214
|
+
description: |
|
|
215
|
+
RFC 7591。只接受公开客户端(`token_endpoint_auth_method=none`),且必须使用 PKCE。
|
|
216
|
+
`redirect_uris` 只能是 https,或 http 的 localhost / 127.0.0.1。同一 IP 每小时最多 20 次。
|
|
217
|
+
错误体是 `{ error, error_description }`,不是 OpenAPI 的 `code` 结构。
|
|
218
|
+
security: []
|
|
219
|
+
requestBody:
|
|
220
|
+
required: true
|
|
221
|
+
content:
|
|
222
|
+
application/json:
|
|
223
|
+
schema:
|
|
224
|
+
$ref: '#/components/schemas/OAuthClientRegistration'
|
|
225
|
+
responses:
|
|
226
|
+
'201':
|
|
227
|
+
description: 已注册。只返回 client_id,没有 client_secret
|
|
228
|
+
content:
|
|
229
|
+
application/json:
|
|
230
|
+
schema:
|
|
231
|
+
$ref: '#/components/schemas/OAuthClientInformation'
|
|
232
|
+
'400':
|
|
233
|
+
description: invalid_redirect_uri 或 invalid_client_metadata
|
|
234
|
+
'429':
|
|
235
|
+
description: 注册过于频繁
|
|
236
|
+
/oauth/token:
|
|
237
|
+
post:
|
|
238
|
+
tags: [授权]
|
|
239
|
+
operationId: exchangeOAuthToken
|
|
240
|
+
summary: 用授权码、刷新令牌或设备码换访问令牌
|
|
241
|
+
description: |
|
|
242
|
+
`grant_type=authorization_code` 时需要 `code`、`redirect_uri`、`client_id`、`code_verifier`。
|
|
243
|
+
`grant_type=refresh_token` 时需要 `refresh_token`、`client_id`。刷新会轮换,旧令牌再使用会吊销整次授权。
|
|
244
|
+
`grant_type=urn:ietf:params:oauth:grant-type:device_code` 时需要 `device_code`、`client_id`。
|
|
245
|
+
用户还没确认时返回 `authorization_pending`,拒绝时返回 `access_denied`,过期时返回 `expired_token`。
|
|
246
|
+
访问令牌 1 小时,刷新令牌 30 天并在每次刷新时顺延。请求体是 `application/x-www-form-urlencoded` 或 JSON。
|
|
247
|
+
security: []
|
|
248
|
+
requestBody:
|
|
249
|
+
required: true
|
|
250
|
+
content:
|
|
251
|
+
application/x-www-form-urlencoded:
|
|
252
|
+
schema:
|
|
253
|
+
type: object
|
|
254
|
+
properties:
|
|
255
|
+
grant_type:
|
|
256
|
+
type: string
|
|
257
|
+
enum: [authorization_code, refresh_token, 'urn:ietf:params:oauth:grant-type:device_code']
|
|
258
|
+
code: {type: string}
|
|
259
|
+
redirect_uri: {type: string}
|
|
260
|
+
client_id: {type: string}
|
|
261
|
+
code_verifier: {type: string}
|
|
262
|
+
refresh_token: {type: string}
|
|
263
|
+
device_code: {type: string}
|
|
264
|
+
responses:
|
|
265
|
+
'200':
|
|
266
|
+
description: 令牌
|
|
267
|
+
content:
|
|
268
|
+
application/json:
|
|
269
|
+
schema:
|
|
270
|
+
$ref: '#/components/schemas/OAuthTokenResponse'
|
|
271
|
+
'400':
|
|
272
|
+
description: invalid_grant、authorization_pending、expired_token、access_denied 或 unsupported_grant_type
|
|
273
|
+
/oauth/device:
|
|
274
|
+
post:
|
|
275
|
+
tags: [授权]
|
|
276
|
+
operationId: beginDeviceAuthorization
|
|
277
|
+
summary: 申请设备码(OAuth 设备授权)
|
|
278
|
+
description: |
|
|
279
|
+
RFC 8628。不需要登录。`client_id` 省略时按官方命令行 `easyv-screen-cli` 处理;
|
|
280
|
+
其他客户端必须先动态注册。用户在 `verification_uri` 确认后,
|
|
281
|
+
用 `grant_type=urn:ietf:params:oauth:grant-type:device_code` 调用 `/oauth/token`。
|
|
282
|
+
`verificationPath` 是站内路径,命令行把它拼到 Web 站点域名上。
|
|
283
|
+
security: []
|
|
284
|
+
requestBody:
|
|
285
|
+
required: false
|
|
286
|
+
content:
|
|
287
|
+
application/json:
|
|
288
|
+
schema:
|
|
289
|
+
type: object
|
|
290
|
+
properties:
|
|
291
|
+
client_id: {type: string}
|
|
292
|
+
scope: {type: string, description: 空格分隔。不传则使用命令行默认权限,发布需要用户在授权页勾选}
|
|
293
|
+
responses:
|
|
294
|
+
'200':
|
|
295
|
+
description: 设备码和授权页地址
|
|
296
|
+
content:
|
|
297
|
+
application/json:
|
|
298
|
+
schema:
|
|
299
|
+
$ref: '#/components/schemas/DeviceAuthorization'
|
|
300
|
+
'400':
|
|
301
|
+
description: invalid_scope
|
|
302
|
+
'401':
|
|
303
|
+
description: invalid_client
|
|
304
|
+
/oauth/revoke:
|
|
305
|
+
post:
|
|
306
|
+
tags: [授权]
|
|
307
|
+
operationId: revokeOAuthToken
|
|
308
|
+
summary: 吊销刷新令牌或访问令牌
|
|
309
|
+
description: 无论令牌是否存在都返回 200。吊销访问令牌只影响这一枚;禁用对应的 OpenAPI Key 会使这次授权的全部令牌失效。
|
|
310
|
+
security: []
|
|
311
|
+
responses:
|
|
312
|
+
'200':
|
|
313
|
+
description: 已处理
|
|
314
|
+
/meta:
|
|
315
|
+
get:
|
|
316
|
+
operationId: getMeta
|
|
317
|
+
tags: [元信息]
|
|
318
|
+
summary: 获取当前 Key 的能力与上下文
|
|
319
|
+
description: |
|
|
320
|
+
集成方的第一步。用返回值确认:
|
|
321
|
+
|
|
322
|
+
- `context`:这把 Key 能操作哪个空间、哪个团队,含 `spaceName` 与 `teamName`
|
|
323
|
+
- `scopes`:系统定义过的全部 scope;当前 Key 实际拥有的在 `context.scopes`
|
|
324
|
+
- `capabilities`:各类资源哪些动作已开放(`false` 表示还不能当可用能力依赖)
|
|
325
|
+
- `operations`:文档操作词表。`available: true` 表示词表标记为可用
|
|
326
|
+
- `limits`:分页、文档体积、元素数量、上传大小等数值,后续限制以这里为准
|
|
327
|
+
|
|
328
|
+
词表与写入实现有一处不一致:`element.update` 在 `POST /screens/{screenId}/operations` 中已经可以调用,
|
|
329
|
+
但本接口的 `operations[].available` 目前仍为 `false`。能否写入以「大屏文档」各接口的说明为准。
|
|
330
|
+
x-easyv-status: stable
|
|
331
|
+
responses:
|
|
332
|
+
'200':
|
|
333
|
+
description: 当前 Key 的元信息
|
|
334
|
+
content:
|
|
335
|
+
application/json:
|
|
336
|
+
schema: {$ref: '#/components/schemas/Meta'}
|
|
337
|
+
example:
|
|
338
|
+
apiVersion: v1
|
|
339
|
+
documentSchemaVersion: '1.0'
|
|
340
|
+
context:
|
|
341
|
+
appId: ev_a1b2c3d4e5f60718
|
|
342
|
+
spaceId: 10
|
|
343
|
+
spaceName: 演示空间
|
|
344
|
+
teamId: 20
|
|
345
|
+
teamName: 默认团队
|
|
346
|
+
scopes: ['screen:read', 'screen:write', 'component:read', 'asset:write']
|
|
347
|
+
capabilities:
|
|
348
|
+
screens: {list: true, create: true, get: true, updateMeta: true, delete: false}
|
|
349
|
+
document: {read: true, write: true, operations: true, validate: true}
|
|
350
|
+
publish: {publish: true, unpublish: true, readShare: true}
|
|
351
|
+
components: {list: false, detail: false, schema: true}
|
|
352
|
+
assets: {upload: true}
|
|
353
|
+
versions: {list: false, create: false, rollback: false}
|
|
354
|
+
jobs: {get: false, cancel: false}
|
|
355
|
+
operations:
|
|
356
|
+
- {op: screen.updateMeta, description: 修改名称/分组, available: true}
|
|
357
|
+
- {op: element.update, description: 修改组件名称或整棵属性树, available: true}
|
|
358
|
+
scopes: ['screen:read', 'screen:write', 'screen:publish', 'component:read', 'asset:write']
|
|
359
|
+
limits:
|
|
360
|
+
listPageSizeMax: 100
|
|
361
|
+
listPageSizeDefault: 20
|
|
362
|
+
documentMaxBytes: 8388608
|
|
363
|
+
documentMaxElements: 2000
|
|
364
|
+
assetMaxBytes: 20971520
|
|
365
|
+
requestsPerMinute: 120
|
|
366
|
+
'401': {$ref: '#/components/responses/Unauthorized'}
|
|
367
|
+
|
|
368
|
+
/groups:
|
|
369
|
+
get:
|
|
370
|
+
operationId: listGroups
|
|
371
|
+
tags: [分组]
|
|
372
|
+
summary: 列出当前团队的大屏分组
|
|
373
|
+
description: |
|
|
374
|
+
返回 Key 绑定团队下的工作区分组(不含数据集分组),按 `rank` 从大到小,与工作台展示顺序一致。
|
|
375
|
+
|
|
376
|
+
分组数量很少,一次返回全部,没有分页。
|
|
377
|
+
`POST /screens` 的 `groupId`,以及 `GET /screens?groupId=`,都必须使用这里的 `id`。
|
|
378
|
+
x-easyv-status: stable
|
|
379
|
+
x-easyv-scope: screen:read
|
|
380
|
+
responses:
|
|
381
|
+
'200':
|
|
382
|
+
description: 分组全量列表
|
|
383
|
+
content:
|
|
384
|
+
application/json:
|
|
385
|
+
schema: {$ref: '#/components/schemas/GroupList'}
|
|
386
|
+
example:
|
|
387
|
+
teamId: 20
|
|
388
|
+
items:
|
|
389
|
+
- id: 3
|
|
390
|
+
name: 默认分组
|
|
391
|
+
rank: 1000
|
|
392
|
+
createdAt: '2026-11-01T02:00:00.000Z'
|
|
393
|
+
updatedAt: '2026-11-01T02:00:00.000Z'
|
|
394
|
+
'401': {$ref: '#/components/responses/Unauthorized'}
|
|
395
|
+
'403': {$ref: '#/components/responses/Forbidden'}
|
|
396
|
+
|
|
397
|
+
/screens:
|
|
398
|
+
get:
|
|
399
|
+
operationId: listScreens
|
|
400
|
+
tags: [大屏]
|
|
401
|
+
summary: 列出当前团队的大屏
|
|
402
|
+
description: |
|
|
403
|
+
只返回 Key 绑定团队内的大屏元信息,不含组件内容,也不含分享密码和 Token。
|
|
404
|
+
|
|
405
|
+
过滤在服务端完成:先取出该团队符合条件的大屏,再按 `offset` / `limit` 切片。
|
|
406
|
+
响应里没有 `total`;要判断是否还有下一页,看本页 `items` 的长度是否等于 `limit`。
|
|
407
|
+
x-easyv-status: stable
|
|
408
|
+
x-easyv-scope: screen:read
|
|
409
|
+
parameters:
|
|
410
|
+
- name: groupId
|
|
411
|
+
in: query
|
|
412
|
+
required: false
|
|
413
|
+
description: 只返回该分组下的大屏。必须是正整数,且属于当前团队;不传则不按分组过滤。
|
|
414
|
+
schema: {type: integer, format: int64, minimum: 1}
|
|
415
|
+
- name: name
|
|
416
|
+
in: query
|
|
417
|
+
required: false
|
|
418
|
+
description: 按大屏名称精确匹配,不是模糊搜索。最长 100 个字符。
|
|
419
|
+
schema: {type: string, maxLength: 100}
|
|
420
|
+
- name: limit
|
|
421
|
+
in: query
|
|
422
|
+
required: false
|
|
423
|
+
description: 本页条数。默认 20,最大 100(以 `GET /meta` 的 `limits.listPageSizeMax` 为准)。
|
|
424
|
+
schema: {type: integer, minimum: 1, maximum: 100, default: 20}
|
|
425
|
+
- name: offset
|
|
426
|
+
in: query
|
|
427
|
+
required: false
|
|
428
|
+
description: 跳过的条数,从 0 开始。
|
|
429
|
+
schema: {type: integer, minimum: 0, default: 0}
|
|
430
|
+
responses:
|
|
431
|
+
'200':
|
|
432
|
+
description: 当前页大屏
|
|
433
|
+
content:
|
|
434
|
+
application/json:
|
|
435
|
+
schema: {$ref: '#/components/schemas/ScreenList'}
|
|
436
|
+
example:
|
|
437
|
+
items:
|
|
438
|
+
- id: 1001
|
|
439
|
+
name: 运营总览
|
|
440
|
+
teamId: 20
|
|
441
|
+
groupId: 3
|
|
442
|
+
thumb: null
|
|
443
|
+
createdAt: '2026-11-01T02:00:00.000Z'
|
|
444
|
+
updatedAt: '2026-11-03T06:12:00.000Z'
|
|
445
|
+
limit: 20
|
|
446
|
+
offset: 0
|
|
447
|
+
'400': {$ref: '#/components/responses/BadRequest'}
|
|
448
|
+
'401': {$ref: '#/components/responses/Unauthorized'}
|
|
449
|
+
'403': {$ref: '#/components/responses/Forbidden'}
|
|
450
|
+
post:
|
|
451
|
+
operationId: createScreen
|
|
452
|
+
tags: [大屏]
|
|
453
|
+
summary: 在当前团队创建一个空白大屏
|
|
454
|
+
description: |
|
|
455
|
+
大屏落在 Key 绑定的团队下,因此 body 里没有 `teamId`。
|
|
456
|
+
`groupId` 必须来自 `GET /groups`,否则 `404 GROUP_NOT_FOUND`。
|
|
457
|
+
空间大屏数量达到上限时返回 `429 SCREEN_QUOTA_EXCEEDED`。
|
|
458
|
+
x-easyv-status: stable
|
|
459
|
+
x-easyv-scope: screen:write
|
|
460
|
+
requestBody:
|
|
461
|
+
required: true
|
|
462
|
+
content:
|
|
463
|
+
application/json:
|
|
464
|
+
schema: {$ref: '#/components/schemas/CreateScreenRequest'}
|
|
465
|
+
example: {name: 运营总览, groupId: 3}
|
|
466
|
+
responses:
|
|
467
|
+
'201':
|
|
468
|
+
description: 已创建。此时大屏还没有业务组件,内容请随后用文档接口写入。
|
|
469
|
+
content:
|
|
470
|
+
application/json:
|
|
471
|
+
schema: {$ref: '#/components/schemas/ScreenCreated'}
|
|
472
|
+
example: {id: 1001, name: 运营总览, teamId: 20, groupId: 3}
|
|
473
|
+
'400': {$ref: '#/components/responses/BadRequest'}
|
|
474
|
+
'401': {$ref: '#/components/responses/Unauthorized'}
|
|
475
|
+
'403': {$ref: '#/components/responses/Forbidden'}
|
|
476
|
+
'404':
|
|
477
|
+
description: '`GROUP_NOT_FOUND`:分组不存在,或不属于当前团队。'
|
|
478
|
+
content:
|
|
479
|
+
application/json:
|
|
480
|
+
schema: {$ref: '#/components/schemas/Error'}
|
|
481
|
+
'429':
|
|
482
|
+
description: '`SCREEN_QUOTA_EXCEEDED`:大屏数量已达空间上限。'
|
|
483
|
+
content:
|
|
484
|
+
application/json:
|
|
485
|
+
schema: {$ref: '#/components/schemas/Error'}
|
|
486
|
+
|
|
487
|
+
/screens/{screenId}:
|
|
488
|
+
get:
|
|
489
|
+
operationId: getScreen
|
|
490
|
+
tags: [大屏]
|
|
491
|
+
summary: 读取大屏元信息和发布状态
|
|
492
|
+
description: |
|
|
493
|
+
只返回名称、分组、缩略图和脱敏后的分享状态。
|
|
494
|
+
组件与画布用 `GET /screens/{screenId}/document`;分享密码不会出现在这里。
|
|
495
|
+
x-easyv-status: stable
|
|
496
|
+
x-easyv-scope: screen:read
|
|
497
|
+
parameters:
|
|
498
|
+
- {$ref: '#/components/parameters/ScreenId'}
|
|
499
|
+
responses:
|
|
500
|
+
'200':
|
|
501
|
+
description: 大屏元信息
|
|
502
|
+
content:
|
|
503
|
+
application/json:
|
|
504
|
+
schema: {$ref: '#/components/schemas/ScreenDetail'}
|
|
505
|
+
example:
|
|
506
|
+
id: 1001
|
|
507
|
+
name: 运营总览
|
|
508
|
+
teamId: 20
|
|
509
|
+
groupId: 3
|
|
510
|
+
thumb: null
|
|
511
|
+
createdAt: '2026-11-01T02:00:00.000Z'
|
|
512
|
+
updatedAt: '2026-11-03T06:12:00.000Z'
|
|
513
|
+
share:
|
|
514
|
+
published: true
|
|
515
|
+
needPassword: false
|
|
516
|
+
needToken: false
|
|
517
|
+
shareType: 1
|
|
518
|
+
expiredAt: null
|
|
519
|
+
'401': {$ref: '#/components/responses/Unauthorized'}
|
|
520
|
+
'403': {$ref: '#/components/responses/Forbidden'}
|
|
521
|
+
'404': {$ref: '#/components/responses/ScreenNotFound'}
|
|
522
|
+
|
|
523
|
+
/screens/{screenId}/document:
|
|
524
|
+
get:
|
|
525
|
+
operationId: getScreenDocument
|
|
526
|
+
tags: [大屏文档]
|
|
527
|
+
summary: 读取完整大屏文档
|
|
528
|
+
description: |
|
|
529
|
+
返回规范化后的文档:`meta`、`canvas`、`layers`、`elements`。
|
|
530
|
+
动态面板和组件容器会递归展开到各自 state 里。
|
|
531
|
+
|
|
532
|
+
响应头 `ETag` 与 body 里的 `revision` 是同一个摘要,写回时放到 `If-Match`。
|
|
533
|
+
组件 key 稳定:创建时指定过的 key 优先,否则是 `c-<组件 id>`。
|
|
534
|
+
x-easyv-status: beta
|
|
535
|
+
x-easyv-scope: screen:read
|
|
536
|
+
parameters:
|
|
537
|
+
- {$ref: '#/components/parameters/ScreenId'}
|
|
538
|
+
responses:
|
|
539
|
+
'200':
|
|
540
|
+
description: 当前已保存的文档
|
|
541
|
+
headers:
|
|
542
|
+
ETag:
|
|
543
|
+
description: 带双引号的 revision,例如 `"9f2c1ab34de5f607"`
|
|
544
|
+
schema: {type: string}
|
|
545
|
+
content:
|
|
546
|
+
application/json:
|
|
547
|
+
schema: {$ref: '#/components/schemas/ScreenDocument'}
|
|
548
|
+
'401': {$ref: '#/components/responses/Unauthorized'}
|
|
549
|
+
'403': {$ref: '#/components/responses/Forbidden'}
|
|
550
|
+
'404': {$ref: '#/components/responses/ScreenNotFound'}
|
|
551
|
+
put:
|
|
552
|
+
operationId: putScreenDocument
|
|
553
|
+
tags: [大屏文档]
|
|
554
|
+
summary: 用整份文档声明式更新大屏
|
|
555
|
+
description: |
|
|
556
|
+
把「期望中的完整文档」提交上来。服务端与当前文档做 diff,只写入变化的部分。
|
|
557
|
+
|
|
558
|
+
适合改动面比较散的场景:改名称、改画布、增删组件、改多个组件的 `config`。
|
|
559
|
+
只改一两个已有组件时,用 `POST /screens/{screenId}/operations` 更直接。
|
|
560
|
+
|
|
561
|
+
建议流程:`GET` 文档 → 在副本上修改 → `POST /validate` → 带 `If-Match` 提交本接口。
|
|
562
|
+
|
|
563
|
+
支持范围和会被整单拒绝的变更,见文首「文档写入目前支持什么」。
|
|
564
|
+
内容与当前完全一致时返回 200,`changes` 全为 0,`patch` 为空数组,不写库。
|
|
565
|
+
|
|
566
|
+
`patch` 只汇总名称和画布字段的变化,不含组件增删改;组件变化看 `changes` 的计数。
|
|
567
|
+
x-easyv-status: beta
|
|
568
|
+
x-easyv-scope: screen:write
|
|
569
|
+
parameters:
|
|
570
|
+
- {$ref: '#/components/parameters/ScreenId'}
|
|
571
|
+
- {$ref: '#/components/parameters/IfMatch'}
|
|
572
|
+
requestBody:
|
|
573
|
+
required: true
|
|
574
|
+
content:
|
|
575
|
+
application/json:
|
|
576
|
+
schema: {$ref: '#/components/schemas/ScreenDocument'}
|
|
577
|
+
example:
|
|
578
|
+
schemaVersion: '1.0'
|
|
579
|
+
revision: 9f2c1ab34de5f607
|
|
580
|
+
meta: {name: 运营总览}
|
|
581
|
+
canvas: {width: 1920, height: 1080, backgroundColor: '#0b1b2b'}
|
|
582
|
+
layers:
|
|
583
|
+
- {key: kpi-1}
|
|
584
|
+
elements:
|
|
585
|
+
kpi-1:
|
|
586
|
+
kind: component
|
|
587
|
+
module: title_text
|
|
588
|
+
version: 1.0.0
|
|
589
|
+
name: 标题
|
|
590
|
+
config:
|
|
591
|
+
- name: chart
|
|
592
|
+
value:
|
|
593
|
+
- name: text
|
|
594
|
+
value: 运营总览
|
|
595
|
+
responses:
|
|
596
|
+
'200':
|
|
597
|
+
description: 已应用,或内容无变化。`revision` 是写入之后的新摘要。
|
|
598
|
+
content:
|
|
599
|
+
application/json:
|
|
600
|
+
schema: {$ref: '#/components/schemas/ApplyResult'}
|
|
601
|
+
example:
|
|
602
|
+
revision: a0b1c2d3e4f50617
|
|
603
|
+
changes: {added: 1, updated: 0, removed: 0}
|
|
604
|
+
patch: []
|
|
605
|
+
'400':
|
|
606
|
+
description: |
|
|
607
|
+
- `SCHEMA_VIOLATION`:缺 `schemaVersion` / `meta.name` / `canvas` / `layers` / `elements`,或类型不对。`details.issues` 是 `{path, message}[]`
|
|
608
|
+
- `UNSUPPORTED_CHANGE`:包含当前不能落库的变更,整单未写入。`details.unsupported` 是路径列表,如 `elements.panel-1`、`layers.chart-1`
|
|
609
|
+
- `BAD_REQUEST`:其它参数错误
|
|
610
|
+
content:
|
|
611
|
+
application/json:
|
|
612
|
+
schema: {$ref: '#/components/schemas/Error'}
|
|
613
|
+
'401': {$ref: '#/components/responses/Unauthorized'}
|
|
614
|
+
'403': {$ref: '#/components/responses/Forbidden'}
|
|
615
|
+
'404': {$ref: '#/components/responses/ScreenNotFound'}
|
|
616
|
+
'409': {$ref: '#/components/responses/RevisionConflict'}
|
|
617
|
+
|
|
618
|
+
/screens/{screenId}/operations:
|
|
619
|
+
post:
|
|
620
|
+
operationId: applyScreenOperations
|
|
621
|
+
tags: [大屏文档]
|
|
622
|
+
summary: 批量修改大屏名称或已有组件
|
|
623
|
+
description: |
|
|
624
|
+
在服务端读取到的当前文档上依次应用 `operations`,再按与 `PUT /document` 相同的规则落库。
|
|
625
|
+
|
|
626
|
+
**当前会执行的操作只有两个:**
|
|
627
|
+
|
|
628
|
+
- `screen.updateMeta`:把 `name` 写成新的大屏名称
|
|
629
|
+
- `element.update`:按 `key` 修改已有组件的 `name` 和 / 或 `config`。`key` 必须指向已存在的组件;面板、容器、不存在的 key 会失败
|
|
630
|
+
|
|
631
|
+
数组里只要有一个不支持的 `op`,或某条 `element.update` 找不到组件,就返回 `400 UNSUPPORTED_OPERATION`,整批不落库。
|
|
632
|
+
`GET /meta` 词表里的 `element.add`、`element.remove`、`screen.updateCanvas` 等,在本接口里还不能用;
|
|
633
|
+
增删组件、改画布请改完整文档后调用 `PUT /screens/{screenId}/document`。
|
|
634
|
+
|
|
635
|
+
`element.update` 的 `config` 是整棵属性树替换,不是按 path 打补丁。只想改一个字段时,先 `GET` 文档,改对应节点,再把整棵 `config` 传回来。
|
|
636
|
+
x-easyv-status: beta
|
|
637
|
+
x-easyv-scope: screen:write
|
|
638
|
+
parameters:
|
|
639
|
+
- {$ref: '#/components/parameters/ScreenId'}
|
|
640
|
+
- {$ref: '#/components/parameters/IfMatch'}
|
|
641
|
+
requestBody:
|
|
642
|
+
required: true
|
|
643
|
+
content:
|
|
644
|
+
application/json:
|
|
645
|
+
schema: {$ref: '#/components/schemas/OperationsRequest'}
|
|
646
|
+
examples:
|
|
647
|
+
rename:
|
|
648
|
+
summary: 只改大屏名称
|
|
649
|
+
value:
|
|
650
|
+
revision: 9f2c1ab34de5f607
|
|
651
|
+
operations:
|
|
652
|
+
- {op: screen.updateMeta, name: 运营总览(夜)}
|
|
653
|
+
updateComponent:
|
|
654
|
+
summary: 修改已有组件的名称和配置
|
|
655
|
+
value:
|
|
656
|
+
revision: 9f2c1ab34de5f607
|
|
657
|
+
operations:
|
|
658
|
+
- op: element.update
|
|
659
|
+
key: c-88
|
|
660
|
+
name: 主标题
|
|
661
|
+
config:
|
|
662
|
+
- name: chart
|
|
663
|
+
value:
|
|
664
|
+
- {name: text, value: 今晚值班}
|
|
665
|
+
responses:
|
|
666
|
+
'200':
|
|
667
|
+
description: 已应用。响应与 `PUT /document` 相同。
|
|
668
|
+
content:
|
|
669
|
+
application/json:
|
|
670
|
+
schema: {$ref: '#/components/schemas/ApplyResult'}
|
|
671
|
+
'400':
|
|
672
|
+
description: |
|
|
673
|
+
- `UNSUPPORTED_OPERATION`:含未实现的操作,或 `element.update` 的 key 无效。`details.unsupported` 为操作名或 `elements.<key>`
|
|
674
|
+
- `UNSUPPORTED_CHANGE`:操作能解释成文档,但落库阶段发现变更不受支持
|
|
675
|
+
- `BAD_REQUEST`:body 不符合 `OperationsRequest`(例如 `operations` 不是数组)
|
|
676
|
+
content:
|
|
677
|
+
application/json:
|
|
678
|
+
schema: {$ref: '#/components/schemas/Error'}
|
|
679
|
+
'401': {$ref: '#/components/responses/Unauthorized'}
|
|
680
|
+
'403': {$ref: '#/components/responses/Forbidden'}
|
|
681
|
+
'404': {$ref: '#/components/responses/ScreenNotFound'}
|
|
682
|
+
'409': {$ref: '#/components/responses/RevisionConflict'}
|
|
683
|
+
|
|
684
|
+
/screens/{screenId}/validate:
|
|
685
|
+
post:
|
|
686
|
+
operationId: validateScreenDocument
|
|
687
|
+
tags: [大屏文档]
|
|
688
|
+
summary: 校验大屏文档,不写入
|
|
689
|
+
description: |
|
|
690
|
+
保存前的预检。
|
|
691
|
+
|
|
692
|
+
- body 里带 `document`:校验这份待写入文档,不读库、不落库
|
|
693
|
+
- 不带 `document`(body 为 `{}` 或省略可选字段):校验当前已保存的大屏,响应里的 `revision` 即当前摘要
|
|
694
|
+
|
|
695
|
+
`valid` 只看 `severity: error`。`warn` 表示能保存,但有展示或数据上的问题(例如元素不在图层里、超出画布)。
|
|
696
|
+
本接口不做元素重叠检测。
|
|
697
|
+
|
|
698
|
+
规则码见 `ValidationIssue`。
|
|
699
|
+
x-easyv-status: beta
|
|
700
|
+
x-easyv-scope: screen:read
|
|
701
|
+
parameters:
|
|
702
|
+
- {$ref: '#/components/parameters/ScreenId'}
|
|
703
|
+
requestBody:
|
|
704
|
+
required: false
|
|
705
|
+
content:
|
|
706
|
+
application/json:
|
|
707
|
+
schema: {$ref: '#/components/schemas/ValidateDocumentRequest'}
|
|
708
|
+
responses:
|
|
709
|
+
'200':
|
|
710
|
+
description: 校验结果。HTTP 200 不代表文档合法,请看 `valid`。
|
|
711
|
+
content:
|
|
712
|
+
application/json:
|
|
713
|
+
schema: {$ref: '#/components/schemas/ValidationResult'}
|
|
714
|
+
example:
|
|
715
|
+
valid: false
|
|
716
|
+
revision: 9f2c1ab34de5f607
|
|
717
|
+
issues:
|
|
718
|
+
- severity: error
|
|
719
|
+
code: LAYER_ELEMENT_MISSING
|
|
720
|
+
path: /layers
|
|
721
|
+
message: 图层引用的元素不存在:chart-9
|
|
722
|
+
details: {key: chart-9}
|
|
723
|
+
- severity: warn
|
|
724
|
+
code: ELEMENT_OUT_OF_CANVAS
|
|
725
|
+
path: /elements/chart-1/layout
|
|
726
|
+
message: 元素超出画布:右 280px / 下 220px
|
|
727
|
+
details: {right: 280, bottom: 220}
|
|
728
|
+
'400':
|
|
729
|
+
description: '`SCHEMA_VIOLATION`:传入的 `document` 连基本结构都不满足。'
|
|
730
|
+
content:
|
|
731
|
+
application/json:
|
|
732
|
+
schema: {$ref: '#/components/schemas/Error'}
|
|
733
|
+
'401': {$ref: '#/components/responses/Unauthorized'}
|
|
734
|
+
'403': {$ref: '#/components/responses/Forbidden'}
|
|
735
|
+
'404': {$ref: '#/components/responses/ScreenNotFound'}
|
|
736
|
+
|
|
737
|
+
/components/{module}/schema:
|
|
738
|
+
get:
|
|
739
|
+
operationId: getComponentSchema
|
|
740
|
+
tags: [组件]
|
|
741
|
+
summary: 读取组件的配置字段
|
|
742
|
+
description: |
|
|
743
|
+
从组件包脚本里静态提取默认配置,不执行组件代码。用来回答「这个组件能配什么」。
|
|
744
|
+
|
|
745
|
+
- `fields[].path` 是属性树路径,对应文档里组件 `config` 的嵌套 `name`
|
|
746
|
+
- `dataFields` 来自组件默认数据字段,描述数据绑定的列,不是配置项
|
|
747
|
+
- `source: extracted` 且 `strict: true`:字段提取完整
|
|
748
|
+
- `source: partial` 或 `unsupported` 非空:组件里有动态表达式,列出的字段不完整,改配置时不要假设只有这些字段
|
|
749
|
+
- `version` 不传时用该组件当前发布版本
|
|
750
|
+
- 结果缓存 24 小时;`refresh=true` 强制重新解析
|
|
751
|
+
|
|
752
|
+
本接口不提供组件目录。`module` 使用组件包名,例如 `bar_chart`。
|
|
753
|
+
x-easyv-status: beta
|
|
754
|
+
x-easyv-scope: component:read
|
|
755
|
+
parameters:
|
|
756
|
+
- name: module
|
|
757
|
+
in: path
|
|
758
|
+
required: true
|
|
759
|
+
description: 组件模块名,与文档元素的 `module` 相同。
|
|
760
|
+
schema: {type: string}
|
|
761
|
+
example: bar_chart
|
|
762
|
+
- name: version
|
|
763
|
+
in: query
|
|
764
|
+
required: false
|
|
765
|
+
description: 语义化版本,至少 `主.次.修订` 三段数字。不传则取当前发布版本。
|
|
766
|
+
schema: {type: string, pattern: '^\\d+\\.\\d+\\.\\d+'}
|
|
767
|
+
example: 2.1.0
|
|
768
|
+
- name: refresh
|
|
769
|
+
in: query
|
|
770
|
+
required: false
|
|
771
|
+
description: 为 `true` 时忽略缓存,重新解析组件包。默认 `false`。
|
|
772
|
+
schema: {type: boolean, default: false}
|
|
773
|
+
responses:
|
|
774
|
+
'200':
|
|
775
|
+
description: 组件配置结构
|
|
776
|
+
content:
|
|
777
|
+
application/json:
|
|
778
|
+
schema: {$ref: '#/components/schemas/ComponentSchema'}
|
|
779
|
+
example:
|
|
780
|
+
module: bar_chart
|
|
781
|
+
version: 2.1.0
|
|
782
|
+
source: extracted
|
|
783
|
+
strict: true
|
|
784
|
+
fields:
|
|
785
|
+
- path: chart.style.color
|
|
786
|
+
name: color
|
|
787
|
+
label: 颜色
|
|
788
|
+
type: color
|
|
789
|
+
default: '#ffffff'
|
|
790
|
+
group: 样式
|
|
791
|
+
dataFields:
|
|
792
|
+
- {name: text, value: text, desc: 文本}
|
|
793
|
+
unsupported: []
|
|
794
|
+
cached: false
|
|
795
|
+
stats: {bytes: 120345, parseMs: 12, fieldCount: 42, dataFieldCount: 3}
|
|
796
|
+
'400': {$ref: '#/components/responses/BadRequest'}
|
|
797
|
+
'401': {$ref: '#/components/responses/Unauthorized'}
|
|
798
|
+
'403': {$ref: '#/components/responses/Forbidden'}
|
|
799
|
+
'404':
|
|
800
|
+
description: '`COMPONENT_NOT_FOUND`:组件不存在,或该版本不可用。'
|
|
801
|
+
content:
|
|
802
|
+
application/json:
|
|
803
|
+
schema: {$ref: '#/components/schemas/Error'}
|
|
804
|
+
'422':
|
|
805
|
+
description: '`COMPONENT_SCHEMA_UNAVAILABLE`:组件包里提取不出配置结构。'
|
|
806
|
+
content:
|
|
807
|
+
application/json:
|
|
808
|
+
schema: {$ref: '#/components/schemas/Error'}
|
|
809
|
+
|
|
810
|
+
/components/{module}/config-fields:
|
|
811
|
+
get:
|
|
812
|
+
operationId: searchComponentConfigFields
|
|
813
|
+
tags: [组件]
|
|
814
|
+
summary: 按意图查找组件配置字段
|
|
815
|
+
description: |
|
|
816
|
+
组件配置通常有几百项,整份 schema 太大。这里按关键词返回少量字段,供 `addComponent` / `setComponentConfig` 的 `configPatches` 使用。
|
|
817
|
+
|
|
818
|
+
- 关键词按中文标签链(`labelPath`,如 `['图例', '宽度']`)和路径匹配,空格分隔的多个词需要同时命中
|
|
819
|
+
- 不传 `keyword` 时 `fields` 为空,只返回 `groups` 分组概览,用来决定下一步搜什么
|
|
820
|
+
- 字段来自静态解析,`strict: false` 时清单不完整
|
|
821
|
+
x-easyv-status: beta
|
|
822
|
+
x-easyv-scope: component:read
|
|
823
|
+
parameters:
|
|
824
|
+
- name: module
|
|
825
|
+
in: path
|
|
826
|
+
required: true
|
|
827
|
+
schema: {type: string}
|
|
828
|
+
example: basicLineV2
|
|
829
|
+
- name: version
|
|
830
|
+
in: query
|
|
831
|
+
required: false
|
|
832
|
+
description: 不传则取当前发布版本。
|
|
833
|
+
schema: {type: string, pattern: '^\\d+\\.\\d+\\.\\d+'}
|
|
834
|
+
- name: keyword
|
|
835
|
+
in: query
|
|
836
|
+
required: false
|
|
837
|
+
schema: {type: string, maxLength: 100}
|
|
838
|
+
example: 图例 宽度
|
|
839
|
+
- name: limit
|
|
840
|
+
in: query
|
|
841
|
+
required: false
|
|
842
|
+
schema: {type: integer, minimum: 1, maximum: 100, default: 30}
|
|
843
|
+
responses:
|
|
844
|
+
'200':
|
|
845
|
+
description: 匹配的字段
|
|
846
|
+
content:
|
|
847
|
+
application/json:
|
|
848
|
+
schema:
|
|
849
|
+
type: object
|
|
850
|
+
required: [module, version, strict, total, groups, fields]
|
|
851
|
+
properties:
|
|
852
|
+
module: {type: string}
|
|
853
|
+
version: {type: string}
|
|
854
|
+
strict: {type: boolean, description: 字段是否完整提取。}
|
|
855
|
+
total: {type: integer, description: 命中总数;不传关键词时是字段总数。}
|
|
856
|
+
groups:
|
|
857
|
+
type: array
|
|
858
|
+
description: 顶层分组及字段数。
|
|
859
|
+
items:
|
|
860
|
+
type: object
|
|
861
|
+
properties:
|
|
862
|
+
label: {type: string}
|
|
863
|
+
count: {type: integer}
|
|
864
|
+
fields:
|
|
865
|
+
type: array
|
|
866
|
+
description: 按匹配度排序,最多 `limit` 条。
|
|
867
|
+
items: {$ref: '#/components/schemas/ComponentField'}
|
|
868
|
+
example:
|
|
869
|
+
module: basicLineV2
|
|
870
|
+
version: 1.8.19
|
|
871
|
+
strict: true
|
|
872
|
+
total: 1
|
|
873
|
+
groups: [{label: 图例, count: 12}, {label: 坐标轴, count: 40}]
|
|
874
|
+
fields:
|
|
875
|
+
- path: chart.legend.iconSize.width
|
|
876
|
+
name: width
|
|
877
|
+
labelPath: [图例, 图标, 宽度]
|
|
878
|
+
label: 宽度
|
|
879
|
+
type: number
|
|
880
|
+
default: 10
|
|
881
|
+
group: 图例
|
|
882
|
+
'401': {$ref: '#/components/responses/Unauthorized'}
|
|
883
|
+
'403': {$ref: '#/components/responses/Forbidden'}
|
|
884
|
+
'404':
|
|
885
|
+
description: '`COMPONENT_NOT_FOUND`'
|
|
886
|
+
content:
|
|
887
|
+
application/json:
|
|
888
|
+
schema: {$ref: '#/components/schemas/Error'}
|
|
889
|
+
'422':
|
|
890
|
+
description: '`COMPONENT_SCHEMA_UNAVAILABLE`'
|
|
891
|
+
content:
|
|
892
|
+
application/json:
|
|
893
|
+
schema: {$ref: '#/components/schemas/Error'}
|
|
894
|
+
|
|
895
|
+
/components:
|
|
896
|
+
get:
|
|
897
|
+
operationId: listComponents
|
|
898
|
+
tags: [组件]
|
|
899
|
+
summary: 组件目录
|
|
900
|
+
description: 官方组件与当前空间的私有组件,含最新版本和发布状态。用于选择组件或检查重名。
|
|
901
|
+
x-easyv-status: available
|
|
902
|
+
x-easyv-scope: component:read
|
|
903
|
+
parameters:
|
|
904
|
+
- name: keyword
|
|
905
|
+
in: query
|
|
906
|
+
schema: {type: string}
|
|
907
|
+
description: 按名称或 module 过滤。
|
|
908
|
+
responses:
|
|
909
|
+
'200':
|
|
910
|
+
description: 组件列表。
|
|
911
|
+
content:
|
|
912
|
+
application/json:
|
|
913
|
+
schema:
|
|
914
|
+
type: object
|
|
915
|
+
required: [components]
|
|
916
|
+
properties:
|
|
917
|
+
components:
|
|
918
|
+
type: array
|
|
919
|
+
items: {$ref: '#/components/schemas/ComponentCatalogItem'}
|
|
920
|
+
'401': {$ref: '#/components/responses/Unauthorized'}
|
|
921
|
+
'403': {$ref: '#/components/responses/Forbidden'}
|
|
922
|
+
post:
|
|
923
|
+
operationId: publishComponent
|
|
924
|
+
tags: [组件]
|
|
925
|
+
summary: 上传空间组件包
|
|
926
|
+
description: |
|
|
927
|
+
上传 `easyv pack` 产出的组件包(字段名 `file`)。
|
|
928
|
+
版本必须高于空间内已有版本,且不能与平台组件重名。上传后即可在大屏中使用。
|
|
929
|
+
x-easyv-status: available
|
|
930
|
+
x-easyv-scope: component:write
|
|
931
|
+
requestBody:
|
|
932
|
+
required: true
|
|
933
|
+
content:
|
|
934
|
+
multipart/form-data:
|
|
935
|
+
schema:
|
|
936
|
+
type: object
|
|
937
|
+
required: [file]
|
|
938
|
+
properties:
|
|
939
|
+
file: {type: string, format: binary, description: 组件包。}
|
|
940
|
+
responses:
|
|
941
|
+
'201':
|
|
942
|
+
description: 已上传。
|
|
943
|
+
content:
|
|
944
|
+
application/json:
|
|
945
|
+
schema: {$ref: '#/components/schemas/PublishedComponent'}
|
|
946
|
+
'400': {$ref: '#/components/responses/BadRequest'}
|
|
947
|
+
'401': {$ref: '#/components/responses/Unauthorized'}
|
|
948
|
+
'403': {$ref: '#/components/responses/Forbidden'}
|
|
949
|
+
'409':
|
|
950
|
+
description: '`COMPONENT_NAME_CONFLICT` 或 `COMPONENT_VERSION_NOT_HIGHER`。'
|
|
951
|
+
content:
|
|
952
|
+
application/json:
|
|
953
|
+
schema: {$ref: '#/components/schemas/Error'}
|
|
954
|
+
|
|
955
|
+
/data-sources:
|
|
956
|
+
get:
|
|
957
|
+
operationId: listDataSources
|
|
958
|
+
tags: [数据源]
|
|
959
|
+
summary: 数据源列表
|
|
960
|
+
description: 当前团队的数据源,不返回密码。
|
|
961
|
+
x-easyv-status: available
|
|
962
|
+
x-easyv-scope: datasource:read
|
|
963
|
+
parameters:
|
|
964
|
+
- name: dataType
|
|
965
|
+
in: query
|
|
966
|
+
schema: {type: string}
|
|
967
|
+
description: 按类型过滤,如 `mysql`。
|
|
968
|
+
responses:
|
|
969
|
+
'200':
|
|
970
|
+
description: 数据源列表。
|
|
971
|
+
content:
|
|
972
|
+
application/json:
|
|
973
|
+
schema:
|
|
974
|
+
type: object
|
|
975
|
+
properties:
|
|
976
|
+
dataSources:
|
|
977
|
+
type: array
|
|
978
|
+
items: {$ref: '#/components/schemas/DataSource'}
|
|
979
|
+
'401': {$ref: '#/components/responses/Unauthorized'}
|
|
980
|
+
'403': {$ref: '#/components/responses/Forbidden'}
|
|
981
|
+
post:
|
|
982
|
+
operationId: createDataSource
|
|
983
|
+
tags: [数据源]
|
|
984
|
+
summary: 新建数据源
|
|
985
|
+
description: 配置结构与平台创建数据源一致,新建后可在编辑器中使用。
|
|
986
|
+
x-easyv-status: available
|
|
987
|
+
x-easyv-scope: datasource:write
|
|
988
|
+
requestBody:
|
|
989
|
+
required: true
|
|
990
|
+
content:
|
|
991
|
+
application/json:
|
|
992
|
+
schema: {$ref: '#/components/schemas/DataSourceInput'}
|
|
993
|
+
responses:
|
|
994
|
+
'201':
|
|
995
|
+
description: 已创建。
|
|
996
|
+
content:
|
|
997
|
+
application/json:
|
|
998
|
+
schema: {$ref: '#/components/schemas/DataSource'}
|
|
999
|
+
'400': {$ref: '#/components/responses/BadRequest'}
|
|
1000
|
+
'401': {$ref: '#/components/responses/Unauthorized'}
|
|
1001
|
+
'409':
|
|
1002
|
+
description: '`DATASOURCE_EXISTS`:同名数据源已存在。'
|
|
1003
|
+
content:
|
|
1004
|
+
application/json:
|
|
1005
|
+
schema: {$ref: '#/components/schemas/Error'}
|
|
1006
|
+
|
|
1007
|
+
/data-sources/{dataId}:
|
|
1008
|
+
get:
|
|
1009
|
+
operationId: getDataSource
|
|
1010
|
+
tags: [数据源]
|
|
1011
|
+
summary: 数据源详情
|
|
1012
|
+
description: 返回配置,但密码等敏感字段固定为 `******`。
|
|
1013
|
+
x-easyv-status: available
|
|
1014
|
+
x-easyv-scope: datasource:read
|
|
1015
|
+
parameters:
|
|
1016
|
+
- {$ref: '#/components/parameters/DataId'}
|
|
1017
|
+
responses:
|
|
1018
|
+
'200':
|
|
1019
|
+
description: 数据源详情。
|
|
1020
|
+
content:
|
|
1021
|
+
application/json:
|
|
1022
|
+
schema: {$ref: '#/components/schemas/DataSource'}
|
|
1023
|
+
'401': {$ref: '#/components/responses/Unauthorized'}
|
|
1024
|
+
'404':
|
|
1025
|
+
description: '`DATASOURCE_NOT_FOUND`。'
|
|
1026
|
+
content:
|
|
1027
|
+
application/json:
|
|
1028
|
+
schema: {$ref: '#/components/schemas/Error'}
|
|
1029
|
+
patch:
|
|
1030
|
+
operationId: updateDataSource
|
|
1031
|
+
tags: [数据源]
|
|
1032
|
+
summary: 更新数据源
|
|
1033
|
+
description: 不传 `password` 时保留原密码。
|
|
1034
|
+
x-easyv-status: available
|
|
1035
|
+
x-easyv-scope: datasource:write
|
|
1036
|
+
parameters:
|
|
1037
|
+
- {$ref: '#/components/parameters/DataId'}
|
|
1038
|
+
requestBody:
|
|
1039
|
+
content:
|
|
1040
|
+
application/json:
|
|
1041
|
+
schema: {$ref: '#/components/schemas/DataSourceInput'}
|
|
1042
|
+
responses:
|
|
1043
|
+
'200':
|
|
1044
|
+
description: 已更新。
|
|
1045
|
+
content:
|
|
1046
|
+
application/json:
|
|
1047
|
+
schema: {$ref: '#/components/schemas/DataSource'}
|
|
1048
|
+
'401': {$ref: '#/components/responses/Unauthorized'}
|
|
1049
|
+
'404':
|
|
1050
|
+
description: '`DATASOURCE_NOT_FOUND`。'
|
|
1051
|
+
content:
|
|
1052
|
+
application/json:
|
|
1053
|
+
schema: {$ref: '#/components/schemas/Error'}
|
|
1054
|
+
delete:
|
|
1055
|
+
operationId: deleteDataSource
|
|
1056
|
+
tags: [数据源]
|
|
1057
|
+
summary: 删除数据源
|
|
1058
|
+
x-easyv-status: available
|
|
1059
|
+
x-easyv-scope: datasource:write
|
|
1060
|
+
parameters:
|
|
1061
|
+
- {$ref: '#/components/parameters/DataId'}
|
|
1062
|
+
responses:
|
|
1063
|
+
'200':
|
|
1064
|
+
description: 已删除。
|
|
1065
|
+
'401': {$ref: '#/components/responses/Unauthorized'}
|
|
1066
|
+
'404':
|
|
1067
|
+
description: '`DATASOURCE_NOT_FOUND`。'
|
|
1068
|
+
content:
|
|
1069
|
+
application/json:
|
|
1070
|
+
schema: {$ref: '#/components/schemas/Error'}
|
|
1071
|
+
|
|
1072
|
+
/data-sources/{dataId}/test:
|
|
1073
|
+
post:
|
|
1074
|
+
operationId: testDataSource
|
|
1075
|
+
tags: [数据源]
|
|
1076
|
+
summary: 测试数据源连接
|
|
1077
|
+
description: 转发到数据源服务。未配置 `OPENAPI_DS_BASE_URL` 时返回 `DATASOURCE_SERVICE_UNAVAILABLE`。
|
|
1078
|
+
x-easyv-status: available
|
|
1079
|
+
x-easyv-scope: datasource:write
|
|
1080
|
+
parameters:
|
|
1081
|
+
- {$ref: '#/components/parameters/DataId'}
|
|
1082
|
+
responses:
|
|
1083
|
+
'200': {description: 连接结果。}
|
|
1084
|
+
'401': {$ref: '#/components/responses/Unauthorized'}
|
|
1085
|
+
'502':
|
|
1086
|
+
description: '`DATASOURCE_SERVICE_UNAVAILABLE`。'
|
|
1087
|
+
content:
|
|
1088
|
+
application/json:
|
|
1089
|
+
schema: {$ref: '#/components/schemas/Error'}
|
|
1090
|
+
|
|
1091
|
+
/data-sources/{dataId}/tables:
|
|
1092
|
+
get:
|
|
1093
|
+
operationId: listDataSourceTables
|
|
1094
|
+
tags: [数据源]
|
|
1095
|
+
summary: 数据源的表列表
|
|
1096
|
+
x-easyv-status: available
|
|
1097
|
+
x-easyv-scope: datasource:read
|
|
1098
|
+
parameters:
|
|
1099
|
+
- {$ref: '#/components/parameters/DataId'}
|
|
1100
|
+
responses:
|
|
1101
|
+
'200': {description: 表列表。}
|
|
1102
|
+
'401': {$ref: '#/components/responses/Unauthorized'}
|
|
1103
|
+
|
|
1104
|
+
/data-sources/{dataId}/columns:
|
|
1105
|
+
post:
|
|
1106
|
+
operationId: listDataSourceColumns
|
|
1107
|
+
tags: [数据源]
|
|
1108
|
+
summary: 表字段
|
|
1109
|
+
x-easyv-status: available
|
|
1110
|
+
x-easyv-scope: datasource:read
|
|
1111
|
+
parameters:
|
|
1112
|
+
- {$ref: '#/components/parameters/DataId'}
|
|
1113
|
+
requestBody:
|
|
1114
|
+
content:
|
|
1115
|
+
application/json:
|
|
1116
|
+
schema:
|
|
1117
|
+
type: object
|
|
1118
|
+
properties:
|
|
1119
|
+
tables: {type: array, items: {type: object}, description: 要查询的表,每项含 `tableName`。}
|
|
1120
|
+
responses:
|
|
1121
|
+
'200': {description: 字段列表。}
|
|
1122
|
+
'401': {$ref: '#/components/responses/Unauthorized'}
|
|
1123
|
+
|
|
1124
|
+
/data-sources/{dataId}/preview:
|
|
1125
|
+
post:
|
|
1126
|
+
operationId: previewDataSource
|
|
1127
|
+
tags: [数据源]
|
|
1128
|
+
summary: 预览数据
|
|
1129
|
+
x-easyv-status: available
|
|
1130
|
+
x-easyv-scope: datasource:read
|
|
1131
|
+
parameters:
|
|
1132
|
+
- {$ref: '#/components/parameters/DataId'}
|
|
1133
|
+
requestBody:
|
|
1134
|
+
content:
|
|
1135
|
+
application/json:
|
|
1136
|
+
schema: {type: object, additionalProperties: true, description: 查询配置,透传给数据源服务。}
|
|
1137
|
+
responses:
|
|
1138
|
+
'200': {description: 数据。}
|
|
1139
|
+
'401': {$ref: '#/components/responses/Unauthorized'}
|
|
1140
|
+
|
|
1141
|
+
/screens/{screenId}/preview-token:
|
|
1142
|
+
post:
|
|
1143
|
+
operationId: issuePreviewToken
|
|
1144
|
+
tags: [预览]
|
|
1145
|
+
summary: 签发只读预览 token
|
|
1146
|
+
description: 10 分钟有效。CLI 用返回的 `previewPath` 打开预览页截图。
|
|
1147
|
+
x-easyv-status: available
|
|
1148
|
+
x-easyv-scope: screen:read
|
|
1149
|
+
parameters:
|
|
1150
|
+
- {$ref: '#/components/parameters/ScreenId'}
|
|
1151
|
+
responses:
|
|
1152
|
+
'200':
|
|
1153
|
+
description: 预览 token。
|
|
1154
|
+
content:
|
|
1155
|
+
application/json:
|
|
1156
|
+
schema: {$ref: '#/components/schemas/PreviewToken'}
|
|
1157
|
+
'401': {$ref: '#/components/responses/Unauthorized'}
|
|
1158
|
+
'404': {$ref: '#/components/responses/ScreenNotFound'}
|
|
1159
|
+
|
|
1160
|
+
/preview/{token}:
|
|
1161
|
+
get:
|
|
1162
|
+
operationId: readPreview
|
|
1163
|
+
tags: [预览]
|
|
1164
|
+
summary: 用预览 token 读取大屏文档
|
|
1165
|
+
description: 不需要 API Key。token 无效或过期分别返回 `PREVIEW_TOKEN_INVALID`、`PREVIEW_TOKEN_EXPIRED`。
|
|
1166
|
+
security: []
|
|
1167
|
+
x-easyv-status: available
|
|
1168
|
+
parameters:
|
|
1169
|
+
- name: token
|
|
1170
|
+
in: path
|
|
1171
|
+
required: true
|
|
1172
|
+
schema: {type: string}
|
|
1173
|
+
responses:
|
|
1174
|
+
'200':
|
|
1175
|
+
description: 大屏文档。
|
|
1176
|
+
content:
|
|
1177
|
+
application/json:
|
|
1178
|
+
schema: {$ref: '#/components/schemas/ScreenDocument'}
|
|
1179
|
+
'404':
|
|
1180
|
+
description: '`PREVIEW_TOKEN_INVALID`。'
|
|
1181
|
+
content:
|
|
1182
|
+
application/json:
|
|
1183
|
+
schema: {$ref: '#/components/schemas/Error'}
|
|
1184
|
+
'410':
|
|
1185
|
+
description: '`PREVIEW_TOKEN_EXPIRED`。'
|
|
1186
|
+
content:
|
|
1187
|
+
application/json:
|
|
1188
|
+
schema: {$ref: '#/components/schemas/Error'}
|
|
1189
|
+
|
|
1190
|
+
/auth/device/code:
|
|
1191
|
+
post:
|
|
1192
|
+
operationId: issueDeviceCode
|
|
1193
|
+
tags: [授权]
|
|
1194
|
+
summary: 申请设备码
|
|
1195
|
+
description: 不需要 API Key。返回设备码、用户码和授权页路径。
|
|
1196
|
+
security: []
|
|
1197
|
+
x-easyv-status: available
|
|
1198
|
+
responses:
|
|
1199
|
+
'200':
|
|
1200
|
+
description: 设备码。
|
|
1201
|
+
content:
|
|
1202
|
+
application/json:
|
|
1203
|
+
schema: {$ref: '#/components/schemas/DeviceCode'}
|
|
1204
|
+
|
|
1205
|
+
/auth/device/token:
|
|
1206
|
+
post:
|
|
1207
|
+
operationId: pollDeviceToken
|
|
1208
|
+
tags: [授权]
|
|
1209
|
+
summary: 用设备码换长期 API Key(旧版)
|
|
1210
|
+
description: |
|
|
1211
|
+
保留给还没升级的命令行。按 `interval` 轮询。用户尚未确认时返回 `AUTHORIZATION_PENDING`,应继续轮询。
|
|
1212
|
+
授权后只返回一次 `appId.secret`。新客户端改用 `/oauth/device` 和 `/oauth/token` 的设备码授权,拿到的是 1 小时访问令牌。
|
|
1213
|
+
同一次同意只能取走一种凭证。
|
|
1214
|
+
security: []
|
|
1215
|
+
x-easyv-status: available
|
|
1216
|
+
requestBody:
|
|
1217
|
+
required: true
|
|
1218
|
+
content:
|
|
1219
|
+
application/json:
|
|
1220
|
+
schema:
|
|
1221
|
+
type: object
|
|
1222
|
+
required: [deviceCode]
|
|
1223
|
+
properties:
|
|
1224
|
+
deviceCode: {type: string}
|
|
1225
|
+
responses:
|
|
1226
|
+
'200':
|
|
1227
|
+
description: token 与其绑定的空间、团队。
|
|
1228
|
+
content:
|
|
1229
|
+
application/json:
|
|
1230
|
+
schema: {$ref: '#/components/schemas/DeviceToken'}
|
|
1231
|
+
'400':
|
|
1232
|
+
description: '`AUTHORIZATION_PENDING`、`DEVICE_CODE_EXPIRED` 或 `DEVICE_CODE_INVALID`。'
|
|
1233
|
+
content:
|
|
1234
|
+
application/json:
|
|
1235
|
+
schema: {$ref: '#/components/schemas/Error'}
|
|
1236
|
+
|
|
1237
|
+
/assets:
|
|
1238
|
+
post:
|
|
1239
|
+
operationId: uploadAsset
|
|
1240
|
+
tags: [静态资源]
|
|
1241
|
+
summary: 上传一张组件素材
|
|
1242
|
+
description: |
|
|
1243
|
+
上传图片、音视频、字体或少量文本素材,写入与编辑器相同的对象存储。
|
|
1244
|
+
|
|
1245
|
+
调用方不指定存储路径。服务端生成 `spaces/{spaceId}/openapi-assets/{yyyyMM}/{随机名}{扩展名}`,不会覆盖已有文件。
|
|
1246
|
+
|
|
1247
|
+
返回两个地址:
|
|
1248
|
+
|
|
1249
|
+
- `path`:相对路径。写入组件配置或 `canvas.backgroundImage` 时用这个值
|
|
1250
|
+
- `url`:可直接访问的绝对地址,不要把它存进组件配置
|
|
1251
|
+
|
|
1252
|
+
限制(具体字节数以 `GET /meta` 的 `limits.assetMaxBytes` 为准,当前 20MB):
|
|
1253
|
+
|
|
1254
|
+
- 扩展名:`.png` `.jpg` `.jpeg` `.gif` `.webp` `.svg` `.bmp` `.ico` `.mp4` `.webm` `.mp3` `.wav` `.ttf` `.otf` `.woff` `.woff2` `.json` `.csv` `.txt`
|
|
1255
|
+
- 空文件视为未上传
|
|
1256
|
+
x-easyv-status: stable
|
|
1257
|
+
x-easyv-scope: asset:write
|
|
1258
|
+
requestBody:
|
|
1259
|
+
required: true
|
|
1260
|
+
content:
|
|
1261
|
+
multipart/form-data:
|
|
1262
|
+
schema:
|
|
1263
|
+
type: object
|
|
1264
|
+
required: [file]
|
|
1265
|
+
properties:
|
|
1266
|
+
file:
|
|
1267
|
+
type: string
|
|
1268
|
+
format: binary
|
|
1269
|
+
description: 表单字段名必须是 `file`。
|
|
1270
|
+
responses:
|
|
1271
|
+
'201':
|
|
1272
|
+
description: 上传成功
|
|
1273
|
+
content:
|
|
1274
|
+
application/json:
|
|
1275
|
+
schema: {$ref: '#/components/schemas/AssetUploaded'}
|
|
1276
|
+
example:
|
|
1277
|
+
path: spaces/10/openapi-assets/202611/Ab3xYz9kQ2LmNoPq.png
|
|
1278
|
+
url: https://dt-easyv-test.oss-cn-hangzhou.aliyuncs.com/spaces/10/openapi-assets/202611/Ab3xYz9kQ2LmNoPq.png
|
|
1279
|
+
fileName: poster.png
|
|
1280
|
+
size: 20480
|
|
1281
|
+
contentType: image/png
|
|
1282
|
+
'400':
|
|
1283
|
+
description: '`ASSET_FILE_REQUIRED`:没有 `file` 字段,或文件大小为 0。'
|
|
1284
|
+
content:
|
|
1285
|
+
application/json:
|
|
1286
|
+
schema: {$ref: '#/components/schemas/Error'}
|
|
1287
|
+
'401': {$ref: '#/components/responses/Unauthorized'}
|
|
1288
|
+
'403': {$ref: '#/components/responses/Forbidden'}
|
|
1289
|
+
'413':
|
|
1290
|
+
description: |
|
|
1291
|
+
文件超过 `limits.assetMaxBytes`。
|
|
1292
|
+
业务校验命中时 `code` 为 `ASSET_TOO_LARGE`(`details` 含 `size`、`maxBytes`);
|
|
1293
|
+
在进入业务前被解析器截断时 `code` 可能是 `DOCUMENT_TOO_LARGE`。
|
|
1294
|
+
content:
|
|
1295
|
+
application/json:
|
|
1296
|
+
schema: {$ref: '#/components/schemas/Error'}
|
|
1297
|
+
'415':
|
|
1298
|
+
description: '`ASSET_TYPE_NOT_ALLOWED`:扩展名不在白名单。`details.allowed` 为允许的扩展名列表。'
|
|
1299
|
+
content:
|
|
1300
|
+
application/json:
|
|
1301
|
+
schema: {$ref: '#/components/schemas/Error'}
|
|
1302
|
+
'500':
|
|
1303
|
+
description: '`ASSET_UPLOAD_FAILED`:对象存储写入失败。'
|
|
1304
|
+
content:
|
|
1305
|
+
application/json:
|
|
1306
|
+
schema: {$ref: '#/components/schemas/Error'}
|
|
1307
|
+
|
|
1308
|
+
/screens/{screenId}/share:
|
|
1309
|
+
get:
|
|
1310
|
+
operationId: getScreenShare
|
|
1311
|
+
tags: [发布]
|
|
1312
|
+
summary: 读取发布状态(不含密码和 Token)
|
|
1313
|
+
description: |
|
|
1314
|
+
查看大屏是否已发布、是否要求密码或 Token、分享类型和过期时间。
|
|
1315
|
+
不返回密码和 Token 明文。明文只在 `PUT /screens/{screenId}/publish` 的当次响应里出现。
|
|
1316
|
+
x-easyv-status: stable
|
|
1317
|
+
x-easyv-scope: screen:read
|
|
1318
|
+
parameters:
|
|
1319
|
+
- {$ref: '#/components/parameters/ScreenId'}
|
|
1320
|
+
responses:
|
|
1321
|
+
'200':
|
|
1322
|
+
description: 脱敏后的发布信息。从未发布时 `published` 为 `false`,其余开关为 `false`。
|
|
1323
|
+
content:
|
|
1324
|
+
application/json:
|
|
1325
|
+
schema: {$ref: '#/components/schemas/ShareInfo'}
|
|
1326
|
+
example:
|
|
1327
|
+
published: true
|
|
1328
|
+
needPassword: true
|
|
1329
|
+
needToken: false
|
|
1330
|
+
shareType: 1
|
|
1331
|
+
expiredAt: null
|
|
1332
|
+
'401': {$ref: '#/components/responses/Unauthorized'}
|
|
1333
|
+
'403': {$ref: '#/components/responses/Forbidden'}
|
|
1334
|
+
'404': {$ref: '#/components/responses/ScreenNotFound'}
|
|
1335
|
+
|
|
1336
|
+
/screens/{screenId}/publish:
|
|
1337
|
+
put:
|
|
1338
|
+
operationId: publishScreen
|
|
1339
|
+
tags: [发布]
|
|
1340
|
+
summary: 发布大屏或更新分享设置
|
|
1341
|
+
description: |
|
|
1342
|
+
生成或复用分享链接,并写入发布配置。同步完成,不进入异步任务。
|
|
1343
|
+
|
|
1344
|
+
服务端固定为普通分享(`shareType = 1`)。不要传 `shareType`,该字段会被忽略;
|
|
1345
|
+
缓存发布(`shareType = 2`)未开放。若最终没有生成分享 id,返回 `400 PUBLISH_CACHE_NOT_SUPPORTED`。
|
|
1346
|
+
|
|
1347
|
+
规则:
|
|
1348
|
+
|
|
1349
|
+
- 只能发布根大屏,子屏返回 `400 PUBLISH_ROOT_ONLY`
|
|
1350
|
+
- `needPassword` 与 `needToken` 不能同时为 `true`,否则 `400 PUBLISH_OPTION_CONFLICT`
|
|
1351
|
+
- 开启密码或 Token 但不传 `password` / `token` 时,由服务端生成,并在本次响应里返回
|
|
1352
|
+
- `password`、`token` 长度 6~20
|
|
1353
|
+
- `expiredAt` 需要高级版及以上,否则 `403 PUBLISH_OPTION_NOT_ALLOWED`(`details.option` 为 `expiredAt`)
|
|
1354
|
+
- 续费版产品不能发布,返回 `403 PUBLISH_NOT_ALLOWED_FOR_PLAN`
|
|
1355
|
+
- `republish: true` 会换一条新链接,旧链接立即失效
|
|
1356
|
+
- `path` 是相对路径,域名由调用方自己拼
|
|
1357
|
+
|
|
1358
|
+
未出现在 body 里的字段保持原配置,不会被重置。
|
|
1359
|
+
x-easyv-status: beta
|
|
1360
|
+
x-easyv-scope: screen:publish
|
|
1361
|
+
parameters:
|
|
1362
|
+
- {$ref: '#/components/parameters/ScreenId'}
|
|
1363
|
+
requestBody:
|
|
1364
|
+
required: true
|
|
1365
|
+
content:
|
|
1366
|
+
application/json:
|
|
1367
|
+
schema: {$ref: '#/components/schemas/PublishRequest'}
|
|
1368
|
+
examples:
|
|
1369
|
+
public:
|
|
1370
|
+
summary: 公开分享
|
|
1371
|
+
value: {needPassword: false, needToken: false}
|
|
1372
|
+
password:
|
|
1373
|
+
summary: 指定访问密码
|
|
1374
|
+
value: {needPassword: true, password: abc12345}
|
|
1375
|
+
responses:
|
|
1376
|
+
'200':
|
|
1377
|
+
description: 已发布。`password` / `token` 仅在本次对应开关打开且有值时返回。
|
|
1378
|
+
content:
|
|
1379
|
+
application/json:
|
|
1380
|
+
schema: {$ref: '#/components/schemas/PublishResult'}
|
|
1381
|
+
example:
|
|
1382
|
+
published: true
|
|
1383
|
+
shareId: 8f3c1a2b4d5e6f70
|
|
1384
|
+
path: /shareScreen/8f3c1a2b4d5e6f70
|
|
1385
|
+
needPassword: true
|
|
1386
|
+
needToken: false
|
|
1387
|
+
password: abc12345
|
|
1388
|
+
expiredAt: null
|
|
1389
|
+
'400':
|
|
1390
|
+
description: |
|
|
1391
|
+
- `PUBLISH_ROOT_ONLY`
|
|
1392
|
+
- `PUBLISH_OPTION_CONFLICT`
|
|
1393
|
+
- `PUBLISH_CACHE_NOT_SUPPORTED`
|
|
1394
|
+
- `BAD_REQUEST`:密码或 Token 长度不在 6~20
|
|
1395
|
+
content:
|
|
1396
|
+
application/json:
|
|
1397
|
+
schema: {$ref: '#/components/schemas/Error'}
|
|
1398
|
+
'401': {$ref: '#/components/responses/Unauthorized'}
|
|
1399
|
+
'403':
|
|
1400
|
+
description: |
|
|
1401
|
+
- `SCOPE_FORBIDDEN` / `SPACE_PERMISSION_FORBIDDEN` / `SPACE_PERMISSION_EXPIRED`
|
|
1402
|
+
- `PUBLISH_NOT_ALLOWED_FOR_PLAN`
|
|
1403
|
+
- `PUBLISH_OPTION_NOT_ALLOWED`
|
|
1404
|
+
content:
|
|
1405
|
+
application/json:
|
|
1406
|
+
schema: {$ref: '#/components/schemas/Error'}
|
|
1407
|
+
'404': {$ref: '#/components/responses/ScreenNotFound'}
|
|
1408
|
+
delete:
|
|
1409
|
+
operationId: unpublishScreen
|
|
1410
|
+
tags: [发布]
|
|
1411
|
+
summary: 取消发布
|
|
1412
|
+
description: 关闭分享。已发出的分享链接立即失效。大屏本身和文档内容保留。
|
|
1413
|
+
x-easyv-status: beta
|
|
1414
|
+
x-easyv-scope: screen:publish
|
|
1415
|
+
parameters:
|
|
1416
|
+
- {$ref: '#/components/parameters/ScreenId'}
|
|
1417
|
+
responses:
|
|
1418
|
+
'204':
|
|
1419
|
+
description: 已取消发布,无响应体。
|
|
1420
|
+
'401': {$ref: '#/components/responses/Unauthorized'}
|
|
1421
|
+
'403': {$ref: '#/components/responses/Forbidden'}
|
|
1422
|
+
'404': {$ref: '#/components/responses/ScreenNotFound'}
|
|
1423
|
+
|
|
1424
|
+
/screens/{screenId}/versions:
|
|
1425
|
+
get:
|
|
1426
|
+
operationId: listScreenVersions
|
|
1427
|
+
tags: [版本]
|
|
1428
|
+
summary: 列出版本快照
|
|
1429
|
+
description: |
|
|
1430
|
+
规划中的整屏快照列表(上限 3 个)。当前固定返回 `501 NOT_IMPLEMENTED`,`details.phase` 为 `Phase 2.2`。
|
|
1431
|
+
x-easyv-status: planned
|
|
1432
|
+
x-easyv-scope: screen:version
|
|
1433
|
+
parameters:
|
|
1434
|
+
- {$ref: '#/components/parameters/ScreenId'}
|
|
1435
|
+
responses:
|
|
1436
|
+
'200':
|
|
1437
|
+
description: 尚未实现。实现后的结构见 schema,调用方不要依赖这次响应。
|
|
1438
|
+
content:
|
|
1439
|
+
application/json:
|
|
1440
|
+
schema: {$ref: '#/components/schemas/VersionList'}
|
|
1441
|
+
'401': {$ref: '#/components/responses/Unauthorized'}
|
|
1442
|
+
'403': {$ref: '#/components/responses/Forbidden'}
|
|
1443
|
+
'501': {$ref: '#/components/responses/NotImplemented'}
|
|
1444
|
+
post:
|
|
1445
|
+
operationId: createScreenVersion
|
|
1446
|
+
tags: [版本]
|
|
1447
|
+
summary: 创建整屏快照
|
|
1448
|
+
description: |
|
|
1449
|
+
规划中:把整屏序列化为快照,由调用方显式触发,不会在写文档时自动创建。
|
|
1450
|
+
当前固定返回 `501 NOT_IMPLEMENTED`。
|
|
1451
|
+
x-easyv-status: planned
|
|
1452
|
+
x-easyv-scope: screen:version
|
|
1453
|
+
parameters:
|
|
1454
|
+
- {$ref: '#/components/parameters/ScreenId'}
|
|
1455
|
+
requestBody:
|
|
1456
|
+
required: false
|
|
1457
|
+
content:
|
|
1458
|
+
application/json:
|
|
1459
|
+
schema: {$ref: '#/components/schemas/CreateVersionRequest'}
|
|
1460
|
+
responses:
|
|
1461
|
+
'201':
|
|
1462
|
+
description: 尚未实现。
|
|
1463
|
+
content:
|
|
1464
|
+
application/json:
|
|
1465
|
+
schema: {$ref: '#/components/schemas/VersionSummary'}
|
|
1466
|
+
'401': {$ref: '#/components/responses/Unauthorized'}
|
|
1467
|
+
'403': {$ref: '#/components/responses/Forbidden'}
|
|
1468
|
+
'501': {$ref: '#/components/responses/NotImplemented'}
|
|
1469
|
+
|
|
1470
|
+
/screens/{screenId}/versions/{versionId}/rollback:
|
|
1471
|
+
post:
|
|
1472
|
+
operationId: rollbackScreenVersion
|
|
1473
|
+
tags: [版本]
|
|
1474
|
+
summary: 回滚到指定快照
|
|
1475
|
+
description: |
|
|
1476
|
+
规划中:用快照覆盖当前大屏,并尽量保持组件 id 与文档 key 不变。
|
|
1477
|
+
当前固定返回 `501 NOT_IMPLEMENTED`。
|
|
1478
|
+
x-easyv-status: planned
|
|
1479
|
+
x-easyv-scope: screen:version
|
|
1480
|
+
parameters:
|
|
1481
|
+
- {$ref: '#/components/parameters/ScreenId'}
|
|
1482
|
+
- name: versionId
|
|
1483
|
+
in: path
|
|
1484
|
+
required: true
|
|
1485
|
+
description: 快照 id,来自版本列表的 `id`。
|
|
1486
|
+
schema: {type: integer, format: int64, minimum: 1}
|
|
1487
|
+
responses:
|
|
1488
|
+
'204':
|
|
1489
|
+
description: 尚未实现。
|
|
1490
|
+
'401': {$ref: '#/components/responses/Unauthorized'}
|
|
1491
|
+
'403': {$ref: '#/components/responses/Forbidden'}
|
|
1492
|
+
'501': {$ref: '#/components/responses/NotImplemented'}
|
|
1493
|
+
|
|
1494
|
+
/jobs/{jobId}:
|
|
1495
|
+
get:
|
|
1496
|
+
operationId: getJob
|
|
1497
|
+
tags: [异步任务]
|
|
1498
|
+
summary: 查询异步任务
|
|
1499
|
+
description: |
|
|
1500
|
+
预留给以后的缓存发布、渲染等长任务。当前固定返回 `501 NOT_IMPLEMENTED`,`details.phase` 为 `Phase 2`。
|
|
1501
|
+
现有的发布和文档写入都是同步的,不需要轮询本接口。
|
|
1502
|
+
x-easyv-status: planned
|
|
1503
|
+
parameters:
|
|
1504
|
+
- name: jobId
|
|
1505
|
+
in: path
|
|
1506
|
+
required: true
|
|
1507
|
+
description: 任务 id。当前没有任何接口会返回它。
|
|
1508
|
+
schema: {type: string}
|
|
1509
|
+
responses:
|
|
1510
|
+
'200':
|
|
1511
|
+
description: 尚未实现。
|
|
1512
|
+
content:
|
|
1513
|
+
application/json:
|
|
1514
|
+
schema: {$ref: '#/components/schemas/Job'}
|
|
1515
|
+
'401': {$ref: '#/components/responses/Unauthorized'}
|
|
1516
|
+
'501': {$ref: '#/components/responses/NotImplemented'}
|
|
1517
|
+
|
|
1518
|
+
components:
|
|
1519
|
+
securitySchemes:
|
|
1520
|
+
bearerAuth:
|
|
1521
|
+
type: http
|
|
1522
|
+
scheme: bearer
|
|
1523
|
+
description: |
|
|
1524
|
+
值为 `<appId>.<secret>`,不要再套一层引号。
|
|
1525
|
+
示例:`Authorization: Bearer ev_a1b2c3d4e5f60718.0123456789abcdef0123456789abcdef01234567`
|
|
1526
|
+
|
|
1527
|
+
parameters:
|
|
1528
|
+
ScreenId:
|
|
1529
|
+
name: screenId
|
|
1530
|
+
in: path
|
|
1531
|
+
required: true
|
|
1532
|
+
description: 大屏 id。必须是当前 Key 所在团队中的大屏,否则 404。
|
|
1533
|
+
schema: {type: integer, format: int64, minimum: 1}
|
|
1534
|
+
DataId:
|
|
1535
|
+
name: dataId
|
|
1536
|
+
in: path
|
|
1537
|
+
required: true
|
|
1538
|
+
description: 数据源 id。必须属于当前 Key 所在团队,否则 404。
|
|
1539
|
+
schema: {type: string}
|
|
1540
|
+
IfMatch:
|
|
1541
|
+
name: If-Match
|
|
1542
|
+
in: header
|
|
1543
|
+
required: false
|
|
1544
|
+
description: |
|
|
1545
|
+
读取文档时拿到的 revision。可带双引号或 `W/` 前缀,服务端会去掉后再比较。
|
|
1546
|
+
与 body 里的 `revision` 同时存在时,以本请求头为准。不传且 body 也没有 revision 时不做乐观锁。
|
|
1547
|
+
schema: {type: string}
|
|
1548
|
+
example: '"9f2c1ab34de5f607"'
|
|
1549
|
+
|
|
1550
|
+
responses:
|
|
1551
|
+
Unauthorized:
|
|
1552
|
+
description: |
|
|
1553
|
+
- `UNAUTHORIZED`:没有 `Authorization`,或不是 `Bearer <appId>.<secret>`
|
|
1554
|
+
- `TOKEN_EXPIRED`:Key 已禁用或不存在
|
|
1555
|
+
content:
|
|
1556
|
+
application/json:
|
|
1557
|
+
schema: {$ref: '#/components/schemas/Error'}
|
|
1558
|
+
Forbidden:
|
|
1559
|
+
description: |
|
|
1560
|
+
- `SCOPE_FORBIDDEN`:Key 没有该接口要求的 scope
|
|
1561
|
+
- `SPACE_PERMISSION_FORBIDDEN`:空间角色不允许做这件事
|
|
1562
|
+
- `SPACE_PERMISSION_EXPIRED`:空间权限已过期
|
|
1563
|
+
- `TEAM_FORBIDDEN`:Key 绑定的用户不在该团队
|
|
1564
|
+
content:
|
|
1565
|
+
application/json:
|
|
1566
|
+
schema: {$ref: '#/components/schemas/Error'}
|
|
1567
|
+
BadRequest:
|
|
1568
|
+
description: '`BAD_REQUEST`:查询参数或 body 未通过类型、范围、长度校验。'
|
|
1569
|
+
content:
|
|
1570
|
+
application/json:
|
|
1571
|
+
schema: {$ref: '#/components/schemas/Error'}
|
|
1572
|
+
ScreenNotFound:
|
|
1573
|
+
description: '`SCREEN_NOT_FOUND`:大屏不存在,或不属于当前 Key 的团队。'
|
|
1574
|
+
content:
|
|
1575
|
+
application/json:
|
|
1576
|
+
schema: {$ref: '#/components/schemas/Error'}
|
|
1577
|
+
RevisionConflict:
|
|
1578
|
+
description: |
|
|
1579
|
+
`REVISION_CONFLICT`:提交的 revision 与当前文档不一致。
|
|
1580
|
+
`details.expected` 是请求里的值,`details.actual` 是服务端当前值。重新 `GET` 文档后再提交。
|
|
1581
|
+
content:
|
|
1582
|
+
application/json:
|
|
1583
|
+
schema: {$ref: '#/components/schemas/Error'}
|
|
1584
|
+
example:
|
|
1585
|
+
code: REVISION_CONFLICT
|
|
1586
|
+
message: 文档已被修改,请重新拉取后再提交
|
|
1587
|
+
details: {expected: 9f2c1ab34de5f607, actual: a0b1c2d3e4f50617}
|
|
1588
|
+
requestId: ''
|
|
1589
|
+
NotImplemented:
|
|
1590
|
+
description: '`NOT_IMPLEMENTED`:接口在规划中,当前版本没有业务逻辑。'
|
|
1591
|
+
content:
|
|
1592
|
+
application/json:
|
|
1593
|
+
schema: {$ref: '#/components/schemas/Error'}
|
|
1594
|
+
example:
|
|
1595
|
+
code: NOT_IMPLEMENTED
|
|
1596
|
+
message: 接口尚未实现
|
|
1597
|
+
details: {phase: Phase 2}
|
|
1598
|
+
requestId: ''
|
|
1599
|
+
|
|
1600
|
+
schemas:
|
|
1601
|
+
OAuthAuthorizationServerMetadata:
|
|
1602
|
+
type: object
|
|
1603
|
+
required: [issuer, authorization_endpoint, token_endpoint, registration_endpoint, response_types_supported, grant_types_supported, code_challenge_methods_supported]
|
|
1604
|
+
properties:
|
|
1605
|
+
issuer: {type: string}
|
|
1606
|
+
authorization_endpoint: {type: string, description: 工作台授权页 `/openapi/authorize`}
|
|
1607
|
+
token_endpoint: {type: string}
|
|
1608
|
+
registration_endpoint: {type: string}
|
|
1609
|
+
revocation_endpoint: {type: string}
|
|
1610
|
+
device_authorization_endpoint: {type: string, description: RFC 8628 设备码授权,`/oauth/device`}
|
|
1611
|
+
response_types_supported: {type: array, items: {type: string}}
|
|
1612
|
+
grant_types_supported: {type: array, items: {type: string}}
|
|
1613
|
+
code_challenge_methods_supported: {type: array, items: {type: string}}
|
|
1614
|
+
token_endpoint_auth_methods_supported: {type: array, items: {type: string}}
|
|
1615
|
+
scopes_supported: {type: array, items: {type: string}}
|
|
1616
|
+
OAuthClientRegistration:
|
|
1617
|
+
type: object
|
|
1618
|
+
required: [redirect_uris]
|
|
1619
|
+
properties:
|
|
1620
|
+
client_name: {type: string}
|
|
1621
|
+
redirect_uris: {type: array, items: {type: string}}
|
|
1622
|
+
grant_types: {type: array, items: {type: string}}
|
|
1623
|
+
response_types: {type: array, items: {type: string}}
|
|
1624
|
+
token_endpoint_auth_method: {type: string, enum: [none]}
|
|
1625
|
+
OAuthClientInformation:
|
|
1626
|
+
type: object
|
|
1627
|
+
required: [client_id, redirect_uris, token_endpoint_auth_method]
|
|
1628
|
+
properties:
|
|
1629
|
+
client_id: {type: string}
|
|
1630
|
+
client_name: {type: string}
|
|
1631
|
+
redirect_uris: {type: array, items: {type: string}}
|
|
1632
|
+
grant_types: {type: array, items: {type: string}}
|
|
1633
|
+
response_types: {type: array, items: {type: string}}
|
|
1634
|
+
token_endpoint_auth_method: {type: string}
|
|
1635
|
+
OAuthTokenResponse:
|
|
1636
|
+
type: object
|
|
1637
|
+
required: [access_token, token_type, expires_in, refresh_token]
|
|
1638
|
+
properties:
|
|
1639
|
+
access_token: {type: string, description: 前缀 oat_,1 小时有效}
|
|
1640
|
+
token_type: {type: string, enum: [Bearer]}
|
|
1641
|
+
expires_in: {type: integer, description: 秒}
|
|
1642
|
+
refresh_token: {type: string, description: 前缀 ort_,30 天,每次刷新轮换并顺延}
|
|
1643
|
+
scope: {type: string, description: 空格分隔}
|
|
1644
|
+
Error:
|
|
1645
|
+
type: object
|
|
1646
|
+
description: |
|
|
1647
|
+
所有失败响应的正文。按 `code` 分支。
|
|
1648
|
+
|
|
1649
|
+
| code | HTTP | 含义 |
|
|
1650
|
+
| --- | --- | --- |
|
|
1651
|
+
| `UNAUTHORIZED` | 401 | 缺少或无法解析访问凭证 |
|
|
1652
|
+
| `TOKEN_EXPIRED` | 401 | 凭证不存在或已禁用 |
|
|
1653
|
+
| `UNTRUSTED_HEADER` | 400 | 请求带了内部身份头。`details.headers` 列出这些头 |
|
|
1654
|
+
| `SCOPE_FORBIDDEN` | 403 | Key 的 scope 不够 |
|
|
1655
|
+
| `SPACE_PERMISSION_FORBIDDEN` | 403 | 没有对应的空间权限 |
|
|
1656
|
+
| `SPACE_PERMISSION_EXPIRED` | 403 | 空间权限已过期 |
|
|
1657
|
+
| `TEAM_FORBIDDEN` | 403 | 不能访问 Key 绑定的团队 |
|
|
1658
|
+
| `TEAM_REQUIRED` | 400 | 凭证没有绑定团队 |
|
|
1659
|
+
| `SCREEN_NOT_FOUND` | 404 | 大屏不存在或不属于当前团队 |
|
|
1660
|
+
| `GROUP_NOT_FOUND` | 404 | 分组不存在或不属于当前团队 |
|
|
1661
|
+
| `SCREEN_QUOTA_EXCEEDED` | 429 | 大屏数量达到空间上限 |
|
|
1662
|
+
| `REVISION_CONFLICT` | 409 | revision 与当前文档不一致 |
|
|
1663
|
+
| `SCHEMA_VIOLATION` | 400 | 文档缺少必填结构。`details.issues` |
|
|
1664
|
+
| `UNSUPPORTED_CHANGE` | 400 | 文档 diff 含未支持的变更,未落库 |
|
|
1665
|
+
| `UNSUPPORTED_OPERATION` | 400 | operations 含未支持的操作,未落库 |
|
|
1666
|
+
| `DOCUMENT_TOO_LARGE` | 413 | 请求体超过限制(也用作上传在解析阶段被截断时的码) |
|
|
1667
|
+
| `PUBLISH_ROOT_ONLY` | 400 | 只有根大屏可以发布 |
|
|
1668
|
+
| `PUBLISH_OPTION_CONFLICT` | 400 | 密码和 Token 不能同时开启 |
|
|
1669
|
+
| `PUBLISH_NOT_ALLOWED_FOR_PLAN` | 403 | 当前产品版本不能发布 |
|
|
1670
|
+
| `PUBLISH_OPTION_NOT_ALLOWED` | 403 | 当前版本不能使用该发布选项 |
|
|
1671
|
+
| `PUBLISH_CACHE_NOT_SUPPORTED` | 400 | 不能走缓存发布,或没有生成分享链接 |
|
|
1672
|
+
| `COMPONENT_NOT_FOUND` | 404 | 组件或版本不存在 |
|
|
1673
|
+
| `COMPONENT_SCHEMA_UNAVAILABLE` | 422 | 无法从组件脚本提取配置 |
|
|
1674
|
+
| `COMPONENT_CONFIG_INVALID` | 400 | 新增组件的 `config` 含默认配置里没有的路径,`details.elements[].unknownPaths` 列出路径 |
|
|
1675
|
+
| `COMPONENT_PRESET_REQUIRED` | 400 | 组件需要先选预设,暂不支持通过 OpenAPI 新增 |
|
|
1676
|
+
| `ASSET_FILE_REQUIRED` | 400 | 没有上传文件或文件为空 |
|
|
1677
|
+
| `ASSET_TYPE_NOT_ALLOWED` | 415 | 扩展名不在白名单 |
|
|
1678
|
+
| `ASSET_TOO_LARGE` | 413 | 文件超过 `limits.assetMaxBytes` |
|
|
1679
|
+
| `ASSET_UPLOAD_FAILED` | 500 | 对象存储写入失败 |
|
|
1680
|
+
| `RATE_LIMITED` | 429 | 请求过于频繁 |
|
|
1681
|
+
| `NOT_IMPLEMENTED` | 501 | 接口尚未实现 |
|
|
1682
|
+
| `BAD_REQUEST` | 400 | 参数校验失败,或未能归类的 4xx |
|
|
1683
|
+
| `INTERNAL_ERROR` | 500 | 未捕获的服务端异常 |
|
|
1684
|
+
|
|
1685
|
+
空间权限的历史数字错误码若没有映射,会变成 `E` 加原数字码,例如 `E403011`。
|
|
1686
|
+
required: [code, message, requestId]
|
|
1687
|
+
properties:
|
|
1688
|
+
code:
|
|
1689
|
+
type: string
|
|
1690
|
+
description: 稳定错误码,见本 schema 说明中的表。
|
|
1691
|
+
message:
|
|
1692
|
+
type: string
|
|
1693
|
+
description: 给人看的说明,会随文案调整,不要用来做判断。
|
|
1694
|
+
details:
|
|
1695
|
+
description: 补充数据。没有额外信息时省略。
|
|
1696
|
+
requestId:
|
|
1697
|
+
type: string
|
|
1698
|
+
description: 请求头 `x-request-id` 的回传;调用方没传时为空字符串。
|
|
1699
|
+
traceId:
|
|
1700
|
+
type: string
|
|
1701
|
+
description: 链路追踪 id。没有活跃 span 时省略。
|
|
1702
|
+
|
|
1703
|
+
ApiKeyContext:
|
|
1704
|
+
type: object
|
|
1705
|
+
description: 当前 API Key 绑定的身份。一把 Key 只能操作这里的一个空间、一个团队。
|
|
1706
|
+
required: [appId, spaceId, spaceName, teamId, teamName, scopes]
|
|
1707
|
+
properties:
|
|
1708
|
+
appId:
|
|
1709
|
+
type: string
|
|
1710
|
+
description: Key 的公开标识,即 Bearer token 中点号前的一段。
|
|
1711
|
+
examples: [ev_a1b2c3d4e5f60718]
|
|
1712
|
+
spaceId:
|
|
1713
|
+
type: integer
|
|
1714
|
+
format: int64
|
|
1715
|
+
description: 绑定的空间 id。请求参数里不要再传。
|
|
1716
|
+
spaceName:
|
|
1717
|
+
type: string
|
|
1718
|
+
description: 绑定的空间名称。
|
|
1719
|
+
teamId:
|
|
1720
|
+
type: integer
|
|
1721
|
+
format: int64
|
|
1722
|
+
description: 绑定的团队 id。列表和创建都限定在这个团队。
|
|
1723
|
+
teamName:
|
|
1724
|
+
type: string
|
|
1725
|
+
description: 绑定的团队名称。
|
|
1726
|
+
scopes:
|
|
1727
|
+
type: array
|
|
1728
|
+
description: 这把 Key 被授予的 scope,是「系统全部 scope」的子集。
|
|
1729
|
+
items: {$ref: '#/components/schemas/Scope'}
|
|
1730
|
+
|
|
1731
|
+
Scope:
|
|
1732
|
+
type: string
|
|
1733
|
+
description: |
|
|
1734
|
+
Key 维度的操作范围。接口另需空间权限,两者独立。
|
|
1735
|
+
|
|
1736
|
+
| 值 | 用于 |
|
|
1737
|
+
| --- | --- |
|
|
1738
|
+
| `screen:read` | 分组列表、大屏列表与详情、读文档、校验、读发布状态 |
|
|
1739
|
+
| `screen:write` | 创建大屏、写文档、原子操作 |
|
|
1740
|
+
| `screen:delete` | 预留,当前没有删除大屏接口 |
|
|
1741
|
+
| `screen:publish` | 发布、取消发布 |
|
|
1742
|
+
| `screen:render` | 预留 |
|
|
1743
|
+
| `screen:version` | 版本接口(当前 501) |
|
|
1744
|
+
| `component:read` | 组件目录、读取组件 schema |
|
|
1745
|
+
| `component:write` | 上传空间组件包 |
|
|
1746
|
+
| `datasource:read` | 数据源列表、详情、表结构、数据预览 |
|
|
1747
|
+
| `datasource:write` | 新建、更新、删除数据源、连接测试 |
|
|
1748
|
+
| `asset:write` | 上传静态资源 |
|
|
1749
|
+
| `data:read` / `data:read-sql` / `template:read` | 预留,当前没有对应接口 |
|
|
1750
|
+
enum:
|
|
1751
|
+
- screen:read
|
|
1752
|
+
- screen:write
|
|
1753
|
+
- screen:delete
|
|
1754
|
+
- screen:publish
|
|
1755
|
+
- screen:render
|
|
1756
|
+
- screen:version
|
|
1757
|
+
- component:read
|
|
1758
|
+
- component:write
|
|
1759
|
+
- datasource:read
|
|
1760
|
+
- datasource:write
|
|
1761
|
+
- data:read
|
|
1762
|
+
- data:read-sql
|
|
1763
|
+
- asset:write
|
|
1764
|
+
- template:read
|
|
1765
|
+
|
|
1766
|
+
Meta:
|
|
1767
|
+
type: object
|
|
1768
|
+
description: '`GET /meta` 的响应。数值限制和能力开关以本次响应为准,不要把文档里的示例数字写死在客户端。'
|
|
1769
|
+
required: [apiVersion, documentSchemaVersion, context, capabilities, operations, scopes, limits]
|
|
1770
|
+
properties:
|
|
1771
|
+
apiVersion:
|
|
1772
|
+
type: string
|
|
1773
|
+
description: URL 版本。当前恒为 `v1`。
|
|
1774
|
+
const: v1
|
|
1775
|
+
documentSchemaVersion:
|
|
1776
|
+
type: string
|
|
1777
|
+
description: 大屏文档的 `schemaVersion`。当前为 `1.0`。
|
|
1778
|
+
examples: ['1.0']
|
|
1779
|
+
context: {$ref: '#/components/schemas/ApiKeyContext'}
|
|
1780
|
+
capabilities:
|
|
1781
|
+
type: object
|
|
1782
|
+
description: |
|
|
1783
|
+
资源 → 动作 → 是否已开放。`false` 表示不要调用对应能力
|
|
1784
|
+
(版本、任务、删除大屏、组件目录等)。键会随版本增加。
|
|
1785
|
+
additionalProperties:
|
|
1786
|
+
type: object
|
|
1787
|
+
additionalProperties: {type: boolean}
|
|
1788
|
+
operations:
|
|
1789
|
+
type: array
|
|
1790
|
+
description: |
|
|
1791
|
+
文档操作词表,供客户端发现有哪些 op 名字。
|
|
1792
|
+
`available` 是词表标记,不完全等于 `POST /operations` 的实际行为:
|
|
1793
|
+
`element.update` 已经可以调用,但这里可能仍是 `false`。
|
|
1794
|
+
items: {$ref: '#/components/schemas/OperationVocabularyItem'}
|
|
1795
|
+
scopes:
|
|
1796
|
+
type: array
|
|
1797
|
+
description: 系统定义的全部 scope,不是当前 Key 的权限。当前 Key 的权限看 `context.scopes`。
|
|
1798
|
+
items: {$ref: '#/components/schemas/Scope'}
|
|
1799
|
+
limits:
|
|
1800
|
+
type: object
|
|
1801
|
+
description: 数值限制。单位除说明外均为「个」;字节类字段单位是 byte。
|
|
1802
|
+
additionalProperties: {type: number}
|
|
1803
|
+
properties:
|
|
1804
|
+
listPageSizeMax:
|
|
1805
|
+
type: number
|
|
1806
|
+
description: '`GET /screens` 的 `limit` 上限。'
|
|
1807
|
+
listPageSizeDefault:
|
|
1808
|
+
type: number
|
|
1809
|
+
description: 不传 `limit` 时的页大小。
|
|
1810
|
+
documentMaxBytes:
|
|
1811
|
+
type: number
|
|
1812
|
+
description: 单个文档请求体的字节上限。
|
|
1813
|
+
documentMaxElements:
|
|
1814
|
+
type: number
|
|
1815
|
+
description: 单屏元素数量上限,校验规则 `ELEMENT_COUNT_EXCEEDED` 使用它。
|
|
1816
|
+
assetMaxBytes:
|
|
1817
|
+
type: number
|
|
1818
|
+
description: 单个上传文件的字节上限。
|
|
1819
|
+
requestsPerMinute:
|
|
1820
|
+
type: number
|
|
1821
|
+
description: 每把 Key 每分钟的请求预算,由 `GET /meta` 公布。平台限流触发时返回 `429 RATE_LIMITED`。
|
|
1822
|
+
|
|
1823
|
+
OperationVocabularyItem:
|
|
1824
|
+
type: object
|
|
1825
|
+
required: [op, description, available]
|
|
1826
|
+
properties:
|
|
1827
|
+
op:
|
|
1828
|
+
type: string
|
|
1829
|
+
description: 操作名,例如 `screen.updateMeta`。
|
|
1830
|
+
description:
|
|
1831
|
+
type: string
|
|
1832
|
+
description: 该操作的简短说明。
|
|
1833
|
+
available:
|
|
1834
|
+
type: boolean
|
|
1835
|
+
description: 词表是否把它标记为当前可用。写入时仍以「大屏文档」接口说明为准。
|
|
1836
|
+
|
|
1837
|
+
GroupSummary:
|
|
1838
|
+
type: object
|
|
1839
|
+
description: 当前团队下的一个大屏分组。
|
|
1840
|
+
required: [id, name, rank, createdAt, updatedAt]
|
|
1841
|
+
properties:
|
|
1842
|
+
id:
|
|
1843
|
+
type: integer
|
|
1844
|
+
format: int64
|
|
1845
|
+
description: 分组 id。创建大屏、按分组筛选时传这个值。
|
|
1846
|
+
name:
|
|
1847
|
+
type: string
|
|
1848
|
+
description: 分组名称。
|
|
1849
|
+
rank:
|
|
1850
|
+
type: number
|
|
1851
|
+
description: 展示权重,越大越靠前,与工作台一致。
|
|
1852
|
+
createdAt: {type: string, format: date-time, description: 创建时间,ISO 8601。}
|
|
1853
|
+
updatedAt: {type: string, format: date-time, description: 更新时间,ISO 8601。}
|
|
1854
|
+
|
|
1855
|
+
GroupList:
|
|
1856
|
+
type: object
|
|
1857
|
+
required: [teamId, items]
|
|
1858
|
+
properties:
|
|
1859
|
+
teamId:
|
|
1860
|
+
type: integer
|
|
1861
|
+
format: int64
|
|
1862
|
+
description: 这些分组所属的团队,等于 Key 绑定的 `teamId`。
|
|
1863
|
+
items:
|
|
1864
|
+
type: array
|
|
1865
|
+
description: 全量分组,已按 `rank` 降序。
|
|
1866
|
+
items: {$ref: '#/components/schemas/GroupSummary'}
|
|
1867
|
+
|
|
1868
|
+
ScreenSummary:
|
|
1869
|
+
type: object
|
|
1870
|
+
description: 大屏元信息,不含文档内容。
|
|
1871
|
+
required: [id, name, teamId, createdAt, updatedAt]
|
|
1872
|
+
properties:
|
|
1873
|
+
id: {type: integer, format: int64, description: 大屏 id。}
|
|
1874
|
+
name: {type: string, description: 大屏名称。}
|
|
1875
|
+
teamId: {type: integer, format: int64, description: 所属团队,即 Key 绑定的团队。}
|
|
1876
|
+
groupId:
|
|
1877
|
+
type: [integer, 'null']
|
|
1878
|
+
format: int64
|
|
1879
|
+
description: 所属分组。未分组时为 `null`。
|
|
1880
|
+
thumb:
|
|
1881
|
+
type: [string, 'null']
|
|
1882
|
+
description: 缩略图地址。还没有缩略图时为 `null`。
|
|
1883
|
+
createdAt: {type: string, format: date-time, description: 创建时间。}
|
|
1884
|
+
updatedAt: {type: string, format: date-time, description: 最近一次内容或元信息变更的时间。}
|
|
1885
|
+
|
|
1886
|
+
ScreenList:
|
|
1887
|
+
type: object
|
|
1888
|
+
description: 大屏列表的一页。没有 `total`。
|
|
1889
|
+
required: [items, limit, offset]
|
|
1890
|
+
properties:
|
|
1891
|
+
items:
|
|
1892
|
+
type: array
|
|
1893
|
+
items: {$ref: '#/components/schemas/ScreenSummary'}
|
|
1894
|
+
limit: {type: integer, description: 实际使用的页大小。}
|
|
1895
|
+
offset: {type: integer, description: 实际使用的偏移。}
|
|
1896
|
+
|
|
1897
|
+
ShareInfo:
|
|
1898
|
+
type: object
|
|
1899
|
+
description: 脱敏后的发布信息。没有密码、Token、分享路径。
|
|
1900
|
+
required: [published, needPassword, needToken]
|
|
1901
|
+
properties:
|
|
1902
|
+
published:
|
|
1903
|
+
type: boolean
|
|
1904
|
+
description: 是否已有分享 id。`false` 表示未发布或已取消。
|
|
1905
|
+
needPassword: {type: boolean, description: 访问是否需要密码。}
|
|
1906
|
+
needToken: {type: boolean, description: 访问是否需要 Token。}
|
|
1907
|
+
shareType:
|
|
1908
|
+
type: integer
|
|
1909
|
+
description: |
|
|
1910
|
+
分享类型。`1` 普通分享(前端拉数据),`2` 缓存文件。
|
|
1911
|
+
未发布或历史数据缺失时可能不返回。OpenAPI 发布只会写成 `1`。
|
|
1912
|
+
enum: [1, 2]
|
|
1913
|
+
expiredAt:
|
|
1914
|
+
type: [string, 'null']
|
|
1915
|
+
format: date-time
|
|
1916
|
+
description: 分享过期时间。不过期时为 `null`。
|
|
1917
|
+
|
|
1918
|
+
ScreenDetail:
|
|
1919
|
+
description: 大屏详情 = 元信息 + 脱敏发布状态。
|
|
1920
|
+
allOf:
|
|
1921
|
+
- {$ref: '#/components/schemas/ScreenSummary'}
|
|
1922
|
+
- type: object
|
|
1923
|
+
required: [share]
|
|
1924
|
+
properties:
|
|
1925
|
+
share: {$ref: '#/components/schemas/ShareInfo'}
|
|
1926
|
+
|
|
1927
|
+
CreateScreenRequest:
|
|
1928
|
+
type: object
|
|
1929
|
+
description: 在 Key 绑定的团队中创建空白大屏。不要传 `teamId` 或 `spaceId`。
|
|
1930
|
+
required: [name, groupId]
|
|
1931
|
+
properties:
|
|
1932
|
+
name:
|
|
1933
|
+
type: string
|
|
1934
|
+
minLength: 1
|
|
1935
|
+
maxLength: 255
|
|
1936
|
+
description: 大屏名称。
|
|
1937
|
+
groupId:
|
|
1938
|
+
type: integer
|
|
1939
|
+
format: int64
|
|
1940
|
+
minimum: 1
|
|
1941
|
+
description: 目标分组,必须属于当前团队。
|
|
1942
|
+
|
|
1943
|
+
ScreenCreated:
|
|
1944
|
+
type: object
|
|
1945
|
+
required: [id, name, teamId]
|
|
1946
|
+
properties:
|
|
1947
|
+
id: {type: integer, format: int64, description: 新建大屏的 id,后续文档和发布接口都用它。}
|
|
1948
|
+
name: {type: string, description: 已保存的名称。}
|
|
1949
|
+
teamId: {type: integer, format: int64, description: 所属团队。}
|
|
1950
|
+
groupId:
|
|
1951
|
+
type: [integer, 'null']
|
|
1952
|
+
format: int64
|
|
1953
|
+
description: 所属分组。
|
|
1954
|
+
|
|
1955
|
+
ScreenDocument:
|
|
1956
|
+
type: object
|
|
1957
|
+
description: |
|
|
1958
|
+
大屏文档 v1。`GET` 返回的就是这份结构;`PUT` 提交的也是这份结构。
|
|
1959
|
+
|
|
1960
|
+
`additionalProperties` 在运行时不会因为多了未列出的字段就拒绝整份文档,
|
|
1961
|
+
但未在「文档写入目前支持什么」中列出的变化会被 `UNSUPPORTED_CHANGE` 拒绝或被忽略。
|
|
1962
|
+
写入时请保留从 `GET` 拿到、自己不打算改的元素和图层,否则删除组件会被当成「移除」。
|
|
1963
|
+
required: [schemaVersion, meta, canvas, layers, elements]
|
|
1964
|
+
properties:
|
|
1965
|
+
schemaVersion:
|
|
1966
|
+
type: string
|
|
1967
|
+
const: '1.0'
|
|
1968
|
+
description: 文档格式版本。只能是 `1.0`。
|
|
1969
|
+
revision:
|
|
1970
|
+
type: string
|
|
1971
|
+
pattern: '^[0-9a-f]{16}$'
|
|
1972
|
+
description: |
|
|
1973
|
+
服务端生成的内容摘要。客户端只做回传,用来做乐观锁。
|
|
1974
|
+
`PUT` 时也可以把上次读到的值放在这里;与 `If-Match` 冲突时以请求头为准。
|
|
1975
|
+
meta: {$ref: '#/components/schemas/ScreenMeta'}
|
|
1976
|
+
canvas: {$ref: '#/components/schemas/ScreenCanvas'}
|
|
1977
|
+
layers:
|
|
1978
|
+
type: array
|
|
1979
|
+
description: |
|
|
1980
|
+
图层树,只表达谁在谁里面、谁在谁前面。数组顺序即同级顺序,靠前者在上层。
|
|
1981
|
+
叶子的 `key` 必须能在 `elements`(或所在 state 的 `elements`)里找到。
|
|
1982
|
+
items: {$ref: '#/components/schemas/LayerNode'}
|
|
1983
|
+
elements:
|
|
1984
|
+
type: object
|
|
1985
|
+
description: 元素表。属性名是元素 key,属性值是组件、面板或容器。
|
|
1986
|
+
additionalProperties: {$ref: '#/components/schemas/ScreenElement'}
|
|
1987
|
+
dataContainers:
|
|
1988
|
+
type: object
|
|
1989
|
+
description: 数据容器。当前写入路径不处理对它的修改。
|
|
1990
|
+
additionalProperties: {type: object}
|
|
1991
|
+
filters:
|
|
1992
|
+
type: object
|
|
1993
|
+
description: 过滤器。当前写入路径不处理对它的修改。
|
|
1994
|
+
additionalProperties: {type: object}
|
|
1995
|
+
|
|
1996
|
+
ScreenMeta:
|
|
1997
|
+
type: object
|
|
1998
|
+
required: [name]
|
|
1999
|
+
description: 大屏自身的信息。写入时只有 `name` 的变化会落库;`id`、`teamId` 等由服务端维护,改了也不会被采用。
|
|
2000
|
+
properties:
|
|
2001
|
+
id: {type: integer, description: 大屏 id,只读。}
|
|
2002
|
+
name: {type: string, minLength: 1, maxLength: 255, description: 大屏名称。修改它会同步图层名称。}
|
|
2003
|
+
teamId: {type: integer, description: 所属团队,只读。}
|
|
2004
|
+
groupId:
|
|
2005
|
+
type: [integer, 'null']
|
|
2006
|
+
description: 所属分组,只读。换分组不在文档写入范围内。
|
|
2007
|
+
createdAt: {type: string, format: date-time, description: 创建时间,只读。}
|
|
2008
|
+
updatedAt: {type: string, format: date-time, description: 更新时间,只读。}
|
|
2009
|
+
|
|
2010
|
+
ScreenCanvas:
|
|
2011
|
+
type: object
|
|
2012
|
+
description: |
|
|
2013
|
+
画布。只提交要改的字段即可;未出现的字段保持原值。
|
|
2014
|
+
读不到的字段会直接省略,而不是填默认值。
|
|
2015
|
+
properties:
|
|
2016
|
+
width: {type: number, exclusiveMinimum: 0, description: 画布宽度,像素。}
|
|
2017
|
+
height: {type: number, exclusiveMinimum: 0, description: 画布高度,像素。}
|
|
2018
|
+
backgroundColor: {type: string, description: '背景色,如 `#0b1b2b`。'}
|
|
2019
|
+
backgroundImage:
|
|
2020
|
+
type: [string, 'null']
|
|
2021
|
+
description: 背景图。使用 `POST /assets` 返回的 `path`,不是 `url`。不用背景图时可为 `null`。
|
|
2022
|
+
useBackground: {type: boolean, description: 是否启用背景图。}
|
|
2023
|
+
grid: {type: number, description: 网格间距。}
|
|
2024
|
+
zoom:
|
|
2025
|
+
type: string
|
|
2026
|
+
description: 缩放方式。`0` 按比例适配,`1` 强制铺满,`2` 原比例滚动。值为字符串,不是数字。
|
|
2027
|
+
enum: ['0', '1', '2']
|
|
2028
|
+
guides:
|
|
2029
|
+
type: object
|
|
2030
|
+
description: 参考线,写入大屏的辅助线配置。
|
|
2031
|
+
properties:
|
|
2032
|
+
h: {type: array, items: {type: number}, description: 水平参考线的 y 坐标。}
|
|
2033
|
+
v: {type: array, items: {type: number}, description: 垂直参考线的 x 坐标。}
|
|
2034
|
+
globalFilter:
|
|
2035
|
+
type: object
|
|
2036
|
+
description: 全屏滤镜配置,结构与编辑器中保存的对象一致。
|
|
2037
|
+
additionalProperties: true
|
|
2038
|
+
|
|
2039
|
+
LayerNode:
|
|
2040
|
+
type: object
|
|
2041
|
+
required: [key]
|
|
2042
|
+
description: 图层节点。没有 `children` 时,`key` 引用一个元素;有 `children` 且 `kind` 为 `group` 时是分组。
|
|
2043
|
+
properties:
|
|
2044
|
+
key:
|
|
2045
|
+
type: string
|
|
2046
|
+
description: 图层 key。分组为 `g-` 开头;元素 key 见 `ScreenElement` 的说明。
|
|
2047
|
+
kind:
|
|
2048
|
+
type: string
|
|
2049
|
+
enum: [group]
|
|
2050
|
+
description: 仅分组节点会带 `group`。叶子节点省略。
|
|
2051
|
+
name: {type: string, description: 图层或分组显示名。}
|
|
2052
|
+
visible: {type: boolean, description: 是否显示。}
|
|
2053
|
+
locked: {type: boolean, description: 是否锁定。}
|
|
2054
|
+
children:
|
|
2055
|
+
type: array
|
|
2056
|
+
description: 分组内的子图层,顺序即叠放顺序。
|
|
2057
|
+
items: {$ref: '#/components/schemas/LayerNode'}
|
|
2058
|
+
|
|
2059
|
+
ScreenElement:
|
|
2060
|
+
description: 元素。用 `kind` 区分组件、动态面板、组件容器。
|
|
2061
|
+
oneOf:
|
|
2062
|
+
- {$ref: '#/components/schemas/ComponentElement'}
|
|
2063
|
+
- {$ref: '#/components/schemas/PanelElement'}
|
|
2064
|
+
- {$ref: '#/components/schemas/ContainerElement'}
|
|
2065
|
+
discriminator:
|
|
2066
|
+
propertyName: kind
|
|
2067
|
+
mapping:
|
|
2068
|
+
component: '#/components/schemas/ComponentElement'
|
|
2069
|
+
panel: '#/components/schemas/PanelElement'
|
|
2070
|
+
container: '#/components/schemas/ContainerElement'
|
|
2071
|
+
|
|
2072
|
+
ComponentElement:
|
|
2073
|
+
type: object
|
|
2074
|
+
required: [kind, module, version]
|
|
2075
|
+
description: |
|
|
2076
|
+
组件。新增时必须同时出现在 `elements` 和 `layers` 里。
|
|
2077
|
+
key 由调用方指定,并会持久化,便于重试时识别为同一次新增。
|
|
2078
|
+
properties:
|
|
2079
|
+
kind: {const: component, description: 固定为 `component`。}
|
|
2080
|
+
module:
|
|
2081
|
+
type: string
|
|
2082
|
+
description: 组件模块名,如 `bar_chart`。已有组件不能修改,否则整单拒绝。
|
|
2083
|
+
version:
|
|
2084
|
+
type: string
|
|
2085
|
+
description: 组件版本,如 `2.1.0`。可以升级版本,不能更换 module。
|
|
2086
|
+
name: {type: string, description: 画布上的组件名称。}
|
|
2087
|
+
layout:
|
|
2088
|
+
$ref: '#/components/schemas/ElementLayout'
|
|
2089
|
+
description: 从属性树读出的位置和尺寸,便于查看。单独修改它不会落库,位置要改 `config` 里的对应节点。
|
|
2090
|
+
config:
|
|
2091
|
+
type: array
|
|
2092
|
+
description: |
|
|
2093
|
+
组件属性树。节点一般是 `{name, value}`,`value` 可以是子节点数组或最终值。
|
|
2094
|
+
`fields[].path` 用点号把各级 `name` 串起来。
|
|
2095
|
+
传入时按整棵树替换该组件配置。
|
|
2096
|
+
items: {$ref: '#/components/schemas/PropNode'}
|
|
2097
|
+
interactions:
|
|
2098
|
+
$ref: '#/components/schemas/Interactions'
|
|
2099
|
+
description: 交互配置,可以修改。
|
|
2100
|
+
staticData:
|
|
2101
|
+
$ref: '#/components/schemas/StaticData'
|
|
2102
|
+
description: 组件静态数据。不传则保持原值。
|
|
2103
|
+
dataBinding:
|
|
2104
|
+
$ref: '#/components/schemas/DataBinding'
|
|
2105
|
+
description: 数据源绑定。`dataType` 为 `static` 表示改回静态数据。
|
|
2106
|
+
|
|
2107
|
+
PanelElement:
|
|
2108
|
+
type: object
|
|
2109
|
+
required: [kind, states]
|
|
2110
|
+
description: 动态面板或引用面板。可以读到完整子内容。新增、删除、修改内部结构当前都会被拒绝。
|
|
2111
|
+
properties:
|
|
2112
|
+
kind: {const: panel}
|
|
2113
|
+
name: {type: string, description: 面板名称。}
|
|
2114
|
+
layout: {$ref: '#/components/schemas/ElementLayout'}
|
|
2115
|
+
states:
|
|
2116
|
+
type: array
|
|
2117
|
+
description: 面板状态。每个状态是一套独立的图层和元素。
|
|
2118
|
+
items: {$ref: '#/components/schemas/ElementState'}
|
|
2119
|
+
|
|
2120
|
+
ContainerElement:
|
|
2121
|
+
type: object
|
|
2122
|
+
required: [kind, states]
|
|
2123
|
+
description: 组件容器。读写限制与动态面板相同。
|
|
2124
|
+
properties:
|
|
2125
|
+
kind: {const: container}
|
|
2126
|
+
name: {type: string, description: 容器名称。}
|
|
2127
|
+
layout: {$ref: '#/components/schemas/ElementLayout'}
|
|
2128
|
+
states:
|
|
2129
|
+
type: array
|
|
2130
|
+
items: {$ref: '#/components/schemas/ElementState'}
|
|
2131
|
+
|
|
2132
|
+
ElementState:
|
|
2133
|
+
type: object
|
|
2134
|
+
required: [key, layers, elements]
|
|
2135
|
+
description: 面板或容器中的一个状态。
|
|
2136
|
+
properties:
|
|
2137
|
+
key: {type: string, description: 状态 key。}
|
|
2138
|
+
name: {type: string, description: 状态名称。}
|
|
2139
|
+
screenId: {type: integer, description: 该状态对应的子屏 id,只读。}
|
|
2140
|
+
layers:
|
|
2141
|
+
type: array
|
|
2142
|
+
items: {$ref: '#/components/schemas/LayerNode'}
|
|
2143
|
+
elements:
|
|
2144
|
+
type: object
|
|
2145
|
+
additionalProperties: {$ref: '#/components/schemas/ScreenElement'}
|
|
2146
|
+
|
|
2147
|
+
ElementLayout:
|
|
2148
|
+
type: object
|
|
2149
|
+
description: 元素在画布上的位置和尺寸,单位像素。由组件属性树投影而来。
|
|
2150
|
+
properties:
|
|
2151
|
+
left: {type: number, description: 距画布左边的距离。}
|
|
2152
|
+
top: {type: number, description: 距画布上边的距离。}
|
|
2153
|
+
width: {type: number, exclusiveMinimum: 0, description: 宽度。小于等于 0 时校验为 `ELEMENT_SIZE_INVALID`。}
|
|
2154
|
+
height: {type: number, exclusiveMinimum: 0, description: 高度。小于等于 0 时校验为 `ELEMENT_SIZE_INVALID`。}
|
|
2155
|
+
|
|
2156
|
+
PropNode:
|
|
2157
|
+
type: object
|
|
2158
|
+
description: |
|
|
2159
|
+
属性树节点。组件配置使用 `name` + `value`;大屏画布配置使用 `_name` + `_value`。
|
|
2160
|
+
读写时保持原字段名,不要把一种改成另一种。
|
|
2161
|
+
`value` / `_value` 为数组时表示还有下一级,为标量时表示叶子。
|
|
2162
|
+
additionalProperties: true
|
|
2163
|
+
properties:
|
|
2164
|
+
name: {type: string, description: 组件属性名。}
|
|
2165
|
+
value: {description: 组件属性值,或子节点数组。}
|
|
2166
|
+
_name: {type: string, description: 大屏配置属性名。}
|
|
2167
|
+
_value: {description: 大屏配置属性值,或子节点数组。}
|
|
2168
|
+
|
|
2169
|
+
StaticData:
|
|
2170
|
+
type: object
|
|
2171
|
+
description: 组件静态数据。
|
|
2172
|
+
properties:
|
|
2173
|
+
data: {description: 数据内容,通常是对象数组。}
|
|
2174
|
+
fields: {description: 字段映射。}
|
|
2175
|
+
|
|
2176
|
+
DataBinding:
|
|
2177
|
+
type: object
|
|
2178
|
+
required: [dataType]
|
|
2179
|
+
description: |
|
|
2180
|
+
组件的数据源绑定。`dataType` 不是 `static` 时,`data.data_id` 必须是当前团队的数据源 id。
|
|
2181
|
+
properties:
|
|
2182
|
+
dataType: {type: string, description: 数据源类型,如 `mysql`、`api`、`static`。}
|
|
2183
|
+
data:
|
|
2184
|
+
type: object
|
|
2185
|
+
additionalProperties: true
|
|
2186
|
+
description: 查询配置。非静态时包含 `data_id`,数据库类型还可包含 `sql`。
|
|
2187
|
+
fields: {description: 字段映射。}
|
|
2188
|
+
|
|
2189
|
+
Interactions:
|
|
2190
|
+
type: object
|
|
2191
|
+
description: 组件交互,可以读取和修改。
|
|
2192
|
+
properties:
|
|
2193
|
+
events: {type: array, items: {}, description: 事件。}
|
|
2194
|
+
triggers: {type: array, items: {}, description: 触发器。}
|
|
2195
|
+
actions: {type: array, items: {}, description: 动作。}
|
|
2196
|
+
|
|
2197
|
+
ApplyResult:
|
|
2198
|
+
type: object
|
|
2199
|
+
description: 文档写入的结果。
|
|
2200
|
+
required: [revision, changes, patch]
|
|
2201
|
+
properties:
|
|
2202
|
+
revision:
|
|
2203
|
+
type: string
|
|
2204
|
+
pattern: '^[0-9a-f]{16}$'
|
|
2205
|
+
description: 写入完成后的文档摘要。无变化时仍是原摘要。
|
|
2206
|
+
changes:
|
|
2207
|
+
type: object
|
|
2208
|
+
description: 本次计划中的数量。无变化时三个数都是 0。
|
|
2209
|
+
required: [added, updated, removed]
|
|
2210
|
+
properties:
|
|
2211
|
+
added: {type: integer, minimum: 0, description: 新增的组件个数。}
|
|
2212
|
+
updated: {type: integer, minimum: 0, description: 修改的组件个数;若名称有变化,再加 1。}
|
|
2213
|
+
removed: {type: integer, minimum: 0, description: 删除(进回收站)的组件个数。}
|
|
2214
|
+
patch:
|
|
2215
|
+
type: array
|
|
2216
|
+
description: |
|
|
2217
|
+
名称和画布的变化摘要,便于核对。每一项是 `{op: replace, path, value}`,
|
|
2218
|
+
`path` 为 `/meta/name` 或 `/canvas/<字段>`。组件级变化不会出现在这里。
|
|
2219
|
+
items:
|
|
2220
|
+
type: object
|
|
2221
|
+
properties:
|
|
2222
|
+
op: {type: string, description: 目前只有 `replace`。}
|
|
2223
|
+
path: {type: string, description: JSON Pointer。}
|
|
2224
|
+
value: {description: 新值。}
|
|
2225
|
+
|
|
2226
|
+
OperationsRequest:
|
|
2227
|
+
type: object
|
|
2228
|
+
required: [operations]
|
|
2229
|
+
properties:
|
|
2230
|
+
revision:
|
|
2231
|
+
type: string
|
|
2232
|
+
pattern: '^[0-9a-f]{16}$'
|
|
2233
|
+
description: 可选的乐观锁。不传则只看 `If-Match`;两者都不传则不校验版本。
|
|
2234
|
+
operations:
|
|
2235
|
+
type: array
|
|
2236
|
+
minItems: 1
|
|
2237
|
+
description: 按数组顺序应用。任一操作不被支持,则整批失败。
|
|
2238
|
+
items: {$ref: '#/components/schemas/DocumentOperation'}
|
|
2239
|
+
|
|
2240
|
+
DocumentOperation:
|
|
2241
|
+
description: |
|
|
2242
|
+
一条原子操作。`op` 不在支持列表里会得到 `UNSUPPORTED_OPERATION`,整批不落库。
|
|
2243
|
+
元素和图层都用文档 key 引用。
|
|
2244
|
+
oneOf:
|
|
2245
|
+
- {$ref: '#/components/schemas/UpdateMetaOperation'}
|
|
2246
|
+
- {$ref: '#/components/schemas/UpdateElementOperation'}
|
|
2247
|
+
- {$ref: '#/components/schemas/AddComponentOperation'}
|
|
2248
|
+
- {$ref: '#/components/schemas/RemoveComponentOperation'}
|
|
2249
|
+
- {$ref: '#/components/schemas/SetComponentConfigOperation'}
|
|
2250
|
+
- {$ref: '#/components/schemas/SetComponentLayoutOperation'}
|
|
2251
|
+
- {$ref: '#/components/schemas/AddComponentEventOperation'}
|
|
2252
|
+
- {$ref: '#/components/schemas/UpdateComponentEventOperation'}
|
|
2253
|
+
- {$ref: '#/components/schemas/DeleteComponentEventOperation'}
|
|
2254
|
+
- {$ref: '#/components/schemas/SetStaticDataOperation'}
|
|
2255
|
+
- {$ref: '#/components/schemas/BindDataOperation'}
|
|
2256
|
+
- {$ref: '#/components/schemas/UnbindDataOperation'}
|
|
2257
|
+
- {$ref: '#/components/schemas/UpgradeVersionOperation'}
|
|
2258
|
+
- {$ref: '#/components/schemas/SetLayerVisibleOperation'}
|
|
2259
|
+
- {$ref: '#/components/schemas/MoveLayerOperation'}
|
|
2260
|
+
- {$ref: '#/components/schemas/GroupLayersOperation'}
|
|
2261
|
+
- {$ref: '#/components/schemas/UngroupLayerOperation'}
|
|
2262
|
+
|
|
2263
|
+
UpdateMetaOperation:
|
|
2264
|
+
type: object
|
|
2265
|
+
required: [op, name]
|
|
2266
|
+
description: 修改大屏名称。
|
|
2267
|
+
properties:
|
|
2268
|
+
op:
|
|
2269
|
+
const: screen.updateMeta
|
|
2270
|
+
description: 固定值。
|
|
2271
|
+
name:
|
|
2272
|
+
type: string
|
|
2273
|
+
minLength: 1
|
|
2274
|
+
maxLength: 255
|
|
2275
|
+
description: 新名称。空字符串不会写入。
|
|
2276
|
+
|
|
2277
|
+
UpdateElementOperation:
|
|
2278
|
+
type: object
|
|
2279
|
+
required: [op, key]
|
|
2280
|
+
description: 修改一个已存在的组件。`name` 与 `config` 至少应传一个有意义的变更;都与现值相同则该元素不算更新。
|
|
2281
|
+
properties:
|
|
2282
|
+
op:
|
|
2283
|
+
const: element.update
|
|
2284
|
+
description: 固定值。
|
|
2285
|
+
key:
|
|
2286
|
+
type: string
|
|
2287
|
+
description: 组件 key,例如 `c-88` 或创建时指定的自定义 key。必须已存在,且 `kind` 为 `component`。
|
|
2288
|
+
name:
|
|
2289
|
+
type: string
|
|
2290
|
+
description: 新的组件名称。不传则不改名称。
|
|
2291
|
+
config:
|
|
2292
|
+
type: array
|
|
2293
|
+
description: 新的完整属性树。不传则不改配置。传入时替换整棵树,不是按字段合并。
|
|
2294
|
+
items: {$ref: '#/components/schemas/PropNode'}
|
|
2295
|
+
|
|
2296
|
+
ConfigPatch:
|
|
2297
|
+
type: object
|
|
2298
|
+
required: [path, value]
|
|
2299
|
+
properties:
|
|
2300
|
+
path: {type: string, description: '配置路径,取自 `config-fields` 的 `fields[].path`,如 `chart.legend.show`。'}
|
|
2301
|
+
value: {description: 新值,类型随字段变化。}
|
|
2302
|
+
|
|
2303
|
+
AddComponentOperation:
|
|
2304
|
+
type: object
|
|
2305
|
+
required: [op, key, module, version]
|
|
2306
|
+
description: |
|
|
2307
|
+
新增一个组件。只写要改的字段,其余使用组件包默认配置。
|
|
2308
|
+
`key` 不能和已有元素或图层重复;`parentKey` 必须是分组,不传则放在根层级。
|
|
2309
|
+
properties:
|
|
2310
|
+
op: {const: addComponent}
|
|
2311
|
+
key: {type: string, description: 自定义 key,如 `c-kpi-1`。}
|
|
2312
|
+
module: {type: string}
|
|
2313
|
+
version: {type: string}
|
|
2314
|
+
name: {type: string}
|
|
2315
|
+
layout: {$ref: '#/components/schemas/ElementLayout'}
|
|
2316
|
+
configPatches:
|
|
2317
|
+
type: array
|
|
2318
|
+
items: {$ref: '#/components/schemas/ConfigPatch'}
|
|
2319
|
+
data: {description: 静态数据,不传则用组件默认数据。}
|
|
2320
|
+
fields: {description: 静态数据的字段说明,不传则用组件默认值。}
|
|
2321
|
+
parentKey: {type: string, description: 目标分组 key。}
|
|
2322
|
+
index: {type: integer, minimum: 0, description: 在兄弟图层中的位置,不传则放最后。}
|
|
2323
|
+
|
|
2324
|
+
RemoveComponentOperation:
|
|
2325
|
+
type: object
|
|
2326
|
+
required: [op, key]
|
|
2327
|
+
description: 删除组件,同时移出图层,进入回收站。
|
|
2328
|
+
properties:
|
|
2329
|
+
op: {const: removeComponent}
|
|
2330
|
+
key: {type: string}
|
|
2331
|
+
|
|
2332
|
+
SetComponentConfigOperation:
|
|
2333
|
+
type: object
|
|
2334
|
+
required: [op, key, configPatches]
|
|
2335
|
+
description: 按路径修改已有组件的配置。路径不存在时整批拒绝,不会自动创建。
|
|
2336
|
+
properties:
|
|
2337
|
+
op: {const: setComponentConfig}
|
|
2338
|
+
key: {type: string}
|
|
2339
|
+
configPatches:
|
|
2340
|
+
type: array
|
|
2341
|
+
minItems: 1
|
|
2342
|
+
items: {$ref: '#/components/schemas/ConfigPatch'}
|
|
2343
|
+
|
|
2344
|
+
SetComponentLayoutOperation:
|
|
2345
|
+
type: object
|
|
2346
|
+
required: [op, key, layout]
|
|
2347
|
+
description: 修改组件位置尺寸,写入属性树 `chart.dimension.chartPosition`。
|
|
2348
|
+
properties:
|
|
2349
|
+
op: {const: setComponentLayout}
|
|
2350
|
+
key: {type: string}
|
|
2351
|
+
layout: {$ref: '#/components/schemas/ElementLayout'}
|
|
2352
|
+
|
|
2353
|
+
AddComponentEventOperation:
|
|
2354
|
+
type: object
|
|
2355
|
+
required: [op, key, event]
|
|
2356
|
+
description: 给组件新增一个交互事件。未提供 `event.id` 时服务端生成。
|
|
2357
|
+
properties:
|
|
2358
|
+
op: {const: addComponentEvent}
|
|
2359
|
+
key: {type: string, description: 组件 key。}
|
|
2360
|
+
event:
|
|
2361
|
+
type: object
|
|
2362
|
+
additionalProperties: true
|
|
2363
|
+
description: 事件对象,包含 `trigger`、`actions` 等,结构与编辑器保存的事件一致。
|
|
2364
|
+
|
|
2365
|
+
UpdateComponentEventOperation:
|
|
2366
|
+
type: object
|
|
2367
|
+
required: [op, key, eventId, event]
|
|
2368
|
+
description: 按 id 替换组件的一个交互事件。
|
|
2369
|
+
properties:
|
|
2370
|
+
op: {const: updateComponentEvent}
|
|
2371
|
+
key: {type: string}
|
|
2372
|
+
eventId: {type: string, description: 要替换的事件 id。}
|
|
2373
|
+
event: {type: object, additionalProperties: true}
|
|
2374
|
+
|
|
2375
|
+
DeleteComponentEventOperation:
|
|
2376
|
+
type: object
|
|
2377
|
+
required: [op, key, eventId]
|
|
2378
|
+
description: 删除组件的一个交互事件。
|
|
2379
|
+
properties:
|
|
2380
|
+
op: {const: deleteComponentEvent}
|
|
2381
|
+
key: {type: string}
|
|
2382
|
+
eventId: {type: string}
|
|
2383
|
+
|
|
2384
|
+
SetStaticDataOperation:
|
|
2385
|
+
type: object
|
|
2386
|
+
required: [op, key]
|
|
2387
|
+
description: 设置组件静态数据,只更新传入的 `data` 或 `fields`。
|
|
2388
|
+
properties:
|
|
2389
|
+
op: {const: setComponentStaticData}
|
|
2390
|
+
key: {type: string}
|
|
2391
|
+
data: {description: 静态数据内容。}
|
|
2392
|
+
fields: {description: 字段映射。}
|
|
2393
|
+
|
|
2394
|
+
BindDataOperation:
|
|
2395
|
+
type: object
|
|
2396
|
+
required: [op, key, dataType]
|
|
2397
|
+
description: 把组件绑定到数据源。`dataType` 不是 `static` 时,`data.data_id` 必填。
|
|
2398
|
+
properties:
|
|
2399
|
+
op: {const: element.bindData}
|
|
2400
|
+
key: {type: string}
|
|
2401
|
+
dataType: {type: string, description: 数据源类型,如 `mysql`、`api`。}
|
|
2402
|
+
data:
|
|
2403
|
+
type: object
|
|
2404
|
+
additionalProperties: true
|
|
2405
|
+
description: 查询配置,包含 `data_id`。
|
|
2406
|
+
fields: {description: 字段映射。}
|
|
2407
|
+
|
|
2408
|
+
UnbindDataOperation:
|
|
2409
|
+
type: object
|
|
2410
|
+
required: [op, key]
|
|
2411
|
+
description: 组件改回使用静态数据。
|
|
2412
|
+
properties:
|
|
2413
|
+
op: {const: element.unbindData}
|
|
2414
|
+
key: {type: string}
|
|
2415
|
+
|
|
2416
|
+
UpgradeVersionOperation:
|
|
2417
|
+
type: object
|
|
2418
|
+
required: [op, key, version]
|
|
2419
|
+
description: 把组件升级到指定版本,不更换 module。
|
|
2420
|
+
properties:
|
|
2421
|
+
op: {const: upgradeComponentVersion}
|
|
2422
|
+
key: {type: string}
|
|
2423
|
+
version: {type: string, description: 目标版本,如 `1.0.1`。}
|
|
2424
|
+
|
|
2425
|
+
SetLayerVisibleOperation:
|
|
2426
|
+
type: object
|
|
2427
|
+
required: [op, key, visible]
|
|
2428
|
+
description: 设置图层显隐。
|
|
2429
|
+
properties:
|
|
2430
|
+
op: {const: setLayerVisible}
|
|
2431
|
+
key: {type: string, description: 图层 key,可以是组件或分组。}
|
|
2432
|
+
visible: {type: boolean}
|
|
2433
|
+
|
|
2434
|
+
MoveLayerOperation:
|
|
2435
|
+
type: object
|
|
2436
|
+
required: [op, key]
|
|
2437
|
+
description: 移动图层。`parentKey` 为 null 或不传表示移到根层级,`index` 是目标位置。
|
|
2438
|
+
properties:
|
|
2439
|
+
op: {const: moveLayer}
|
|
2440
|
+
key: {type: string}
|
|
2441
|
+
parentKey: {type: string, nullable: true, description: 目标父图层 key。}
|
|
2442
|
+
index: {type: integer, minimum: 0}
|
|
2443
|
+
|
|
2444
|
+
GroupLayersOperation:
|
|
2445
|
+
type: object
|
|
2446
|
+
required: [op, keys, groupKey]
|
|
2447
|
+
description: 把同一父节点下的多个图层合成一个分组。
|
|
2448
|
+
properties:
|
|
2449
|
+
op: {const: groupLayers}
|
|
2450
|
+
keys: {type: array, minItems: 2, items: {type: string}, description: 要成组的图层 key。}
|
|
2451
|
+
groupKey: {type: string, description: 新分组的 key,必须以 `g-` 开头。}
|
|
2452
|
+
name: {type: string, description: 分组名称。}
|
|
2453
|
+
|
|
2454
|
+
UngroupLayerOperation:
|
|
2455
|
+
type: object
|
|
2456
|
+
required: [op, key]
|
|
2457
|
+
description: 解散分组,子图层回到分组原来的位置。
|
|
2458
|
+
properties:
|
|
2459
|
+
op: {const: ungroupLayer}
|
|
2460
|
+
key: {type: string, description: 分组 key。}
|
|
2461
|
+
|
|
2462
|
+
ValidateDocumentRequest:
|
|
2463
|
+
type: object
|
|
2464
|
+
description: 可以是空对象。不要为了「校验已保存大屏」而省略整个 body 时再带一个非法的 `document`。
|
|
2465
|
+
properties:
|
|
2466
|
+
document:
|
|
2467
|
+
$ref: '#/components/schemas/ScreenDocument'
|
|
2468
|
+
description: 待校验的文档。省略则校验已保存内容。
|
|
2469
|
+
|
|
2470
|
+
ValidationIssue:
|
|
2471
|
+
type: object
|
|
2472
|
+
required: [severity, code, path, message]
|
|
2473
|
+
properties:
|
|
2474
|
+
severity:
|
|
2475
|
+
type: string
|
|
2476
|
+
enum: [error, warn]
|
|
2477
|
+
description: '`error` 使 `valid` 为 false;`warn` 不影响 `valid`。'
|
|
2478
|
+
code:
|
|
2479
|
+
type: string
|
|
2480
|
+
description: |
|
|
2481
|
+
| code | 级别 | 含义 |
|
|
2482
|
+
| --- | --- | --- |
|
|
2483
|
+
| `SCHEMA_VERSION_UNSUPPORTED` | error | `schemaVersion` 不是 `1.0` |
|
|
2484
|
+
| `SCREEN_NAME_REQUIRED` | error | 名称为空 |
|
|
2485
|
+
| `SCREEN_NAME_TOO_LONG` | error | 名称超过 255 |
|
|
2486
|
+
| `CANVAS_WIDTH_INVALID` / `CANVAS_HEIGHT_INVALID` | error | 宽或高不是大于 0 的数 |
|
|
2487
|
+
| `LAYERS_INVALID` | error | `layers` 不是数组 |
|
|
2488
|
+
| `LAYERS_EMPTY` | error | 没有任何图层 |
|
|
2489
|
+
| `LAYER_KEY_DUPLICATED` | error | 图层 key 重复 |
|
|
2490
|
+
| `LAYER_ELEMENT_MISSING` | error | 图层引用了不存在的元素 |
|
|
2491
|
+
| `ELEMENT_NOT_IN_LAYERS` | warn | 元素不在图层树里,不会渲染 |
|
|
2492
|
+
| `ELEMENT_KIND_INVALID` | error | `kind` 不是 component / panel / container |
|
|
2493
|
+
| `ELEMENT_INVALID` | error | 元素不是对象 |
|
|
2494
|
+
| `COMPONENT_MODULE_REQUIRED` / `COMPONENT_VERSION_REQUIRED` | error | 组件缺 module 或 version |
|
|
2495
|
+
| `COMPONENT_CONFIG_INVALID` | error | `config` 存在但不是数组 |
|
|
2496
|
+
| `ELEMENT_SIZE_INVALID` | error | layout 宽或高小于等于 0 |
|
|
2497
|
+
| `ELEMENT_OUT_OF_CANVAS` | warn | 超出画布,`details` 含超出的像素 |
|
|
2498
|
+
| `ELEMENT_HIDDEN` | warn | 图层或所在分组被隐藏,预览里看不到 |
|
|
2499
|
+
| `ELEMENT_OVERLAP` | warn | 两个组件部分重叠,`details.keys` 是这两个 key;完全包含(如背景)不报 |
|
|
2500
|
+
| `DATA_SOURCE_REQUIRED` | error | 绑定了数据源但 `dataBinding.data.data_id` 为空 |
|
|
2501
|
+
| `DATA_SOURCE_NOT_FOUND` | error | dataId 不属于当前团队 |
|
|
2502
|
+
| `DATA_FIELDS_MISSING` | warn | 没有字段映射 |
|
|
2503
|
+
| `STATE_EMPTY` | warn | 面板或容器没有状态 |
|
|
2504
|
+
| `ELEMENT_COUNT_EXCEEDED` | error | 元素数超过 `limits.documentMaxElements` |
|
|
2505
|
+
path:
|
|
2506
|
+
type: string
|
|
2507
|
+
description: JSON Pointer,指向文档中的位置,例如 `/elements/chart-1/layout`。
|
|
2508
|
+
message: {type: string, description: 说明。}
|
|
2509
|
+
details:
|
|
2510
|
+
type: object
|
|
2511
|
+
description: 补充数据,如重复的 key、越界像素。没有时省略。
|
|
2512
|
+
additionalProperties: true
|
|
2513
|
+
|
|
2514
|
+
ValidationResult:
|
|
2515
|
+
type: object
|
|
2516
|
+
required: [valid, issues]
|
|
2517
|
+
properties:
|
|
2518
|
+
valid:
|
|
2519
|
+
type: boolean
|
|
2520
|
+
description: 没有任何 `error` 级问题时为 `true`。
|
|
2521
|
+
revision:
|
|
2522
|
+
type: string
|
|
2523
|
+
description: 被校验文档上的 revision。校验已保存大屏时就是当前摘要。
|
|
2524
|
+
issues:
|
|
2525
|
+
type: array
|
|
2526
|
+
description: 全部 error 和 warn,顺序为校验器发现的顺序。
|
|
2527
|
+
items: {$ref: '#/components/schemas/ValidationIssue'}
|
|
2528
|
+
|
|
2529
|
+
PublishRequest:
|
|
2530
|
+
type: object
|
|
2531
|
+
description: |
|
|
2532
|
+
发布选项。未出现的字段保持大屏上的原配置。
|
|
2533
|
+
没有 `shareType`:服务端始终按普通分享处理。
|
|
2534
|
+
properties:
|
|
2535
|
+
needPassword:
|
|
2536
|
+
type: boolean
|
|
2537
|
+
description: '是否开启访问密码。与 `needToken: true` 互斥。'
|
|
2538
|
+
password:
|
|
2539
|
+
type: string
|
|
2540
|
+
minLength: 6
|
|
2541
|
+
maxLength: 20
|
|
2542
|
+
description: 访问密码。`needPassword` 为 true 且不传时,由服务端生成并在响应中返回。
|
|
2543
|
+
needToken:
|
|
2544
|
+
type: boolean
|
|
2545
|
+
description: '是否开启访问 Token。与 `needPassword: true` 互斥。'
|
|
2546
|
+
token:
|
|
2547
|
+
type: string
|
|
2548
|
+
minLength: 6
|
|
2549
|
+
maxLength: 20
|
|
2550
|
+
description: 访问 Token。`needToken` 为 true 且不传时,由服务端生成并在响应中返回。
|
|
2551
|
+
expiredAt:
|
|
2552
|
+
type: [string, 'null']
|
|
2553
|
+
format: date-time
|
|
2554
|
+
description: 分享过期时间。传 `null` 表示不过期。需要高级版及以上。
|
|
2555
|
+
republish:
|
|
2556
|
+
type: boolean
|
|
2557
|
+
description: 为 true 时重新生成分享路径,旧链接失效。
|
|
2558
|
+
|
|
2559
|
+
PublishResult:
|
|
2560
|
+
type: object
|
|
2561
|
+
description: 发布成功后的分享信息。密码和 Token 只在本次响应里出现这一次,之后的查询接口不再返回。
|
|
2562
|
+
required: [published, shareId, path, needPassword, needToken]
|
|
2563
|
+
properties:
|
|
2564
|
+
published: {type: boolean, description: 恒为 `true`。}
|
|
2565
|
+
shareId: {type: string, description: 分享 id。}
|
|
2566
|
+
path:
|
|
2567
|
+
type: string
|
|
2568
|
+
description: 分享页相对路径,形如 `/shareScreen/{shareId}`。域名由调用方拼接。
|
|
2569
|
+
needPassword: {type: boolean, description: 是否需要密码。}
|
|
2570
|
+
needToken: {type: boolean, description: 是否需要 Token。}
|
|
2571
|
+
password:
|
|
2572
|
+
type: string
|
|
2573
|
+
description: 本次生效的密码。未开启密码时省略。
|
|
2574
|
+
token:
|
|
2575
|
+
type: string
|
|
2576
|
+
description: 本次生效的 Token。未开启 Token 时省略。
|
|
2577
|
+
expiredAt:
|
|
2578
|
+
type: [string, 'null']
|
|
2579
|
+
format: date-time
|
|
2580
|
+
description: 过期时间。不过期时为 `null`。
|
|
2581
|
+
|
|
2582
|
+
VersionSummary:
|
|
2583
|
+
type: object
|
|
2584
|
+
description: 规划中的快照摘要。当前接口不会返回它。
|
|
2585
|
+
required: [id, version, createdAt]
|
|
2586
|
+
properties:
|
|
2587
|
+
id: {type: integer, format: int64, description: 快照 id,回滚时作为 `versionId`。}
|
|
2588
|
+
version: {type: string, description: 版本号。}
|
|
2589
|
+
description: {type: [string, 'null'], description: 创建时填写的说明。}
|
|
2590
|
+
lock: {type: boolean, description: 是否锁定,锁定后不能被自动清理。}
|
|
2591
|
+
createdAt: {type: string, format: date-time, description: 创建时间。}
|
|
2592
|
+
|
|
2593
|
+
VersionList:
|
|
2594
|
+
type: object
|
|
2595
|
+
description: 规划中的版本列表。
|
|
2596
|
+
required: [items]
|
|
2597
|
+
properties:
|
|
2598
|
+
items:
|
|
2599
|
+
type: array
|
|
2600
|
+
items: {$ref: '#/components/schemas/VersionSummary'}
|
|
2601
|
+
limit: {type: integer, description: 每个大屏保留的快照上限,当前设计为 3。}
|
|
2602
|
+
|
|
2603
|
+
CreateVersionRequest:
|
|
2604
|
+
type: object
|
|
2605
|
+
description: 规划中的创建快照参数。当前会被 501 拒绝,body 不会被读取。
|
|
2606
|
+
properties:
|
|
2607
|
+
version: {type: string, description: 版本号。不传则由服务端生成。}
|
|
2608
|
+
description: {type: string, description: 这段快照的说明。}
|
|
2609
|
+
|
|
2610
|
+
ComponentField:
|
|
2611
|
+
type: object
|
|
2612
|
+
required: [path, name]
|
|
2613
|
+
description: 从组件默认配置摊平后的一个字段。
|
|
2614
|
+
properties:
|
|
2615
|
+
path:
|
|
2616
|
+
type: string
|
|
2617
|
+
description: 属性树路径,用 `.` 连接各级 `name`,如 `chart.style.color`。
|
|
2618
|
+
name: {type: string, description: 该节点自己的名字,即 path 的最后一段。}
|
|
2619
|
+
labelPath:
|
|
2620
|
+
type: array
|
|
2621
|
+
items: {type: string}
|
|
2622
|
+
description: 从顶层到自身的中文标签链,跳过没有标签的包装层;自身没有标签时末项是 `name`。
|
|
2623
|
+
label: {type: string, description: 编辑器里展示的中文名。提取不到时省略。}
|
|
2624
|
+
type:
|
|
2625
|
+
type: string
|
|
2626
|
+
description: 控件类型,如 `number`、`string`、`select`、`color`、`boolean`。提取不到时省略。
|
|
2627
|
+
default: {description: 默认值,类型随字段变化。}
|
|
2628
|
+
options:
|
|
2629
|
+
type: array
|
|
2630
|
+
description: '`select` 等控件的可选项。'
|
|
2631
|
+
items:
|
|
2632
|
+
type: object
|
|
2633
|
+
properties:
|
|
2634
|
+
label: {type: string, description: 选项显示名。}
|
|
2635
|
+
value: {description: 选项值。}
|
|
2636
|
+
group: {type: string, description: 所属顶层分组的中文名,如「样式」。}
|
|
2637
|
+
rule: {description: 面板联动规则,原样保留,结构由组件自己定义。}
|
|
2638
|
+
|
|
2639
|
+
ComponentDataField:
|
|
2640
|
+
type: object
|
|
2641
|
+
required: [name, value]
|
|
2642
|
+
description: 组件默认数据的一列,用于理解数据绑定,不是配置项。
|
|
2643
|
+
properties:
|
|
2644
|
+
name: {type: string, description: 字段名。}
|
|
2645
|
+
value: {type: string, description: 字段映射值。}
|
|
2646
|
+
desc: {type: string, description: 字段说明。}
|
|
2647
|
+
|
|
2648
|
+
ComponentSchema:
|
|
2649
|
+
type: object
|
|
2650
|
+
required: [module, version, source, strict, fields, dataFields, triggers, actions, requiresPreset, unsupported, cached, stats]
|
|
2651
|
+
properties:
|
|
2652
|
+
module: {type: string, description: 请求的组件模块名。}
|
|
2653
|
+
version: {type: string, description: 实际解析的版本。}
|
|
2654
|
+
source:
|
|
2655
|
+
type: string
|
|
2656
|
+
enum: [extracted, partial, inferred]
|
|
2657
|
+
description: |
|
|
2658
|
+
`extracted`:静态提取成功。
|
|
2659
|
+
`partial`:提取到一部分,但存在动态表达式。
|
|
2660
|
+
`inferred`:无法完整提取、只能推断。
|
|
2661
|
+
strict:
|
|
2662
|
+
type: boolean
|
|
2663
|
+
description: 是否完全静态提取(没有 unsupported,且至少有一个字段)。
|
|
2664
|
+
base: {type: object, description: 组件包中的 base 信息,如模块名。没有则省略。}
|
|
2665
|
+
extra: {type: object, description: 提取过程中的附加信息。没有则省略。}
|
|
2666
|
+
fields:
|
|
2667
|
+
type: array
|
|
2668
|
+
description: 配置字段,顺序与属性树遍历顺序一致。
|
|
2669
|
+
items: {$ref: '#/components/schemas/ComponentField'}
|
|
2670
|
+
dataFields:
|
|
2671
|
+
type: array
|
|
2672
|
+
items: {$ref: '#/components/schemas/ComponentDataField'}
|
|
2673
|
+
triggers:
|
|
2674
|
+
type: array
|
|
2675
|
+
description: 组件能发出的事件,`value` 用作交互事件的 trigger。
|
|
2676
|
+
items: {$ref: '#/components/schemas/ComponentInteraction'}
|
|
2677
|
+
actions:
|
|
2678
|
+
type: array
|
|
2679
|
+
description: 组件能接收的动作。
|
|
2680
|
+
items: {$ref: '#/components/schemas/ComponentInteraction'}
|
|
2681
|
+
size:
|
|
2682
|
+
type: object
|
|
2683
|
+
description: 拖入画布时的默认宽高。读不到时省略。
|
|
2684
|
+
properties:
|
|
2685
|
+
width: {type: number}
|
|
2686
|
+
height: {type: number}
|
|
2687
|
+
defaultData: {description: 组件包自带的默认数据,结构与 `dataFields` 对应。}
|
|
2688
|
+
requiresPreset: {type: boolean, description: 为 true 时需要先选预设,暂不能通过 OpenAPI 新增。}
|
|
2689
|
+
unsupported:
|
|
2690
|
+
type: array
|
|
2691
|
+
description: 遇到动态表达式的路径。非空时不要把 `fields` 当成完整清单。
|
|
2692
|
+
items: {type: string}
|
|
2693
|
+
cached: {type: boolean, description: 本次是否命中 24 小时缓存。}
|
|
2694
|
+
stats:
|
|
2695
|
+
type: object
|
|
2696
|
+
description: 本次解析的规模,用于排查,不是业务字段。
|
|
2697
|
+
properties:
|
|
2698
|
+
bytes: {type: integer, description: 组件脚本字节数。}
|
|
2699
|
+
parseMs: {type: integer, description: 解析耗时,毫秒。}
|
|
2700
|
+
fieldCount: {type: integer, description: '`fields` 的条数。'}
|
|
2701
|
+
dataFieldCount: {type: integer, description: '`dataFields` 的条数。'}
|
|
2702
|
+
|
|
2703
|
+
ComponentInteraction:
|
|
2704
|
+
type: object
|
|
2705
|
+
required: [name, value]
|
|
2706
|
+
additionalProperties: true
|
|
2707
|
+
properties:
|
|
2708
|
+
name: {type: string, description: 中文名,如「鼠标点击」。}
|
|
2709
|
+
value: {type: string, description: 标识,如 `click`。}
|
|
2710
|
+
|
|
2711
|
+
Job:
|
|
2712
|
+
type: object
|
|
2713
|
+
description: 规划中的异步任务。当前 `GET /jobs/{jobId}` 不会返回它。
|
|
2714
|
+
required: [jobId, status]
|
|
2715
|
+
properties:
|
|
2716
|
+
jobId: {type: string, description: 任务 id。}
|
|
2717
|
+
type: {type: string, description: 任务类型。}
|
|
2718
|
+
status:
|
|
2719
|
+
type: string
|
|
2720
|
+
enum: [pending, running, succeeded, failed, canceled]
|
|
2721
|
+
description: 任务状态。
|
|
2722
|
+
progress: {type: integer, minimum: 0, maximum: 100, description: 进度百分比。}
|
|
2723
|
+
result: {description: 成功时的结果,结构依任务类型而定。}
|
|
2724
|
+
error:
|
|
2725
|
+
type: object
|
|
2726
|
+
description: 失败原因。
|
|
2727
|
+
properties:
|
|
2728
|
+
code: {type: string}
|
|
2729
|
+
message: {type: string}
|
|
2730
|
+
createdAt: {type: string, format: date-time, description: 创建时间。}
|
|
2731
|
+
finishedAt: {type: string, format: date-time, description: 结束时间。未结束时省略。}
|
|
2732
|
+
|
|
2733
|
+
AssetUploaded:
|
|
2734
|
+
type: object
|
|
2735
|
+
description: 上传结果。把 `path` 写入组件或画布,把 `url` 留给预览。
|
|
2736
|
+
required: [path, url, size]
|
|
2737
|
+
properties:
|
|
2738
|
+
path:
|
|
2739
|
+
type: string
|
|
2740
|
+
description: 相对路径,即对象存储的 key。示例:`spaces/10/openapi-assets/202611/Ab3xYz9kQ2LmNoPq.png`。
|
|
2741
|
+
url:
|
|
2742
|
+
type: string
|
|
2743
|
+
description: 资源域名加 `path`,浏览器可直接打开。
|
|
2744
|
+
fileName: {type: string, description: 上传时的原始文件名,仅供核对,不参与存储路径。}
|
|
2745
|
+
size: {type: integer, description: 文件字节数。}
|
|
2746
|
+
contentType: {type: string, description: multipart 声明的 MIME 类型。}
|
|
2747
|
+
|
|
2748
|
+
ComponentCatalogItem:
|
|
2749
|
+
type: object
|
|
2750
|
+
required: [module, name, version, source, status]
|
|
2751
|
+
description: 组件目录中的一项。
|
|
2752
|
+
properties:
|
|
2753
|
+
module: {type: string, description: 组件模块名。}
|
|
2754
|
+
name: {type: string, description: 组件显示名。}
|
|
2755
|
+
version: {type: string, description: 最新版本。}
|
|
2756
|
+
category: {type: string, description: 分类。空间组件固定为「空间组件」。}
|
|
2757
|
+
thumb: {type: string, description: 缩略图路径,原样返回数据库里的值。没有时省略。}
|
|
2758
|
+
source: {type: string, enum: [platform, space], description: platform 官方组件,space 空间私有组件。}
|
|
2759
|
+
status: {type: string, enum: [published, unpublished], description: 发布状态。官方组件恒为 published。}
|
|
2760
|
+
|
|
2761
|
+
PublishedComponent:
|
|
2762
|
+
type: object
|
|
2763
|
+
required: [id, module, name, version, status]
|
|
2764
|
+
description: 上传空间组件包的结果。
|
|
2765
|
+
properties:
|
|
2766
|
+
id: {type: integer}
|
|
2767
|
+
module: {type: string}
|
|
2768
|
+
name: {type: string}
|
|
2769
|
+
version: {type: string}
|
|
2770
|
+
status: {type: string, enum: [published, unpublished], description: 空间组件默认即 published,可直接使用。}
|
|
2771
|
+
|
|
2772
|
+
DataSource:
|
|
2773
|
+
type: object
|
|
2774
|
+
required: [dataId, name, dataType]
|
|
2775
|
+
description: 数据源。详情才返回 config,且敏感字段已掩码。
|
|
2776
|
+
properties:
|
|
2777
|
+
dataId: {type: string}
|
|
2778
|
+
name: {type: string}
|
|
2779
|
+
dataType: {type: string, description: 类型名,如 `mysql`、`api`。}
|
|
2780
|
+
description: {type: string}
|
|
2781
|
+
updatedAt: {type: string, format: date-time}
|
|
2782
|
+
config: {type: object, additionalProperties: true, description: 配置,密码等字段为 `******`。}
|
|
2783
|
+
|
|
2784
|
+
DataSourceInput:
|
|
2785
|
+
type: object
|
|
2786
|
+
required: [name, dataType]
|
|
2787
|
+
description: 新建或更新数据源的入参。密码只写不读。
|
|
2788
|
+
properties:
|
|
2789
|
+
name: {type: string}
|
|
2790
|
+
dataType: {type: string, description: 类型名,如 `mysql`、`postgresql`、`api`、`csv`。}
|
|
2791
|
+
description: {type: string}
|
|
2792
|
+
addr: {type: string, description: 数据库地址。}
|
|
2793
|
+
port: {type: integer}
|
|
2794
|
+
username: {type: string}
|
|
2795
|
+
password: {type: string, description: 只写不读。更新时不传则保留原值。}
|
|
2796
|
+
database: {type: string}
|
|
2797
|
+
sid: {type: string, description: Oracle SID。}
|
|
2798
|
+
serviceName: {type: string, description: Oracle service name。}
|
|
2799
|
+
baseURL: {type: string, description: API、MQTT、WebSocket 的地址。}
|
|
2800
|
+
appKey: {type: string}
|
|
2801
|
+
appSecret: {type: string}
|
|
2802
|
+
apiKey: {type: string}
|
|
2803
|
+
topic: {type: string}
|
|
2804
|
+
filePath: {type: string, description: CSV 文件路径。}
|
|
2805
|
+
useSsl: {type: boolean}
|
|
2806
|
+
baseId: {type: string, description: 数据填报的 baseId。}
|
|
2807
|
+
brokers: {type: array, items: {type: string}, description: Kafka brokers。}
|
|
2808
|
+
|
|
2809
|
+
PreviewToken:
|
|
2810
|
+
type: object
|
|
2811
|
+
required: [token, expiresAt, previewPath]
|
|
2812
|
+
properties:
|
|
2813
|
+
token: {type: string}
|
|
2814
|
+
expiresAt: {type: string, format: date-time}
|
|
2815
|
+
previewPath: {type: string, description: 预览页路径,拼到 Web 站点域名后打开。}
|
|
2816
|
+
|
|
2817
|
+
DeviceAuthorization:
|
|
2818
|
+
type: object
|
|
2819
|
+
required: [device_code, user_code, verification_uri, verification_uri_complete, expires_in, interval]
|
|
2820
|
+
properties:
|
|
2821
|
+
device_code: {type: string}
|
|
2822
|
+
user_code: {type: string}
|
|
2823
|
+
verification_uri: {type: string, description: 授权页绝对地址。网关和 Web 同域时可以直接打开}
|
|
2824
|
+
verification_uri_complete: {type: string}
|
|
2825
|
+
expires_in: {type: integer}
|
|
2826
|
+
interval: {type: integer}
|
|
2827
|
+
verificationPath: {type: string, description: 授权页路径。命令行在 API 与 Web 不同域时,把这个路径拼到 Web 站点上}
|
|
2828
|
+
|
|
2829
|
+
DeviceCode:
|
|
2830
|
+
type: object
|
|
2831
|
+
required: [deviceCode, userCode, verificationPath, interval, expiresIn]
|
|
2832
|
+
properties:
|
|
2833
|
+
deviceCode: {type: string, description: CLI 轮询时使用。}
|
|
2834
|
+
userCode: {type: string, description: 用户在授权页确认的短码,形如 ABCD-EFGH。}
|
|
2835
|
+
verificationPath: {type: string, description: 授权页路径,拼到 Web 站点域名后打开。}
|
|
2836
|
+
interval: {type: integer, description: 建议的轮询间隔,单位秒。}
|
|
2837
|
+
expiresIn: {type: integer, description: 有效期,单位秒。}
|
|
2838
|
+
|
|
2839
|
+
DeviceToken:
|
|
2840
|
+
type: object
|
|
2841
|
+
required: [token, context]
|
|
2842
|
+
properties:
|
|
2843
|
+
token: {type: string, description: API Key,格式 appId.secret。只返回这一次。}
|
|
2844
|
+
context:
|
|
2845
|
+
type: object
|
|
2846
|
+
properties:
|
|
2847
|
+
appId: {type: string}
|
|
2848
|
+
spaceId: {type: integer}
|
|
2849
|
+
teamId: {type: integer}
|
|
2850
|
+
scopes: {type: array, items: {type: string}}
|