Skip to content

Commit

Permalink
perf: 提供步骤详情与步骤执行结果查询的APIGW接口 TencentBlueKing#2596
Browse files Browse the repository at this point in the history 
编写接口文档
  • Loading branch information
@jsonwan
jsonwan committed Dec 7, 2023
1 parent 6c1c388 commit 7157f11
Show file tree
Hide file tree
Showing 2 changed files with 286 additions and 0 deletions.
162 changes: 162 additions & 0 deletions docs/apidoc/bk-api-gateway/v3/zh/get_step_instance_detail.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,162 @@
### 功能描述

根据步骤实例 ID 查询步骤实例详情

### 请求参数说明

{{ bkapi_authorization_description }}

#### Header参数

| 字段 | 类型 | 必选 | 描述 |
|-----------|------------|--------|------------|
| X-Bkapi-Authorization | string | 是 | 认证信息。详情参考[调用网关 API](https://github.com/TencentBlueKing/BKDocs/blob/master/ZH/7.0/APIGateway/apigateway/use-api/use-apigw-api.md) |
| Accept | string | 是 | 固定值。application/json|
| Content-Type | string | 是 | 固定值。application/json|

#### Query参数

| 字段 | 类型 | 必选 | 描述 |
|------------------------|-----------|-------|------------|
| bk_scope_type | string | 是 | 资源范围类型。可选值: biz - 业务，biz_set - 业务集 |
| bk_scope_id | string | 是 | 资源范围ID, 与bk_scope_type对应, 表示业务ID或者业务集ID |
| step_instance_id | long | 是 | 步骤实例ID |


### 请求参数示例

- GET
```json
/api/v3/get_step_instance_detail?bk_scope_type=biz&bk_scope_id=1&step_instance_id=100
```

### 返回结果示例

```json
{
"result": true,
"code": 0,
"message": "",
"data": {
"id": 4,
"type": 1,
"name": "Step 1",
"script_step_info": {
"content": "IyEvYmluL2Jhc2gKCmFueW5vd3RpbWU9ImRhdGUgKyclWS0lbS0lZCAl",
"script_language": 1,
"script_param": "1 2 3",
"timeout": 1000,
"account_id": 123,
"account_name": "root",
"secure_param": 0
},
"file_step_info": {
"file_source_list": [
{
"file_type": 1,
"file_location": [
"/tmp/1.txt",
"/tmp/2.txt"
],
"file_hash": "68b329da9893e34099c7d8ad5cb9c940",
"file_size": 10240,
"account_id": 1,
"account_name": "root",
"file_source_id": 1,
"file_source_name": "测试用蓝鲸制品库"
}
],
"file_destination": {
"path": "/tmp",
"account_id": 1,
"account_name": "root"
},
"timeout": 1000,
"upload_speed_limit": 10,
"download_speed_limit": 10,
"transfer_mode": 2,
"ignore_error": 0
},
"approval_step_info": {
"approval_message": "Pass"
}
}
}
```
### 返回结果说明

| 字段 | 类型 | 描述 |
|-----------|-----------|-----------|
| result | bool | 请求成功与否。true:请求成功；false请求失败 |
| code | int | 错误编码。 0表示success，>0表示失败错误 |
| message | string | 请求失败返回的错误信息|
| data | object | 请求返回的数据|
| permission | object | 权限信息|

##### data

| 字段 | 类型 | 描述 |
|----------------------|-----------|-----------|
| id | long | 作业步骤ID |
| type | int | 步骤类型：1-脚本，2-文件，3-人工确认 |
| name | string | 步骤名称 |
| script_step_info | object | 脚本步骤信息 |
| file_step_info | object | 文件步骤信息 |
| approval_step_info | object | 审批步骤信息 |


##### script_step_info

| 字段 | 类型 | 描述 |
|--------------------|-----------|-----------|
| script_source | int | 脚本类型：1-本地脚本，2-引用业务脚本，3-引用公共脚本 |
| script_id | string | 脚本ID |
| script_version_id | long | 脚本版本ID |
| content | string | BASE64编码的脚本内容 |
| script_language | int | 脚本语言：1-shell，2-bat，3-perl，4-python，5-powershell，6-sql |
| script_param | string | 脚本参数 |
| timeout | int | 脚本超时时间，单位为秒 |
| account_id | long | 执行账号ID |
| account_name | string | 执行账号名称 |
| secure_param | int | 参数是否为敏感参数：0-不敏感，1-敏感 |


##### file_step_info

| 字段 | 类型 | 描述 |
|----------------------|-------------------|-----------|
| file_source_list | list<file_source> | 源文件列表，元素详情见file_source对象定义 |
| file_destination | object | 目标信息，详情见file_destination对象定义 |
| timeout | int | 超时，单位为秒 |
| upload_speed_limit | int | 上传文件限速，单位为MB/s，没有值表示不限速 |
| download_speed_limit | int | 下载文件限速，单位为MB/s，没有值表示不限速 |
| transfer_mode | int | 传输模式： 1-严谨模式，2-强制模式，3-安全模式 |
| ignore_error | int | 是否忽略错误：0-不忽略，1-忽略 |

##### file_source

| 字段 | 类型 | 描述 |
|-------------------|--------------|-----------|
| file_type | int | 文件类型：1-服务器文件，2-本地文件，3-文件源文件 |
| file_location | list<string> | 文件路径列表 |
| file_hash | string | 文件Hash值，仅本地文件该字段有值 |
| file_size | int | 文件大小，单位为字节，仅本地文件该字段有值 |
| account_id | long | 执行账号ID |
| account_name | string | 执行账号名称 |
| file_source_id | long | 第三方文件源ID |
| file_source_name | string | 第三方文件源名称 |

##### file_destination

| 字段 | 类型 | 描述 |
|-----------------|-----------|-----------|
| path | string | 目标路径 |
| account_id | long | 执行账号ID |
| account_name | string | 执行账号名称 |


##### approval_step_info

| 字段 | 类型 | 描述 |
|-------------------|-----------|-----------|
| approval_message | string | 确认消息 |
124 changes: 124 additions & 0 deletions docs/apidoc/bk-api-gateway/v3/zh/get_step_instance_status.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,124 @@
### 功能描述

根据步骤实例 ID 查询步骤执行状态

### 请求参数说明

{{ bkapi_authorization_description }}

#### Header参数

| 字段 | 类型 | 必选 | 描述 |
|-----------|------------|--------|------------|
| X-Bkapi-Authorization | string | 是 | 认证信息。详情参考[调用网关 API](https://github.com/TencentBlueKing/BKDocs/blob/master/ZH/7.0/APIGateway/apigateway/use-api/use-apigw-api.md) |
| Accept | string | 是 | 固定值。application/json|
| Content-Type | string | 是 | 固定值。application/json|

#### Query参数

| 字段 | 类型 | 必选 | 描述 |
|------------------------|-----------|-------|------------|
| bk_scope_type | string | 是 | 资源范围类型。可选值: biz - 业务，biz_set - 业务集 |
| bk_scope_id | string | 是 | 资源范围ID, 与bk_scope_type对应, 表示业务ID或者业务集ID |
| step_instance_id | long | 是 | 步骤实例ID |
| execute_count | int | 否 | 步骤重试次数，从0开始计数，默认值为0。 |
| batch | int | 否 | 滚动批次，从0开始计数，默认值为0。 |
| max_host_num_per_group | int | 否 | 每个分组（按照status与tag进行分组，分组键可参考返回值字段中的group_key字段）里的最大主机数量，不传则返回全量数据。 |
| keyword | string | 否 | 日志搜索关键字，只返回日志中包含该关键字的主机执行状态数据 |
| search_ip | string | 否 | 主机IP搜索关键字，只返回主机IP包含该关键字的主机执行状态数据 |
| status | int | 否 | 执行状态，对应返回值中的status字段。可能的取值：0-未知错误，1-Agent异常，2-无效主机，3-上次已成功，5-等待执行，7-正在执行，9-执行成功，11-执行失败，12-任务下发失败，13-任务超时，15-任务日志错误，16-GSE脚本日志超时，17-GSE文件日志超时，101-脚本执行失败，102-脚本执行超时，103-脚本执行被终止，104-脚本返回码非零，202-文件传输失败，203-源文件不存在，301-文件任务系统错误-未分类的，303-文件任务超时，310-Agent异常，311-用户名不存在，312-用户密码错误，320-文件获取失败，321-文件超出限制，329-文件传输错误，399-任务执行出错，403-任务强制终止成功，404-任务强制终止失败，500-未知状态|
| tag | string | 否 | 结果标签，对应返回值中的tag字段 |

### 请求参数示例

- GET
```json
/api/v3/get_step_instance_status?bk_scope_type=biz&bk_scope_id=1&step_instance_id=100&execute_count=0&batch=0&max_host_num_per_group=1&keyword=aaa&search_ip=&status=9&tag=
```

### 返回结果示例

```json
{
"result": true,
"code": 0,
"message": "",
"data": {
"status": 4,
"total_time": 1000,
"name": "API Quick execution scriptxxx",
"step_instance_id": 75,
"execute_count": 0,
"create_time": 1605064271000,
"end_time": 1605064272000,
"type": 1,
"start_time": 1605064271000,
"step_ip_result_list": [
{
"bk_host_id": 101,
"ip": "10.0.0.1",
"bk_cloud_id": 0,
"status": 9,
"tag": "tag1",
"group_key": "9_tag1",
"exit_code": 0,
"start_time": 1605064271000,
"end_time": 1605064272000,
"total_time": 1000
},
{
"bk_host_id": 102,
"ip": "10.0.0.2",
"bk_cloud_id": 0,
"status": 9,
"tag": "tag2",
"group_key": "9_tag2",
"exit_code": 0,
"start_time": 1605064271000,
"end_time": 1605064272000,
"total_time": 1000
}
]
}
}
```
### 返回结果说明

| 字段 | 类型 | 描述 |
|-----------|-----------|-----------|
| result | bool | 请求成功与否。true:请求成功；false请求失败 |
| code | int | 错误编码。 0表示success，>0表示失败错误 |
| message | string | 请求失败返回的错误信息|
| data | object | 请求返回的数据|
| permission | object | 权限信息|

##### data

| 字段 | 类型 | 描述 |
|-----------------------|--------------------------|-----------|
| status | int | 作业步骤状态码: 1-未执行，2-正在执行，3-执行成功，4-执行失败，5-跳过，6-忽略错误，7-等待用户，8-手动结束，9-状态异常，10-步骤强制终止中，11-步骤强制终止成功，12-步骤强制终止失败 |
| total_time | int | 总耗时，单位毫秒 |
| name | string | 步骤名称 |
| step_instance_id | long | 作业步骤实例ID |
| execute_count | int | 步骤重试次数 |
| create_time | long | 作业步骤实例创建时间，Unix时间戳，单位毫秒 |
| end_time | long | 执行结束时间，Unix时间戳，单位毫秒 |
| type | int | 步骤类型：1-脚本步骤；2-文件步骤；4-SQL步骤 |
| start_time | long | 开始执行时间，Unix时间戳，单位毫秒 |
| step_host_result_list | list<step_host_result> | 每个主机的任务执行结果，定义见step_host_result |


##### step_host_result

| 字段 | 类型 | 描述 |
|-------------|-----------|-----------|
| bk_host_id | long | 主机ID |
| ip | string | IP |
| bk_cloud_id | long | 管控区域ID |
| status | int | 任务状态：0-未知错误，1-Agent异常，2-无效主机，3-上次已成功，5-等待执行，7-正在执行，9-执行成功，11-执行失败，12-任务下发失败，13-任务超时，15-任务日志错误，16-GSE脚本日志超时，17-GSE文件日志超时，101-脚本执行失败，102-脚本执行超时，103-脚本执行被终止，104-脚本返回码非零，202-文件传输失败，203-源文件不存在，301-文件任务系统错误-未分类的，303-文件任务超时，310-Agent异常，311-用户名不存在，312-用户密码错误，320-文件获取失败，321-文件超出限制，329-文件传输错误，399-任务执行出错，403-任务强制终止成功，404-任务强制终止失败，500-未知状态 |
| tag | string | 用户通过job_success/job_fail函数模板自定义输出的结果。仅脚本任务存在该参数 |
| group_key | string | 基于status与tag字段的分组键，仅用于调用方验证分组内数据数量是否正确，请勿强依赖该字段 |
| exit_code | int | 脚本任务exit code |
| start_time | long | 开始执行时间，Unix时间戳，单位毫秒 |
| end_time | long | 执行结束时间，Unix时间戳，单位毫秒 |
| total_time | int | 总耗时，单位毫秒 |

0 comments on commit 7157f11

Please sign in to comment.