---
order: 10
---
# URL参考

本文介绍系统的URL路由规则。

## URL路由规则{#route-rules}

系统内有很多内容都需要通过URL路由访问到，包括系统功能页面、系统的API接口、登录页面、静态图片、js、css等，也包括用户自产的内容，如报表、仪表板、应用页面等，系统会安装如下路由顺序，从上至下，依次匹配路由：

1. [系统内置URL](#sys-paths) - 系统内置URL，是系统功能正常运行的基础，优先级最高。
2. 用户在系统设置中配置的自定义的路由规则 - TODO 补充link
3. 用户在app应用中配置的自定义的路由规则 - TODO 补充link
4. `/{元数据项目名称}/path/to/metafile` - 见[元数据文件URL](#file-url)
5. `/{应用名（不含后缀）}/path/to/metafile` - 见[应用名短路径URL](#app-short-path)

## 系统内置URL{#sys-paths}

系统内置URL如下：

- `/login` 访问当前用户设置的自定义登录页面
  - `/login/default` 总是显示系统默认登录页面，忽略用户对登录页面的设置
- `/api` - API接口
- `/dist` - 静态资源，如js、css、图片等
- `/projects` 项目列表页面
- `/syssettings` 系统设置页面
- `/datasources` 数据源管理
- `/security` 权限管理页面
- `/schedules` 计划
- `/tasks` 任务
- `/extension-mgr` 扩展管理
- `/tasks` 任务
- `/me` - 我的
- `/public`
- `/fid/{元数据ID}` 通过元数据id访问元数据，功能和通过路径访问一致

## 系统URL参数{#sys-url-params}

系统每个页面都可以使用这些参数：

- `:user`、`:password`、`:cipherPassport` - 见[在url上输入用户ID密码登录](../../devops/sso/urllogin.md)
- `access_token` - 用于根据令牌登录系统
- `:embedded` - 传`true`时表示页面是被嵌入到其它的页面中的，此时会给html的body元素上添加一个class：`embedded`，开发者可以通过编写[custom.css](/dev/hooks/custom-css)来重载相应的样式。

### public目录

TODO

### 我的工作URL

如：

1. <https://demo.succbi.com/DEMO/my-tasks>
2. <https://demo.succbi.com/DEMO/my-tasks/todo>

**我的工作URL支持如下参数：**

1. `:visibleTabs` - 显示的标签，多个标签用逗号分隔。不支持直接打开一个标签时使用。
2. `:tab` - 默认显示的标签。不支持直接打开一个标签时使用。

### 登录界面URL

1. 可定制登录界面：<https://demo.succbi.com/login>
2. 默认登录界面：<https://demo.succbi.com/login/default>

**登录界面URL支持如下参数**

1. `redirect_url`：登录成功后跳转的地址：
   - 仅支持传递一个以`/`开头的相对地址，登录成功后跳转到系统内对应的相对地址，**注意：一定不会根据传入地址上下文跳转到其他系统**。
   - 请对参数进行[URL转义](https://tool.chinaz.com/tools/urlencode.aspx)

### 健康检测URL

用于界面检测与服务器的通讯状态。URL:

1. <https://demo.succbi.com/api/sys/health-info>

**返回值和状态说明：**

1. 该接口关注的只是服务器是否能够通讯，接口里直接返回`ok`。

### 附件下载URL

用于下载或者预览附件，URL如：

1. 下载单个附件</br><https://demo.succbi.com/api/dw/services/downloadAttachment?preview=false&resIdOrPath=/TestCase/data/tables/TESTCASE/attachment/test_dwAttachment.tbl&keys=%5B%224febf2e53ca84640a4479e578e85ced0%22%5D&fileField=%E6%96%87%E4%BB%B6%E5%86%85%E5%AE%B9%E5%AD%97%E6%AE%B5&zipFile=true></br>
   参数解析：

```json
{
    "preview": false,
    "resIdOrPath": "/TestCase/data/tables/TESTCASE/attachment/test_dwAttachment.tbl",
    "keys": ["eb232959ef714d35b7459597b1c93e7a"],
    "fileField": "文件内容字段",
    "zipFile": true
}
```

2. 预览附件</br><https://demo.succbi.com/api/dw/services/downloadAttachment?preview=true&resIdOrPath=/TestCase/data/tables/TESTCASE/ana/test_spg.dash&queryId=model2&keys=%5B%224febf2e53ca84640a4479e578e85ced0%22%5D&fileField=%E6%96%87%E4%BB%B6%E5%86%85%E5%AE%B9%E5%AD%97%E6%AE%B5></br>
   参数解析：

```json
{
    "preview": true,
    "resIdOrPath": "/TestCase/data/tables/TESTCASE/ana/test_spg.dash",
    "queryId": "model2",
    "keys": ["eb232959ef714d35b7459597b1c93e7a"],
    "fileField": "文件内容字段"
}
```

3. 批量下载附件</br><https://demo.succbi.com/api/dw/services/downloadAttachment?preview=false&resIdOrPath=/TestCase/data/tables/TESTCASE/attachment/test_dwAttachment.tbl&fileField=%E6%96%87%E4%BB%B6%E8%B7%AF%E5%BE%84%E5%AD%97%E6%AE%B5&dataKeyMap=%7B%22id%22:%5B%229248db7a2e5b4e868646dfffa17329a9%22,%228534431408e244b9a705e87e57a3046c%22,%2237be68098cfb4ea3a7a8b7b96bbb22af%22%5D%7D&fileName=%E4%B8%8B%E8%BD%BD%E5%8E%8B%E7%BC%A9%E9%99%84%E4%BB%B6.zip></br>
   参数解析：

```json
{
    "preview": false,
    "resIdOrPath": "/TestCase/data/tables/TESTCASE/attachment/test_dwAttachment.tbl",
    "fileField": "文件路径字段",
    "dataKeyMap": {
        "id":["9248db7a2e5b4e868646dfffa17329a9","8534431408e244b9a705e87e57a3046c","37be68098cfb4ea3a7a8b7b96bbb22af"]
    },
    "fileName": "下载压缩附件.zip"
}
```

4. 预览下载临时附件</br><https://demo.succbi.com/api/dw/services/downloadAttachment?preview=false&fileId=33e2ff76b09d11a544fba4986a60d2dd55eb-20200213210429.png></br>
   参数解析：

```json
{
    "preview": false,
    "fileId": "33e2ff76b09d11a544fba4986a60d2dd55eb-20200213210429.png"
}
```

参数说明：

1. `resIdOrPath` - 发起查询的资源uuid或路径，可以是报表或spg，也可以是附件模型表本身。如果是报表或spg，则需要传入参数`queryId`
2. `queryId` - 查询约束id。一般是spg中的附件模型id或者别名，后端会根据这个queryId在后端找到真正的附件表
3. `fileField` - 文件角色字段名（或者物理字段名）。附件表可能有多个文件字段，需要指定使用哪个文件字段
4. `keys` - 下载或预览单个附件的过滤条件，参数格式和使用说明见下文
5. `dataKeyMap` - 批量下载附件的过滤条件，可选。`keys`和`dataKeyMap`只有一个生效，若已传入`keys`，则此参数无效。参数格式和使用说明见下文
6. `zipFile` - 下载的附件是否需要压缩，可选。当下载的附件只有一个时，会根据此参数决定是否仍然需要进行压缩后下载，默认不压缩。其他情况：下载多个附件时，始终压缩；预览时，此参数无效。
7. `fileName` - 指定下载附件的名称，可选。下载单个附件时，默认下载名称为附件名字段对应的名称；下载多个附件时（zip压缩文件），默认下载名称为后台根据下载附件id自动生成的名称。
8. `preview` - 传递`true`表示预览，下载附件只有1个时生效；传递`false`表示下载，默认false。
9. `fileId` - 临时附件id，可选。项目需求：上传的附件没有上报到附件表时，直接根据临时id预览下载临时上传的附件。该场景下，只需要传入`preview`和`fileId`，其他参数不需要。
10. 参数中可能包含中文或者特殊字符，因此需要最后对url编码一次（`encodeUrl(url)`）。

**`keys`和`dataKeyMap`参数说明:**

1. `keys`为附件字段的主键值数组的JSON字符串，用来过滤得到唯一附件。例如：附件表有一个主键attachmentId，想要下载主键为`abc`的附件，主键数组就为`["abc"]`，`keys`通过`JSON.stringify(主键数组)`获取。
2. `dataKeyMap`为附件表中字段名（或者物理字段名）和值的键值对的JSON字符串，用来过滤得到对应条件的多个附件。键值对map示例：

```json
//匹配class为"abc"的附件
{
    "class": "abc"
}
```

```json
//匹配dept为"1"或者"2"的附件
{
    //值可以是数组，各个值为“或”的关系
    "dept": ["1","2"]
}
```

```json
//匹配dept为"1"或者"2"并且class为"abc"的附件
{
    //可以有多个键值对，键值对之间是“且”的关系
    "dept": ["1","2"],
    "class": "abc"
}
```

同样的，键值对的JSON字符串需要通过`JSON.stringify(键值对)`获取。

## 元数据文件URL{#file-url}

对于用户自产的内容，如报表、仪表板、应用页面等元数据文件，可以使用约定的系统根路径以外的路径来访问，URL结构如下：

```
/{项目名称}/path/to/metafile(含后缀)
```

不使用元数据路径，使用元数据文件的ID也可以访问文件：

```
/fid/{资源ID}
```

**示例：**

- http://localhost:8080/DEMO/data/tables/%E9%80%9A%E7%94%A8/DIM\_GEN\_CPFZW.tbl  - 通过路径访问DEMO项目下的模型表`/DEMO/data/tables/通用/DIM_GEN_CPFZW.tbl`
- http://localhost:8080/fid/AhFiugf2t4CTxbj93Z7bCC - 通过资源ID访问元数据文件，等价于上面的示例

### 元数据文件通用参数{#file-common-params}

- `:edit` - 进入对应资源的编辑或设计界面，需要有相应的权限。
- `:preview` 传递true表示不需要查询所有数据，比如默认查询最多5000行数据(系统设置有阈值设置)，且不显示工具按钮
- `:animation` 传递false时禁用所有动画（例如为了尽快产生缩略图）
- 通过参数名或输入控件名称传递值，如仪表板或报表支持将参数或输入控件的值作为URL参数传递进来，如`input1=20190201`

### 目录的index页面{#folder-index}

### 应用名短路径URL{#app-short-path}

### 门户应用模版URL{#portal-page}

门户内部嵌入有很多子页面，其内部URL路由规则如下：

`/{资源节点ID}/{钻取ID路径/...}#{HASH}`

- 门户内每个可以定位到的页面都有自己的一个应用内的唯一id，不分模块层次或目录层次，与页面本身的元数据所在位置无关，规则如下：
  - 用户可以在资源节点上手工设置
  -

几个示例（假设通过`/ap`可以路由到`/DEMO/app/ap.app/index.tpg`）：

1. 打开顶部模块
2. 定位左侧资源树节点
3. 全屏预览资源
4. 报表内钻取到下级单位
5. 代办事项列表中点击到某个任务页面

### 报表、仪表板URL{#ana}

如：

1. <https://demo.succbi.com/v5/DEMO/ana/%E8%A1%8C%E4%B8%9A%E5%BA%94%E7%94%A8/%E6%9C%8D%E9%A5%B0%E4%BC%81%E4%B8%9A/%E5%AE%8C%E6%88%90%E7%8E%87%E5%88%86%E6%9E%90.dash>
2. <https://localhost/DEMO/ana/my-dash1.dash>

**报表仪表板支持如下参数：**

1. `:edit` - 对于仪表板、报表、应用、表单等对象，传递`true`将进入设计器模式。
2. `:filters` - 传递给仪表板、报表的个性化过滤条件，过滤条件可以作用到全局、指定数据源、指定控件，更多说明见下文。
3. `:breadcrumb` - 该参数用来控制打开的对于仪表板、报表文件是否在顶部显示面包屑，面包屑用于显示对应元数据的钻取路径，参数值可以为：
   1. `auto`：按需显示。开始不显示面包屑，当发生钻取且显示方式为当前容器时，则显示钻取路径的面包屑。
   2. `none`：不显示。总是不显示面包屑，此参数的优先级高于链接交互中的配置，同时也会影响报表填报应用中的面包屑显示。如果不显示面包屑，仪表板等可通过‘返回上页’交互返回钻取前的页面，表单内部通过关闭按钮返回。
   3. `show`：总是显示。一开始就显示面包屑，面包屑内容为当前打开的元数据名称。
4. 其他参数或输入控件 - 仪表板或报表支持将参数或输入控件的值作为URL参数传递进来，key为控件ID，value为值，如：
   1. `input1=420100`
5. `:showParamsPanel` - 该参数用于控制报表参数栏显示、隐藏，传递`false`表明要隐藏参数栏。该参数仅在报表使用。

**`:filters`参数说明:**

1. 支持两种格式，一种是表达式，一种是JSON，不管是表达式还是JSON，都需要进行编码（如使用javascript的`encodeURIComponent()`函数编码）。
2. 当使用表达式时，表示一个过滤条件表达式字符串，作用范围为全局，例如要传递`XS_DAY.JGDC='01' and XS_DAY.XSSL>1000`作为全局条件给仪表板，URL如：`https://localhost/DEMO/ana/my-dash1.dash?:filters=XS_DAY.JGDC%3D'01'%20and%20XS_DAY.XSSL%3E1000`。
3. 当使用JSON时，可以构造完整的字段过滤和表达式过滤，并自定义作用范围，例如要传递如下条件：

```json
[{
    "range": "1",//作用到：1:画布,2:数据源,3:控件，默认为1
    "exp":"XS_DAY.JGDC='01'",//表达式过滤条件
    "matchAll": true,//为true时表示and，false为or，使用clauses时有效
    "target": ["XS_DAY"],//作用目标，当range为2时，表示目标数据源的名称；range为3时，表示控件名称或ID。
    "clauses":[{
        "exp": "XS_DAY.JGDC='01'",
        "leftExp": "XS_DAY.YEARMONTH",
        "operator": ">=",
        "rightExp": "today()",//右值为表达式
        "rightValue": "20190101"//右值为常量值
    }]
}]
```

URL如下（用`encodeURIComponent(JSON.stringify({你的JSON参数})))`编码）：

```
https://localhost/DEMO/ana/my-dash1.dash?:filters=%5B%7B%22range%22%3A%221%22%2C%22exp%22%3A%22XS_DAY.JGDC%3D'01'%22%2C%22matchAll%22%3Atrue%2C%22target%22%3A%5B%22XS_DAY%22%5D%2C%22clauses%22%3A%5B%7B%22exp%22%3A%22XS_DAY.JGDC%3D'01'%22%2C%22leftExp%22%3A%22XS_DAY.YEARMONTH%22%2C%22operator%22%3A%22%3E%3D%22%2C%22rightExp%22%3A%22today()%22%2C%22rightValue%22%3A%2220190101%22%7D%5D%7D%5D
```

### 模型表URL{#model}

如：

1. <https://demo.succbi.com/v5/DEMO/data/tables/dataflow/DF_1.tbl>

**模型表URL支持如下参数：**

1. `:edit` - 进入模型管理界面，默认false。
2. `:viewer` - 默认为`data`，可以传递:
   1. `data` - 进入模型数据查询界面
   2. `linkages` - 显示模型的血统分析界面
   3. `fields` - 显示模型的字段列表界面
   4. `relations` - 显示模型的关联关系界面
   5. `dataflow` - 显示模型的加工流程图
   6. `hierarchy` - 显示模型的层次界面
   7. `settings` - 显示模型的基本设置界面

**当`:viewer`传递`data`时，可以使用如下更多参数配置：**

1. `:fields` - 指定显示出来的字段，不传递时显示所有字段，可以传递如下值：
   1. 一个JSON数组或者一个逗号（或竖线）分割的字段名（物理字段名或字段名）列表。
2. `:moreFields` - 指定哪些可选的输出字段，这些字段默认不显示出来，但是用户可以添加到查询结果中
3. `:titleVisible` 是否显示标题，不传递时默认不显示标题，传递`true`显示标题。
4. `:title` - 默认取元数据描述（没有描述取名称）作为标题，可以传递一个指定的标题。
5. `:limit` - 每页行数，默认100。
6. `:queryTotalRowCount` - 是否查询总行数，默认查询，传递`false`时不查询总行数，可以节省一些数据库资源。
7. `:filter` - 传递一个表达式过滤条件，只查询满足此条件的数据。
8. `:paramFields` - 指定默认显示哪些字段当作可选过滤条件，不传递时显示前5个维键字段，可以传递如下值：
   1. 数字，如`3`，表示显示前3个维键字段
   2. 一个JSON数组或者一个逗号（或竖线）分割的字段名（物理字段名或字段名）列表
   3. 一个JSON，key是物理字段名或字段名，value是字段对应的默认值
9. `:moreParamFields` - 指定哪些可选的条件过滤字段，这些字段默认不显示出来，但是用户可以添加进来，不传递时所有维键字段都是可选的，可以传递如下值：
   1. 一个JSON数组或者一个逗号（或竖线）分割的字段名（物理字段名或字段名）列表
   2. 一个JSON，key是物理字段名或字段名，value是字段对应的默认值
10. `:sortField` - 指定排序字段，默认不排序，可以传递一个字段的字段名或物理字段名，默认升序，可以在字段名后面加一个空格后输入`desc`或`asc`指定降序或升序，如需对多个字段进行排序传递多次此参数即可。
11. `:allowExport` - 是否显示导出按钮，默认显示。
12. `:allowSelectCell` - 是否能框选单元格，默认false。
13. `:allowChangePageSize` - 是否允许切换每页行数，默认true。
14. `:rowLink` - 指定一个宏字符串表示点击行后定位到的路径，宏中可以使用当前输出的字段或条件字段作为变量。
15. `:rowLinkTarget` 行链接默认显示的位置，可以指定如下值：
    1. `dialog` 在对话框中打开
    2. `_blank` 在新浏览器标签页中打开
    3. `_self` 在当前浏览器标签页中打开
    4. `container` 在当前容器中打开，此时会在容器上方显示钻取路径，点击路径可以回到钻取前的页面
16. `:fieldsLink` - 指定具体的字段的连接设置，是一个json，key是字段名或物理字段名，value是一个json包含link、target 属性。

### ActiveDoc URL{#activedoc}

显示一个文档（docx、pptx、pdf等）的预览效果，URL如：

1. <https://demo.succbi.com/v5/DEMO/app/ap.app/test.d.docx?param1=xx&param2=yy>

支持如下参数：

1. `:toolbar` - 是否显示工具栏，可选：`visible`显示工具栏（默认）, `hide`隐藏
2. `:scale` - 缩放设置，可选：`auto`自动缩放, `page-actual`实际大小, `page-fit`适合页面, `page-width`适合宽度, `0.5`表示50%, `0.75`表示75%, `3`表示300%...
3. `:sidebar` - 是否显示侧边栏，`visible`表示默认侧边栏可见，`hide`表示默认侧边栏隐藏（默认）
4. `:sidebarView` - 侧边栏显示大纲还是缩略图，`thumbnail`表示侧边栏默认显示缩略图，`outline`表示侧边栏默认显示大纲（默认）
5. `:printButton` - 是否显示打印按钮，`visible`显示（默认）, `hide`隐藏
6. `:downloadButton` - 是否显示下载按钮，`visible`显示（默认）, `hide`隐藏
7. `:bookmarkButton` - 是否显示书签按钮，`visible`显示（默认）, `hide`隐藏
8. `:mouseWheelZoom` - 默认时按ctrl+鼠标滚轮可以缩放页面，设置为true时鼠标滚轮将直接缩放页面无需按下ctrl
9. `:textSelect` - 是否能选择文本，默认true
10. `:dragScroll` - 默认时按ctrl+鼠标拖动可以滚动页面，设置为true时鼠标拖动将直接滚动页面无需按下ctrl
11. `:cache` - 传递`false`表示忽略缓存，重新刷新文档（但本次刷新的结果还是会缓存起来供下次使用），默认系统会使用缓存尽量快速的显示文档。
12. `:viewSource` - 传递`true`表示不运行动态文档，直接预览或下载源文件（需要有源文件的编辑权限）
13. `:viewMode` - 可传递`page`或`web`，对应word的Web版式和页面版式，对word文档和pdf有效
14. `:export` - 传递此参数表示此URL是要导出文件的（如果浏览器支持预览pdf或docx，那么浏览器会自动使用原生功能预览），参数值表示导出的格式或文件名：
    1. `pdf`: 导出pdf
    2. `true`: 表示文档原来的格式。
    3. `xxxxxx.pdf`: 同时指定文件名和类型，此时浏览器将总是下载并保存文件，并不会预览文件

### 报表填报应用 URL{#fapp}

用于显示一个报表填报应用，或者报表填报应用内部的某个子功能页面，URL如：

1. <https://demo.succbi.com/v5/DEMO/fapp/%E6%B5%81%E7%A8%8B/%E6%8A%A5%E9%94%80%E7%94%B3%E8%AF%B7.fapp>

**报表填报应用 URL 支持如下参数：**

1. `:edit` - 进入应用设计界面。
2. `:tab` - 显示指定的标签，如`todo`。
3. `:tabs` - 显示多个标签，顶部有标签页切换。
4. `:newData` - 进入表单填写界面，开始一个新的流程申请、或者打开编辑一个已存在的数据。
5. `:hideNewDataButton` - 隐藏“新申请”按钮。
6. `:dataPeriod` - 显示某个数据期的数据，适用于周期填报应用。
7. `:orgId` - 显示某个单位或部门的数据。
8. `:detailId` - 显示某个明细数据。
9. `:sheet` - 默认显示哪张表单。
10. `:sheets` - 显示哪些表单，逗号分隔，不传默认显示全部
11. `:hideSheets` - 隐藏哪些表单，逗号分隔，从目前可以显示的表单中，剔除掉
12. `:readonly` - 用只读方式显示表单。
13. `:embedForm` - 可传入`true`指定为嵌入表单形式，此时不会显示填报单位树、数据列表、工具栏等元素。一般在SuperPage、报表中打开某个表单数据时使用。传入此参数时，需传入完整的数据级次参数(有三个`:dataPeriod`、`:orgId`、`:detailId`，根据应用的类型需要传入1个到3个)。
14. `:XXX_Select` - 设置过滤条件栏（包括左侧树和工具栏）上的维树选中的节点，参数名为`:主模型字段名_Select`的形式，多个值用逗号分隔，如`:DEPT_Select=1000`，表示部门树默认高亮选择节点1000。
15. `:XXX_RootItems` - 设置过滤条件栏（包括左侧树和工具栏）上的维树的根节点，参数名为`:主模型字段名_RootItems`的形式，多个值用逗号分隔，如`DEPT_RootItems=1000`，表示部门树只显示1000的子节点。
16. `:XXX_Filter` - 两种场景：1. 设置过滤条件栏（包括左侧树和工具栏）上的维树的过滤条件，参数名为`:主模型物理字段名_Filter`的形式；2. 设置装载数据时模型的过滤条件，参数名为`:模型别名.物理字段名_Filter`。可传入一个值和多个值，多个值用逗号分隔，如`:DEPT_ID_Filter=001`、`:JCB.JG_Filter=1,2`

## 计划任务URL{#schedules}

如：

1. <https://demo.succbi.com/v5/schedules>             // 系统计划列表
2. <https://demo.succbi.com/v5/DEMO/schedules>        // DEMO项目下的计划列表
3. <https://demo.succbi.com/v5/schedules?schedule=server-init-dataetl&subPage=tasks>  // 查看某个计划下的任务列表

**计划任务URL支持如下参数：**

1. `schedule` - 指定计划名称，如`server-init-dataetl`。
2. `schpage` - 指定显示那个子页面，可选：`settings`计划设置页面、`tasks`任务列表页面、`lastrun`最近调度、`allrun`所有调度。
3. `schpagebar` - 传递`hidden`隐藏隐藏切换页面的标签页
4. `schhidden` - `subpagebar,gotoschedules,help,`

## 我的工作URL{#mytasks}

如：

1. <https://demo.succbi.com/v5/DEMO/my-tasks>
2. <https://demo.succbi.com/v5/DEMO/my-tasks/todo>

**我的工作URL支持如下参数：**

1. `:visibleTabs` - 显示的标签，多个标签用逗号分隔。不支持直接打开一个标签时使用。
2. `:tab` - 默认显示的标签。不支持直接打开一个标签时使用。

## 登录界面URL{#login}

1. 可定制登录界面：<https://demo.succbi.com/v5/login>
2. 默认登录界面：<https://demo.succbi.com/v5/login/default>

**登录界面URL支持如下参数**

1. `redirect_url`：登录成功后跳转的地址：
   - 仅支持传递一个以`/`开头的相对地址，登录成功后跳转到系统内对应的相对地址，**注意：一定不会根据传入地址上下文跳转到其他系统**。
   - 请对参数进行[URL转义](https://tool.chinaz.com/tools/urlencode.aspx)

## 健康检测URL{#health}

用于界面检测与服务器的通讯状态。URL:

1. <https://demo.succbi.com/v5/api/sys/health-info>

**返回值和状态说明：**

1. 该接口关注的只是服务器是否能够通讯，接口里直接返回`ok`。

## 附件下载URL{#downloadAttachment}

用于下载或者预览附件，URL如：

1. 下载单个附件</br><https://demo.succbi.com/v5/api/dw/services/downloadAttachment?preview=false&resIdOrPath=/TestCase/data/tables/TESTCASE/attachment/test_dwAttachment.tbl&keys=%5B%224febf2e53ca84640a4479e578e85ced0%22%5D&fileField=%E6%96%87%E4%BB%B6%E5%86%85%E5%AE%B9%E5%AD%97%E6%AE%B5&zipFile=true></br>
   参数解析：

```json
{
    "preview": false,
    "resIdOrPath": "/TestCase/data/tables/TESTCASE/attachment/test_dwAttachment.tbl",
    "keys": ["eb232959ef714d35b7459597b1c93e7a"],
    "fileField": "文件内容字段",
    "zipFile": true
}
```

2. 预览附件</br><https://demo.succbi.com/v5/api/dw/services/downloadAttachment?preview=true&resIdOrPath=/TestCase/data/tables/TESTCASE/ana/test_spg.dash&queryId=model2&keys=%5B%224febf2e53ca84640a4479e578e85ced0%22%5D&fileField=%E6%96%87%E4%BB%B6%E5%86%85%E5%AE%B9%E5%AD%97%E6%AE%B5></br>
   参数解析：

```json
{
    "preview": true,
    "resIdOrPath": "/TestCase/data/tables/TESTCASE/ana/test_spg.dash",
    "queryId": "model2",
    "keys": ["eb232959ef714d35b7459597b1c93e7a"],
    "fileField": "文件内容字段"
}
```

3. 批量下载附件</br><https://demo.succbi.com/v5/api/dw/services/downloadAttachment?preview=false&resIdOrPath=/TestCase/data/tables/TESTCASE/attachment/test_dwAttachment.tbl&fileField=%E6%96%87%E4%BB%B6%E8%B7%AF%E5%BE%84%E5%AD%97%E6%AE%B5&dataKeyMap=%7B%22id%22:%5B%229248db7a2e5b4e868646dfffa17329a9%22,%228534431408e244b9a705e87e57a3046c%22,%2237be68098cfb4ea3a7a8b7b96bbb22af%22%5D%7D&fileName=%E4%B8%8B%E8%BD%BD%E5%8E%8B%E7%BC%A9%E9%99%84%E4%BB%B6.zip></br>
   参数解析：

```json
{
    "preview": false,
    "resIdOrPath": "/TestCase/data/tables/TESTCASE/attachment/test_dwAttachment.tbl",
    "fileField": "文件路径字段",
    "dataKeyMap": {
        "id":["9248db7a2e5b4e868646dfffa17329a9","8534431408e244b9a705e87e57a3046c","37be68098cfb4ea3a7a8b7b96bbb22af"]
    },
    "fileName": "下载压缩附件.zip"
}
```

4. 预览下载临时附件</br><https://demo.succbi.com/v5/api/dw/services/downloadAttachment?preview=false&fileId=33e2ff76b09d11a544fba4986a60d2dd55eb-20200213210429.png></br>
   参数解析：

```json
{
    "preview": false,
    "fileId": "33e2ff76b09d11a544fba4986a60d2dd55eb-20200213210429.png"
}
```

参数说明：

1. `resIdOrPath` - 发起查询的资源uuid或路径，可以是报表或spg，也可以是附件模型表本身。如果是报表或spg，则需要传入参数`queryId`
2. `queryId` - 查询约束id。一般是spg中的附件模型id或者别名，后端会根据这个queryId在后端找到真正的附件表
3. `fileField` - 文件角色字段名（或者物理字段名）。附件表可能有多个文件字段，需要指定使用哪个文件字段
4. `keys` - 下载或预览单个附件的过滤条件，参数格式和使用说明见下文
5. `dataKeyMap` - 批量下载附件的过滤条件，可选。`keys`和`dataKeyMap`只有一个生效，若已传入`keys`，则此参数无效。参数格式和使用说明见下文
6. `zipFile` - 下载的附件是否需要压缩，可选。当下载的附件只有一个时，会根据此参数决定是否仍然需要进行压缩后下载，默认不压缩。其他情况：下载多个附件时，始终压缩；预览时，此参数无效。
7. `fileName` - 指定下载附件的名称，可选。下载单个附件时，默认下载名称为附件名字段对应的名称；下载多个附件时（zip压缩文件），默认下载名称为后台根据下载附件id自动生成的名称。
8. `preview` - 传递`true`表示预览，下载附件只有1个时生效；传递`false`表示下载，默认false。
9. `fileId` - 临时附件id，可选。项目需求：上传的附件没有上报到附件表时，直接根据临时id预览下载临时上传的附件。该场景下，只需要传入`preview`和`fileId`，其他参数不需要。
10. 参数中可能包含中文或者特殊字符，因此需要最后对url编码一次（`encodeUrl(url)`）。

**`keys`和`dataKeyMap`参数说明:**

1. `keys`为附件字段的主键值数组的JSON字符串，用来过滤得到唯一附件。例如：附件表有一个主键attachmentId，想要下载主键为`abc`的附件，主键数组就为`["abc"]`，`keys`通过`JSON.stringify(主键数组)`获取。
2. `dataKeyMap`为附件表中字段名（或者物理字段名）和值的键值对的JSON字符串，用来过滤得到对应条件的多个附件。键值对map示例：

```json
//匹配class为"abc"的附件
{
    "class": "abc"
}
```

```json
//匹配dept为"1"或者"2"的附件
{
    //值可以是数组，各个值为“或”的关系
    "dept": ["1","2"]
}
```

```json
//匹配dept为"1"或者"2"并且class为"abc"的附件
{
    //可以有多个键值对，键值对之间是“且”的关系
    "dept": ["1","2"],
    "class": "abc"
}
```

同样的，键值对的JSON字符串需要通过`JSON.stringify(键值对)`获取。