diff --git a/docs/_coverpage.md b/docs/_coverpage.md index be178183b5..d47466faaa 100644 --- a/docs/_coverpage.md +++ b/docs/_coverpage.md @@ -1,4 +1,4 @@ # 蓝盾制品库文档 [部署文档](/install/) -[接口文档](/apidoc/) +[接口文档](/apidoc-user/) diff --git a/docs/_navbar.md b/docs/_navbar.md index 2630a91794..fe21009c62 100644 --- a/docs/_navbar.md +++ b/docs/_navbar.md @@ -1,2 +1,2 @@ - [部署文档](/install/) -- [接口文档](/apidoc/) \ No newline at end of file +- [接口文档](/apidoc-user/) \ No newline at end of file diff --git a/docs/apidoc-user/README.md b/docs/apidoc-user/README.md new file mode 100644 index 0000000000..473283c2c5 --- /dev/null +++ b/docs/apidoc-user/README.md @@ -0,0 +1,34 @@ +# 蓝鲸制品库接口文档 +- **接口公共说明** + - [通用接口协议](common/common.md) + - [自定义搜索协议](common/search.md) + - [事件类型](common/event.md) +- **项目/仓库** + - [项目接口](repo/project.md) + - [仓库接口](repo/repository.md) + - [代理源接口](repo/proxy-channel.md) +- **节点** + - [节点操作接口](node/node.md) + - [分享链接接口](node/share.md) +- **制品包/版本** + - [制品包版本接口](package/package.md) +- **元数据** + - [系统元数据说明](metadata/system-metadata.md) + - [节点元数据](metadata/node-metadata.md) + - [元数据搜索](metadata/search.md) +- **Generic通用制品仓库** + - [简单文件操作](generic/simple.md) + - [分块文件操作](generic/block.md) + - [临时访问凭证](generic/temporary-access.md) +- **认证服务** + - [用户相关](auth/user.md) + - [用户token相关](auth/token.md) +- **制品分析** + - [扫描器管理](scanner/scanner.md) + - [扫描](scanner/scan.md) + - [扫描报告](scanner/report.md) +- **WebHook** + - [webhook接口](webhook/webhook.md) + - [webhook消息](webhook/payload.md) +- **审计日志** + - [审计日志接口](log/log.md) diff --git a/docs/apidoc-user/_sidebar.md b/docs/apidoc-user/_sidebar.md new file mode 100644 index 0000000000..4fa4a543ac --- /dev/null +++ b/docs/apidoc-user/_sidebar.md @@ -0,0 +1,33 @@ +- **接口公共说明** + - [通用接口协议](/apidoc-user/common/common.md) + - [自定义搜索协议](/apidoc-user/common/search.md) + - [事件类型](/apidoc-user/common/event.md) +- **项目/仓库** + - [项目接口](/apidoc-user/repo/project.md) + - [仓库接口](/apidoc-user/repo/repository.md) + - [代理源接口](/apidoc-user/repo/proxy-channel.md) +- **节点** + - [节点操作接口](/apidoc-user/node/node.md) + - [分享链接接口](/apidoc-user/node/share.md) +- **制品包/版本** + - [制品包版本接口](/apidoc-user/package/package.md) +- **元数据** + - [系统元数据说明](/apidoc-user/metadata/system-metadata.md) + - [节点元数据](/apidoc-user/metadata/node-metadata.md) + - [元数据搜索](/apidoc-user/metadata/search.md) +- **Generic通用制品仓库** + - [简单文件操作](/apidoc-user/generic/simple.md) + - [分块文件操作](/apidoc-user/generic/block.md) + - [临时访问凭证](/apidoc-user/generic/temporary-access.md) +- **认证服务** + - [用户相关](/apidoc-user/auth/user.md) + - [用户token相关](/apidoc-user/auth/token.md) +- **制品分析** + - [扫描器管理](/apidoc-user/scanner/scanner.md) + - [扫描](/apidoc-user/scanner/scan.md) + - [扫描报告](/apidoc-user/scanner/report.md) +- **WebHook** + - [webhook接口](/apidoc-user/webhook/webhook.md) + - [webhook消息](/apidoc-user/webhook/payload.md) +- **审计日志** + - [审计日志接口](/apidoc-user/log/log.md) \ No newline at end of file diff --git a/docs/apidoc-user/auth/token.md b/docs/apidoc-user/auth/token.md new file mode 100644 index 0000000000..4dd5c4915d --- /dev/null +++ b/docs/apidoc-user/auth/token.md @@ -0,0 +1,179 @@ +## bkrepo token相关接口 + +### 新增用户token + +- API:POST /auth/api/user/token/{uid}/{name}?expiredAt=2019-12-21T09:46:37.877Z&projectId=aaa +- API 名称: add_user_token +- 功能说明： + - 中文：新增用户token + - English：add user token + +- input body: + +``` json + +``` + +- input 字段说明 + +|字段|类型|是否必须|默认值|说明|Description| +|---|---|---|---|---|---| +|name|string|是|无|token名|the token name| +|uid|string|是|无|用户id|the user id| +|expiredAt|datetime|否|无|过期时间|expiredAt| +|projectId|aaa|否|无|项目ID|projectId| + +- output: + +``` +{ + "code":0, + "data":{ + "createdAt":"2019-12-21T09:46:37.877Z", + "expiredAt":"2019-12-21T09:46:37.877Z", + "id":"abcd", + "name":"abcd" + }, + "message":"string", + "traceId":"string" +} + +``` + +- output 字段说明 + +| 字段|类型|说明|Description| +|---|---|---|---| +|code|bool|错误编码。 0表示success，>0表示失败错误 |0:success, other: failure| +|message|result message|错误消息 |the failure message | +|data | bool | result data |the data for response| +|traceId|string|请求跟踪id|the trace id| + + +- data 字段说明 + +| 字段|类型|说明|Description| +|---|---|---|---| +|createdAt|time|创建时间|create time| +|expiredAt|time|过期时间,null标识永久 |expired time | +|name | string | token name|the name of token| +|id|string|token id |the id of token| + +### 用户token列表 + +- API:GET /auth/api/user/list/token/{uid} +- API 名称: list_user_token +- 功能说明： + - 中文：新增用户token + - English：add user token + +- input body: + +``` json + +``` + +- input 字段说明 + +|字段|类型|是否必须|默认值|说明|Description| +|---|---|---|---|---|---| +|uid|string|是|无|用户id|the user id| + +- output: + +``` +{ + "code":0, + "data":[ + { + "createdAt":"2019-12-21T09:46:37.877Z", + "expiredAt":"2019-12-21T09:46:37.877Z", + "name":"token1" + }, + { + "createdAt":"2019-12-21T09:46:37.877Z", + "expiredAt":null, + "name":"token2" + } + ], + "message":"string", + "traceId":"string" +} +``` + +- output 字段说明 + +| 字段|类型|说明|Description| +|---|---|---|---| +|code|bool|错误编码。 0表示success，>0表示失败错误 |0:success, other: failure| +|message|result message|错误消息 |the failure message | +|data | bool | result data |the data for response| +|traceId|string|请求跟踪id|the trace id| + + +- data 字段说明 + +| 字段|类型|说明|Description| +|---|---|---|---| +|createdAt|time|创建时间|create time| +|expiredAt|time|过期时间 |expired time | +|name | string | token name|the name of token| +|id|string|token id |the id of token| + +### 删除用户token + +- API:DELETE /auth/api/user/token/{uid}/{name} +- API 名称: delete_user_token +- 功能说明： + - 中文：删除用户token + - English：delete user token + +- input body: + +``` json + +``` + +- input 字段说明 + +|字段|类型|是否必须|默认值|说明|Description| +|---|---|---|---|---|---| +|uid|string|是|无|用户id|the user id| +|name|string|是|无|用户token|the user token| + +- output: + +``` +{ + "code":0, + "data":{ + "admin":true, + "locked":true, + "name":"string", + "pwd":"string", + "roles":[ + "string" + ], + "tokens":[ + { + "createdAt":"2019-12-21T09:46:37.877Z", + "expiredAt":"2019-12-21T09:46:37.877Z", + "name":"string" + } + ], + "uid":"string" + }, + "message":"string", + "traceId":"string" +} + +``` + +- output 字段说明 + +| 字段|类型|说明|Description| +|---|---|---|---| +|code|bool|错误编码。 0表示success，>0表示失败错误 |0:success, other: failure| +|message|result message|错误消息 |the failure message | +|data | bool | result data |the data for response| +|traceId|string|请求跟踪id|the trace id| diff --git a/docs/apidoc-user/auth/user.md b/docs/apidoc-user/auth/user.md new file mode 100644 index 0000000000..5e48e25a76 --- /dev/null +++ b/docs/apidoc-user/auth/user.md @@ -0,0 +1,243 @@ +## bkrepo 用户相关接口 + +### 创建用户 + +- API: POST /auth/api/user/create +- API 名称: create_user +- 功能说明： + - 中文：创建用户 + - English：create user + +- input body: + +``` json +{ + "userId":"public", + "name":"public", + "pwd":"blueking", + "group":true, + "asstUsers":["tt"] +} + +``` + + +- input 字段说明 + +|字段|类型|是否必须|默认值|说明|Description| +|---|---|---|---|---|---| +|name|string|是|无|用户名|the name| +|pwd|string|否|无|用户密码|the user password| +|userId|string|是|无|用户id|the user id| +|asstUsers|string array|否|[]|关联用户|association user| +|group|boot |否|false|是否群组账号|is group user| +- output: + +``` +{ + "code":0, + "message":null, + "data":true, + "traceId":"" +} +``` + +- output 字段说明 + +| 字段|类型|说明|Description| +|---|---|---|---| +|code|bool|错误编码。 0表示success，>0表示失败错误 |0:success, other: failure| +|message|result message|错误消息 |the failure message | +|data | bool | result data |the data for response| +|traceId|string|请求跟踪id|the trace id| + + +### 创建用户到项目管理员 + +- API: POST /auth/api/user/create/project +- API 名称: create_user_to_project +- 功能说明： + - 中文：创建用户 + - English：create user to project + +- input body: + +``` json +{ + "name":"string", + "pwd":"string", + "userId":"string", + "asstUsers":[ + "owen" + ], + "group":true, + "projectId":"test" +} +``` + + +- input 字段说明 + +|字段|类型|是否必须|默认值|说明|Description| +|---|---|---|---|---|---| +|name|string|是|无|用户名|the name| +|pwd|string|是|无|用户密码|the user password| +|userId|string|是|无|用户id|the user id| +|asstUsers|string array|否|[]|关联用户|association user| +|group|boot |否|false|是否群组账号|is group user| +|projectId|string|是|无|关联到的项目|the association project| + +- output: + +``` +{ +"code": 0, +"message": null, +"data": true, +"traceId": "" +} + +``` + +- output 字段说明 + +| 字段|类型|说明|Description| +|---|---|---|---| +|code|bool|错误编码。 0表示success，>0表示失败错误 |0:success, other: failure| +|message|result message|错误消息 |the failure message | +|data | bool | result data |the data for response| +|traceId|string|请求跟踪id|the trace id| + + +### 创建用户到仓库管理员 + +- API: POST /auth/api/user/create/repo +- API 名称: create_user_to_repo +- 功能说明： + - 中文：创建用户为仓库管理员 + - English：create user to repo + +- input body: + +``` json +{ + "name":"string", + "pwd":"string", + "userId":"string", + "asstUsers":[ + "owen", + "necr" + ], + "group":true, + "projectId":"test", + "repoName":"generic" +} +``` + + +- input 字段说明 + +|字段|类型|是否必须|默认值|说明|Description| +|---|---|---|---|---|---| +|name|string|是|无|用户名|the name| +|pwd|string|是|无|用户密码|the user password| +|userId|string|是|无|用户id|the user id| +|asstUsers|string array|否|[]|关联用户|association user| +|group|boot |否|false|是否群组账号|is group user| +|projectId|string|是|无|关联到的项目|the association project| +|repoName|string|是|无|关联到的仓库|the association repo| + +- output: + +``` +{ +"code": 0, +"message": null, +"data": true, +"traceId": "" +} + +``` + +- output 字段说明 + +| 字段|类型|说明|Description| +|---|---|---|---| +|code|bool|错误编码。 0表示success，>0表示失败错误 |0:success, other: failure| +|message|result message|错误消息 |the failure message | +|data | bool | result data |the data for response| +|traceId|string|请求跟踪id|the trace id| + + +### 用户详情 + +- API:GET /auth/api/user/detail/{uid} +- API 名称: user_detail +- 功能说明： + - 中文：用户详情 + - English：user detail + +- input body: + +``` json + + +``` + + +- input 字段说明 + +|字段|类型|是否必须|默认值|说明|Description| +|---|---|---|---|---|---| +|uid|string|是|无|用户id|the user id| + + +- output: + +``` +{ + "code":0, + "data":{ + "admin":true, + "locked":true, + "name":"string", + "pwd":"string", + "roles":[ + "632d9e127er87746e2320df1c" + ], + "tokens":[ + ], + "uid":"owen" + }, + "message":"", + "traceId":"" +} + + +``` + +- output 字段说明 + +| 字段|类型|说明|Description| +|---|---|---|---| +|code|bool|错误编码。 0表示success，>0表示失败错误 |0:success, other: failure| +|message|result message|错误消息 |the failure message | +|data | object | user data info |the info of user| +|traceId|string|请求跟踪id|the trace id| + +- data 字段说明 + +| 字段|类型|说明|Description| +|---|---|---|---| +|roles|string array|用户所属的角色列表 |the user role list| +|tokens|object array|用户创建的所有token |the tokens of user | + +- tokens 字段说明 + +| 字段|类型|说明|Description| +|---|---|---|---| +|id|string |token id |the token id| +|createdAt|date time| token创建时间|create time | +|expiredAt|date time|token失效 |expire time | + + | \ No newline at end of file diff --git a/docs/apidoc-user/common/common.md b/docs/apidoc-user/common/common.md new file mode 100644 index 0000000000..337c9fe707 --- /dev/null +++ b/docs/apidoc-user/common/common.md @@ -0,0 +1,93 @@ +# 通用接口协议 + +各个依赖源有单独的服务接口协议，除了这类接口，系统其余接口使用统一的通用接口协议。 + +此部分对系统的通用接口协议作介绍。 + +## 公共请求头 + +### 对接个人账号(通用) +|字段|类型|是否必须|默认值|说明|Description| +|---|---|---|---|---|---| +|Authorization|string|是|无|Basic Auth认证头，Basic base64(username:password)|Basic Auth header| + +### 对接合作系统，需要先申请bkrepo appId +|字段|类型|是否必须|默认值|说明|Description| +|---|---|---|---|---|---| +|Authorization|string|是|无|自定义Auth认证头，Platform base64(accessKey:secretKey)|Platform Auth header| +|X-BKREPO-UID|string|是|无|实际操作用户，需要有对应资源的操作权限|operate user| + +## 统一响应格式 + +- 响应体格式 + + `application/json` + +- 响应体内容 + + ```json + { + "code" : 0, + "message" : null, + "data" : [object], + "traceId" : null + } + ``` + +- 响应字段说明 + + |字段|类型|说明|Description| + |---|---|---|---| + |code|bool|错误编码。 0表示success，>0表示失败错误|0:success, other: failure| + |message|string|错误提示消息，请求成功此字段为null|the failure message| + |data|object|响应数据，允许为null|response data| + |traceId|string|请求跟踪id，允许为null|trace id| + + **TIPS: 无特殊说明，后文的接口响应体说明只介绍data字段** + +## 统一分页接口响应格式 + +|字段|类型|说明|Description| +|---|---|---|---| +|totalRecords|long|节点信息|total count| +|pageNumber|int|当前页|page number| +|pageSize|int|每页记录数|page size| +|totalPages|long|总页数|total pages| +|records|list|数据记录列表|record list| + +## 统一时间响应格式 + +接口返回的时间，使用`ISO_DATETIME`格式，如：`2011-12-03T10:15:30` + +## 通用概念 + +|名称|解释| +|---|---| +|project/projectId|项目id，全局唯一| +|repo/repoName|仓库名称，项目内唯一| +|fullPath|节点完整路径| +|path|节点目录，在restful格式的url中也可以表示fullPath，后台会自动处理| + +## 统一错误码 + +|错误码|错误原因| +|---|---| +|250102|系统错误| +|250103|请求参数缺失| +|250104|请求参数非法| +|250105|请求参数无效| +|250106|请求内容无效| +|250107|请求资源已经存在| +|250108|请求资源不存在| +|250109|请求资源过期| +|250110|不支持的操作| +|250111|访问被拒绝| +|250112|认证失败| +|250113|内部依赖服务被熔断| +|250114|内部依赖服务调用异常| +|250115|服务认证失败| +|250116|请求头缺失| +|250117|不支持的Media Type| +|250118|请求range格式无效| +|250119|修改密码失败| +|...|待补充| diff --git a/docs/apidoc-user/common/event.md b/docs/apidoc-user/common/event.md new file mode 100644 index 0000000000..951406e706 --- /dev/null +++ b/docs/apidoc-user/common/event.md @@ -0,0 +1,16 @@ +# 公共事件类型 + +| 枚举值 | 说明 | +| ---------------- | ----------- | +| PROJECT_CREATED | 项目创建 | +| REPO_CREATED | 仓库创建 | +| REPO_UPDATED | 仓库更新 | +| NODE_CREATED | 节点创建 | +| NODE_DOWNLOADED | 节点下载 | +| NODE_RENAMED | 节点重命名 | +| NODE_MOVED | 节点移动 | +| NODE_COPIED | 节点复制 | +| NODE_DELETED | 节点删除 | +| METADATA_DELETED | 元数据删除 | +| METADATA_SAVED | 元数据保存 | +| VERSION_CREATED | 版本创建 | \ No newline at end of file diff --git a/docs/apidoc-user/common/search.md b/docs/apidoc-user/common/search.md new file mode 100644 index 0000000000..5721b20dbf --- /dev/null +++ b/docs/apidoc-user/common/search.md @@ -0,0 +1,125 @@ +# 自定义搜索协议 + +> 自定义搜索协议用于数据搜索接口，支持前端自定义查询条件、筛选字段、排序规则、分页参数等信息。 + +[toc] + +## 请求体格式 + +```json +{ + "select": ["xxx", "yyy", "xxx"], + "page": { + "pageNumber": 0, + "pageSize": 20 + }, + "sort": { + "properties": ["name"], + "direction": "ASC" + }, + "rule": { + "rules": [ + { + "field": "projectId", + "value": "test", + "operation": "EQ" + }, + { + "field": "repoName", + "value": ["generic-local1", "generic-local2"], + "operation": "IN" + } + ], + "relation": "AND" + } +} +``` + +### 请求字段说明 + +|字段|类型|是否必须|默认值|说明|Description| +|---|---|---|---|---|---| +|select|list|否|无，代表查询所有字段|筛选字段列表。支持的字段列表请参照对应数据的列表接口响应字段。|select fields list| +|page|PageLimit|否|pageNumber=1, pageSize=20|分页参数|page limit| +|sort|Sort|否|无|排序规则|sort rule| +|rule|Rule|是|无|自定义查询规则|custom query rule| + +### PageLimit参数说明 + +|字段|类型|是否必须|默认值|说明|Description| +|---|---|---|---|---|---| +|pageNumber|int|否|1|当前页(第1页开始)|page number| +|pageSize|int|否|20|每页数量|page size| + +### Sort参数说明 + +|字段|类型|是否必须|默认值|说明|Description| +|---|---|---|---|---|---| +|properties|[string]|是|无|排序字段|sort properties| +|direction|string|否|ASC|排序方向。支持ASC升序和DESC降序|sort direction| + +### Rule参数说明 + +> Rule包含两种格式，一种用于表示嵌套规则NestedRule，另一种用于表示条件规则QueryRule + +- **嵌套规则NestedRule** + +|字段|类型|是否必须|默认值|说明|Description| +|---|---|---|---|---|---| +|rules|[Rule]|是|无|规则列表，可以任意嵌套NestedRule和QueryRule|rule list| +|relation|string|否|AND|规则列表rules的关系。支持AND、OR、NOR|rule relation| + +- **条件规则QueryRule** + +|字段|类型|是否必须|默认值|说明|Description| +|---|---|---|---|---|---| +|field|string|是|无|查询字段|filed| +|value|any|否|无|查询值。数据类型和查询操作类型相关|value| +|operation|enum|否|EQ|查询操作类型。枚举类型见下文|operation| + + +### OperationType查询操作类型 + +|枚举值|对应查询值类型|Description| +|---|---|---| +|EQ|string/boolean/number/date|等于| +|NE|number/date|不等于| +|LTE|number/date|小于或者等于| +|LT|number/date|小于| +|GTE|number/date|大于或者等于| +|GT|number/date|大于| +|BEFORE|date|在某个时间之间，不包含等于| +|AFTER|date|在某个时间之后，不包含等于| +|IN|list|包含于| +|NIN|list|不包含于| +|PREFIX|string|以xxx为前缀| +|SUFFIX|string|以xxx为后缀| +|MATCH|string|通配符匹配，\*表示匹配任意字符。如\*test\*表示包含test的字符串| +|NULL|null|匹配查询字段为空，filed == null| +|NOT_NULL|null|匹配查询字段不为空，filed != null| + +## 响应体格式 + +响应体参考[分页接口响应格式](../common/common.md?id=统一分页接口响应格式) + +``` json +{ + "code": 0, + "message": null, + "data": { + "pageNumber": 0, + "pageSize": 1, + "totalRecords": 18, + "totalPages": 18, + "records": [ + { + "xxx": "", + "yyy": "" + } + ] + }, + "traceId": null +} +``` + +`records`字段根据`select`筛选字段条件决定 \ No newline at end of file diff --git a/docs/apidoc-user/generic/block.md b/docs/apidoc-user/generic/block.md new file mode 100644 index 0000000000..3b3362b9c4 --- /dev/null +++ b/docs/apidoc-user/generic/block.md @@ -0,0 +1,224 @@ +# Generic通用制品仓库分块文件操作 + +[toc] + +## 初始化分块上传 + +- API: POST /generic/block/{project}/{repo}/{path} +- API 名称: start_block_upload +- 功能说明： + - 中文：初始化分块上传 + - English：start block upload + +- 请求体 +此接口请求体为空 + +- 请求字段说明 + + |字段|类型|是否必须|默认值|说明|Description| + |---|---|---|---|---|---| + |project|string|是|无|项目名称|project name| + |repo|string|是|无|仓库名称|repo name| + |path|string|是|无|完整路径|full path| + +- 请求头 + + |字段|类型|是否必须|默认值|说明|Description| + |---|---|---|---|---|---| + |X-BKREPO-MD5|string|否|无|文件md5|file md5| + |X-BKREPO-OVERWRITE|boolean|否|false|是否覆盖已存在文件|overwrite exist file| + |X-BKREPO-EXPIRES|long|否|0|过期时间，单位天(0代表永久保存)|file expired days| + +- 响应体 + +``` json +{ + "code" : 0, + "message" : null, + "data" : { + "uploadId" : "8be31384f82a45b0aafb6c6add29e94f", + "expireSeconds" : 43200 + }, + "traceId" : null +} +``` + +- data字段说明 + + |字段|类型|说明|Description| + |---|---|---|---| + |uploadId|string|分块上传id|block upload id| + |expireSeconds|string|上传有效期(秒)|expire time(seconds)| + +## 上传分块文件 + +- API: PUT /generic/{project}/{repo}/{path} +- API 名称: block_upload +- 功能说明： + - 中文：分块上传通用制品文件 + - English：upload generic artifact file block + +- 请求体 +[文件流] + +- 请求字段说明 + + |字段|类型|是否必须|默认值|说明|Description| + |---|---|---|---|---|---| + |project|string|是|无|项目名称|project name| + |repo|string|是|无|仓库名称|repo name| + |path|string|是|无|完整路径|full path| + +- 请求头 + + |字段|类型|是否必须|默认值|说明|Description| + |---|---|---|---|---|---| + |X-BKREPO-UPLOAD-ID|string|否|无|分块上传id|block upload id| + |X-BKREPO-SEQUENCE|int|否|无|分块序号(从1开始)|block sequence(start from 1)| + |X-BKREPO-SHA256|string|否|无|文件sha256|file sha256| + |X-BKREPO-MD5|string|否|无|文件md5|file md5| + +- 响应体 + + ``` json + { + "code" : 0, + "message" : null, + "data" : null, + "traceId" : null + } + ``` + +## 完成分块上传 + +- API: PUT /generic/block/{project}/{repo}/{path} +- API 名称: complete_block_upload +- 功能说明： + - 中文：完成化分块上传 + - English：complete block upload + +- 请求体 +此接口请求体为空 + +- 请求字段说明 + + |字段|类型|是否必须|默认值|说明|Description| + |---|---|---|---|---|---| + |project|string|是|无|项目名称|project name| + |repo|string|是|无|仓库名称|repo name| + |path|string|是|无|完整路径|full path| + +- 请求头 + + |字段|类型|是否必须|默认值|说明|Description| + |---|---|---|---|---|---| + |X-BKREPO-UPLOAD-ID|string|是|无|分块上传ID|block upload id| + +- 响应体 + + ``` json + { + "code" : 0, + "message" : null, + "data" : null, + "traceId" : "" + } + ``` + +## 终止(取消)分块上传 + +- API: DELETE /generic/block/{project}/{repo}/{path} +- API 名称: abort_block_upload +- 功能说明： + - 中文：终止(取消)分块上传 + - English：abort block upload + +- 请求体 +此接口请求体为空 + +- 请求字段说明 + + |字段|类型|是否必须|默认值|说明|Description| + |---|---|---|---|---|---| + |project|string|是|无|项目名称|project name| + |repo|string|是|无|仓库名称|repo name| + |path|string|是|无|完整路径|full path| + +- 请求头 + + |字段|类型|是否必须|默认值|说明|Description| + |---|---|---|---|---|---| + |X-BKREPO-UPLOAD-ID|string|是|无|分块上传ID|block upload id| + +- 响应体 + + ``` json + { + "code" : 0, + "message" : null, + "data" : null, + "traceId" : null + } + ``` + +## 查询已上传的分块列表 + +- API: GET /generic/block/{project}/{repo}/{path} +- API 名称: list_upload_block +- 功能说明： + - 中文：查询已上传的分块列表 + - English：list upload block + +- 请求体 + 此接口请求体为空 + +- 请求字段说明 + + |字段|类型|是否必须|默认值|说明|Description| + |---|---|---|---|---|---| + |project|string|是|无|项目名称|project name| + |repo|string|是|无|仓库名称|repo name| + |path|string|是|无|完整路径|full path| + +- 请求头 + + |字段|类型|是否必须|默认值|说明|Description| + |---|---|---|---|---|---| + |Authorization|string|否|无|Basic Auth认证头，Basic base64(username:password)|Basic Auth header| + |X-BKREPO-UPLOAD-ID|string|是|无|分块上传ID|block upload id| + +- 响应体 + + ``` json + { + "code" : 0, + "message" : null, + "data" : [ { + "size" : 10240, + "sha256" : "d17f25ecfbcc7857f7bebea469308be0b2580943e96d13a3ad98a13675c4bfc2", + "sequence" : 1 + }, { + "size" : 10240, + "sha256" : "cc399d73903f06ee694032ab0538f05634ff7e1ce5e8e50ac330a871484f34cf", + "sequence" : 2 + } ], + "traceId" : null + } + ``` + +- 响应字段说明 + + |字段|类型|说明|Description| + |---|---|---|---| + |code|bool|错误编码。 0表示success，>0表示失败错误|0:success, other: failure| + |message|string|错误消息|the failure message| + |data|list|分块列表|block list| + |traceId|string|请求跟踪id|trace id| + +- 分块信息字段说明 + + |字段|类型|说明|Description| + |---|---|---|---| + |size|long|分块大小|block size| + |sha256|string|分块sha256|block sha256 checksum| + |sequence|int|分块序号|block sequence| \ No newline at end of file diff --git a/docs/apidoc-user/generic/simple.md b/docs/apidoc-user/generic/simple.md new file mode 100644 index 0000000000..b3f28214cd --- /dev/null +++ b/docs/apidoc-user/generic/simple.md @@ -0,0 +1,221 @@ +# Generic通用制品仓库简单文件操作 + +[toc] + +## 上传文件 + +- API: PUT /generic/{project}/{repo}/{path} +- API 名称: upload +- 功能说明： + - 中文：上传通用制品文件 + - English：upload generic artifact file + +- 请求体 +[文件流] + +- 请求字段说明 + + |字段|类型|是否必须|默认值|说明|Description| + |---|---|---|---|---|---| + |project|string|是|无|项目名称|project name| + |repo|string|是|无|仓库名称|repo name| + |path|string|是|无|完整路径|full path| + +- 请求头 + + |字段|类型|是否必须|默认值|说明|Description| + |---|---|---|---|---|---| + |X-BKREPO-SHA256|string|否|无|文件sha256|file sha256| + |X-BKREPO-MD5|string|否|无|文件md5|file md5| + |X-BKREPO-OVERWRITE|boolean|否|false|是否覆盖已存在文件|overwrite exist file| + |X-BKREPO-EXPIRES|long|否|0|过期时间，单位天(0代表永久保存)|file expired days| + |X-BKREPO-META-{key}|string|否|无|文件元数据，{key}表示元数据key，可以添加多个。key大小写不敏感，按小写存储|file metadata| + |X-BKREPO-META|string|否|无|文件元数据，格式为base64(key1=value1&key2=value2)。key大小写敏感。当`X-BKREPO-META-{key}`不能满足需求时可用此字段代替|file metadata| + + +- 响应体 + + ``` json + { + "code" : 0, + "message" : null, + "data" : { + "createdBy" : "admin", + "createdDate" : "2020-07-27T16:02:31.394", + "lastModifiedBy" : "admin", + "lastModifiedDate" : "2020-07-27T16:02:31.394", + "folder" : false, + "path" : "/", + "name" : "test.json", + "fullPath" : "/test.json", + "size" : 34, + "sha256" : "6a7983009447ecc725d2bb73a60b55d0ef5886884df0ffe3199f84b6df919895", + "md5" : "2947b3932900d4534175d73964ec22ef", + "metadata": {}, + "projectId" : "test", + "repoName" : "generic-local" + }, + "traceId" : null + } + ``` + +- data字段说明 + + |字段|类型|说明|Description| + |---|---|---|---| + |createdBy|string|创建者|create user| + |createdDate|string|创建时间|create time| + |lastModifiedBy|string|上次修改者|last modify user| + |lastModifiedDate|string|上次修改时间|last modify time| + |folder|bool|是否为文件夹|is folder| + |path|string|节点目录|node path| + |name|string|节点名称|node name| + |fullPath|string|节点完整路径|node full path| + |size|long|文件大小|file size| + |sha256|string|文件sha256|file sha256| + |md5|string|文件md5|file md5 checksum| + |metadata|object|节点元数据|node metadata| + |projectId|string|节点所属项目|node project id| + |repoName|string|节点所属仓库|node repository name| + +## 下载文件 + +- API: GET /generic/{project}/{repo}/{path}?download=true +- API 名称: download +- 功能说明： + - 中文：下载通用制品文件 + - English：download generic file + +- 请求体 + 此接口请求体为空 + +- 请求字段说明 + + |字段|类型|是否必须|默认值|说明|Description| + |---|---|---|---|---|---| + |project|string|是|无|项目名称|project name| + |repo|string|是|无|仓库名称|repo name| + |path|string|是|无|完整路径|full path| + |download|boolean|否|false|是否为下载请求。如果为true，响应体会添加Content-Disposition，强制浏览器进行下载；不加此参数，浏览器将根据情况展示文件预览 |is download request| + +- 请求头 + + |字段|类型|是否必须|默认值|说明|Description| + |---|---|---|---|---|---| + |Range|string|否|无|RFC 2616 中定义的字节范围，范围值必须使用 bytes=first-last 格式且仅支持单一范围，不支持多重范围。first 和 last 都是基于0开始的偏移量。例如 bytes=0-9，表示下载对象的开头10个字节的数据；bytes=5-9，表示下载对象的第6到第10个字节。此时返回 HTTP 状态码206（Partial Content）及 Content-Range 响应头部。如果 first 超过对象的大小，则返回 HTTP 状态码416（Requested Range Not Satisfiable）错误。如果不指定，则表示下载整个对象|bytes range| + +- 响应头 + + |字段|类型|说明|Description| + |---|---|---|---| + |Accept-Ranges|string|RFC 2616 中定义的服务器接收Range范围|RFC 2616 Accept-Ranges| + |Cache-Control|string|RFC 2616 中定义的缓存指令|RFC 2616 Cache-Control| + |Connection|string|RFC 2616 中定义，表明响应完成后是否会关闭网络连接。枚举值：keep-alive，close。|RFC 2616 Connection| + |Content-Disposition|string|RFC 2616 中定义的文件名称，当download=true才会添加此参数|RFC 2616 Content-Disposition| + |Content-Length|long|RFC 2616 中定义的 HTTP 响应内容长度（字节）|RFC 2616 Content Length| + |Content-Range|string|RFC 2616 中定义的返回内容的字节范围，仅当请求中指定了 Range 请求头部时才会返回该头部|RFC 2616 Content-Range| + |Content-Type|string|RFC 2616 中定义的 HTTP 响应内容类型（MIME）|RFC 2616 Content Length| + |Date|string|RFC 1123 中定义的 GMT 格式服务端响应时间，例如Mon, 27 Jul 2020 08:51:59 GMT|RFC 1123 Content Length| + |Etag|string|ETag 全称为 Entity Tag，是文件被创建时标识对象内容的信息标签，可用于检查对象的内容是否发生变化，通用制品文件会返回文件的sha256值|ETag, file sha256 checksum| + |Last-Modified|string|文件的最近一次上传的时间，例如Mon, 27 Jul 2020 08:51:58 GMT|file last modified time| + +- 响应体 + [文件流] + +## 获取文件头部信息 + +- API: HEAD /generic/{project}/{repo}/{path} +- API 名称: head +- 功能说明： + - 中文：获取通用制品文件头部信息 + - English：get generic file head info + +- 请求体 + 此接口请求体为空 + +- 请求字段说明 + + |字段|类型|是否必须|默认值|说明|Description| + |---|---|---|---|---|---| + |project|string|是|无|项目名称|project name| + |repo|string|是|无|仓库名称|repo name| + |path|string|是|无|完整路径|full path| + +- 请求头 + + |字段|类型|是否必须|默认值|说明|Description| + |---|---|---|---|---|---| + |Range|string|否|无|RFC 2616 中定义的字节范围，范围值必须使用 bytes=first-last 格式且仅支持单一范围，不支持多重范围。first 和 last 都是基于0开始的偏移量。例如 bytes=0-9，表示下载对象的开头10个字节的数据；bytes=5-9，表示下载对象的第6到第10个字节。此时返回 HTTP 状态码206（Partial Content）及 Content-Range 响应头部。如果 first 超过对象的大小，则返回 HTTP 状态码416（Requested Range Not Satisfiable）错误。如果不指定，则表示下载整个对象|bytes range| + +- 响应头 + + |字段|类型|说明|Description| + |---|---|---|---| + |Accept-Ranges|string|RFC 2616 中定义的服务器接收Range范围|RFC 2616 Accept-Ranges| + |Cache-Control|string|RFC 2616 中定义的缓存指令|RFC 2616 Cache-Control| + |Connection|string|RFC 2616 中定义，表明响应完成后是否会关闭网络连接。枚举值：keep-alive，close。|RFC 2616 Connection| + |Content-Disposition|string|RFC 2616 中定义的文件名称|RFC 2616 Content-Disposition| + |Content-Length|long|RFC 2616 中定义的 HTTP 响应内容长度（字节）|RFC 2616 Content Length| + |Content-Range|string|RFC 2616 中定义的返回内容的字节范围，仅当请求中指定了 Range 请求头部时才会返回该头部|RFC 2616 Content-Range| + |Content-Type|string|RFC 2616 中定义的 HTTP 响应内容类型（MIME）|RFC 2616 Content Length| + |Date|string|RFC 1123 中定义的 GMT 格式服务端响应时间，例如Mon, 27 Jul 2020 08:51:59 GMT|RFC 1123 Content Length| + |Etag|string|ETag 全称为 Entity Tag，是文件被创建时标识对象内容的信息标签，可用于检查对象的内容是否发生变化，通用制品文件会返回文件的sha256值|ETag, file sha256 checksum| + |Last-Modified|string|文件的最近一次上传的时间，例如Mon, 27 Jul 2020 08:51:58 GMT|file last modified time| + +- 响应体 + 此接口响应体为空 + +## 删除文件 + +- API: DELETE /generic/{project}/{repo}/{path} +- API 名称: delete +- 功能说明： + - 中文：删除通用制品文件 + - English：delete generic file + +- 请求体 + 此接口请求体为空 + +- 请求字段说明 + + |字段|类型|是否必须|默认值|说明|Description| + |---|---|---|---|---|---| + |project|string|是|无|项目名称|project name| + |repo|string|是|无|仓库名称|repo name| + |path|string|是|无|完整路径|full path| + +- 响应体 + + ``` json + { + "code" : 0, + "message" : null, + "data" : null, + "traceId" : null + } + ``` + +## 批量下载 +- API : GET /generic/batch/{project}/{repo} +- API名称： batch download +- 功能说明： + - 中文：批量下载通用制品文件,将文件打包成zip压缩包并下载 + - English：batch download generic file +- 请求body +``` json +{ + "paths": ["/dir/file1", "/file2"] +} +``` + +- 请求字段说明 + + |字段|类型|是否必须|默认值|说明|Description| + |---|---|---|---|---|---| + |project|string|是|无|项目名称|project name| + |repo|string|是|无|仓库名称|repo name| + |paths|list|是|无|文件完整路径，支持添加多个文件路径|full path list| + + +- 响应体 + [文件流] \ No newline at end of file diff --git a/docs/apidoc-user/generic/temporary-access.md b/docs/apidoc-user/generic/temporary-access.md new file mode 100644 index 0000000000..5887027d4c --- /dev/null +++ b/docs/apidoc-user/generic/temporary-access.md @@ -0,0 +1,169 @@ +# Generic通用制品仓库临时访问凭证接口 + +[toc] + +## 创建临时访问token + +- API: POST /generic/temporary/token/create +- API 名称: create_temporary_access_token +- 功能说明： + - 中文：创建临时访问token + - English：create temporary access token + +- 请求体 + + ``` json + { + "projectId": "test", + "repoName": "generic-local", + "fullPathSet": ["/path/file"], + "authorizedUserSet": ["user1", "user2"], + "authorizedIpSet": ["127.0.0.1", "192.168.191.1"], + "expireSeconds": 3600, + "permits": 1, + "type": "DOWNLOAD" + } + ``` + +- 请求字段说明 + + |字段|类型|是否必须|默认值|说明|Description| + |---|---|---|---|---|---| + |projectId|string|是|无|项目名称|project name| + |repoName|string|是|无|仓库名称|repo name| + |fullPathSet|list|是|无|授权路径列表，支持批量创建|full path set| + |authorizedUserSet|list|否|无|授权访问用户，不传则任意用户可访问|authorized user set| + |authorizedIpSet|list|否|无|授权访问ip，不传则任意ip可访问|authorized ip set| + |expireSeconds|long|否|3600*24|token有效时间，单位秒，小于等于0则永久有效|expire seconds| + |permits|int|否|null|允许访问次数，null表示无限制|access permits| + |type|string|是|无|token类型。UPLOAD: 运行上传, DOWNLOAD: 允许下载, ALL: 同时运行上传和下载|token type| + +- 响应体 + +``` json +{ + "code" : 0, + "message" : null, + "data" : [{ + "projectId": "test", + "repoName": "generic-local", + "fullPath": "/path1", + "token": "xxx", + "authorizedUserSet": ["user1", "user2"], + "authorizedIpSet": ["127.0.0.1", "192.168.191.1"], + "expireDate": "2020-02-02T02:02:02.002", + "permits": 1, + "type": "DOWNLOAD" + }], + "traceId" : null +} +``` + +- data字段说明 + + |字段|类型|说明|Description| + |---|---|---|---| + |projectId|string|项目名称|project name| + |repoName|string|仓库名称|repo name| + |fullPath|string|完整路径|node full path| + |token|string|临时访问token|temporary access token| + |authorizedUserSet|list|授权访问用户|authorized user set| + |authorizedIpSet|list|授权访问ip|authorized ip set| + |expireDate|string|过期时间，null表示永久token|expire date| + |permits|int|允许访问次数，null表示无限制|access permits| + |type|string|token类型|token type| + +## 创建临时访问url + +- API: POST /generic/temporary/url/create +- API 名称: create_temporary_access_url +- 功能说明： + - 中文：创建临时访问url + - English：create temporary access url + +- 请求体 + + ``` json + { + "projectId": "test", + "repoName": "generic-local", + "fullPathSet": ["/path/file"], + "authorizedUserSet": ["user1", "user2"], + "authorizedIpSet": ["127.0.0.1", "192.168.191.1"], + "expireSeconds": 3600, + "permits": 1, + "type": "DOWNLOAD", + "host": "http://custom-host.com/", + "needsNotify": false + } + ``` + +- 请求字段说明 + + |字段|类型|是否必须|默认值|说明|Description| + |---|---|---|---|---|---| + |projectId|string|是|无|项目名称|project name| + |repoName|string|是|无|仓库名称|repo name| + |fullPathSet|list|是|无|授权路径列表，支持批量创建|full path set| + |authorizedUserSet|list|否|无|授权访问用户，不传则任意用户可访问|authorized user set| + |authorizedIpSet|list|否|无|授权访问ip，不传则任意ip可访问|authorized ip set| + |expireSeconds|long|否|3600*24|token有效时间，单位秒，小于等于0则永久有效|expire seconds| + |permits|int|否|null|允许访问次数，null表示无限制|access permits| + |type|string|是|无|token类型。UPLOAD:允许上传, DOWNLOAD: 允许下载, ALL: 同时允许上传和下载|token type| + |host|string|否|无|自定义分享链接host，不指定则使用系统默认host|custom url host| + |needsNotify|boolean|否|false|是否通知授权访问用户|notify authorized users| + +- 响应体 + +``` json +{ + "code" : 0, + "message" : null, + "data" : [{ + "projectId": "test", + "repoName": "generic-local", + "fullPath": "/path/file", + "url": "http://bkrepo.example.com/generic/temporary/test/generic-local/path/file?token=xxx", + "authorizedUserSet": ["user1", "user2"], + "authorizedIpSet": ["127.0.0.1", "192.168.191.1"], + "expireDate": "2020-02-02T02:02:02.002", + "permits": 1, + "type": "DOWNLOAD" + }], + "traceId" : null +} +``` + +- data字段说明 + + |字段|类型|说明|Description| + |---|---|---|---| + |projectId|string|项目名称|project name| + |repoName|string|仓库名称|repo name| + |fullPath|string|完整路径|node full path| + |url|string|临时访问url|temporary access url| + |authorizedUserSet|list|授权访问用户|authorized user set| + |authorizedIpSet|list|授权访问ip|authorized ip set| + |expireDate|string|过期时间，null表示永久token|expire date| + |permits|int|允许访问次数，null表示无限制|access permits| + |type|string|token类型|token type| + +## 临时token文件下载接口 + +- API: GET /generic/temporary/download/{project}/{repo}/{path}?token=xxx +- API 名称: temporary download +- 功能说明： + - 中文：临时token文件下载 + - English：temporary download +- 接口说明 + 除`token`参数外，其余参数和协议和[generic下载文件](./simple.md)一致 + +## 临时token文件上传接口 + +- API: PUT /generic/temporary/upload/{project}/{repo}/{path}?token=xxx +- API 名称: temporary upload +- 功能说明： + - 中文：临时token文件上传 + - English：temporary upload +- 接口说明 + 除`token`参数外，其余参数和协议和[generic上传文件](./simple.md)一致 diff --git a/docs/apidoc-user/log/log.md b/docs/apidoc-user/log/log.md new file mode 100644 index 0000000000..73a1eb01a9 --- /dev/null +++ b/docs/apidoc-user/log/log.md @@ -0,0 +1,94 @@ +# 审计日志接口 + +[toc] + +## 分页查询日志 + +- API: POST /repository/api/log/list +- API 名称: list_log +- 功能说明： + - 中文：查询日志 + - English：list_log + +- 请求体 +```json + { + "pageNumber": 1, + "pageSize": 20, + "projectId": "test", + "repoName": "generic-local", + "resourceKey": "/release/1.0.0/boot-example.jar", + "eventType": "NODE_DOWNLOADED", + "sha256": "6671fe83b7a07c8932ee89164d1f2793b2318058eb8b98dc5c06ee0a5a3b0ec1", + "pipelinId": "p-123456", + "buildId": "b-123456", + "userId": "admin", + "startTime": "2022-08-01T15:00:00.000", + "endTime": "2022-08-02T15:00:00.000", + "direction": "DESC" + } +``` + +- 请求字段说明 + + |字段|类型|是否必须|默认值| 说明 |Description| + |---|---|---|---------------------------------------------------------------------|---|---| + |pageNumber|int|否|1| 页数 |page number| + |pageSize|int|否|20| 页大小 |page size| + |projectId|string|是|无| 项目ID |project id| + |repoName|string|是|无| 仓库名称 |repo name| + |resourceKey|string|是|无| 事件资源key，支持通配符*，[详细说明](#resourcekey%E8%AF%B4%E6%98%8E) |resource key| + |eventType|string|是|无| 事件类型，参考[公共事件](../common/event.md) |event type| + |sha256|string|否|无| 文件sha256。查询节点类型事件日志时选填 |sha256| + |pipelinId|string|否|无| 文件元数据pipelineId。查询节点类型事件日志时选填 |pipeline id| + |buildId|string|否|无| 文件元数据buildId。查询节点类型事件日志时选填 |buildId| + |userId|string|否|无| 事件触发用户名 |user id| + |startTime|string|否|当前时间的前3个月| 开始时间 |start time| + |endTime|string|否|当前时间| 截至时间 |end time| + |direction|string|否|DESC| 按时间排序方向，默认降序。可选值ASC/DESC |direction| + + +- 响应体 + +``` json +{ + "code": 0, + "message": null, + "data": { + "pageNumber": 1, + "pageSize": 20, + "totalRecords": 1, + "totalPages": 1, + "records": [ + { + "createdDate": "2022-08-02T15:20:47.235", + "type": "NODE_DOWNLOADED", + "projectId": "test", + "repoName": "generic-local", + "resourceKey": "/release/1.0.0/boot-example.jar", + "userId": "admin", + "clientAddress": "127.0.0.1", + "description": { + "md5": "036208b4a1ab4a235d75c181e685e5a3", + "sha256": "6671fe83b7a07c8932ee89164d1f2793b2318058eb8b98dc5c06ee0a5a3b0ec1" + } + } + ], + "count": 1, + "page": 1 + }, + "traceId": "" +} +``` + +## resourceKey说明 + +事件资源key，具有唯一性 +1. 节点类型对应fullPath +2. 仓库类型对应仓库名称 +3. 包类型对应包名称 + +例如： +- 节点下载事件，resourceKey即为下载节点的fullPath。节点的fullPath为/release/1.0.0/boot-example.jar,那么resourceKey为/release/1.0.0/boot-example.jar。 +- 查询节点下载记录时，可以查询某个文件或目录的下载记录。查询/release/1.0.0/目录下文件的下载记录，resourceKey为/release/1.0.0/；查询/release/1.0.0/目录下jar类型文件的下载记录，resouceKey为/release/1.0.0/*.jar + \ No newline at end of file diff --git a/docs/apidoc-user/metadata/node-metadata.md b/docs/apidoc-user/metadata/node-metadata.md new file mode 100644 index 0000000000..80f5a568af --- /dev/null +++ b/docs/apidoc-user/metadata/node-metadata.md @@ -0,0 +1,77 @@ +# NodeMetadata节点元数据接口 + +[toc] + +## 查询元数据 + +- API: GET /repository/api/metadata/{projectId}/{repoName}/{fullPath} +- API 名称: query_metadata +- 功能说明： + - 中文：查询元数据信息 + - English：query metadata info +- 请求体 + 此接口请求体为空 + +- 请求字段说明 + + |字段|类型|是否必须|默认值|说明|Description| + |---|---|---|---|---|---| + |projectId|string|是|无|项目名称|project name| + |repoName|string|是|无|仓库名称|repo name| + |fullPath|string|是|无|完整路径|full path| + +- 响应体 + + ``` json + { + "code": 0, + "message": null, + "data": { + "key1": "value1", + "key2": "value2" + }, + "traceId": null + } + ``` + +- data字段说明 + + 键值对，key为元数据名称，value为元数据值 + + +## 删除元数据 + +- API: DELETE /repository/api/metadata/{projectId}/{repoName}/{fullPath} +- API 名称: delete_metadata +- 功能说明： + - 中文：根据提供的key列表删除元数据 + - English：delete metadata info +- 请求体 + + ```json + { + "keyList": ["key1", "key2"] + } + ``` + +- 请求字段说明 + + |字段|类型|是否必须|默认值|说明|Description| + |---|---|---|---|---|---| + |projectId|string|是|无|项目名称|project name| + |repoName|string|是|无|仓库名称|repo name| + |fullPath|string|是|无|完整路径|full path| + |keyList|[string]|是|无|待删除的元数据key列表|metadata key list| + +- 响应体 + + ``` json + { + "code": 0, + "message": null, + "data": null, + "traceId": null + } + ``` + + diff --git a/docs/apidoc-user/metadata/search.md b/docs/apidoc-user/metadata/search.md new file mode 100644 index 0000000000..03f7a4eacd --- /dev/null +++ b/docs/apidoc-user/metadata/search.md @@ -0,0 +1,45 @@ +# 利用元数据搜索制品 +[TOC] + +## 利用元数据搜索节点 + +利用[自定义搜索接口](../node/node.md?id=自定义搜索)查询节点，请求体如下 + +```json +{ + "select": ["xxx", "yyy", "xxx"], + "page": { + "pageNumber": 0, + "pageSize": 20 + }, + "sort": { + "properties": ["name"], + "direction": "ASC" + }, + "rule": { + "rules": [ + { + "field": "projectId", + "value": "test", + "operation": "EQ" + }, + { + "field": "repoName", + "value": ["generic-local1", "generic-local2"], + "operation": "IN" + }, + { + "field": "metadata.key1", + "value": "xxxxx", + "operation": "EQ" + }, + { + "field": "metadata.key2", + "value": "xxxx", + "operation": "EQ" + } + ], + "relation": "AND" + } +} +``` \ No newline at end of file diff --git a/docs/apidoc-user/metadata/system-metadata.md b/docs/apidoc-user/metadata/system-metadata.md new file mode 100644 index 0000000000..fd1a1f0c44 --- /dev/null +++ b/docs/apidoc-user/metadata/system-metadata.md @@ -0,0 +1,13 @@ +# 系统元数据说明 + +制品库运行过程中会为制品增加一些系统元数据，例如制品扫描状态，依赖包版本，包名等信息 + +## 制品分析产生的元数据 + +| key | 类型 | 必须 | 取值范围 | Node元数据 | Package元数据 | 说明 | Description | +|----------------|---------|-----|--------------------------------|---------|------------|---------------------------|------------------------------| +| scanStatus | string | 否 | INIT,RUNNING,SUCCESS,FAILED | 是 | 是 | 扫描状态,待扫描，扫描中，扫描成功，扫描失败 | scan status | +| qualityRedLine | boolean | 否 | true,false | 是 | 是 | 是否通过质量红线 | pass quality red line or not | +| forbidStatus | boolean | 否 | true,false | 是 | 是 | 是否被禁用 | forbid status | +| forbidUser | string | 否 | 无 | 是 | 是 | 仅手动禁用时有值，表示谁禁用了该制品 | forbid user | +| forbidType | string | 否 | SCANNING,QUALITY_UNPASS,MANUAL | 是 | 是 | 禁用类型，分为扫描中，未通过质量红线，用户手动禁用 | forbid type | diff --git a/docs/apidoc-user/node/node.md b/docs/apidoc-user/node/node.md new file mode 100644 index 0000000000..8992f02600 --- /dev/null +++ b/docs/apidoc-user/node/node.md @@ -0,0 +1,540 @@ +# Node节点操作接口 + +[toc] + +## 查询节点详情 + +- API: GET /repository/api/node/detail/{projectId}/{repoName}/{fullPath} +- API 名称: query_node_detail +- 功能说明： + - 中文：查询节点详情 + - English：query node detail +- 请求体 + 此接口请求体为空 +- 请求字段说明 + + |字段|类型|是否必须|默认值|说明|Description| + |---|---|---|---|---|---| + |projectId|string|是|无|项目名称|project name| + |repoName|string|是|无|仓库名称|repo name| + |fullPath|string|是|无|完整路径|full path| + +- 响应体 + + ```json + { + "code": 0, + "message": null, + "data": { + "projectId" : "test", + "repoName" : "generic-local", + "path" : "/", + "name" : "test.json", + "fullPath" : "/test.json", + "folder" : false, + "size" : 34, + "sha256" : "6a7983009447ecc725d2bb73a60b55d0ef5886884df0ffe3199f84b6df919895", + "md5" : "2947b3932900d4534175d73964ec22ef", + "stageTag": "@release", + "metadata": { + "key": "value" + }, + "nodeMetadata": [ + { + "key": "key", + "value": "value", + "description": "", + "system": false, + "link": "https://bkrepo.example.com" + } + ], + "createdBy" : "admin", + "createdDate" : "2020-07-27T16:02:31.394", + "lastModifiedBy" : "admin", + "lastModifiedDate" : "2020-07-27T16:02:31.394" + }, + "traceId": null + } + ``` + +- data字段说明 + + |字段|类型| 说明 |Description| + |---|--------------------|---|---| + |projectId|string| 节点所属项目 |node project id| + |repoName|string| 节点所属仓库 |node repository name| + |path|string| 节点目录 |node path| + |name|string| 节点名称 |node name| + |fullPath|string| 节点完整路径 |node full path| + |folder|bool| 是否为文件夹 |is folder| + |size|long| 节点大小 |file size| + |sha256|string| 节点sha256 |file sha256| + |md5|string| 节点md5 |file md5 checksum| + |stageTag|string| 晋级状态标签 |stage status tag| + |metadata|object| 节点元数据，key-value键值对 |node metadata| + |nodeMetadata|object| 节点元数据列表 |node metadata| + |createdBy|string| 创建者 |create user| + |createdDate|string| 创建时间 |create time| + |lastModifiedBy|string| 上次修改者 |last modify user| + |lastModifiedDate|string| 上次修改时间 |last modify time| + +## 分页查询节点 + +- API: GET /repository/api/node/page/{projectId}/{repoName}/{fullPath}?pageNumber=0&pageSize=20&includeFolder=true&includeMetadata=true&deep=false&sort=false&sortProperty=xx&direction=ASC&sortProperty=xx&direction=DESC +- API 名称: list_node_page +- 功能说明： + - 中文：分页查询节点，返回的结果列表中目录在前，文件在后，并按照文件名称排序, 同时支持自定义排序 + - English：list node page +- 请求体 + 此接口请求体为空 + +- 请求字段说明 + + |字段|类型|是否必须|默认值| 说明 |Description| + |---|---|---|---------------------------------------------------------------|---|---| + |projectId|string|是|无| 项目名称 |project name| + |repoName|string|是|无| 仓库名称 |repo name| + |fullPath|string|是|无| 完整路径 |full path| + |pageNumber|int|否|1| 当前页 |current page| + |pageSize|int|否|20| 分页大小 |page size| + |includeFolder|boolean|否|true| 是否包含目录 |include folder| + |includeMetadata|boolean|否|false| 是否包含元数据 |include metadata| + |deep|boolean|否|false| 是否查询子目录节点 |deep query| + |sort|boolean|否|false| 是否排序输出结果 |sort result| + |sortProperty|string|否|false| 自定义排序字段,可添加多个。自定义排序字段优先级高于sort=true时的排序规则。多个自定义排序字段优先级与参数顺序相同 |sort property| + |direction|string|否|false| 自定义排序方向,可添加多个，与排序字段一一对应 |sort direction| + +- 响应体 + + ```json + { + "code": 0, + "message": null, + "data": { + "pageNumber": 1, + "pageSize": 20, + "totalRecords": 18, + "totalPages": 18, + "records": [ + { + "projectId" : "test", + "repoName" : "generic-local", + "path" : "/", + "name" : "test.json", + "fullPath" : "/test.json", + "folder" : false, + "size" : 34, + "sha256" : "6a7983009447ecc725d2bb73a60b55d0ef5886884df0ffe3199f84b6df919895", + "md5" : "2947b3932900d4534175d73964ec22ef", + "stageTag": "@release", + "metadata": {}, + "nodeMetadata": [], + "createdBy" : "admin", + "createdDate" : "2020-07-27T16:02:31.394", + "lastModifiedBy" : "admin", + "lastModifiedDate" : "2020-07-27T16:02:31.394" + } + ] + }, + "traceId": null + } + ``` + +- record字段说明 + + | 字段 |类型|说明|Description| + |---|---|---|---| + | projectId |string|节点所属项目|node project id| + | repoName |string|节点所属仓库|node repository name| + | path |string|节点目录|node path| + | name |string|节点名称|node name| + | fullPath |string|节点完整路径|node full path| + | folder |bool|是否为文件夹|is folder| + | size |long|节点大小|file size| + | sha256 |string|节点sha256|file sha256| + | md5 |string|节点md5|file md5 checksum| + | stageTag |string|晋级状态标签，includeMetadata=false将返回空|stage status tag| + | metadata |object|节点元数据，key-value键值对，includeMetadata=false将返回空|node metadata| + | nodeMetadata |object|节点元数据，key-value键值对，includeMetadata=false将返回空|node metadata| + | createdBy |string|创建者|create user| + | createdDate |string|创建时间|create time| + | lastModifiedBy |string|上次修改者|last modify user| + | lastModifiedDate |string|上次修改时间|last modify time| + +## 创建目录 + +- API: POST /repository/api/node/mkdir/{projectId}/{repoName}/{path} +- API 名称: mkdir +- 功能说明： + - 中文：创建目录节点 + - English：create directory node +- 请求体 + 此接口请求体为空 +- 请求字段说明 + + |字段|类型|是否必须|默认值|说明|Description| + |---|---|---|---|---|---| + |projectId|string|是|无|项目名称|project name| + |repoName|string|是|无|仓库名称|repo name| + |path|string|是|无|完整路径|full path| + +- 响应体 + + ```json + { + "code": 0, + "message": null, + "data": null, + "traceId": null + } + ``` + +## 删除节点 + +- API: DELETE /repository/api/node/delete/{projectId}/{repoName}/{fullPath} +- API 名称: delete_node +- 功能说明： + - 中文：删除节点，同时支持删除目录和文件节点 + - English：delete node +- 请求体 + 此接口请求体为空 +- 请求字段说明 + + |字段|类型|是否必须|默认值|说明|Description| + |---|---|---|---|---|---| + |projectId|string|是|无|项目名称|project name| + |repoName|string|是|无|仓库名称|repo name| + |fullPath|string|是|无|完整路径|full path| + +- 响应体 + +```json + { + "code": 0, + "message": null, + "data": {"deletedNumber": 0, + "deletedSize": 0, + "deletedTime": "yyyy-MM-dd'T'HH:mm:ss.SSSXXX" + }, + "traceId": null + } + ``` + +## 更新节点 + +- API: POST /repository/api/node/update/{projectId}/{repoName}/{fullPath} +- API 名称: update_node +- 功能说明： + - 中文：更新节点信息，目前支持修改文件过期时间 + - English：update node info +- 请求体 + + ```json + { + "expires": 0 + } + ``` + +- 请求字段说明 + +|字段|类型|是否必须|默认值|说明|Description| +|---|---|---|---|---|---| +|projectId|string|是|无|项目名称|project name| +|repoName|string|是|无|仓库名称|repo name| +|fullPath|string|是|无|完整路径|full path| +|expires|long|否|0|过期时间，单位天(0代表永久保存)|expires day| + +- 响应体 + + ```json + { + "code": 0, + "message": null, + "data": null, + "traceId": null + } + ``` + +## 重命名节点 + +- API: POST /repository/api/node/rename/{projectId}/{repoName}/{fullPath}?newFullPath=/data/new_name.text +- API 名称: rename_node +- 功能说明： + - 中文：重命名节点 + - English：rename node +- 请求体 + 此接口请求体为空 + +- 请求字段说明 + + |字段|类型|是否必须|默认值|说明|Description| + |---|---|---|---|---|---| + |projectId|string|是|无|项目名称|project name| + |repoName|string|是|无|仓库名称|repo name| + |fullPath|string|是|无|完整路径|full path| + |newFullPath|string|是|无|新的完整路径|new full path| + +- 响应体 + + ``` json + { + "code": 0, + "message": null, + "data": null, + "traceId": null + } + ``` + +## 移动节点 + +- API: POST /repository/api/node/move +- API 名称: move_node +- 功能说明： + - 中文：移动节点 + - English：move node + + 移动文件或者文件夹，采用fast-failed模式，移动过程中出现错误则立即返回错误，剩下的文件不会再移动。该接口行为类似linux mv命令: + + - mv 文件 文件 -> 将源文件改名为目标文件 + - mv 文件 目录 -> 将源文件移动到目标目录 + - mv 目录 目录 -> 如果目标目录已存在，将源目录（目录本身及子文件）移动到目标目录；目标目录不存在则改名 + - mv 目录 文件 -> 出错 + +- 请求体 + + ``` json + { + "srcProjectId": "", + "srcRepoName": "", + "srcFullPath": "", + "destProjectId": "", + "destRepoName": "", + "destFullPath": "", + "overwrite": false + } + ``` + +- 请求字段说明 + + |字段|类型|是否必须|默认值|说明|Description| + |---|---|---|---|---|---| + |srcProjectId|string|是|无|源项目名称|src project name| + |srcRepoName|string|是|无|源仓库名称|src repo name| + |srcFullPath|string|是|无|源完整路径|src full path| + |destProjectId|string|否|null|目的项目名称。传null表示源项目|dest project name| + |destRepoName|string|否|null|目的仓库名称。传null表示源仓库|dest repo name| + |destFullPath|string|是|无|目的完整路径|dest full path| + |overwrite|boolean|否|false|同名文件是否覆盖|overwrite same node| + +- 响应体 + + ``` json + { + "code": 0, + "message": null, + "data": null, + "traceId": null + } + ``` + +## 拷贝节点 + +- API: POST /repository/api/node/copy +- API 名称: copy_node +- 功能说明： + - 中文：拷贝节点 + - English：copy node + + 拷贝文件或者文件夹，采用fast-failed模式，拷贝过程中出现错误则立即返回错误，剩下的文件不会再拷贝。该接口行为类似linux cp命令: + + - cp 文件 文件 -> 将源文件拷贝到目标文件 + - cp 文件 目录 -> 将文件移动到目标目录下 + - cp 目录 目录 -> 如果目标目录已存在，将源目录（目录本身及子文件）拷贝到目标目录；否则将源目录下文件拷贝到目标目录 + - cp 目录 文件 -> 出错 + +- 请求体 + + ``` json + { + "srcProjectId": "", + "srcRepoName": "", + "srcFullPath": "", + "destProjectId": "", + "destRepoName": "", + "destFullPath": "", + "overwrite": false + } + ``` + +- 请求字段说明 + + |字段|类型|是否必须|默认值|说明|Description| + |---|---|---|---|---|---| + |srcProjectId|string|是|无|源项目名称|src project name| + |srcRepoName|string|是|无|源仓库名称|src repo name| + |srcFullPath|string|是|无|源完整路径|src full path| + |destProjectId|string|否|null|目的项目名称。传null表示源项目|dest project name| + |destRepoName|string|否|null|目的仓库名称。传null表示源仓库|dest repo name| + |destFullPath|string|是|无|目的完整路径|dest full path| + |overwrite|boolean|否|false|同名文件是否覆盖|overwrite same node| + +- 响应体 + + ``` json + { + "code": 0, + "message": null, + "data": null, + "traceId": null + } + ``` + +## 统计节点大小信息 + +- API: GET /repository/api/node/size/{projectId}/{repoName}/{fullPath} +- API 名称: compute_node_size +- 功能说明： + - 中文：统计节点大小信息 + - English：compute node size +- 请求体 + 此接口请求体为空 + +- 请求字段说明 + + |字段|类型|是否必须|默认值|说明|Description| + |---|---|---|---|---|---| + |projectId|string|是|无|项目名称|project name| + |repoName|string|是|无|仓库名称|repo name| + |fullPath|string|是|无|完整路径|full path| + +- 响应体 + + ```json + { + "code": 0, + "message": null, + "data": { + "subNodeCount": 32, + "size": 443022203 + }, + "traceId": null + } + ``` + +- data字段说明 + + |字段|类型|说明|Description| + |---|---|---|---| + |subNodeCount|long|子节点数量（包括目录）|sub node count| + |size|long|目录/文件大小|directory/file size| + + +## 自定义搜索 + +- API: POST /repository/api/node/search +- API 名称: node search +- 功能说明： + - 中文：节点自定义搜索。最外层的查询条件中必须包含projectId条件，可以传入repoType指定仓库类型或者repoName指定仓库查询。 + - English：search node +- 请求体 + 参考[自定义搜索接口公共说明](../common/search.md?id=自定义搜索协议) + + 假设需要查询*项目test下, 仓库为generic-local1或generic-local2，文件名以.tgz结尾的文件，并按照文件名和大小排序，查询结果包含name、fullPath、size、sha256、md5、metadata字段*，构造的请求体如下， + ``` json + + { + "select": ["name", "fullPath", "size", "sha256", "md5", "metadata"], + "page": { + "pageNumber": 1, + "pageSize": 20 + }, + "sort": { + "properties": ["name", "size"], + "direction": "ASC" + }, + "rule": { + "rules": [ + { + "field": "projectId", + "value": "test", + "operation": "EQ" + }, + { + "field": "repoName", + "value": ["generic-local1", "generic-local2"], + "operation": "IN" + }, + { + "field": "name", + "value": ".tgz", + "operation": "SUFFIX" + }, + { + "field": "folder", + "value": "false", + "operation": "EQ" + }, + ], + "relation": "AND" + } + } + ``` + + + +## 查询节点总览 + +- API: GET /repository/api/node/search/overview?projectId={projectId}&name={name}&exRepo={reponames} + +- API 名称: query_node_overview + +- 功能说明： + + - 中文：查询节点总览 + - English：query node overview + +- 请求体 + 此接口请求体为空 + +- 请求字段说明 + + | 字段 | 类型 | 是否必须 | 默认值 | 说明 | Description | + | --------- | ------ | -------- | ------ | -------------------------------- | ------------ | + | projectId | string | 是 | 无 | 项目名称 | project name | + | name | string | 是 | 无 | 查询文件名 | file name | + | exRepo | string | 否 | null | 排除的仓库，多个仓库以 `,` 分隔" | repo name | + +- 响应体 + + ```json + { + "code": 0, + "message": null, + "data": [ + { + "projectId": "test", + "repos": [ + { + "repoName": "custom", + "packages": 10 + }, + { + "repoName": "scan_test", + "packages": 2 + } + ], + "sum": 20 + } + ], + "traceId": "" + } + ``` + +- data字段说明 + + | 字段 | 类型 | 说明 | Description | + | --------- | ------ | ------------ | -------------------- | + | projectId | string | 节点所属项目 | node project id | + | repoName | string | 节点所属仓库 | node repository name | + | packages | Int | 节点数量 | node count | + diff --git a/docs/apidoc-user/node/share.md b/docs/apidoc-user/node/share.md new file mode 100644 index 0000000000..0f18ee532c --- /dev/null +++ b/docs/apidoc-user/node/share.md @@ -0,0 +1,182 @@ +# Share文件分享接口 + +[toc] + +## 创建分享下载链接 + +- API: POST /repository/api/share/{projectId}/{repoName}/{fullPath} +- API 名称: create_share_url +- 功能说明： + - 中文：创建分享下载链接 + - English：create share url +- 请求体 + + ```json + { + "authorizedUserList": ["user1", "user2"], + "authorizedIpList": ["192.168.1.1", "127.0.0.1"], + "expireSeconds": 3600 + } + ``` + +- 请求字段说明 + + |字段|类型|是否必须|默认值|说明|Description| + |---|---|---|---|---|---| + |projectId|string|是|无|项目名称|project name| + |repoName|string|是|无|仓库名称|repo name| + |fullPath|string|是|无|完整路径|full path| + |authorizedUserList|[string]|否|无|授权用户列表，若为空所有用户可下载|share user list| + |authorizedIpList|[string]|否|无|授权ip列表，若为空所有ip可下载|share ip list| + |expireSeconds|long|否|0|下载链接有效时间，单位秒|expire seconds| + +- 响应体 + + ``` json + { + "code": 0, + "message": null, + "data": { + "projectId": "test", + "repoName": "generic-local", + "fullPath": "/test.txt", + "shareUrl": "/api/share/test/generic-local/test.json?token=bef56a14c33342beba7fdb5f63508d24", + "authorizedUserList": [ + "user1", + "user2" + ], + "authorizedIpList": [ + "192.168.1.1", + "127.0.0.1" + ], + "expireDate": "2020-08-13T12:35:38.541" + }, + "traceId": null + } + ``` + +- data字段说明 + + |字段|类型|说明|Description| + |---|---|---|---| + |projectId|string|项目id|project id| + |repoName|string|仓库名称|repo name| + |fullPath|string|完整路径|full path| + |shareUrl|string|分享下载链接|share url| + |authorizedUserList|list|授权用户列表|authorized user list| + |authorizedIpList|list|授权ip列表|authorized ip list| + |expireDate|string|过期时间|expire date| + +## 创建分享下载链接（批量） + +- API: POST /repository/api/share/batch +- API 名称: create_batch_share_url +- 功能说明： + - 中文：创建分享下载链接（批量） + - English：create batch share url +- 请求体 + + ```json + { + "projectId": "", + "repoName": "", + "fullPathList": "", + "authorizedUserList": ["user1", "user2"], + "authorizedIpList": ["192.168.1.1", "127.0.0.1"], + "expireSeconds": 3600 + } + ``` + +- 请求字段说明 + + |字段|类型|是否必须|默认值|说明|Description| + |---|---|---|---|---|---| + |projectId|string|是|无|项目名称|project name| + |repoName|string|是|无|仓库名称|repo name| + |fullPathList|list|是|无|完整路径列表|full path list| + |authorizedUserList|[string]|否|无|授权用户列表，若为空所有用户可下载|share user list| + |authorizedIpList|[string]|否|无|授权ip列表，若为空所有ip可下载|share ip list| + |expireSeconds|long|否|0|下载链接有效时间，单位秒|expire seconds| + +- 响应体 + + ``` json + { + "code": 0, + "message": null, + "data": { + [ + "projectId": "test", + "repoName": "generic-local", + "fullPath": "/test.txt", + "shareUrl": "/api/share/test/generic-local/test.json?token=bef56a14c33342beba7fdb5f63508d24", + "authorizedUserList": [ + "user1", + "user2" + ], + "authorizedIpList": [ + "192.168.1.1", + "127.0.0.1" + ], + "expireDate": "2020-08-13T12:35:38.541" + ] + }, + "traceId": null + } + ``` + + +- data字段说明 + + |字段|类型|说明|Description| + |---|---|---|---| + |projectId|string|项目id|project id| + |repoName|string|仓库名称|repo name| + |fullPath|string|完整路径|full path| + |shareUrl|string|分享下载链接|share url| + |authorizedUserList|[string]|授权用户列表|authorized user list| + |authorizedIpList|[string]|授权ip列表|authorized ip list| + |expireDate|string|过期时间|expire date| + +## 分享链接下载 + +- API: GET /repository/api/share/{projectId}/{repoName}/{fullPath}?token=xxx +- API 名称: download_share_url +- 功能说明： + - 中文：分享链接下载，支持HEAD操作 + - English：download by share url +- 请求体 + 此接口请求体为空 + +- 请求字段说明 + + |字段|类型|是否必须|默认值|说明|Description| + |---|---|---|---|---|---| + |projectId|string|是|无|项目名称|project name| + |repoName|string|是|无|仓库名称|repo name| + |fullPath|string|是|无|完整路径|full path| + |token|string|是|无|下载凭证|download token| + +- 请求头 + + |字段|类型|是否必须|默认值|说明|Description| + |---|---|---|---|---|---| + |Range|string|否|无|RFC 2616 中定义的字节范围，范围值必须使用 bytes=first-last 格式且仅支持单一范围，不支持多重范围。first 和 last 都是基于0开始的偏移量。例如 bytes=0-9，表示下载对象的开头10个字节的数据；bytes=5-9，表示下载对象的第6到第10个字节。此时返回 HTTP 状态码206（Partial Content）及 Content-Range 响应头部。如果 first 超过对象的大小，则返回 HTTP 状态码416（Requested Range Not Satisfiable）错误。如果不指定，则表示下载整个对象|bytes range| + +- 响应头 + + |字段|类型|说明|Description| + |---|---|---|---| + |Accept-Ranges|string|RFC 2616 中定义的服务器接收Range范围|RFC 2616 Accept-Ranges| + |Cache-Control|string|RFC 2616 中定义的缓存指令|RFC 2616 Cache-Control| + |Connection|string|RFC 2616 中定义，表明响应完成后是否会关闭网络连接。枚举值：keep-alive，close。|RFC 2616 Connection| + |Content-Disposition|string|RFC 2616 中定义的文件名称|RFC 2616 Content-Disposition| + |Content-Length|long|RFC 2616 中定义的 HTTP 响应内容长度（字节）|RFC 2616 Content Length| + |Content-Range|string|RFC 2616 中定义的返回内容的字节范围，仅当请求中指定了 Range 请求头部时才会返回该头部|RFC 2616 Content-Range| + |Content-Type|string|RFC 2616 中定义的 HTTP 响应内容类型（MIME）|RFC 2616 Content Length| + |Date|string|RFC 1123 中定义的 GMT 格式服务端响应时间，例如Mon, 27 Jul 2020 08:51:59 GMT|RFC 1123 Content Length| + |Etag|string|ETag 全称为 Entity Tag，是文件被创建时标识对象内容的信息标签，可用于检查对象的内容是否发生变化，通用制品文件会返回文件的sha256值|ETag, file sha256 checksum| + |Last-Modified|string|文件的最近一次上传的时间，例如Mon, 27 Jul 2020 08:51:58 GMT|file last modified time| + +- 响应体 + [文件流] diff --git a/docs/apidoc-user/package/package.md b/docs/apidoc-user/package/package.md new file mode 100644 index 0000000000..c8457bd5ee --- /dev/null +++ b/docs/apidoc-user/package/package.md @@ -0,0 +1,565 @@ +# Package制品包版本接口 + +[toc] + +## 分页查询包列表 + +- API: GET /repository/api/package/page/{projectId}/{repoName}?packageName=xxx&pageNumber=0&pageSize=20 +- API 名称: list_package_page +- 功能说明： + - 中文：分页查询包列表 + - English：list package page +- 请求体 + 此接口请求体为空 +- 请求字段说明 + + |字段|类型|是否必须|默认值|说明|Description| + |---|---|---|---|---|---| + |projectId|string|是|无|项目名称|project name| + |repoName|string|是|无|仓库名称|repo name| + |packageName|string|否|无|包名称，支持前缀匹配模糊搜索|package name| + |pageNumber|Int|是|无|页码|page number| + |pageSize|Int|是|无|每页数量|page size| + +- 响应体 + + ```json + { + "code": 0, + "message": null, + "data": { + "pageNumber": 0, + "pageSize": 1, + "totalRecords": 18, + "totalPages": 18, + "records": [ + { + "projectId" : "test", + "repoName" : "generic-local", + "name" : "test", + "key" : "com.tencent.bkrepo", + "type" : "MAVEN", + "latest" : "0.0.9", + "downloads" : 101, + "versions" : 9, + "description": null, + "createdBy" : "admin", + "createdDate" : "2020-07-27T16:02:31.394", + "lastModifiedBy" : "admin", + "lastModifiedDate" : "2020-07-27T16:02:31.394", + "extension" : { + "appVersion": "4.2.4" + }, + "historyVersion" : [ + "7.8.10" + ] + } + ] + }, + "traceId": null + } + ``` + +- records字段说明 + + |字段|类型|说明|Description| + |---|---|---|---| + |projectId|string|节点所属项目|project id| + |repoName|string|节点所属仓库|repository name| + |name|string|包名称|package name| + |key|string|包唯一key|package unique key| + |type|string|包类别|package type| + |latest|string|最新上传版本名称|latest version name| + |downloads|Long|下载次数|download times| + |versions|Long|版本数量|version count| + |description|string|简要描述|brief description| + |createdBy|string|创建者|create user| + |createdDate|string|创建时间|create time| + |lastModifiedBy|string|上次修改者|last modify user| + |extension|object|扩展信息，key-value键值对|extension| + |historyVersion|list[string]|历史版本|history version| + +- extension字段说明 + |字段|类型|说明|Description| + |---|---|---|---| + |appVersion|string|软件版本|app version| + +## 查询包信息 + +- API: GET /repository/api/package/info/{projectId}/{repoName}?packageKey=docker://nginx +- API 名称: get_package_info +- 功能说明： + - 中文：查询包信息 + - English：get package info +- 请求体 + 此接口请求体为空 +- 请求字段说明 + + |字段|类型|是否必须|默认值|说明|Description| + |---|---|---|---|---|---| + |projectId|string|是|无|项目名称|project name| + |repoName|string|是|无|仓库名称|repo name| + |packageKey|string|是|无|包唯一key|package unique key| + +- 响应体 + + ```json + { + "code": 0, + "message": null, + "data": { + { + "projectId" : "test", + "repoName" : "generic-local", + "name" : "test", + "key" : "com.tencent.bkrepo", + "type" : "MAVEN", + "latest" : "0.0.9", + "downloads" : 101, + "versions": 9, + "description": null, + "createdBy" : "admin", + "createdDate" : "2020-07-27T16:02:31.394", + "lastModifiedBy" : "admin", + "lastModifiedDate" : "2020-07-27T16:02:31.394", + "extension" : { + "appVersion": "4.2.4" + }, + "historyVersion" : [ + "7.8.10" + ] + } + }, + "traceId": null + } + ``` + +- record字段说明 + + |字段|类型|说明|Description| + |---|---|---|---| + |projectId|string|节点所属项目|project id| + |repoName|string|节点所属仓库|repository name| + |name|string|包名称|package name| + |key|string|包唯一key|package unique key| + |type|string|包类别|package type| + |latest|string|最新上传版本名称|latest version name| + |downloads|Long|下载次数|download times| + |versions|Long|版本数量|version count| + |description|string|简要描述|brief description| + |createdBy|string|创建者|create user| + |createdDate|string|创建时间|create time| + |lastModifiedBy|string|上次修改者|last modify user| + |lastModifiedDate|string|上次修改时间|last modify time| + |extension|object|扩展信息，key-value键值对|extension| + |historyVersion|list[string]|历史版本|history version| + +- extension字段说明 + |字段|类型|说明|Description| + |---|---|---|---| + |appVersion|string|软件版本|app version| + + +## 分页查询包版本 + +- API: GET /repository/api/version/page/{projectId}/{repoName}?packageKey=gav://com.tencent:test&version=0.0.1&stageTag=release&pageNumber=0&pageSize=20&sortProperty=lastModifiedDate&direction=DESC +- API 名称: list_version_page +- 功能说明： + - 中文：分页查询版本列表 + - English：list version page +- 请求体 + 此接口请求体为空 +- 请求字段说明 + + |字段|类型|是否必须|默认值|说明|Description| + |---|---|---|---|---|---| + |projectId|string|是|无|项目名称|project name| + |repoName|string|是|无|仓库名称|repo name| + |packageKey|string|否|无|包唯一key|package unique key| + |version|string|否|无|版本名称，前缀匹配|version name| + |stageTag|string|否|无|晋级标签， 逗号分隔|stage tag list| + |pageNumber|Int|是|无|页码|page number| + |pageSize|Int|是|无|每页数量|page size| + |sortProperty|string|否|无|排序字段|sort property| + |direction|string|否|DESC|排序方向(ASC、DESC)|sort direction| + +- 响应体 + + ```json + { + "code": 0, + "message": null, + "data": { + "pageNumber": 0, + "pageSize": 1, + "totalRecords": 18, + "totalPages": 18, + "records": [ + { + "name" : "0.0.9", + "size" : 1024, + "downloads" : 18, + "stageTag" : ["@prerelease", "@release"], + "createdBy" : "admin", + "createdDate" : "2020-07-27T16:02:31.394", + "lastModifiedBy" : "admin", + "lastModifiedDate" : "2020-07-27T16:02:31.394", + "metadata": { + "apiVersion": "v1", + "appVersion": "7.0", + "description": "Deploy a basic tomcat application server with sidecar as web archive container", + "home": "https://github.com/yahavb", + "icon": "http://tomcat.apache.org/res/images/tomcat.png", + "keywords": [], + "maintainers": [ + { + "name": "yahavb", + "email": "ybiran@ananware.systems" + } + ], + "name": "tomcat", + "sources": [], + "urls": [], + "version": "0.4.2" + }, + "nodeMetadata": [ + { + "key": "apiVersion", + "value": "v1", + "description": "", + "system": false + }, + { + "key": "appVersion", + "value": "7.0", + "description": "", + "system": false + }, + { + "key": "description", + "value": "Deploy a basic tomcat application server with sidecar as web archive container", + "description": "", + "system": false + }, + { + "key": "home", + "value": "https://github.com/yahavb", + "description": "", + "system": false + }, + { + "key": "icon", + "value": "http://tomcat.apache.org/res/images/tomcat.png", + "description": "", + "system": false + }, + { + "key": "keywords", + "value": [], + "description": "", + "system": false + }, + { + "key": "maintainers", + "value": [ + { + "name": "yahavb", + "email": "ybiran@ananware.systems" + } + ], + "description": "", + "system": false + }, + { + "key": "name", + "value": "tomcat", + "description": "", + "system": false + }, + { + "key": "sources", + "value": [], + "description": "", + "system": false + }, + { + "key": "urls", + "value": [], + "description": "", + "system": false + }, + { + "key": "version", + "value": "0.4.2", + "description": "", + "system": false + } + ] + } + ] + }, + "traceId": null + } + ``` + +- records字段说明 + + | 字段 |类型|说明|Description| + |---|---|---|---| + | name |string|版本名称|version name| + | size |long|版本大小|version size| + | downloads |long|版本下载次数|download times| + | stageTag |list[string]|晋级阶段标签列表|stage tag list| + | metadata |object|元数据，key-value键值对|metadata| + | nodeMetadata |object|元数据，key-value键值对|metadata| + | createdBy |string|创建者|create user| + | createdDate |string|创建时间|create time| + | lastModifiedBy |string|上次修改者|last modify user| + | lastModifiedDate |string|上次修改时间|last modify time| + +## 查询包版本 + +- API: POST /repository/api/version/list/{projectId}/{repoName}?packageKey=gav://com.tencent:test +- API 名称: list_version +- 功能说明： + - 中文：查询版本列表 + - English：list version +- 请求体 +```json + { + "pageNumber": 1, + "pageSize": 20, + "version": "1.0.0", + "stageTag": "release", + "metadata": [ + { + "key": "apiVersion", + "value": "v1" + } + ], + "sortProperty": "lastModifiedDate", + "direction": "DESC" + } +``` +- 请求字段说明 + + |字段|类型|是否必须|默认值|说明|Description| + |---|---|---|---|---|---| + |projectId|string|是|无|项目名称|project name| + |repoName|string|是|无|仓库名称|repo name| + |packageKey|string|否|无|包唯一key|package unique key| + |version|string|否|无|版本名称，前缀匹配|version name| + |stageTag|string|否|无|晋级标签， 逗号分隔|stage tag list| + |metadata|List|否|无|版本元数据|package version metadata| + |pageNumber|Int|是|无|页码|page number| + |pageSize|Int|是|无|每页数量|page size| + |sortProperty|string|否|无|排序字段|sort property| + |direction|string|否|DESC|排序方向(ASC、DESC)|sort direction| + + +- 响应体 + + ```json + { + "code": 0, + "message": null, + "data": { + "name" : "0.0.9", + "size" : 1024, + "downloads" : 18, + "stageTag" : ["@prerelease", "@release"], + "createdBy" : "admin", + "createdDate" : "2020-07-27T16:02:31.394", + "lastModifiedBy" : "admin", + "lastModifiedDate" : "2020-07-27T16:02:31.394", + "metadata": { + "apiVersion": "v1", + "appVersion": "7.0", + "description": "Deploy a basic tomcat application server with sidecar as web archive container", + "home": "https://github.com/yahavb", + "icon": "http://tomcat.apache.org/res/images/tomcat.png", + "keywords": [], + "maintainers": [ + { + "name": "yahavb", + "email": "ybiran@ananware.systems" + } + ], + "name": "tomcat", + "sources": [], + "urls": [], + "version": "0.4.2" + }, + "nodeMetadata": [ + { + "key": "apiVersion", + "value": "v1", + "description": "", + "system": false + }, + { + "key": "appVersion", + "value": "7.0", + "description": "", + "system": false + }, + { + "key": "description", + "value": "Deploy a basic tomcat application server with sidecar as web archive container", + "description": "", + "system": false + }, + { + "key": "home", + "value": "https://github.com/yahavb", + "description": "", + "system": false + }, + { + "key": "icon", + "value": "http://tomcat.apache.org/res/images/tomcat.png", + "description": "", + "system": false + }, + { + "key": "keywords", + "value": [], + "description": "", + "system": false + }, + { + "key": "maintainers", + "value": [ + { + "name": "yahavb", + "email": "ybiran@ananware.systems" + } + ], + "description": "", + "system": false + }, + { + "key": "name", + "value": "tomcat", + "description": "", + "system": false + }, + { + "key": "sources", + "value": [], + "description": "", + "system": false + }, + { + "key": "urls", + "value": [], + "description": "", + "system": false + }, + { + "key": "version", + "value": "0.4.2", + "description": "", + "system": false + } + ] + }, + "traceId": null + } + ``` + + +## 自定义搜索包 + +- API: POST /repository/api/package/search +- API 名称: package search +- 功能说明： + - 中文：节点自定义搜索。最外层的查询条件中必须包含projectId条件，可以传入repoType指定仓库类型或者repoName指定仓库查询。 + - English：search package +- 请求体 + 参考[自定义搜索接口公共说明](../common/search.md) + + ``` json + 查询在项目test下, 仓库类型为MAVEN，包名为spring开头的包，并按照包名排序，查询结果包含name、key、latest、donwloads、versions字段 + { + "select": ["name", "key", "latest", "downloads", "versions"], + "page": { + "pageNumber": 1, + "pageSize": 20 + }, + "sort": { + "properties": ["name"], + "direction": "ASC" + }, + "rule": { + "rules": [ + { + "field": "projectId", + "value": "test", + "operation": "EQ" + }, + { + "field": "repoType", + "value": "MAVEN", + "operation": "EQ" + }, + { + "field": "name", + "value": "spring", + "operation": "PREFIX" + } + ], + "relation": "AND" + } + } + ``` + +## 下载版本 + +- API: GET /repository/api/version/download/{projectId}/{repoName}?packageKey=npm://test&version=0.0.1 +- API 名称: download_version +- 功能说明： + - 中文：下载版本 + - English：download version + +- 请求体 + 此接口请求体为空 + +- 请求字段说明 + + |字段|类型|是否必须|默认值|说明|Description| + |---|---|---|---|---|---| + |projectId|string|是|无|项目名称|project name| + |repoName|string|是|无|仓库名称|repo name| + |packageKey|string|是|无|包唯一key|package unique key| + |version|string|是|无|版本名称|version name| + +- 响应体 + [文件流] + +## 公共说明 + +### 包类型枚举 + +> 用于标识构件包类型 + +|枚举值|说明| +|---|---| +|DOCKER|Docker包| +|MAVEN|Maven包| +|PYPI|Pypi包| +|NPM|Npm包| +|HELM|Helm包| +|COMPOSER|Composer包| +|RPM|Rpm包| + +### package key 格式 + +> 因为同个仓库下包名称不唯一， 所以使用package key来确定包的唯一性。 +> pakcage key的格式为: `{type}://{value}` + +|type类型|value格式|例子| +|---|---|---| +|gav (maven采用此格式)|groupId:artifactId|gav://com.tencent.bkrepo:test| +|docker|name(包名称，docker中名称唯一)|docker://test| +|npm|name|npm://test| \ No newline at end of file diff --git a/docs/apidoc-user/repo/project.md b/docs/apidoc-user/repo/project.md new file mode 100644 index 0000000000..9c438f512e --- /dev/null +++ b/docs/apidoc-user/repo/project.md @@ -0,0 +1,92 @@ +# Project项目接口 + +[toc] + +## 创建项目 + +- API: POST /repository/api/project/create +- API 名称: create_project +- 功能说明： + - 中文：创建项目 + - English：create project +- 请求体 + + ```json + { + "name": "test", + "displayName": "test", + "description": "project description" + } + ``` + +- 请求字段说明 + + |字段|类型|是否必须|默认值|说明|Description| + |---|---|---|---|---|---| + |name|string|是|无|项目名称，要求以字母或者下划线开头，长度不超过32位|proejct name| + |displayName|string|是|无|显示名称，要求以字母或者下划线开头，长度不超过32位。此字段保留作用，和name设置为相同值即可|project display name| + |description|string|是|无|项目描述|project description| + +- 响应体 + + ```json + { + "code": 0, + "message": null, + "data": null, + "traceId": null + } + ``` + +## 查询项目列表 + +- API: GET /repository/api/project/list?pageNumber=1&pageSize=10&sortProperty=name&direction=DESC +- API 名称: get_project_list +- 功能说明： + - 中文：查询项目列表 + - English：get project list +- 请求体 + 此接口请求体为空 +- 请求字段说明 + + |字段|类型|是否必须|默认值|说明|Description| + |---|---|---|---|---|---| + |names|string|否|无|项目名称，多个以,隔开|project name| + |displayNames|string|否|无|显示名称，多个以,隔开|project display name| + |pageSize|int|否|无|分页数量|page size| + |pageNumber|int|否|无|当前页|page number| + |sortProperty|string|否|无|排序字段|sort property| + |direction|string|否|无|排序方向(ASC或DESC)|direction| + - 响应体 + + ``` json + { + "code":0, + "message":"", + "data":[ + { + "name":"project1", + "displayName":"project1", + "description":"project1", + "createdBy": "user", + "createdDate": "2019-12-20T10:32:51.89", + "lastModifiedBy": "user", + "lastModifiedDate": "2019-12-20T10:32:51.89" + } + ], + "traceId": null + } + ``` + +- data 字段说明 + + | 字段|类型| 说明 | Description | + |---|---|--------|-----------------------------------| + |name|string| 项目名 | the project name | + |displayName|string| 项目展示名称 | the display name of project | + |description|string| 项目描述 | the description of project | + |createdBy|string| 创建人 | the creator of project | + |createdDate|string| 创建时间 | the create date of project | + |lastModifiedBy|string| 最后修改人 | the last modified of project | + |lastModifiedDate|string| 最后修改时间 | the last modified date of project | + diff --git a/docs/apidoc-user/repo/proxy-channel.md b/docs/apidoc-user/repo/proxy-channel.md new file mode 100644 index 0000000000..1acf75fdc2 --- /dev/null +++ b/docs/apidoc-user/repo/proxy-channel.md @@ -0,0 +1,46 @@ +# ProxyChannel代理源接口 + +[toc] + +## 查询公有源列表 + +- API: GET /repository/api/proxy-channel/list/public/{repoType} +- API 名称: list_public_proxy_channel +- 功能说明： + - 中文：列表查询公有源 + - English：list puiblic proxy channel +- 请求体 + 此接口无请求体 +- 请求字段说明 + + |字段|类型|是否必须|默认值|说明|Description| + |---|---|---|---|---|---| + |repoType|string|是|无|仓库类型，枚举值|repo type| + +- 响应体 + + ```json + { + "code" : 0, + "message" : null, + "data" : [ { + "id" : "5f48b52fdf23460c0e2251e9", + "public" : true, + "name" : "maven-center", + "url" : "http://http://center.maven.com", + "repoType" : "MAVEN" + } ], + "traceId" : null + } + ``` + +- data字段说明 + + |字段|类型|说明|Description| + |---|---|---|---| + |id|string|代理源id|proxy channel id| + |public|boolean|是否为公有源|is public channel| + |name|string|代理源名称|repo name| + |url|string|代理源url|repo category| + |repoType|string|仓库类型|repo type| + diff --git a/docs/apidoc-user/repo/repository.md b/docs/apidoc-user/repo/repository.md new file mode 100644 index 0000000000..2aca7cf632 --- /dev/null +++ b/docs/apidoc-user/repo/repository.md @@ -0,0 +1,583 @@ +# Repository仓库接口 + +[toc] + +## 创建仓库 + +- API: POST /repository/api/repo/create +- API 名称: create_repo +- 功能说明： + - 中文：创建仓库 + - English：create repo +- 请求体 + + ```json + { + "projectId": "test", + "name": "generic-local", + "type": "GENERIC", + "category": "LOCAL", + "public": false, + "description": "repo description", + "configuration": null, + "storageCredentialsKey": null, + "quota": 1024 + } + ``` + +- 请求字段说明 + + |字段|类型|是否必须|默认值|说明|Description| + |---|---|---|---|---|---| + |projectId|string|是|无|项目名称|project name| + |name|string|是|无|仓库名称|repo name| + |type|string|是|无|仓库类型，枚举值|repo type| + |category|string|否|COMPOSITE|仓库类别，枚举值|repo category| + |public|boolean|否|false|是否公开|is public repo| + |description|string|否|无|仓库描述|repo description| + |configuration|object|否|无|仓库配置，参考后文|repo configuration| + |storageCredentialsKey|string|否|无|存储凭证key|storage credentials key| + |quota|long|否|无|仓库配额|repo quota| + +- 响应体 + + ```json + { + "code": 0, + "message": null, + "data": null, + "traceId": null + } + ``` + + +## 更新仓库信息 + +- API: POST /repository/api/repo/update/{projectId}/{repoName} +- API 名称: update_repo +- 功能说明： + - 中文：更新仓库信息 + - English：update repo +- 请求体 + ```json + { + "public": false, + "description": "repo description", + "configuration": null + } + ``` + + + - 增加依赖源仓库清理配置 + + ```json + { + "configuration":{ + "type":"xxx", + "settings": { + "cleanupStrategy":{ + "enable": true, + "cleanupType":"retentionDays", + "cleanupValue":"30", + "cleanTargets":["xxx","xxx"] + } + } + } + } + ``` + + - 增加Generic仓库清理配置 + + ```json + { + "configuration":{ + "type":"xxx", + "settings": { + "cleanupStrategy":{ + "enable": true, + "cleanupType":"retentionDays", + "cleanupValue":"30", + "cleanTargets":["xxx","xxx"] + } + } + } + } + ``` + +- 请求字段说明 + + |字段|类型|是否必须|默认值|说明|Description| + |---|---|---|---|---|---| + |projectId|string|是|无|项目名称|project name| + |repoName|string|是|无|仓库名称|repo name| + |public|boolean|否|无|是否公开。null则不修改|is public repo| + |description|string|否|无|仓库描述。null则不修改|repo description| + |configuration|RepositoryConfiguration|否|无|仓库配置，参考后文。null则不修改|repo configuration| + + +- **cleanupStrategy** + | 字段 | 类型 | 是否必须 | 默认值 | 说明 | Description | + | --------------- | ------- | ------------------ | ------ | ---------------- | ---------------------- | + | enable | boolean | 是 | false | 是否开启清理 | enable repo clean or not | + | cleanupType | String | 清理策略类型 | 无 | 清理策略类型： 包含retentionDays/retentionDate/retentionNums retentionDays： 保留天数，清理（当前日期-保留天数）之前的制品；retentionDate: 保留日期，清理保留日志之前的制品； retentionNums： 保留个数（只针对依赖源有效）， 每个package只保留多少个制品 | cleanup type | + | cleanupValue | String | 清理策略对应的实际值 | 无 | 清理策略对应的实际值，对应值例如: retentionDate： 2023-07-01T00:00:00.00； retentionNums：10； retentionDays：30 | cleanup type value | + | cleanTargets | List | 否 | 无 | 清理目标（generic仓库可以指定待清理目录，依赖源可以指定对应package，不指定则为整个仓库） | clean target | + + + + +- 响应体 + + ```json + { + "code": 0, + "message": null, + "data": null, + "traceId": null + } + ``` + + +## 查询仓库信息 + +- API: GET /repository/api/repo/info/{projectId}/{repoName}/{type} +- API 名称: get_repo_info +- 功能说明： + - 中文：查询仓库详情 + - English：get repo info +- 请求体 + 此接口无请求体 +- 请求字段说明 + + |字段|类型|是否必须|默认值|说明|Description| + |---|---|---|---|---|---| + |projectId|string|是|无|项目名称|project name| + |repoName|string|是|无|仓库名称|repo name| + |type|string|否|无|仓库类型|repo type| + +- 响应体 + + ```json + { + "code": 0, + "message": null, + "data": { + "projectId" : "test", + "name" : "local", + "type" : "GENERIC", + "category" : "LOCAL", + "public" : false, + "description" : "", + "configuration": {}, + "createdBy" : "system", + "createdDate" : "2020-03-16T12:13:03.371", + "lastModifiedBy" : "system", + "lastModifiedDate" : "2020-03-16T12:13:03.371", + "quota": 1024, + "used": 100 + }, + "traceId": null + } + ``` + +- data字段说明 + + |字段|类型|说明|Description| + |---|---|---|---| + |projectId|string|项目id|project id| + |name|string|仓库名称|repo name| + |type|string|仓库类型|repo type| + |category|string|仓库类别|repo category| + |public|boolean|是否公开项目|is public repo| + |description|string|仓库描述|repo description| + |configuration|[object]|仓库配置，参考仓库配置介绍|repo configuration| + |createdBy|string|创建者|create user| + |createdDate|string|创建时间|create time| + |lastModifiedBy|string|上次修改者|last modify user| + |lastModifiedDate|string|上次修改时间|last modify time| + |quota|long|仓库配额，单位字节，值为nul时表示未设置仓库配额|repo quota| + |used|long|仓库已使用容量，单位字节|repo used volume| + +## 校验仓库是否存在 + +- API: GET /repository/api/repo/exist/{projectId}/{repoName} +- API 名称: check_repo_exist +- 功能说明： + - 中文：校验仓库是否存在 + - English：check repo exist +- 请求体 + 此接口无请求体 +- 请求字段说明 + + |字段|类型|是否必须|默认值|说明|Description| + |---|---|---|---|---|---| + |projectId|string|是|无|项目名称|project name| + |repoName|string|是|无|仓库名称|repo name| + +- 响应体 + + ```json + { + "code": 0, + "message": null, + "data": true, + "traceId": null + } + ``` + +- data字段说明 + + |字段|类型|说明|Description| + |---|---|---|---| + |data|boolean|仓库是否存在|repo exist or not| + +## 分页查询仓库 + +- API: GET /repository/api/repo/page/{projectId}/{pageNumber}/{pageSize}?name=local&type=GENERIC +- API 名称: list_repo_page +- 功能说明： + - 中文：分页查询仓库 + - English：list repo page +- 请求体 + 此接口无请求体 +- 请求字段说明 + + |字段|类型|是否必须|默认值|说明|Description| + |---|---|---|---|---|---| + |projectId|string|是|无|项目名称|project name| + |pageNumber|int|是|无|当前页|page number| + |pageSize|int|是|无|分页数量|page size| + |name|string|否|无|仓库名称，支持前缀模糊匹配|repo name| + |type|string|否|无|仓库类型，枚举值|repo type| + +- 响应体 + + ```json + { + "code": 0, + "message": null, + "data": { + "pageNumber": 0, + "pageSize": 1, + "totalRecords": 18, + "totalPages": 2, + "records": [ + { + "projectId" : "test", + "name" : "local", + "type" : "GENERIC", + "category" : "LOCAL", + "public" : false, + "description" : "", + "createdBy" : "system", + "createdDate" : "2020-03-16T12:13:03.371", + "lastModifiedBy" : "system", + "lastModifiedDate" : "2020-03-16T12:13:03.371", + "quota": 1024, + "used": 100 + } + ] + }, + "traceId": null + } + ``` + +- data字段说明 + + |字段|类型|说明|Description| + |---|---|---|---| + |projectId|string|项目id|project id| + |name|string|仓库名称|repo name| + |type|string|仓库类型|repo type| + |category|string|仓库类别|repo category| + |public|boolean|是否公开项目|is public repo| + |description|string|仓库描述|repo description| + |createdBy|string|创建者|create user| + |createdDate|string|创建时间|create time| + |lastModifiedBy|string|上次修改者|last modify user| + |lastModifiedDate|string|上次修改时间|last modify time| + |quota|long|仓库配额，单位字节，值为nul时表示未设置仓库配额|repo quota| + |used|long|仓库已使用容量，单位字节|repo used volume| + +## 列表查询仓库 + +- API: GET /repository/api/repo/list/{projectId}?name=local&type=GENERIC +- API 名称: list_repo +- 功能说明： + - 中文：列表查询仓库 + - English：list repo +- 请求体 + 此接口无请求体 +- 请求字段说明 + + |字段|类型|是否必须|默认值|说明|Description| + |---|---|---|---|---|---| + |projectId|string|是|无|项目名称|project name| + |name|string|否|无|仓库名称，支持前缀模糊匹配|repo name| + |type|string|否|无|仓库类型，枚举值|repo type| + +- 响应体 + + ```json + { + "code": 0, + "message": null, + "data": [ + { + "projectId" : "test", + "name" : "local", + "type" : "GENERIC", + "category" : "LOCAL", + "public" : false, + "description" : "", + "createdBy" : "system", + "createdDate" : "2020-03-16T12:13:03.371", + "lastModifiedBy" : "system", + "lastModifiedDate" : "2020-03-16T12:13:03.371", + "quota": 1024, + "used": 100 + } + ], + "traceId": null + } + ``` + +- data字段说明 + + |字段|类型|说明|Description| + |---|---|---|---| + |projectId|string|项目id|project id| + |name|string|仓库名称|repo name| + |type|string|仓库类型|repo type| + |category|string|仓库类别|repo category| + |public|boolean|是否公开项目|is public repo| + |description|string|仓库描述|repo description| + |createdBy|string|创建者|create user| + |createdDate|string|创建时间|create time| + |lastModifiedBy|string|上次修改者|last modify user| + |lastModifiedDate|string|上次修改时间|last modify time| + |quota|long|仓库配额，单位字节，值为nul时表示未设置仓库配额|repo quota| + |used|long|仓库已使用容量，单位字节|repo used volume| + +## 查询仓库配额 + +- API： GET /repository/api/repo/quota/{projectId}/{repoName} + +- API 名称：get_repo_quota + +- 功能说明： + + - 中文：查询仓库配额 + - English：get repo quota + +- 请求体 + + - 此接口无请求体 + + - 请求字段说明 + + | 字段 | 类型 | 是否必须 | 默认值 | 说明 | Description | + | --------- | ------ | -------- | ------ | -------- | ------------ | + | projectId | string | 是 | 无 | 项目名称 | project name | + | repoName | string | 是 | 无 | 仓库名称 | repo name | + +- 响应体 + + ```json + { + "code": 0, + "message": null, + "data": { + "quota": 1024, + "used": 100 + }, + "traceId": "" + } + ``` + +- data字段说明 + + | 字段 | 类型 | 说明 | Description | + | ----- | ---- | ----------------------------------------------- | ---------------- | + | quota | long | 仓库配额，单位字节，值为nul时表示未设置仓库配额 | repo quota | + | used | long | 仓库已使用容量，单位字节 | repo used volume | + + +## 仓库公共枚举值说明 +### 仓库类型RepositoryType + +> 用于标识仓库功能类型 + +|枚举值|说明| +|---|---| +|GENERIC|通用二进制文件仓库| +|DOCKER|Docker仓库| +|MAVEN|Maven仓库| +|PYPI|Pypi仓库| +|NPM|Npm仓库| +|HELM|Helm仓库| +|COMPOSER|Composer仓库| +|RPM|Rpm仓库| + +### 仓库类别RepositoryCategory + +> 用于标识仓库类别 + +|枚举值|说明| +|---|---| +|LOCAL|本地仓库。普通仓库，上传/下载构件都在本地进行。| +|REMOTE|远程仓库。通过访问远程地址拉取构件，不支持上传| +|VIRTUAL|虚拟仓库。可以组合多个本地仓库和远程仓库拉取构件，不支持上传| +|COMPOSITE|组合仓库。具有LOCAL的功能，同时也支持代理多个远程地址进行下载| + +## RepositoryConfiguration仓库配置项 +### 公共配置项 + +每一类配置都具有下列公共配置项 + +|字段|类型|是否必须|默认值|说明|Description| +|---|---|---|---|---|---| +|type|string|是|无|不同类型仓库分别对应local、remote、virtual、composite(小写)，用于反序列化，创建和修改时需要提供该字段|configuration type| +|settings|map|否|无|不同类型仓库可以通过该字段进行差异化配置|repo settings| + +### local本地仓库配置项 + +|字段|类型|是否必须|默认值|说明|Description| +|:------|---|---|---|---|---| +|webHook|WebHook|否|无|WebHook相关配置|web hook| + +- **WebHook配置项** + +|字段|类型|是否必须|默认值|说明|Description| +|:----------|---|---|---|---|---| +|webHookList|[WebHookSetting]|否|无|WebHook 列表|web hook list| + +- **WebHookSetting配置项** + +|字段|类型|是否必须|默认值|说明|Description| +|:------|---|---|---|---|---| +|url|string|否|无|远程url地址|remote web hook url| +|headers|map|否|无|发起远程url的自定义headers|web hook headers| + +### remote远程仓库配置项 + +|字段|类型|是否必须|默认值|说明|Description| +|---|---|---|---|---|---| +|url|string|否|空|远程地址|remote repository url| +|credentials|RemoteCredentialsConfiguration|否|默认配置|访问凭证配置|remote credentials configuration| +|network|RemoteNetworkConfiguration|否|默认配置|网络配置|remote network configuration| +|cache|RemoteCacheConfiguration|否|默认配置|缓存配置|remote cache configuration| + +- **RemoteCredentialsConfiguration** + +|字段|类型|是否必须|默认值|说明|Description| +|---|---|---|---|---|---| +|username|string|否|无|远程仓库 用户名|remote repo username| +|password|string|否|无|远程仓库 密码|remote repo password| + +- **RemoteNetworkConfiguration** + +|字段|类型|是否必须|默认值|说明|Description| +|---|---|---|---|---|---| +|proxy|NetworkProxyConfiguration|否|无|网络代理配置|network proxy| +|connectTimeout|long|否|10 * 1000|网络连接超时时间(单位ms)|network connect timeout| +|readTimeout|long|否|10 * 1000|网络读取超时时间(单位ms)|network read timeout| + +- **NetworkProxyConfiguration** + +|字段|类型|是否必须|默认值|说明|Description| +|---|---|---|---|---|---| +|host|string|是|无|网络代理主机|proxy host| +|port|int|是|无|网络代理端口|proxy int| +|username|string|否|无|网络代理用户名|proxy username| +|password|string|否|无|网络代理密码|proxy password| + +- **RemoteCacheConfiguration** + +|字段|类型|是否必须|默认值|说明|Description| +|---|---|---|---|---|---| +|enabled|boolean|否|true|是否开启缓存|cache enabled| +|expiration|long|否|---1|构件缓存过期时间（单位分钟，0或负数表示永久缓存）|cache expiration| + +### virtual虚拟仓库配置项 + +|字段|类型|是否必须|默认值|说明|Description| +|---|---|---|---|---|---| +|repositoryList|[RepositoryIdentify]|否|无|仓库列表|repo list| + +- **RepositoryIdentify** + +|字段|类型|是否必须|默认值|说明|Description| +|---|---|---|---|---|---| +|projectId|string|是|无|代理项目名称|project id| +|name|string|是|无|代理仓库名称|repo name| + +### composite组合仓库配置项 + +|字段|类型|是否必须|默认值|说明|Description| +|---|---|---|---|---|---| +|proxy|ProxyConfiguration|否|无|仓库代理配置|repo proxy configuration| + +- **ProxyConfiguration** + +|字段|类型|是否必须|默认值|说明|Description| +|---|---|---|---|---|---| +|channelList|[ProxyChannelSetting]|否|无|代理源列表|proxy channel list| + +- **ProxyChannelSetting** + +|字段|类型|是否必须|默认值|说明|Description| +|---|---|---|---|---|---| +|public|boolean|是|无|是否为公有源|is public| +|name|string|否|无|代理源名称|proxy channel name| +|url|string|否|无|代理源地址|proxy channel url| +|credentialKey|string|否|无|鉴权凭据key|proxy credentials id| +|username|string|否|无|代理源认证用户名|channel username| +|password|string|否|无|代理源认证密码|channel password| + +### generic仓库下载限制配置项 +```json +"configuration" : { + "settings" : { + "interceptors" : [ { + "type" : "MOBILE", + "rules" : { + "filename" : "*.apk", + "metadata" : "key:value" + } + }, { + "type" : "WEB", + "rules" : { + "filename" : "*.txt", + "metadata" : "key:value" + } + }, { + "type" : "IP_SEGMENT", + "rules" : { + "ipSegment" : [ "10.0.0.0/24", "11.1.0.0/16" ], + "whitelistUser" : [ "userId" ], + "officeNetwork" : false + } + } ] + } + }, +``` +|字段|类型|是否必须|默认值|说明|Description| +|---|---|---|---|---|---| +|type|String|是|无|下载限制类型，MOBILE移动端下载限制，WEB网页端下载限制，IP_SEGMENT IP段下载限制|download interceptor type| +|rules|Map|是|无|下载限制规则，符合规则的可以下载|download interceptor rules| + +- **移动端下载限制** + - filename 文件名规则，支持通配符* + - metadata 元数据规则，格式为key:value +- **网页端下载限制** + - filename 文件名规则，支持通配符* + - metadata 元数据规则，格式为key:value +- **IP段下载限制** + - ipSegmnt Ip段规则，支持多个Ip段 + - officeNetwork 办公网下载规则，办公网网段由后台配置的，开启后ip段添加办公网网段 + - whitelistUser 白名单用户，不受Ip段下载限制约束 + +### 依赖源的差异化配置项 + +各个依赖源的差异化配置通过`settings`进行配置，每项配置的具体含义请参考依赖源文档。 \ No newline at end of file diff --git a/docs/apidoc-user/scanner/report.md b/docs/apidoc-user/scanner/report.md new file mode 100644 index 0000000000..beac89528b --- /dev/null +++ b/docs/apidoc-user/scanner/report.md @@ -0,0 +1,335 @@ +# 扫描报告接口 + +[toc] + +## 获取扫描报告预览 + +- API: POST /analyst/api/scan/reports/overview +- API 名称: get_report_overview +- 功能说明： + - 中文：预览扫描报告 + - English：scan report overview +- 请求体 + +```json +{ + "scanner": "default", + "credentialsKeyFiles": [ + { + "credentialsKey": null, + "sha256List":["af5d27f8921339531c5315c0928558f0de9ef1d27d07ff0f487602239cf885b5"] + } + ] +} +``` + +- 请求字段说明 + +| 字段 | 类型 | 是否必须 | 默认值 | 说明 | Description | +|------------------------------------|--------|------|-----|-------------------------|-----------------| +| scanner | string | 是 | 无 | 要获取的报告使用的扫描器名称 | scanner name | +| credentialsKeyFiles.credentialsKey | string | 否 | 无 | 被扫描文件所在存储,为null时表示在默认存储 | credentials key | +| credentialsKeyFiles.sha256List | array | 是 | 无 | 要查询报告的文件sha256列表 | sha256 list | + +- 响应体 + +```json +{ + "code": 0, + "message": null, + "data": [ + { + "status": "SUCCESS", + "sha256": "726683039c3af2005142c80af8ba823715ee07acbff17eb2662f08fb2b903d0f", + "scanDate": "2022-03-10T17:06:05.122", + "overview": { + "cveLowCount": 5, + "cveCriticalCount": 10, + "cveHighCount": 44, + "cveMediumCount": 35 + } + } + ], + "traceId": "" +} +``` +- data字段说明 + +| 字段 | 类型 | 说明 | Description | +|------------------|--------|-----------------------|-------------------------------------| +| status | string | 文件扫描状态 | file scan status | +| sha256 | string | 文件sha256 | file sha256 | +| scanDate | string | 文件扫描时间 | file scan datetime | +| overview | object | 文件扫描结果预览，不同扫描器预览结果不一样 | file scan result overview | +| cveLowCount | number | 低风险漏洞数 | low risk vulnerabilities count | +| cveMediumCount | number | 中风险漏洞数 | mid risk vulnerabilities count | +| cveHighCount | number | 高风险漏洞数 | high risk vulnerabilities count | +| cveCriticalCount | number | 严重风险漏洞数 | critical risk vulnerabilities count | + +## 获取扫描报告详情 + +- API: POST /analyst/api/scan/reports/detail/{projectId}/{repoName}/{fullPath} +- API 名称: get_report_detail +- 功能说明： + - 中文：获取扫描报告详情 + - English：scan report detail +- 请求体 + +```json +{ + "scanner": "default", + "arguments": { + "type": "standard", + "reportType": "SECURITY", + "pageLimit": { + "pageNumber": 1, + "pageSize": 10 + } + } +} +``` + +- 请求字段说明 + +| 字段 | 类型 | 是否必须 | 默认值 | 说明 | Description | +|-------------------------------|--------|------|-----|---------------------------------------|-----------------| +| projectId | string | 是 | 无 | 文件所属项目id | project id | +| repoName | string | 是 | 无 | 文件所属仓库名 | repository name | +| fullPath | string | 是 | 无 | 文件完整路径 | file path | +| scanner | string | 是 | 无 | 扫描器名 | scanner name | +| arguments.type | string | 是 | 无 | 参数类型，固定为standard | arg type | +| arguments.reportType | string | 是 | 无 | 扫描报告类型，目前支持SECURITY，LICENSE，SENSITIVE | report type | +| arguments.vulIds | array | 否 | 无 | 查询的漏洞列表 | cve id | +| arguments.vulnerabilityLevels | array | 否 | 无 | 筛选漏洞等级 | vul level | +| pageLimit.pageNumber | number | 否 | 1 | 分页页码 | page number | +| pageLimit.pageSize | number | 否 | 20 | 分页大小 | page size | + +- 响应体 + +```json +{ + "code": 0, + "message": null, + "data": { + "status": "SUCCESS", + "sha256": "dc435b35b5923eb05afe30a24f04e9a0a5372da8e76f986efe8508b96101c4ff", + "detail": { + "pageNumber": 1, + "pageSize": 1, + "totalRecords": 4, + "totalPages": 4, + "records": [ + { + "vulId": "pcmgr-333682", + "vulName": "Apache Log4j安全漏洞", + "cveId": "CVE-2021-45046", + "path": "/dc435b35b5923eb05afe30a24f04e9a0a5372da8e76f986efe8508b96101c4ff.jar", + "versionsPaths": [ + { + "version": "5.3.16", + "paths": [ + "/0903d17e58654a2c79f4e46df79dc73ccaa49b6edbc7c3278359db403b687f6e.jar" + ] + } + ], + "pkgName": "org.apache.logging.log4j:log4j-core", + "pkgVersions": ["2.9.1"], + "fixedVersion": "2.16.0", + "des": "ApacheLog4j是美国阿帕奇（Apache）基金会的一款基于Java的开源日志记录工具。Log4j2.16.0之前的版本(不包括2.3.1, 2.12.2)存在安全漏洞，该漏洞源于当日志配置使用非默认模式布局和上下文查找或线程上下文映射模式使用JNDI查找模式制作恶意输入数据，从而导致拒绝服务攻击。", + "solution": "目前厂商已发布升级补丁以修复漏洞，补丁获取链接：https://logging.apache.org/log4j/2.x/security.html。", + "references": [ + "http://www.openwall.com/lists/oss-security/2021/12/14/4", + "https://logging.apache.org/log4j/2.x/security.html", + "https://www.cve.org/CVERecord?id=CVE-2021-44228", + "https://www.intel.com/content/www/us/en/security-center/advisory/intel-sa-00646.html", + "https://tools.cisco.com/security/center/content/CiscoSecurityAdvisory/cisco-sa-apache-log4j-qRuKNEbd", + "http://www.openwall.com/lists/oss-security/2021/12/15/3", + "https://cert-portal.siemens.com/productcert/pdf/ssa-661247.pdf", + "https://www.kb.cert.org/vuls/id/930724", + "https://cert-portal.siemens.com/productcert/pdf/ssa-714170.pdf", + "https://www.debian.org/security/2021/dsa-5022" + ], + "cvss": 9.0, + "severity": "CRITICAL" + } + ], + "count": 4, + "page": 1 + } + }, + "traceId": null +} +``` + + data字段说明 + +| 字段 | 类型 | 说明 | Description | +|-----------------------|--------|--------------------------------------------------------|---------------------------| +| status | string | 文件扫描状态 | file scan status | +| sha256 | string | 文件sha256 | file sha256 | +| pageNumber | number | 页码 | page number | +| pageSize | number | 页大小 | page size | +| totalRecords | number | 总记录数量 | total records | +| totalPage | number | 总页数 | total page | +| vulId | string | 漏洞id | vul id | +| vulName | string | 漏洞名 | vul Name | +| cveId | string | 漏洞cve id | total page | +| path | string | 已废弃，使用versionsPaths替代，当被扫描的制品是压缩包时，表示存在漏洞的文件的在被扫描包中的路径 | path | +| versionsPaths.version | string | 版本 | version | +| versionsPaths.paths | array | 版本所在路径 | version path | +| pkgName | string | 存在漏洞的组件名 | package name | +| pkgVersions | array | 存在漏洞的组件版本 | package versions | +| fixedVersion | string | 修复版本 | fixed version | +| effectedVersion | string | 影响版本 | effected version | +| des | string | 漏洞描述 | vulnerability description | +| solution | string | 漏洞解决方案 | solution | +| references | array | 漏洞相关引用 | references | +| cvss | number | 漏洞cvss | cvss | +| severity | string | 漏洞评级,取值CRITICAL,HIGH,MEDIUM,LOW | severity | +| licenseName | string | 许可证名 | license name | + +## 获取子任务扫描报告详情 + +- API: GET /analyst/api/scan/reports/{subScanTaskId} +- API 名称: get_subtask_report_detail +- 功能说明： + - 中文：获取扫描子任务漏洞数据 + - English：scan subtask vul info +- 请求体 此接口请求体为空 + +- 请求字段说明 + +| 字段 | 类型 | 是否必须 | 默认值 | 说明 | Description | +|---------------|--------|------|-----|-------|-------------| +| subScanTaskId | string | 是 | 无 | 子任务id | subtask id | +| vulId | string | 否 | 无 | 漏洞id | cve id | +| leakType | string | 否 | 无 | 漏洞等级 | vul level | +| pageNumber | number | 否 | 1 | 分页页码 | page number | +| pageSize | number | 否 | 20 | 分页大小 | page size | + +- 响应体 + +```json +{ + "code": 0, + "message": null, + "data": { + "pageNumber": 1, + "pageSize": 20, + "totalRecords": 1, + "totalPages": 1, + "records": [ + { + "vulId": "CVE-2021-44228", + "severity": "CRITICAL", + "pkgName": "org.apache.logging.log4j:log4j-core", + "installedVersion": [ + "2.14.1" + ], + "title": "Apache log4j2 远程代码执行漏洞", + "vulnerabilityName": "Apache log4j2 远程代码执行漏洞", + "description": "ApacheLog4j是美国阿帕奇（Apache）基金会的一款基于Java的开源日志记录工具。ApacheLog4J存在输入验证错误漏洞.Log4j-2中存在JNDI注入漏洞，当程序将用户输入的数据进行日志记录时，即可触发此漏洞，成功利用此漏洞可以在目标服务器上执行任意代码。", + "officialSolution": "目前厂商已发布升级补丁以修复漏洞，补丁获取链接：https://logging.apache.org/log4j/2.x/security.html", + "reference": [ + "https://logging.apache.org/log4j/2.x/security.html", + "http://www.openwall.com/lists/oss-security/2021/12/10/1", + "http://www.openwall.com/lists/oss-security/2021/12/10/2", + "http://packetstormsecurity.com/files/165225/Apache-Log4j2-2.14.1-Remote-Code-Execution.html", + "https://security.netapp.com/advisory/ntap-20211210-0007/", + "https://tools.cisco.com/security/center/content/CiscoSecurityAdvisory/cisco-sa-apache-log4j-qRuKNEbd", + "http://www.openwall.com/lists/oss-security/2021/12/10/3", + "https://psirt.global.sonicwall.com/vuln-detail/SNWLID-2021-0032", + "https://www.oracle.com/security-alerts/alert-cve-2021-44228.html", + "https://lists.fedoraproject.org/archives/list/package-announce@lists.fedoraproject.org/message/VU57UJDCFIASIO35GC55JMKSRXJMCDFM/", + "http://www.openwall.com/lists/oss-security/2021/12/13/1", + "http://www.openwall.com/lists/oss-security/2021/12/13/2", + "https://twitter.com/kurtseifried/status/1469345530182455296", + "https://lists.debian.org/debian-lts-announce/2021/12/msg00007.html", + "https://www.debian.org/security/2021/dsa-5020", + "https://cert-portal.siemens.com/productcert/pdf/ssa-661247.pdf", + "http://packetstormsecurity.com/files/165270/Apache-Log4j2-2.14.1-Remote-Code-Execution.html", + "http://packetstormsecurity.com/files/165260/VMware-Security-Advisory-2021-0028.html", + "http://packetstormsecurity.com/files/165261/Apache-Log4j2-2.14.1-Information-Disclosure.html", + "http://www.openwall.com/lists/oss-security/2021/12/14/4", + "https://www.intel.com/content/www/us/en/security-center/advisory/intel-sa-00646.html", + "https://www.kb.cert.org/vuls/id/930724", + "http://packetstormsecurity.com/files/165282/Log4j-Payload-Generator.html", + "http://packetstormsecurity.com/files/165281/Log4j2-Log4Shell-Regexes.html", + "http://packetstormsecurity.com/files/165306/L4sh-Log4j-Remote-Code-Execution.html", + "http://packetstormsecurity.com/files/165307/Log4j-Remote-Code-Execution-Word-Bypassing.html", + "http://packetstormsecurity.com/files/165311/log4j-scan-Extensive-Scanner.html", + "http://www.openwall.com/lists/oss-security/2021/12/15/3", + "https://cert-portal.siemens.com/productcert/pdf/ssa-714170.pdf", + "https://msrc-blog.microsoft.com/2021/12/11/microsofts-response-to-cve-2021-44228-apache-log4j2/", + "https://tools.cisco.com/security/center/content/CiscoSecurityAdvisory/cisco-sa-apache-log4j-qRuKNEbd" + ], + "path": "/97eef8b72e121347074c8b3062b010170187a6fa7375555fd1ed68540adaea1f.jar" + } + ], + "page": 1, + "count": 4 + }, + "traceId": "" +} +``` + +data字段说明 + +| 字段 | 类型 | 说明 | Description | +|-------------------|--------|--------|-------------------| +| vulId | string | 漏洞id | vul id | +| severity | string | 漏洞等级 | vul severity | +| pkgName | string | 所属依赖 | dependency | +| installedVersion | array | 使用的版本 | installed version | +| title | string | 漏洞标题 | vul title | +| vulnerabilityName | string | 漏洞名 | vul name | +| description | string | 漏洞描述 | description | +| officialSolution | string | 官方解决方案 | official solution | +| reference | array | 关联引用 | reference | +| path | string | 漏洞文件路径 | vul path | + +响应体参考[分页接口响应格式](../common/common.md?id=统一分页接口响应格式) + +## 获取属于方案的子任务扫描报告详情 + +- API: GET /analyst/api/scan/artifact/leak/{projectId}/{subScanTaskId} +- API 名称: get_plan_subtask_report_detail +- 功能说明： + - 中文：获取属于方案的扫描子任务漏洞数据 + - English：scan plan subtask vul info +- 请求体 此接口请求体为空 + +- 请求字段说明 + +| 字段 | 类型 | 是否必须 | 默认值 | 说明 | Description | +|---------------|--------|------|-----|-------|-------------| +| projectId | string | 是 | 无 | 项目id | project id | +| subScanTaskId | string | 是 | 无 | 子任务id | project id | +| vulId | string | 否 | 无 | 漏洞id | cve id | +| leakType | string | 否 | 无 | 漏洞等级 | vul level | +| pageNumber | number | 否 | 1 | 分页页码 | page number | +| pageSize | number | 否 | 20 | 分页大小 | page size | + +- 响应体 + +响应体参考[获取子任务扫描报告详情](./report.md?id=获取子任务扫描报告详情) + +## 获取属于方案的子任务信息 + +- API: GET /analyst/api/scan/artifact/count/{projectId}/{subScanTaskId} +- API 名称: get_plan_subtask_report_detail +- 功能说明： + - 中文：获取属于方案的扫描子任务信息 + - English：get scan plan subtask +- 请求体 此接口请求体为空 + +- 请求字段说明 + +| 字段 | 类型 | 是否必须 | 默认值 | 说明 | Description | +|---------------|--------|------|-----|-------|-------------| +| projectId | string | 是 | 无 | 项目id | project id | +| subScanTaskId | string | 是 | 无 | 子任务id | project id | + +- 响应体 + +响应体参考[获取扫描子任务](./scan.md?id=获取扫描子任务) \ No newline at end of file diff --git a/docs/apidoc-user/scanner/scan-quality.md b/docs/apidoc-user/scanner/scan-quality.md new file mode 100644 index 0000000000..b276c49767 --- /dev/null +++ b/docs/apidoc-user/scanner/scan-quality.md @@ -0,0 +1,52 @@ +# 扫描方案质量规则接口 + +[toc] + +## 获取扫描方案质量规则 + +- API: GET /analyst/api/scan/quality/{planId} +- API 名称: get_scan_quality +- 功能说明： + - 中文：获取扫描方案质量规则 + - English：get scan quality +- 请求体 此接口请求体为空 + +- 请求字段说明 + +| 字段 | 类型 | 是否必须 | 默认值 | 说明 | Description | +|--------|--------|------|-----|------|-------------| +| planId | string | 是 | 无 | 方案id | plan id | + +- 响应体 + +```json +{ + "code": 0, + "message": null, + "data": { + "critical": 1, + "high": 2, + "medium": 3, + "low": 4, + "forbidScanUnFinished": false, + "forbidQualityUnPass": false, + "recommend": true, + "compliance": false, + "unknown": false + }, + "traceId": "" +} +``` +- data字段说明 + +| 字段 | 类型 | 说明 | Description | +|----------------------|---------|---------------|-------------------------------------| +| critical | number | 严重漏洞数 | critical risk vulnerabilities count | +| high | number | 高危漏洞数 | high risk license count | +| medium | number | 中危漏洞数 | mid risk license count | +| low | number | 低危漏洞数 | low risk license count | +| forbidScanUnFinished | boolean | 扫描未完成是否禁用制品 | whether forbid on scan unfinished | +| forbidQualityUnPass | boolean | 质量规则未通过是否禁用制品 | whether forbid on quality failed | +| recommend | boolean | 许可是否推荐使用 | whether recommend | +| compliance | boolean | 许可是否合规 | whether compliance | +| unknown | boolean | 许可是否未知 | whether compliance | diff --git a/docs/apidoc-user/scanner/scan.md b/docs/apidoc-user/scanner/scan.md new file mode 100644 index 0000000000..6878cf4174 --- /dev/null +++ b/docs/apidoc-user/scanner/scan.md @@ -0,0 +1,408 @@ +# 扫描接口 + +[toc] + +## 创建扫描任务 + +- API: POST /analyst/api/scan +- API 名称: scan +- 功能说明： + - 中文：发起扫描 + - English：scan +- 请求体 + +```json +{ + "planId": "629f415a2511164b6e454145", + "rule": { + "relation": "AND", + "rules": [ + { + "field": "projectId", + "value": "testProjectId", + "operation": "EQ" + }, + { + "field": "repoName", + "value": "maven-local", + "operation": "EQ" + }, + { + "field": "fullPath", + "value": "/", + "operation": "PREFIX" + } + ] + }, + "metadata": [ + { + "key": "buildNumber", + "value": "32" + } + ] +} +``` + +- 请求字段说明 + +| 字段 | 类型 | 是否必须 | 默认值 | 说明 | Description | +|----------|---------|------|-------|------------------------------------------------------------|--------------------| +| scanner | string | 否 | 无 | 要获取的报告使用的扫描器名称，扫描器名称在扫描器注册到制品库后确定，需要联系制品库管理员确认 | scanner name | +| planId | string | 否 | 无 | 使用的扫描方案id,与scanner至少一个字段存在值 | plan id | +| force | boolean | 否 | false | 是否强制扫描，为true时即使文件已扫描过也会再次执行扫描 | force scan | +| rule | object | 否 | 无 | 要扫描的文件匹配规则，参考[自定义搜索接口公共说明](../common/search.md?id=自定义搜索协议) | file match rule | +| metadata | array | 否 | 无 | 为扫描任务附加元数据，用于标识扫描任务 | scan task metadata | + +- 响应体 + +```json +{ + "code": 0, + "message": null, + "data": { + "name": "test", + "taskId": "62a1ae99573ec051504778ee", + "projectId": "testProjectId", + "createdBy": "admin", + "lastModifiedDateTime": "2022-06-09T16:26:01.437", + "triggerDateTime": "2022-06-09T16:26:01.437", + "startDateTime": null, + "finishedDateTime": null, + "triggerType": "MANUAL", + "status": "PENDING", + "scanPlan": { + "id": "629f415a2511164b6e454145", + "projectId": "testProjectId", + "name": "DEFAULT_GENERIC", + "type": "GENERIC", + "scanner": "default", + "description": "", + "scanOnNewArtifact": false, + "repoNames": [], + "rule": { + "rules": [ + { + "field": "projectId", + "value": "testProjectId", + "operation": "EQ" + } + ], + "relation": "AND" + }, + "scanQuality": {}, + "createdBy": "system", + "createdDate": "2022-06-07T20:15:22.886", + "lastModifiedBy": "system", + "lastModifiedDate": "2022-06-07T20:15:22.886" + }, + "rule": { + "rules": [ + { + "field": "projectId", + "value": "testProjectId", + "operation": "EQ" + }, + { + "field": "repoName", + "value": "maven-local", + "operation": "EQ" + }, + { + "field": "fullPath", + "value": "/jar/spring-core-5.3.15.jar", + "operation": "PREFIX" + } + ], + "relation": "AND" + }, + "total": 0, + "scanning": 0, + "failed": 0, + "scanned": 0, + "passed": 0, + "scanner": "default", + "scannerType": "standard", + "scannerVersion": "1::1", + "scanResultOverview": {}, + "force": true, + "metadata": [ + { + "key": "buildNumber", + "value": "32" + } + ] + }, + "traceId": "" +} +``` + +- data字段说明 + +| 字段 | 类型 | 说明 | Description | +|--------------------|---------|------------------------------------------------------------|------------------------| +| name | string | 任务名 | task name | +| taskId | string | 任务id | task id | +| projectId | string | 所属项目id | project id | +| createdBy | string | 任务创建者 | task creator | +| triggerDatetime | string | 触发任务的时间 | task trigger time | +| startDateTime | string | 任务开始执行时间 | task started time | +| finishedDateTime | string | 任务执行结束时间 | task finished time | +| triggerType | string | 触发类型,MANUAL,PIPELINE,ON_NEW_ARTIFACT | trigger type | +| status | string | 任务状态 | task status | +| scanPlan | object | 使用的扫描方案 | scan plan | +| rule | object | 要扫描的文件匹配规则，参考[自定义搜索接口公共说明](../common/search.md?id=自定义搜索协议) | file match rule | +| total | number | 总扫描文件数 | total scan file count | +| failed | number | 扫描失败文件数 | scan failed file count | +| scanned | number | 已扫描文件数 | scanned file count | +| passed | number | 通过质量规则的文件数 | passed file count | +| scanner | string | 使用的扫描器明 | scanner name | +| scannerType | string | 扫描器类型 | scanner type | +| scannerVersion | string | 扫描器版本 | scanner version | +| scanResultOverview | array | 扫描结果预览 | scan result overview | +| force | boolean | 是否为强制扫描 | force scan | +| metadata | array | 扫描任务元数据 | scan task metadata | + +扫描结果预览字段参考[获取扫描报告预览](./report.md?id=获取扫描报告预览) + + +## 停止扫描 + +- API: POST /analyst/api/scan/{projectId}/stop +- API 名称: stop_scan +- 功能说明： + - 中文：停止扫描 + - English：stop scan +- 请求体 此接口请求体为空 + +- 请求字段说明 + +| 字段 | 类型 | 是否必须 | 默认值 | 说明 | Description | +|-----------|--------|------|-----|----------------|----------------------| +| projectId | string | 是 | 无 | 项目id | project id | +| recordId | string | 是 | 无 | 属于扫描方案的扫描子任务id | plan scan subtask id | + +## 停止扫描任务 + +- API: POST /analyst/api/scan/{projectId}/tasks/{taskId}/stop +- API 名称: stop_scan_task +- 功能说明： + - 中文：停止扫描任务 + - English：stop scan task +- 请求体 此接口请求体为空 + +- 请求字段说明 + +| 字段 | 类型 | 是否必须 | 默认值 | 说明 | Description | +|-----------|--------|------|-----|------|--------------| +| projectId | string | 是 | 无 | 项目id | project id | +| taskId | string | 是 | 无 | 任务id | scan task id | + +- 响应体 + +```json +{ + "code": 0, + "message": null, + "data": true, + "traceId": "" +} +``` + + +## 获取扫描任务 + +- API: GET /analyst/api/scan/tasks/{taskId} +- API 名称: get_task +- 功能说明： + - 中文：获取扫描任务 + - English：get scan task +- 请求体 此接口请求体为空 + +- 请求字段说明 + +| 字段 | 类型 | 是否必须 | 默认值 | 说明 | Description | +|--------|--------|------|-----|------|-------------| +| taskId | string | 是 | 无 | 任务id | task id | + +- 响应体 + +```json +{ + "code": 0, + "message": null, + "data": {}, + "traceId": "" +} +``` + +- data字段说明 + +响应体参考[创建扫描任务](./scan.md?id=创建扫描任务)响应体 + +## 分页获取扫描任务 + +- API: GET /analyst/api/scan/tasks +- API 名称: get_tasks +- 功能说明： + - 中文：分页获取扫描任务 + - English：get scan tasks +- 请求体 此接口请求体为空 + +- 请求字段说明 + +| 字段 | 类型 | 是否必须 | 默认值 | 说明 | Description | +|-------------|--------|------|-----|----------------------------------------------------------------------|--------------| +| pageSize | number | 否 | 20 | 分页大小 | page size | +| pageNumber | number | 否 | 1 | 分页页码 | page number | +| projectId | string | 是 | 无 | 项目id | projectId | +| planId | string | 否 | 无 | 扫描方案id | plan id | +| triggerType | string | 否 | 无 | 触发方式MANUAL,PIPELINE,ON_NEW_ARTIFACT | trigger type | +| after | number | 否 | 无 | 在这个时间戳之后创建的任务 | after | +| before | number | 否 | 无 | 在这个时间戳之前创建的任务 | before | +| scanner | string | 否 | 无 | 扫描器名 | scanner | +| scannerType | string | 否 | 无 | 扫描器类型 | scanner type | +| status | string | 否 | 无 | 扫描状态,PENDING,SCANNING_SUBMITTING,SCANNING_SUBMITTED,STOPPED,FINISHED | scan status | + + +- 响应体 + +```json +{ + "code": 0, + "message": null, + "data": { + "pageNumber": 1, + "pageSize": 20, + "totalRecords": 1, + "totalPages": 1, + "records": [], + "count": 1, + "page": 1 + }, + "traceId": "" +} +``` +- data字段说明 + +响应体参考[分页接口响应格式](../common/common.md?id=统一分页接口响应格式) + +响应体参考[创建扫描任务](./scan.md?id=创建扫描任务)响应体 + +## 获取扫描子任务 + +- API: GET /analyst/api/scan/tasks/{taskId}/subtasks/{subtaskId} +- API 名称: get_subtask +- 功能说明： + - 中文：获取扫描子任务 + - English：get scan subtask +- 请求体 此接口请求体为空 + +- 请求字段说明 + +| 字段 | 类型 | 是否必须 | 默认值 | 说明 | Description | +|-----------|--------|------|-----|-------|-------------| +| taskId | string | 是 | 无 | 任务id | task id | +| subtaskId | string | 是 | 无 | 子任务id | subtask id | + +- 响应体 + +```json +{ + "code": 0, + "message": null, + "data": { + "subTaskId": "6295d720a987ad5a9f7b2766", + "name": "jackson-datatype-jsr310-2.13.0.jar", + "packageKey": null, + "version": null, + "fullPath": "/jar/jackson-datatype-jsr310-2.13.0.jar", + "repoType": "GENERIC", + "repoName": "custom", + "highestLeakLevel": null, + "critical": 0, + "high": 0, + "medium": 0, + "low": 0, + "total": 0, + "finishTime": "2022-05-31T16:51:44.747", + "qualityRedLine": true, + "scanQuality": {}, + "duration": 0 + }, + "traceId": "" +} +``` + +- data字段说明 + +| 字段 | 类型 | 说明 | Description | +|------------------|---------|------------|--------------------------| +| subTaskId | string | 子任务id | subtask id | +| name | string | 制品名 | artifact name | +| packageKey | string | packageKey | packageKey | +| version | string | 制品版本 | artifact version | +| fullPath | string | 制品路径 | artifact full path | +| repoType | string | 仓库类型 | repository type | +| repoName | string | 仓库名 | repository name | +| highestLeakLevel | string | 最高漏洞等级 | highest vul level | +| critical | number | 严重漏洞数 | critical level vul count | +| high | number | 高危漏洞数 | high level vul count | +| medium | number | 中危漏洞数 | medium level vul count | +| low | number | 低危漏洞数 | low level vul count | +| total | number | 漏洞总数 | total vul count | +| finishTime | string | 扫描完成时间 | scan finished time | +| qualityRedLine | boolean | 是否通过质量规则 | is pass quality red line | +| scanQuality | object | 扫描时方案的质量规则 | scan quality | +| duration | long | 扫描时长 | scan duration | + + +## 分页获取扫描子任务 + +- API: GET /analyst/api/scan/tasks/{taskId}/subtasks +- API 名称: get_subtasks +- 功能说明： + - 中文：分页获取扫描子任务 + - English：get scan subtasks +- 请求体 此接口请求体为空 + +- 请求字段说明 + +| 字段 | 类型 | 是否必须 | 默认值 | 说明 | Description | +|------------------|---------|------|-----|----------------|----------------------------| +| taskId | string | 是 | 无 | 任务id | task id | +| pageSize | number | 否 | 20 | 分页大小 | page size | +| pageNumber | number | 否 | 1 | 分页页码 | page number | +| projectId | string | 是 | 无 | 项目id | project id | +| id | string | 否 | 无 | 扫描方案id | scan plan id | +| name | string | 否 | 无 | 制品名关键字 | artifact name | +| highestLeakLevel | string | 否 | 无 | 制品最高等级漏洞 | highest vul level | +| repoType | string | 否 | 无 | 制品所属仓库类型 | repository type | +| repoName | string | 否 | 无 | 制品所属仓库名 | repository name | +| status | string | 否 | 无 | 制品扫描状态 | subtask status | +| startTime | string | 否 | 无 | 制品扫描任务创建时间(开始) | subtask create time after | +| endTime | string | 否 | 无 | 制品扫描任务创建时间(截止) | subtask create time before | +| qualityRedLine | boolean | 否 | 无 | 是否通过质量规则 | pass quality red line | + +- 响应体 + +```json +{ + "code": 0, + "message": null, + "data": { + "pageNumber": 1, + "pageSize": 20, + "totalRecords": 1, + "totalPages": 1, + "records": [], + "count": 1, + "page": 1 + }, + "traceId": "" +} +``` +- data字段说明 + +响应体参考[分页接口响应格式](../common/common.md?id=统一分页接口响应格式) + +响应体参考[获取扫描子任务](./scan.md?id=获取扫描子任务)响应体 diff --git a/docs/apidoc-user/scanner/scanner.md b/docs/apidoc-user/scanner/scanner.md new file mode 100644 index 0000000000..f07991b617 --- /dev/null +++ b/docs/apidoc-user/scanner/scanner.md @@ -0,0 +1,105 @@ +# 扫描器接口 + +[toc] + +## 查询扫描器 + +- API: GET /analyst/api/scanners/{scannerName} +- API 名称: get_scanner +- 功能说明： + - 中文：查询扫描器 + - English：get scanner +- 请求体 此接口请求体为空 +- 请求字段说明 + +| 字段 | 类型 | 是否必须 | 默认值 | 说明 | Description | +|-------------|--------|------|-----|------|--------------| +| scannerName | string | 否 | 无 | 扫描器名 | scanner name | + +- 响应体 + +```json +{ + "code": 0, + "message": null, + "data": { + "name": "arrowhead", + "image": "example.com/example/scanner:1.0", + "cmd": "scan", + "version": "1.0", + "args": [ + { + "type": "STRING", + "key": "knowledgeBaseEndpoint", + "value": "https://kb.exmaple.com/", + "des": "knowledge base endpoint" + } + ], + "type": "standard", + "description": "arrowhead scanner", + "rootPath": "/standard", + "cleanWorkDir": true, + "maxScanDurationPerMb": 6000, + "supportFileNameExt": ["tar", "apk", "ipa", "jar"], + "supportPackageTypes": ["DOCKER", "GENERIC", "MAVEN"], + "supportScanTypes": ["SECURITY", "LICENSE"] + }, + "traceId": "" +} + ``` + +- data字段说明 +详情参考[创建扫描器请求体](./scanner.md?id=创建扫描器) + + +## 获取扫描器列表 + +- API: GET /analyst/api/scanners +- API 名称: list_scanner +- 功能说明： + - 中文：获取扫描器列表 + - English：list scanner +- 请求体 此接口请求体为空 + +- 响应体 + +```json +{ + "code": 0, + "message": null, + "data": [ + { + "code": 0, + "message": null, + "data": { + "name": "arrowhead", + "image": "example.com/example/scanner:1.0", + "cmd": "scan", + "version": "1.0", + "args": [ + { + "type": "STRING", + "key": "knowledgeBaseEndpoint", + "value": "https://kb.exmaple.com/", + "des": "knowledge base endpoint" + } + ], + "type": "standard", + "description": "arrowhead scanner", + "rootPath": "/standard", + "cleanWorkDir": true, + "maxScanDurationPerMb": 6000, + "supportFileNameExt": ["tar", "apk", "ipa", "jar"], + "supportPackageTypes": ["DOCKER", "GENERIC", "MAVEN"], + "supportScanTypes": ["SECURITY", "LICENSE"] + }, + "traceId": "" + } + ], + "traceId": "" +} +``` + +- data字段说明 + +详情参考[创建扫描器请求体](./scanner.md?id=创建扫描器) diff --git a/docs/apidoc-user/webhook/payload.md b/docs/apidoc-user/webhook/payload.md new file mode 100644 index 0000000000..7c09cf3ef7 --- /dev/null +++ b/docs/apidoc-user/webhook/payload.md @@ -0,0 +1,659 @@ +# WebHook事件消息载荷 + +## 公共消息 + +### 公共消息载荷 + +每个WebHook事件消息载荷都包含以下字段： + +| 字段 | 类型 | 说明 | +| --------- | ------ | ---------------- | +| eventType | String | 触发事件类型 | +| user | Object | 触发事件用户信息 | + +### 公共请求头 + +| 名称 | 说明 | +| -------------- | --------------- | +| X-BKREPO-EVENT | 触发WebHook事件 | + +## 测试事件 + +WebHook服务提供测试事件，方便用户添加WebHook后测试连通性 + +### 消息载荷 + +| 字段 | 类型 | 说明 | +| --------- | ------ | ----------------- | +| eventType | String | 触发事件类型 | +| user | Object | 触发事件用户信息 | +| webHook | Object | 测试的WebHook信息 | + +示例 + +```json +{ + "user" : { + "userId" : "string", + "name" : "string", + "email" : null, + "phone" : null, + "createdDate" : "2021-07-05T11:19:31.921", + "locked" : false, + "admin" : false + }, + "webHook" : { + "id" : "string", + "url" : "http://localhost", + "triggers" : [ "NODE_CREATED", "NODE_DELETED" ], + "associationType" : "ARTIFACT_REPO", + "associationId" : "string", + "createdBy" : "string", + "createdDate" : "2021-09-13T17:45:33.878", + "lastModifiedBy" : "string", + "lastModifiedDate" : "2021-09-13T17:45:33.879" + }, + "eventType" : "WEBHOOK_TEST" +} +``` + +## 项目事件 + +### 创建项目 + +消息载荷 + +| 字段 | 类型 | 说明 | +| --------- | ------ | ---------------- | +| eventType | String | 触发事件类型 | +| user | Object | 触发事件用户信息 | +| project | Object | 创建的项目信息 | + +示例 + +```json +{ + "user" : { + "userId" : "string", + "name" : "string", + "email" : null, + "phone" : null, + "createdDate" : "2021-07-05T11:19:31.921", + "locked" : false, + "admin" : false + }, + "project" : { + "name" : "string", + "displayName" : "http://localhost", + "description" : "string", + "createdBy" : "test", + "createdDate" : "2021-09-13T17:45:33.878", + "lastModifiedBy" : "test", + "lastModifiedDate" : "2021-09-13T17:45:33.879" + }, + "eventType" : "PROJECT_CREATED" +} +``` + + + +## 仓库事件 + +### 创建仓库 + +消息载荷 + +| 字段 | 类型 | 说明 | +| ---------- | ------ | ---------------- | +| eventType | String | 触发事件类型 | +| user | Object | 触发事件用户信息 | +| repository | Object | 创建的仓库信息 | + +示例 + +```json +{ + "user" : { + "userId" : "string", + "name" : "string", + "email" : null, + "phone" : null, + "createdDate" : "2021-07-05T11:19:31.921", + "locked" : false, + "admin" : false + }, + "repository" : { + "projectId" : "project", + "name" : "repo", + "type" : "GENERIC", + "category" : "LOCAL", + "public" : false, + "description" : "string", + "configuration" : "{}", + "storageCredentialsKey" : "string", + "createdBy" : "test", + "createdDate" : "2021-09-13T17:45:33.878", + "lastModifiedBy" : "test", + "lastModifiedDate" : "2021-09-13T17:45:33.879" + }, + "eventType" : "REPO_CREATED" +} +``` + + + +### 更新仓库 + +消息载荷 + +| 字段 | 类型 | 说明 | +| ---------- | ------ | ---------------- | +| eventType | String | 触发事件类型 | +| user | Object | 触发事件用户信息 | +| repository | Object | 创建的仓库信息 | + +示例 + +```json +{ + "user" : { + "userId" : "string", + "name" : "string", + "email" : null, + "phone" : null, + "createdDate" : "2021-07-05T11:19:31.921", + "locked" : false, + "admin" : false + }, + "repository" : { + "projectId" : "project", + "name" : "repo", + "type" : "GENERIC", + "category" : "LOCAL", + "public" : false, + "description" : "string", + "configuration" : "{}", + "storageCredentialsKey" : "string", + "createdBy" : "test", + "createdDate" : "2021-09-13T17:45:33.878", + "lastModifiedBy" : "test", + "lastModifiedDate" : "2021-09-13T17:45:33.879" + }, + "eventType" : "REPO_UPDATED" +} +``` + + + +### 删除仓库 + +消息载荷 + +| 字段 | 类型 | 说明 | +| --------- | ------ | -------------------- | +| eventType | String | 触发事件类型 | +| user | Object | 触发事件用户信息 | +| projectId | String | 删除仓库的所属项目ID | +| repoName | String | 删除的仓库名称 | + +示例 + +```json +{ + "user" : { + "userId" : "string", + "name" : "string", + "email" : null, + "phone" : null, + "createdDate" : "2021-07-05T11:19:31.921", + "locked" : false, + "admin" : false + }, + "projectId" : "project", + "repoName" : "repo", + "eventType" : "REPO_DELETED" +} +``` + + + +## 节点事件 + +### 创建节点 + +消息载荷 + +| 字段 | 类型 | 说明 | +| --------- | ------ | ---------------- | +| eventType | String | 触发事件类型 | +| user | Object | 触发事件用户信息 | +| node | Object | 创建的节点信息 | + +示例 + +```json +{ + "user" : { + "userId" : "string", + "name" : "string", + "email" : null, + "phone" : null, + "createdDate" : "2021-07-05T11:19:31.921", + "locked" : false, + "admin" : false + }, + "node" : { + "createdBy" : "string", + "createdDate" : "2021-09-15T14:48:40.73", + "lastModifiedBy" : "string", + "lastModifiedDate" : "2021-09-15T14:48:40.73", + "folder" : false, + "path" : "/", + "name" : "test.txt", + "fullPath" : "/test.txt", + "size" : 32, + "sha256" : "28eb526a0b9e4a022cce7e9c6dffb11699c3c19a11b419d1b13873271a3c099e", + "md5" : "156c8805787b870939a80c708b64c946", + "nodeMetadata": [ + { + "key": "key", + "value": "value", + "system": false, + "description": null + } + ], + "projectId" : "project", + "repoName" : "repo" + }, + "eventType" : "NODE_CREATED" +} +``` + + +### 下载节点 + +消息载荷 + +| 字段 | 类型 | 说明 | +| --------- | ------ | ---------------- | +| eventType | String | 触发事件类型 | +| user | Object | 触发事件用户信息 | +| node | Object | 创建的节点信息 | + +示例 + +```json +{ + "user" : { + "userId" : "string", + "name" : "string", + "email" : null, + "phone" : null, + "createdDate" : "2021-07-05T11:19:31.921", + "locked" : false, + "admin" : false + }, + "node" : { + "createdBy" : "string", + "createdDate" : "2021-09-15T14:48:40.73", + "lastModifiedBy" : "string", + "lastModifiedDate" : "2021-09-15T14:48:40.73", + "folder" : false, + "path" : "/", + "name" : "test.txt", + "fullPath" : "/test.txt", + "size" : 32, + "sha256" : "28eb526a0b9e4a022cce7e9c6dffb11699c3c19a11b419d1b13873271a3c099e", + "md5" : "156c8805787b870939a80c708b64c946", + "nodeMetadata": [ + { + "key": "key", + "value": "value", + "system": false, + "description": null + } + ], + "projectId" : "project", + "repoName" : "repo" + }, + "eventType" : "NODE_DOWNLOADED" +} + +### 移动节点 + +消息载荷 + +| 字段 | 类型 | 说明 | +| ------------ | ------ | ---------------- | +| eventType | String | 触发事件类型 | +| user | Object | 触发事件用户信息 | +| node | Object | 移动后的节点信息 | +| srcProjectId | String | 源项目Id | +| srcRepoName | String | 源仓库名 | +| srcFullPath | String | 源节点完整路径 | + +示例 + +```json +{ + "user" : { + "userId" : "string", + "name" : "string", + "email" : null, + "phone" : null, + "createdDate" : "2021-07-05T11:19:31.921", + "locked" : false, + "admin" : false + }, + "node" : { + "createdBy" : "string", + "createdDate" : "2021-09-15T14:48:40.73", + "lastModifiedBy" : "string", + "lastModifiedDate" : "2021-09-15T14:48:40.73", + "folder" : false, + "path" : "/", + "name" : "test.txt", + "fullPath" : "/test.txt", + "size" : 32, + "sha256" : "28eb526a0b9e4a022cce7e9c6dffb11699c3c19a11b419d1b13873271a3c099e", + "md5" : "156c8805787b870939a80c708b64c946", + "nodeMetadata": [ + { + "key": "key", + "value": "value", + "system": false, + "description": null + } + ], + "projectId" : "project", + "repoName" : "repo" + }, + "srcProjectId": "project", + "srcRepoName": "repo", + "srcFullPath": "/test.txt", + "eventType" : "NODE_MOVED" +} +``` + +### 重命名节点 + +消息载荷 + +| 字段 | 类型 | 说明 | +| ----------- | ------ | ---------------------- | +| eventType | String | 触发事件类型 | +| user | Object | 触发事件用户信息 | +| node | Object | 重命名后的节点信息 | +| oldFullPath | String | 节点重命名前的完整路径 | + +示例 + +```json +{ + "user" : { + "userId" : "string", + "name" : "string", + "email" : null, + "phone" : null, + "createdDate" : "2021-07-05T11:19:31.921", + "locked" : false, + "admin" : false + }, + "node" : { + "createdBy" : "string", + "createdDate" : "2021-09-15T14:48:40.73", + "lastModifiedBy" : "string", + "lastModifiedDate" : "2021-09-15T14:48:40.73", + "folder" : false, + "path" : "/", + "name" : "test.txt", + "fullPath" : "/test.txt", + "size" : 32, + "sha256" : "28eb526a0b9e4a022cce7e9c6dffb11699c3c19a11b419d1b13873271a3c099e", + "md5" : "156c8805787b870939a80c708b64c946", + "nodeMetadata": [ + { + "key": "key", + "value": "value", + "system": false, + "description": null + } + ], + "projectId" : "project", + "repoName" : "repo" + }, + "oldFullPath": "/old.txt" + "eventType" : "NODE_RENAMED" +} +``` + +### 复制节点 + +消息载荷 + +| 字段 | 类型 | 说明 | +| ------------ | ------ | ---------------- | +| eventType | String | 触发事件类型 | +| user | Object | 触发事件用户信息 | +| node | Object | 复制后的节点信息 | +| srcProjectId | String | 源项目Id | +| srcRepoName | String | 源仓库名 | +| srcFullPath | String | 源节点完整路径 | + +示例 + +```json +{ + "user" : { + "userId" : "string", + "name" : "string", + "email" : null, + "phone" : null, + "createdDate" : "2021-07-05T11:19:31.921", + "locked" : false, + "admin" : false + }, + "node" : { + "createdBy" : "string", + "createdDate" : "2021-09-15T14:48:40.73", + "lastModifiedBy" : "string", + "lastModifiedDate" : "2021-09-15T14:48:40.73", + "folder" : false, + "path" : "/", + "name" : "test.txt", + "fullPath" : "/test.txt", + "size" : 32, + "sha256" : "28eb526a0b9e4a022cce7e9c6dffb11699c3c19a11b419d1b13873271a3c099e", + "md5" : "156c8805787b870939a80c708b64c946", + "nodeMetadata": [ + { + "key": "key", + "value": "value", + "system": false, + "description": null + } + ], + "projectId" : "project", + "repoName" : "repo" + }, + "srcProjectId": "project", + "srcRepoName": "repo", + "srcFullPath" + "eventType" : "NODE_COPIED" +} +``` + +### 删除节点 + +消息载荷 + +| 字段 | 类型 | 说明 | +| --------- | ------ | ---------------- | +| eventType | String | 触发事件类型 | +| user | Object | 触发事件用户信息 | +| node | Object | 删除的节点信息 | + +示例 + +```json +{ + "user" : { + "userId" : "string", + "name" : "string", + "email" : null, + "phone" : null, + "createdDate" : "2021-07-05T11:19:31.921", + "locked" : false, + "admin" : false + }, + "projectId" : "project", + "repoName" : "repo", + "fullPath" : "/test.txt", + "eventType" : "NODE_DELETED" +} +``` + +## 元数据事件 + +### 保存元数据 + +消息载荷 + +| 字段 | 类型 | 说明 | +| --------- | ------ | ---------------- | +| eventType | String | 触发事件类型 | +| user | Object | 触发事件用户信息 | +| node | Object | 节点信息 | +| metedata | Object | 保存的元数据 | + +示例 + +```json +{ + "user" : { + "userId" : "string", + "name" : "string", + "email" : null, + "phone" : null, + "createdDate" : "2021-07-05T11:19:31.921", + "locked" : false, + "admin" : false + }, + "node" : { + "createdBy" : "string", + "createdDate" : "2021-09-15T14:48:40.73", + "lastModifiedBy" : "string", + "lastModifiedDate" : "2021-09-15T14:48:40.73", + "folder" : false, + "path" : "/", + "name" : "test.txt", + "fullPath" : "/test.txt", + "size" : 32, + "sha256" : "28eb526a0b9e4a022cce7e9c6dffb11699c3c19a11b419d1b13873271a3c099e", + "md5" : "156c8805787b870939a80c708b64c946", + "metadata" : { }, + "projectId" : "project", + "repoName" : "repo" + }, + "metedata" : { "key" : "value" } + "eventType" : "METEDATA_SAVED" +} +``` + +### 删除元数据 + +消息载荷 + +| 字段 | 类型 | 说明 | +| ------------------- | ------ | ---------------- | +| eventType | String | 触发事件类型 | +| user | Object | 触发事件用户信息 | +| node | Object | 节点信息 | +| deletedMetedataKeys | Set | 删除的元数据Key | + +示例 + +```json +{ + "user" : { + "userId" : "string", + "name" : "string", + "email" : null, + "phone" : null, + "createdDate" : "2021-07-05T11:19:31.921", + "locked" : false, + "admin" : false + }, + "node" : { + "createdBy" : "string", + "createdDate" : "2021-09-15T14:48:40.73", + "lastModifiedBy" : "string", + "lastModifiedDate" : "2021-09-15T14:48:40.73", + "folder" : false, + "path" : "/", + "name" : "test.txt", + "fullPath" : "/test.txt", + "size" : 32, + "sha256" : "28eb526a0b9e4a022cce7e9c6dffb11699c3c19a11b419d1b13873271a3c099e", + "md5" : "156c8805787b870939a80c708b64c946", + "nodeMetadata": [ + { + "key": "key", + "value": "value", + "system": false, + "description": null + } + ], + "projectId" : "project", + "repoName" : "repo" + }, + "deletedMetedataKeys": ["key1","key2"] + "eventType" : "METEDATA_DELETED" +} +``` + +## 包版本事件 + +### 创建版本 + +消息载荷 + +| 字段 | 类型 | 说明 | +| -------------- | ------ | ---------------- | +| eventType | String | 触发事件类型 | +| user | Object | 触发事件用户信息 | +| packageVersion | Object | 包版本信息 | + +示例 + +```json +{ + "user" : { + "userId" : "string", + "name" : "string", + "email" : null, + "phone" : null, + "createdDate" : "2021-07-05T11:19:31.921", + "locked" : false, + "admin" : false + }, + "packageVersion" : { + "createdBy" : "string", + "createdDate" : "2021-09-15T14:48:40.73", + "lastModifiedBy" : "string", + "lastModifiedDate" : "2021-09-15T14:48:40.73", + "name" : false, + "size" : "/", + "downloads" : "test.txt", + "stageTag" : "/test.txt", + "metedata" : 32, + "tags" : "28eb526a0b9e4a022cce7e9c6dffb11699c3c19a11b419d1b13873271a3c099e", + "extension" : {"key": "value"}, + "contentPath" : "string" + }, + "eventType" : "VERSION_CREATED" +} +``` + + + diff --git a/docs/apidoc-user/webhook/webhook.md b/docs/apidoc-user/webhook/webhook.md new file mode 100644 index 0000000000..5e01efef77 --- /dev/null +++ b/docs/apidoc-user/webhook/webhook.md @@ -0,0 +1,339 @@ +## Webhook接口 + +### Webhook公共请求参数说明 + +#### 触发器类型 + +触发器类型参考 [公共事件类型](../common/event.md) + +除公共事件类型，WebHook服务还支持以下事件 +| 枚举值 | 说明 | +| ---------------- | ----------- | +| WEBHOOK_TEST | webhook测试 | + +#### 关联对象类型 + +| 枚举值 | 说明 | +| ------- | ---- | +| SYSTEM | 系统 | +| PROJECT | 项目 | +| REPO | 仓库 | + +#### 关联对象Id + +association_type为PROJECT时，association_id为{projectId} + +association_type为REPO时，association_id为{projectId}:{repoName} + +### 创建webhook + +- API: POST /webhook/api/webhook/create + +- API名称: create_webhook + +- 功能说明： + + - 中文：创建webhook + - English：create webhook + +- 请求体 + + ```json + { + "url": "string", + "headers": {"key": "value"}, + "triggers": ["NODE_CREATED"], + "resourceKeyPattern": "regex pattern", + "association_type": "REPO", + "association_id": "string" + } + ``` + + | 字段 | 是否必须 | 说明 | 示例 | + | ---------------- |----------| --------------- | ------------------------- | + | url | 是 | webhook请求地址 | http://bkrepo.example.com | + | headers | 否 | 自定义请求头 | {"key" : "value"} | + | triggers | 是 | 触发事件 | ["NODE_CREATED"] | + | resourceKeyPattern | 否 | 事件资源key正则匹配模型, 不填写则所有资源key都会触发 | (.*).apk | + | association_type | 是 | 关联对象类型 | REPO | + | association_id | 否 | 关联对象id | projectId:repoName | + + +- 响应体 + + ```json + { + "code": 0, + "message": null, + "data": null, + "traceId": null + } + ``` + +### 更新webhook + +- API: PUT /webhook/api/webhook/update + +- API名称: update_webhook + +- 功能说明： + + - 中文：更新webhook + - English：update webhook + +- 请求体 + + ```json + { + "id": "string", + "url": "string", + "token": "string", + "triggers": ["NODE_CREATED"] + } + ``` + +- 响应体 + + ```json + { + "code": 0, + "message": null, + "data": null, + "traceId": null + } + ``` + +### 删除webhook + +- API: DELETE /webhook/api/webhook/delete/{id} + +- API名称: delete_webhook + +- 功能说明： + + - 中文：删除webhook + - English：delete webhook + +- 请求参数 + + | 参数名 | 类型 | 说明 | + | ------ | ------ | ---------- | + | id | string | webhook id | + +- 响应体 + + ```json + { + "code": 0, + "message": null, + "data": null, + "traceId": null + } + ``` + +### 查询webhook + +- API: GET /webhook/api/webhook/{id} + +- API名称: get_webhook + +- 功能说明： + + - 中文：创建webhook + - English：create webhook + +- 请求参数 + + | 参数名 | 类型 | 说明 | + | ------ | ------ | ---------- | + | id | string | webhook id | + +- 响应体 + + ```json + { + "code": 0, + "message": null, + "data": { + "id": "string", + "url": "string", + "token": "string", + "triggers": ["NODE_CREATED"], + "associationType": "REPO", + "associationId": "string", + "createdBy": "string", + "createdDate": "string", + "lastModifiedBy": "string", + "lastModifiedDate": "string" + }, + "traceId": null + } + ``` + +### 查询webhook列表 + +- API: GET /webhook/api/webhook/list + +- API名称: list_webhook + +- 功能说明： + + - 中文：查询webhook列表 + - English：list webhook + +- 请求参数 + + | 参数名 | 类型 | 说明 | + | --------------- | --------------- | ------------ | + | associationId | string | 关联对象id | + | associationType | AssociationType | 关联对象类型 | + +- 响应体 + + ```json + { + "code": 0, + "message": null, + "data": [{ + "id": "string", + "url": "string", + "token": "string", + "triggers": ["NODE_CREATED"], + "associationType": "REPO", + "associationId": "string", + "createdBy": "string", + "createdDate": "string", + "lastModifiedBy": "string", + "lastModifiedDate": "string" + }], + "traceId": null + } + ``` + +### 测试webhook + +- API: GET /webhook/api/webhook/test/{id} + +- API名称: test_webhook + +- 功能说明： + + - 中文：测试webhook + - English：test webhook + +- 请求参数 + + | 参数名 | 类型 | 说明 | + | ------ | ------ | ---------- | + | id | string | webhook id | + +- 响应体 + + ```json + { + "code": 0, + "message": null, + "data": { + "id": "string", + "webHookUrl": "string", + "triggeredEvent": "NODE_CREATED", + "requestHeaders": { + "key": "value" + }, + "requestPayload": "string", + "status": "SUCCESS" / "FAIL", + "responseHeaders": { + "key": "value" + }, + "responseBody": "string", + "requestDuration": 100, + "requestTime": "2021-12-27T00:00:00.000", + "errorMsg": "string" + }, + "traceId": null + } + ``` + +### 重试webhook + +- API: GET /webhook/api/webhook/retry/{logId} + +- API名称: retry_webhook_request + +- 功能说明： + + - 中文：重试webhook请求 + - English：retry webhook request + +- 请求参数 + + | 参数名 | 类型 | 说明 | + | ------ | ------ | ---------------------- | + | logId | string | webhook request log id | + +- 响应体 + +```json +{ + "code": 0, + "message": null, + "data": { + "id": "string", + "webHookUrl": "string", + "triggeredEvent": "NODE_CREATED", + "requestHeaders": { + "key": "value" + }, + "requestPayload": "string", + "status": "SUCCESS", + "responseHeaders": { + "key": "value" + }, + "responseBody": "string", + "requestDuration": 100, + "requestTime": "2021-12-27T00:00:00.000", + "errorMsg": "string" + }, + "traceId": null +} +``` + +### 查询webhook请求日志列表 + +- API: GET /webhook/api/log/list/{webHookId} + +- API名称: list_webhook_log + +- 功能说明： + + - 中文：查询webhook请求日志列表 + - English：list webhook log + +- 请求参数 + + | 参数名 | 类型 | 说明 | + | --------- | ------ | ---------- | + | webHookId | string | webhook id | + +- 响应体 + + ```json + { + "code": 0, + "message": null, + "data": [{ + "webhookUrl": "string", + "triggeredEvent": "NODE_UPLOADED", + "requestHeaders": "string", + "requestPayload": "string", + "status": "SUCCESS", + "responseHeaders": "string", + "responseBody": "string", + "requestDuration": "string", + "requestTime": "string", + "errorMsg": "string" + }], + "traceId": null + } + ``` + diff --git a/docs/apidoc/auth/token.md b/docs/apidoc/auth/token.md index de40b62cd9..2879a3ea0d 100644 --- a/docs/apidoc/auth/token.md +++ b/docs/apidoc/auth/token.md @@ -61,7 +61,7 @@ ### 用户token列表 -- API:POST /auth/api/user/list/token/{uid} +- API:GET /auth/api/user/list/token/{uid} - API 名称: list_user_token - 功能说明： - 中文：新增用户token @@ -180,7 +180,7 @@ ### 校验用户token -- API:POST /auth/api/user/login?uid=owen&token=blueking +- API:POST /auth/api/user/token - API 名称: check_user_token - 功能说明： - 中文：校验用户token @@ -238,7 +238,7 @@ |字段|类型|是否必须|默认值|说明|Description| |---|---|---|---|---|---| -|uid|string|是|无|用户id|the user id| +|x-bkrepo-uid|header|是|无|用户id|the user id| |bkrepo_ticket|cookie|是|无|用户token|the user token| - output: diff --git a/docs/apidoc/auth/user.md b/docs/apidoc/auth/user.md index 88d87a0301..d61aedc57e 100644 --- a/docs/apidoc/auth/user.md +++ b/docs/apidoc/auth/user.md @@ -27,7 +27,7 @@ |字段|类型|是否必须|默认值|说明|Description| |---|---|---|---|---|---| |name|string|是|无|用户名|the name| -|pwd|string|是|无|用户密码|the user password| +|pwd|string|否|无|用户密码|the user password| |userId|string|是|无|用户id|the user id| |asstUsers|string array|否|[]|关联用户|association user| |group|boot |否|false|是否群组账号|is group user| @@ -293,7 +293,7 @@ ### 删除用户 -- API:DELETE /auth/api/user/{uid} +- API:DELETE /auth/api/user/delete/{uid} - API 名称: delete_user - 功能说明： - 中文：删除用户 diff --git a/docs/apidoc/node/node.md b/docs/apidoc/node/node.md index b664226050..fcff5a7c50 100644 --- a/docs/apidoc/node/node.md +++ b/docs/apidoc/node/node.md @@ -208,14 +208,17 @@ - 响应体 - ```json - { - "code": 0, - "message": null, - "data": null, - "traceId": null - } - ``` +```json +{ + "code": 0, + "message": null, + "data": {"deletedNumber": 0, + "deletedSize": 0, + "deletedTime": "yyyy-MM-dd'T'HH:mm:ss.SSSXXX" + }, + "traceId": null +} +``` ## 更新节点 diff --git a/docs/apidoc/node/share.md b/docs/apidoc/node/share.md index 22b326f134..9538bcf5b9 100644 --- a/docs/apidoc/node/share.md +++ b/docs/apidoc/node/share.md @@ -80,7 +80,7 @@ { "projectId": "", "repoName": "", - "fullPathList": "", + "fullPathList": [], "authorizedUserList": ["user1", "user2"], "authorizedIpList": ["192.168.1.1", "127.0.0.1"], "expireSeconds": 3600 @@ -93,7 +93,7 @@ |---|---|---|---|---|---| |projectId|string|是|无|项目名称|project name| |repoName|string|是|无|仓库名称|repo name| - |fullPathList|string|是|无|完整路径列表|full path list| + |fullPathList|list|是|无|完整路径列表|full path list| |authorizedUserList|[string]|否|无|授权用户列表，若为空所有用户可下载|share user list| |authorizedIpList|[string]|否|无|授权ip列表，若为空所有ip可下载|share ip list| |expireSeconds|long|否|0|下载链接有效时间，单位秒|expire seconds|