本文主要介绍如何使用 Open API 来操作 Zadig 的工作流（包括工作流和自定义工作流）。

工作流

获取工作流任务状态

注意事项

  • 目前仅支持 GitLab 的 commitId 查询
  • 支持完整的 commitId 或者输入 commitId 前 8 位查询

请求

GET /api/directory/workflowTask?commitId=<commitId>

Query

参数名类型描述默认值是否必须
commitIdstringcommitId无must

正常返回

[
    {
        "task_id": 49,
        "create_time": 1639466317,
        "start_time": 1639466318,
        "end_time": 1639466354,
        "status": "passed",
        "url": "http://my.zadig.com/v1/projects/detail/proxy/pipelines/multi/workflow-demo/49"
    }
]

返回说明

参数名类型描述
task_idint64任务 id
urlstring任务具体 url
statusstring任务状态
create_timeint64Unix 时间戳格式的任务创建时间
start_timeint64Unix 时间戳格式的任务开始时间
end_timeint64Unix 时间戳格式的任务结束时间

任务状态包括：created(创建中)/running(运行中)/passed(通过)/failed(失败)/timeout(超时)/cancelled(取消)

错误码对应列表


{
	"resultCode":401,"errorMsg":"auth failed!",
	"resultCode":400,"errorMsg":"param is illegal!"
}

工作流任务重试

注意事项

  • 需要有执行工作流的权限
  • 支持对状态是 failed(失败)/timeout(超时)/cancelled(取消) 的工作流任务进行重试

请求

POST /api/directory/workflowTask/id/:id/pipelines/:pipelineName/restart

路径参数说明

参数名类型描述默认值是否必须
idint任务 id无是
pipelineNamestring工作流名称无是

正常返回

{"message":"success"}

异常返回

{
  "code": 6164,
  "description": "获取工作流任务失败",
  "extra": {},
  "message": "重试工作流任务失败",
  "type": "error"
}

取消工作流任务

注意事项

  • 需要有执行工作流的权限；

请求

POST /api/directory/workflowTask/id/:id/pipelines/:pipelineName/cancel

路径参数说明

参数名类型描述默认值是否必须
idint任务 id无是
pipelineNamestring工作流名称无是

正常返回

{"message":"success"}

异常返回

{
  "code": 6163,
  "description": "mongo: no documents in result",
  "extra": {},
  "message": "取消工作流任务失败",
  "type": "error"
}

执行工作流

注意事项

  • 需要有执行工作流的权限；
  • 暂不支持更新环境变量；
  • 暂不支持高级选项，如工作流空间缓存和 Docker 缓存。

请求

POST /openapi/workflows/product/task

body 参数样例

{
  "workflow_name": "my-workflow",
  "project_name": "my-workflow",
  "input": {
    "target_env": "dev",
    "build": {
      "enabled": true,
      "service_list": [
        {
          "service_module": "svc1",
          "service_name": "my_service",
          "repo_info": [
            {
              "codehost_name": "my_codehost",
              "repo_namespace": "my_namespace",
              "repo_name": "my_repo",
              "branch": "main"
            }
          ],
          "inputs": [
            {
              "key": "mykey",
              "value": "myvalue"
            }
          ]
        }
      ]
    },
    "deploy": {
      "enabled": true,
      "source": "zadig",
      "service_list": [
        {
          "service_module": "li",
          "service_name": "li",
          "image": "xxxxx:aaaaaa"
        }
      ]
    }
  }
}

body 参数说明

参数名类型描述默认值是否必须
workflow_namestring工作流名称无must
project_namestring项目名称无must
inputWorkflowInput执行工作流参数无must
input 参数说明
参数名类型描述默认值是否必须
target_envstring目标环境名称无optional
buildBuildArgs构建参数无must
deployDeployArgs部署参数无must
BuildArgs 参数说明
参数名类型描述默认值是否必须
enabledbool是否启用构建无must
service_list[]BuildServiceInfo构建服务所需信息无optional
BuildServiceInfo 参数说明
参数名类型描述默认值是否必须
service_modulestring服务组件名称无must
service_namestring服务名称无must
repo_info[]RepositoryInfo代码仓信息无optional
inputs[]UserInput构建变量无optional
RepositoryInfo 参数说明
参数名类型描述默认值是否必须
codehost_namestring集成的代码仓名称无must
repo_namespacestring代码仓所属namespace（组织/个人）无must
repo_namestring代码仓名称无must
branchstring分支无must
printpr ID0使用 pr 构建时必传
UserInput 参数说明
参数名类型描述默认值是否必须
keystring自定义变量的键无must
valuestring自定义变量的值无must
DeployArgs 参数说明
参数名类型描述默认值是否必须
enabledbool是否启用构建无must
sourcestring部署镜像来源无如果使用zadig构建则固定为"zadig"
service_list[]DeployServiceInfo部署服务所需信息无optional
DeployServiceInfo 参数说明
参数名类型描述默认值是否必须
service_modulestring服务组件名称无must
service_namestring服务名称无must
imagestring镜像信息无使用zadig构建时不填，否则必填

正常返回

{
  "project_name": "test-project",
  "workflow_name": "test-project-workflow-dev",
  "task_id": 74
}

异常返回

{
  "code": 6540,
  "description": "workflow [hello-world-workflow-dev] 在项目 [hellow-world] 中已经存在!",
  "extra": {},
  "message": "新建或更新wokflow失败",
  "type": "error"
}

获取工作流任务详情

请求

GET /api/directory/workflowTask/id/:id/pipelines/:pipelineName

路径参数说明

参数名类型描述默认值是否必须
idint任务 id无是
pipelineNamestring工作流名称无是

正常返回

{
    "workflow_name": "test-project-workflow-dev",
    "env_name": "dev",
    "targets": [
        {
            "name": "gss-1",
            "service_type": "helm",
            "build": {
                "repos": [
                    {
                        "repo_name": "hzx-test",
                        "branch": "main",
                        "pr": 0
                    }
                ]
            }
        },
        {
            "name": "gss-2",
            "service_type": "helm",
            "build": {
                "repos": [
                    {
                        "repo_name": "hzx-test",
                        "branch": "main",
                        "pr": 0
                    }
                ]
            }
        }
    ],
    "images": [
        {                    
                "image": "ccr.ccs.tencentyun.com/trial/go-sample-site:20211221120415-1-main",
                "service_name": "gss-1",
                "registry_repo" : "https://ccr.ccs.tencentyun.com/trial"                    
        },
        {                    
                "image": "ccr.ccs.tencentyun.com/trial/go-sample-site:20211221120415-1-main",
                "service_name": "gss-2",
                "registry_repo" : "https://ccr.ccs.tencentyun.com/trial"                    
        }
    ],
    "test_reports": [
        {
            "test_name": "test",
            "function_test_report": {
                "tests": 24,
                "successes": 24,
                "failures": 0,
                "skips": 0,
                "errors": 0,
                "detail_url": "/v1/projects/detail/test-project/pipelines/multi/testcase/test-project-workflow-dev/51/test/test-project-workflow-dev-51-test?is_workflow=1&service_name=test&test_type=function"
            }
        }
   ],
    "status": "timeout"
}

返回说明

参数名类型描述
workflow_namestring工作流名称
env_namestring环境名称
statusstring任务状态
targets[]TargetArgs构建参数
images[]Image构建生成的镜像信息
test_reports[]TestReport测试报告信息
Image 参数说明
参数名类型描述
imagestring镜像地址
service_namestring服务名称
registry_repostring镜像仓库
TestReport 参数说明
参数名类型描述
test_namestring测试名称
function_test_reportFunctionTestReport测试报告概览
FunctionTestReport 参数说明
参数名类型描述
testsint测试用例数量
successesint成功数量
failuresint失败数量
skipsint跳过数量
errorsint错误数量
detail_urlstring测试报告详情 URL

异常返回

{
    "code": 500,
    "description": "[400 BadRequest] {\"code\":6161,\"description\":\"\",\"extra\":{},\"message\":\"获取工作流任务失败\",\"type\":\"error\"}",
    "message": "Internal Error: "
}

自定义工作流

获取自定义工作流任务详情

GET /openapi/workflows/custom/task

Query

参数名类型描述默认值是否必须
task_idint自定义工作流任务 id无是
workflow_namestring自定义工作流名称无是

正常返回

{
    "task_id": 24,                              # 自定义工作流任务序号 ID
    "workflow_name": "build-images",            # 自定义工作流名称
    "params": [                                 # 自定义工作流变量
        {
            "name": "USERNAME",
            "description": "",
            "type": "string",
            "value": "zadig",
            "default": "",
            "is_credential": false
        }
    ],
    "status": "running",                        # 自定义工作流任务状态
    "task_creator": "admin",                    # 自定义工作流任务触发者
    "create_time": 1664161285,                  # 工作流任务创建时间，Unix 时间戳格式
    "start_time": 1664161286,                   # 工作流任务开始执行时间，Unix 时间戳格式
    "end_time": 1664172997,                     # 工作流任务执行结束时间，Unix 时间戳格式
    "stages": [                                 # 工作流任务包含的所有阶段详情
        {
            "name": "构建",                      # 阶段名称
            "status": "passed",                 # 阶段状态
            "start_time": 1664161286,           # 阶段执行开始时间，Unix 时间戳格式
            "end_time": 1664172974,             # 阶段执行结束时间，Unix 时间戳格式
            "jobs": [                           # 阶段中包含的所有任务详情
                {
                    "name": "a-myapp-1-build-myapps",
                    "type": "zadig-build",      # 内置构建任务
                    "status": "passed",         # 任务状态
                    "start_time": 1664172967,   # 任务执行开始时间，Unix 时间戳格式
                    "end_time": 1664172974,     # 任务执行结束时间，Unix 时间戳格式
                    "spec": {                   # 构建任务执行详细信息（包括代码信息、镜像信息、服务信息、服务组件信息、构建变量信息）
                        "repos": [              # 代码信息
                            {
                                "source": "gitee",
                                "repo_owner": "kr-test-dev",
                                "repo_namespace": "kr-test-dev",
                                "repo_name": "zadig",
                                "remote_name": "origin",
                                "branch": "main",
                                "commit_id": "a13120997b95d8b63f2b5b29c700f89d38a5de54",
                                "commit_message": "update pkg/microservice/warpdrive/config/const.go.\n\nSigned-off-by: grandy <10196377+grandy@user.noreply.gitee.com>",
                                "address": "https://gitee.com",
                                "author_name": "grandy"
                            }
                        ],
                        "image": "koderover.tencentcloudcr.com/koderover-demo/myapp-1:20220926141606-26-main", # 镜像信息
                        "service_name": "a",            # 服务名称
                        "service_module": "myapp-1",    # 服务组件名称
                        "envs": [                       # 构建变量信息
                            {
                                "key": "username",
                                "value": "admin",
                                "type": "string",
                                "is_credential": false
                            },
                            {
                                "key": "password",
                                "value": "zadig",
                                "type": "string",
                                "is_credential": true
                            },
                            {
                                "key": "version",
                                "value": "1",
                                "type": "string",
                                "is_credential": false
                            }
                        ]
                    }
                }
            ]
        },
        {
            "name": "部署",
            "status": "passed",
            "start_time": 1664172974,
            "end_time": 1664172990,
            "approval": {                               # 审批信息
                "enabled": true,                        # 需要审批
                "approve_users": [                      # 审批人列表
                    {
                        "user_name": "admin",
                        "reject_or_approve": "approve",
                        "comment": "LGTM",
                        "operation_time": 1664172985
                    }
                ],
                "timeout": 120,                         # 审批超时时间，单位：分钟
                "needed_approvers": 1,                  # 需要满足的审批通过人数
                "description": "需审批通过方可部署",       # 审批描述
                "reject_or_approve": "approve"          # approve：通过；reject：拒绝
            },
            "jobs": [
                {
                    "name": "a-myapp-1-deploy-myapps",
                    "type": "zadig-deploy",             # 内置部署任务
                    "status": "passed",
                    "start_time": 1664172986,
                    "end_time": 1664172990,
                    "spec": {                           # 部署任务的详细信息
                        "env": "dev",
                        "skip_check_run_status": false, # 是否关闭服务状态检测
                        "service_and_images": [         # 部署的服务、服务组件、镜像信息
                            {
                                "service_name": "a",
                                "service_module": "myapp-1",
                                "image": "koderover.tencentcloudcr.com/koderover-demo/myapp-1:20220926141606-26-main"
                            }
                        ]
                    }
                }
            ]
        },
        {
            "name": "通用任务",
            "status": "passed",
            "start_time": 1664172990,
            "end_time": 1664172993,
            "jobs": [
                {
                    "name": "echo-hello",
                    "type": "freestyle",                # 通用任务
                    "status": "passed",
                    "start_time": 1664172990,
                    "end_time": 1664172993,
                    "spec": {                           # 通用任务执行详细信息
                        "repos": [
                            {
                                "source": "gitee",
                                "repo_owner": "kr-test-dev",
                                "repo_namespace": "kr-test-dev",
                                "repo_name": "demo-test",
                                "remote_name": "origin",
                                "branch": "master",
                                "commit_id": "2000aba9195bfce73b0a676e48c0ebfe2f59a4a9",
                                "commit_message": "update org-debug.txt.\n\nSigned-off-by: grandy <10196377+grandy@user.noreply.gitee.com>",
                                "address": "https://gitee.com",
                                "author_name": "grandy"
                            }
                        ],
                        "image": "",
                        "service_name": "",
                        "service_module": "",
                        "envs": [
                            {
                                "key": "myName",
                                "value": "zadig",
                                "type": "string",
                                "is_credential": false
                            }
                        ]
                    }
                }
            ]
        },
        {
            "name": "自定义任务",
            "status": "passed",
            "start_time": 1664172993,
            "end_time": 1664172997,
            "jobs": [
                {
                    "name": "say-hi",
                    "type": "plugin",                   # 自定义任务
                    "status": "passed",
                    "start_time": 1664172993,
                    "end_time": 1664172997,
                    "error": "",
                    "spec": {
                        "name": "输出 Hello 问候信息",
                        "is_offical": false,
                        "description": "问候指定用户",
                        "repo_url": "",
                        "version": "v0.0.1",
                        "image": "koderover.tencentcloudcr.com/koderover-public/greeting-bot:20220923-amd64",
                        "args": [],
                        "cmds": [],
                        "envs": [
                            {
                                "name": "WHO_AM_I",
                                "value": "Zadig"
                            },
                            {
                                "name": "WEATHER_STATUS",
                                "value": "sunny"
                            }
                        ],
                        "inputs": [
                            {
                                "name": "who_am_i",
                                "description": "who am i",
                                "type": "string",
                                "value": "Zadig",
                                "default": "Zadig",
                                "is_credential": false
                            },
                            {
                                "name": "weather_status",
                                "description": "what's the weather like today",
                                "type": "choice",
                                "value": "sunny",
                                "choice_option": [
                                    "sunny",
                                    "cloudy",
                                    "rainy"
                                ],
                                "default": "sunny",
                                "is_credential": false
                            }
                        ],
                        "outputs": []
                    }
                }
            ]
        }
    ],
    "project_name": "simple-service-demo",              # 项目名称
}

异常返回

# 指定的工作流任务不存在
{
    "code": 500,
    "description": "mongo: no documents in result",
    "message": "Internal Error: "
}

执行自定义工作流

注意事项

  1. 暂不支持通过 OpenAPI 触发自定义任务
  2. 暂不支持通过 OpenAPI 指定工作流全局变量

请求

POST /openapi/workflows/custom/task

body 参数样例

{
    "project_name": "helm",
    "workflow_name": "test-openapi",
    "inputs": [
        {
            "job_name": "build-myapps",
            "job_type": "zadig-build",
            "parameters": {
                "registry": "https://koderover.******.com/test",
                "service_list": [
                    {                                 
                        "service_module": "aslan",
                        "service_name": "zadig",
                        "repo_info": [{
                            "codehost_name": "koderover",
                            "repo_namespace": "koderover",
                            "repo_name": "zadig",
                            "branch": "main"
                        }]
                        inputs: [{
                            "key": "username",
                            "value": "admin"
                        },
                        {
                            "key": "password",
                            "value": "zadig"
                        }]
                    }
                ]
            }
        },
        {
            "job_name": "deploy-myapps",
            "job_type": "zadig-deploy",
            "parameters": {
                "env_name": "dev",
                "service_list": [
                {
                    "service_name": "zadig",
                    "service_module": "aslan",
                    "image_name": "koderover.******.com/test/aslan:main"
                },
                {
                    "service_name": "zadig",
                    "service_module": "zadig-portal",
                    "image_name": "koderover.******.com/test/zadig-portal:main"
                }
            ]
        }
        {
            "job_name": "jira-issue-update",
            "job_type": "freestyle",
            "parameters": {
                "kv": [
                    {
                        "key": "IssueID",
                        "value": "ZAD-10126"
                    },
                    {
                        "key": "FromStatus",
                        "value": "Testing"
                    },
                    {
                        "key": "TargetStatus",
                        "value": "ToBeReleased"
                    }
                ]
            }
        },
        {
            "job_name": "deploy-my-app",
            "job_type": "custom-deploy",
            "parameters": {
                "target_list": [
                    {
                        "workload_type": "Deployment",
                        "workload_name": "service2",
                        "container_name": "service2",
                        "image_name": "koderover.***.com/test/service2:0505"
                    }
                ]
            }
        }
    ]
}

body 参数说明

参数名类型描述默认值是否必须
project_namestring项目名称无must
workflow_namestring自定义工作流名称无must
inputs[]Input执行工作流的具体参数无must

Input 参数说明

下面将分开介绍内置构建任务、部署任务、Kubernetes 部署任务、通用任务的触发参数。

构建任务

{
    "job_name": "build-myapps",                           # 构建任务名称
    "job_type": "zadig-build",                            # 构建任务类型，指定为 zadig-build
    "parameters": {
        "registry": "https://koderover.******.com/test",  # 镜像仓库信息
        "service_list": [                                 # 要构建的服务信息
            {                                 
                "service_module": "aslan",                # 服务组件名称
                "service_name": "zadig",                  # 服务名称
                "repo_info": [{                           # 构建该服务组件的代码库信息
                    "codehost_name": "koderover",         # 代码库标识
                    "repo_namespace": "koderover",        # 代码库组织名/用户名
                    "repo_name": "zadig",                 # 代码库名称
                    "branch": "main"                      # 代码库分支
                }]
                inputs: [{                                # 构建变量信息，若设置为固定值或全局变量，则无需指定
                    "key": "username",
                    "value": "admin"
                },
                {
                    "key": "password",
                    "value": "zadig"
                }]
            },
            {
                "service_module": "zadig-portal",
                "service_name": "zadig",
                "repo_info": [{
                    "codehost_name": "koderover",
                    "repo_namespace": "koderover",
                    "repo_name": "zadig-portal",
                    "branch": "main"
                }]
            }
        ]
    }
}

部署任务

{
    "job_name": "deploy-myapps",                              # 部署任务名称
    "job_type": "zadig-deploy",                               # 部署任务类型，指定为 zadig-deploy
    "parameters": {                                           # 部署参数
        "env_name": "dev",                                    # 待部署环境信息，若设置为固定值或全局变量，则无需配置该字段
        "service_list": [                                     # 待部署服务信息，若设置为其他任务输出，则无需配置该字段
        {
            "service_name": "zadig",                          # 待部署服务名称
            "service_module": "aslan",                        # 待部署服务组件名称
            "image_name": "koderover.***.com/test/aslan:main" # 待部署服务组件的镜像
        },
        {
            "service_name": "zadig",
            "service_module": "zadig-portal",
            "image_name": "koderover.***.com/test/zadig-portal:main"
        }
    ]
}

Kubernetes 部署任务

{
    "job_name": "deploy-my-app",                                     # Kubernetes 部署任务名称
    "job_type": "custom-deploy",                                     # Kubernetes 部署任务类型，指定为 custom-deploy
    "parameters": {
        "target_list": [                                             # 待部署容器信息，若设置为固定值，则无需指定
            {
                "workload_type": "Deployment",                       # 待部署容器应用的类型，支持 Deployment 以及 StatefulSet
                "workload_name": "service2",                         # 待部署容器应用的名称
                "container_name": "service2",                        # 待部署容器应用的 container 名称
                "image_name": "koderover.***.com/test/service2:0505" # 待部署容器的镜像信息
            }
        ]
    }
}

通用任务

{
    "job_name": "jira-issue-update",            # 通用任务名称
    "job_type": "freestyle",                    # 通用任务类型，指定为 freestyle
    "parameters": {                             # 通用任务中的参数和值，若设置为固定值或全局变量，则无需指定
        "kv": [
            {
                "key": "IssueID",
                "value": "ZAD-10126"
            },
            {
                "key": "FromStatus",
                "value": "Testing"
            },
            {
                "key": "TargetStatus",
                "value": "ToBeReleased"
            }
        ],
        "repo_info": [                          # 通用任务中的代码库信息
            {
                "codehost_name": "koderover",   # 代码库标识
                "repo_namespace": "koderover",  # 代码库组织名/用户名
                "repo_name": "zadig",           # 代码库名称
                "branch": "task-mgr"            # 代码库分支
            }
        ]
    }
}

测试任务

{
    "job_name": "test-myapps",                            # 测试任务名称
    "job_type": "zadig-test",                             # 构建任务类型，指定为 zadig-test
    "parameters": {
        "testing_list": [                                 # 要测试的任务信息
            {                                 
                "testing_name": "unit-test",              # 测试任务名称
                "repo_info": [{                           # 测试任务的代码库信息
                    "codehost_name": "koderover",         # 代码库标识
                    "repo_namespace": "koderover",        # 代码库组织名/用户名
                    "repo_name": "zadig",                 # 代码库名称
                    "branch": "main"                      # 代码库分支
                }]
                inputs: [{                                # 测试变量信息，若设置为固定值或全局变量，则无需指定
                    "key": "username",
                    "value": "admin"
                },
                {
                    "key": "password",
                    "value": "zadig"
                }]
            },
            {
                "testing_name": "integration-test",
                "repo_info": [{
                    "codehost_name": "koderover",
                    "repo_namespace": "koderover",
                    "repo_name": "zadig-portal",
                    "branch": "main"
                }]
            }
        ]
    }
}

代码扫描任务

{
    "job_name": "scan-myapps",                            # 代码扫描任务名称
    "job_type": "zadig-scanning",                         # 构建任务类型，指定为 zadig-scanning
    "parameters": {
        "scanning_list": [                                # 代码扫描的任务信息
            {                                 
                "scanning_name": "scan",                  # 代码扫描任务名称
                "repo_info": [{                           # 代码扫描任务的代码库信息
                    "codehost_name": "koderover",         # 代码库标识
                    "repo_namespace": "koderover",        # 代码库组织名/用户名
                    "repo_name": "zadig",                 # 代码库名称
                    "branch": "main"                      # 代码库分支
                }]
            },
            {
                "scanning_name": "scan-1",
                "repo_info": [{
                    "codehost_name": "koderover",
                    "repo_namespace": "koderover",
                    "repo_name": "zadig-portal",
                    "branch": "main"
                }]
            }
        ]
    }
}

正常返回

{
    "project_name": "simple-service-demo", # 项目名称
    "workflow_name": "openapi-test",       # 自定义工作流名称
    "task_id": 20                          # 自定义工作流任务执行的序号 ID
}

取消自定义工作流任务

请求

DELETE /openapi/workflows/custom/task

Query

参数名类型描述默认值是否必须
task_idint自定义工作流任务 ID无must
workflow_namestring自定义工作流名称无must

正常返回

{
    "message": "success"
}

异常返回

# 指定的工作流任务已成功运行完毕
{
    "code": 6163,
    "description": "task: build-images:20 is passed, cannot cancel",
    "extra": {},
    "message": "取消工作流任务失败",
    "type": "error"
}

# 指定的工作流或者任务不存在
{
    "code": 6163,
    "description": "mongo: no documents in result",
    "extra": {},
    "message": "取消工作流任务失败",
    "type": "error"
}

自定义工作流人工审批

请求

POST /openapi/workflows/custom/task/approve

Query

参数名类型描述默认值是否必须
task_idint自定义工作流任务 ID无must
workflow_namestring自定义工作流名称无must
stage_namestring自定义工作流待审批的阶段名称无must
approvebool是否审批通过falseoption
commentstring审批信息无option

正常返回

{
    "message": "success"
}

异常返回

# 指定参数的阶段不需要审批
{
    "code": 6169,
    "description": "workflow build-images ID 23 stage deploy-myapps do not need approve",
    "extra": {},
    "message": "批准工作流任务失败",
    "type": "error"
}