1. 接口描述
本接口(SubmitJob)用于提交一个作业
接口请求域名:batch.api.qcloud.com
2. 输入参数
名称 | 类型 | 是否必选 | 描述 |
---|---|---|---|
Version | String | 是 | API版本 |
Job | Job object | 是 | 作业信息 |
Placement | Placement object | 是 | 作业所提交的位置信息。通过该参数可以指定作业所属可用区等信息。 |
ClientToken | String | 否 | 用于保证请求幂等性的字符串。该字符串由用户生成,需保证不同请求之间唯一,最大值不超过64个ASCII字符。若不指定该参数,则无法保证请求的幂等性。 |
数据类型
Job
名称 | 类型 | 是否必选 | 描述 |
---|---|---|---|
JobName | String | 是 | 作业名称 |
JobDescription | String | 否 | 作业描述 |
Priority | Integer | 是 | 作业优先级,任务(Task)和任务实例(TaskInstance)会继承作业优先级 |
Tasks.N | array of Task objects | 是 | 任务信息 |
Dependences.N | array of Dependence objects | 否 | 依赖信息 |
Notifications | array of Notification objects | 否 | 通知信息 |
TaskExecutionDependOn | String | 否 | 对于存在依赖关系的任务中,后序任务执行对于前序任务的依赖条件。取值范围包括 PRE_TASK_SUCCEED,PRE_TASK_AT_LEAST_PARTLY_SUCCEED,PRE_TASK_FINISHED,默认值为PRE_TASK_SUCCEED。 |
StateIfCreateCvmFailed | String | 否 | 表示创建 CVM 失败按照何种策略处理。取值范围包括 FAILED,RUNNABLE。FAILED 表示创建 CVM 失败按照一次执行失败处理,RUNNABLE 表示创建 CVM 失败按照继续等待处理。默认值为FAILED。StateIfCreateCvmFailed对于提交的指定计算环境的作业无效。 |
Placement
名称 | 类型 | 是否必选 | 描述 |
---|---|---|---|
Zone | String | 是 | 作业创建的 CVM 实例所属的可用区ID |
ProjectId | Integer | 否 | 作业创建的 CVM 实例所属项目ID。该参数可以通过调用 DescribeProject 的返回值中的 projectId 字段来获取。不填为默认项目。 |
Task
名称 | 类型 | 是否必选 | 描述 |
---|---|---|---|
TaskName | String | 是 | 任务名称,在一个作业内部唯一 |
TaskInstanceNum | Integer | 是 | 任务实例运行个数 |
Application | Application object | 是 | 应用程序信息 |
ComputeEnv | ComputeEnv object | 否 | 运行环境信息,ComputeEnv 和 EnvId 必须指定一个(且只有一个)参数。 |
EnvId | String | 否 | 计算环境ID,ComputeEnv 和 EnvId 必须指定一个(且只有一个)参数。 |
RedirectInfo | RedirectInfo object | 是 | 重定向路径 |
RedirectLocalInfo | RedirectLocalInfo object | 否 | 重定向本地路径 |
InputMappings | array of InputMapping objects | 否 | 输入映射 |
OutputMappings | array of OutputMapping objects | 否 | 输出映射 |
OutputMappingConfigs | array of OutputMappingConfig object | 否 | 输出映射配置 |
EnvVars | array of EnvVar objects | 否 | 自定义环境变量 |
Authentications | array of Authentication objects | 否 | 授权信息 |
FailedAction | string | 否 | TaskInstance失败后处理方式,取值包括TERMINATE(默认)、INTERRUPT、FAST_INTERRUPT。 |
MaxRetryCount | Integer | 否 | 任务失败后的最大重试次数,默认为0 |
Timeout | Integer | 否 | 任务启动后的超时时间,单位秒,默认为3600秒 |
备注:关于FailedAction 。TaskInstance失败后处理方式,取值包括TERMINATE(默认)、INTERRUPT、FAST_INTERRUPT。TERMINATE表示正常销毁、释放资源;INTERRUPT表示n次重试后失败保留现场,前n-1次正常销毁;FAST_INTERRUPT表示首次失败即保留现场,不再重试。中断后,TaskInstance处于FAILED_INTERRUPTED状态,配额等不会释放。FailedAction 对于提交的指定计算环境的作业无效。
Application
名称 | 类型 | 是否必选 | 描述 |
---|---|---|---|
Command | String | 是 | 任务执行命令 |
DeliveryForm | String | 是 | 应用程序的交付方式,包括PACKAGE、LOCAL 两种取值,分别指远程存储的软件包、计算环境本地。 |
PackagePath | String | 否 | 应用程序软件包的远程存储路径 |
Docker | String | 否 | 应用使用Docker的相关配置。在使用Docker配置的情况下,DeliveryForm 为 LOCAL 表示直接使用Docker镜像内部的应用软件,通过Docker方式运行;DeliveryForm 为 PACKAGE,表示将远程应用包注入到Docker镜像后,通过Docker方式运行。为避免Docker不同版本的兼容性问题,Docker安装包及相关依赖由Batch统一负责,对于已安装Docker的自定义镜像,请卸载后再使用Docker特性。 |
Docker
名称 | 类型 | 是否必选 | 描述 |
---|---|---|---|
User | String | 是 | Docker Hub 用户名或 Tencent Registry 用户名 |
Password | String | 是 | Docker Hub 密码或 Tencent Registry 密码 |
Server | String | 否 | Docker Hub 可以不填,但确保有公网。或者是 Tencent Registry 服务地址“ccr.ccs.tencentyun.com” |
Image | String | 是 | Docker Hub填写“[user/repo]:[tag]”,Tencent Registry填写“ccr.ccs.tencentyun.com/[namespace/repo]:[tag]” |
ComputeEnv
名称 | 类型 | 是否必选 | 描述 |
---|---|---|---|
EnvType | String | 是 | 计算环境管理类型,包括托管和非托管两种 |
EnvData | EnvData object | 是 | 计算环境具体参数 |
MountDataDisks | array of MountDataDisk objects | 否 | 数据盘挂载选项 |
AgentRunningMode | AgentRunningMode object | 否 | agent运行模式,适用于Windows系统 |
EnvData
名称 | 类型 | 是否必选 | 描述 |
---|---|---|---|
InstanceType | String | 是 | CVM实例类型,托管类型必填 |
ImageId | String | 是 | CVM镜像ID,托管类型必填 |
SystemDisk | SystemDisk object | 否 | 实例系统盘配置信息。若不指定该参数,则按照系统默认值进行分配。 |
DataDisks | array of DataDisk objects | 否 | 实例数据盘配置信息。若不指定该参数,则默认不购买数据盘,当前仅支持购买的时候指定一个数据盘。 |
VirtualPrivateCloud | VirtualPrivateCloud object | 否 | 私有网络相关信息配置。通过该参数可以指定私有网络的ID,子网ID等信息。若不指定该参数,则默认使用基础网络。若在此参数中指定了私有网络 IP,那么InstanceCount参数只能为1。 |
InternetAccessible | InternetAccessible object | 否 | 公网带宽相关信息设置。若不指定该参数,则默认公网带宽为0Mbps。 |
InstanceName | String | 否 | 实例显示名称。如果不指定则batch指定默认命名。最大长度不能超60个字节。 |
LoginSettings | LoginSettings object | 否 | 实例登录设置。通过该参数可以设置实例的登录方式密码、密钥或保持镜像的原始登录设置。如果不指定则batch生成默认密码。 |
SecurityGroupIds | array of Strings | 否 | 实例所属安全组。该参数可以通过调用 DescribeSecurityGroups 的返回值中的SGID字段来获取。若不指定该参数,则默认不绑定安全组。不绑定安全组将暴露所有端口到公网和内网,实例的所有业务(如80、443等端口)将均可被访问,但会有一定的安全风险,建议选择按需新建的安全组。当前仅支持购买的时候指定一个安全组。 |
EnvData 参数参考CVM API文档提供的参数 https://cloud.tencent.com/document/api/213/9384
RedirectInfo
名称 | 类型 | 是否必选 | 描述 |
---|---|---|---|
StdoutRedirectPath | String | 是 | 标准输出重定向路径 |
StderrRedirectPath | String | 是 | 标准错误重定向路径 |
StdoutRedirectFileName | String | 否 | 标准输出重定向文件名,支持三个占位符${BATCH_JOB_ID}、${BATCH_TASK_NAME}、${BATCH_TASK_INSTANCE_INDEX} |
StderrRedirectFileName | String | 否 | 标准错误重定向文件名,支持三个占位符${BATCH_JOB_ID}、${BATCH_TASK_NAME}、${BATCH_TASK_INSTANCE_INDEX} |
RedirectLocalInfo
名称 | 类型 | 是否必选 | 描述 |
---|---|---|---|
StdoutLocalPath | String | 否 | 标准输出重定向本地路径 |
StderrLocalPath | String | 否 | 标准错误重定向本地路径 |
StdoutLocalFileName | String | 否 | 标准输出重定向本地文件名,支持三个占位符${BATCH_JOB_ID}、${BATCH_TASK_NAME}、${BATCH_TASK_INSTANCE_INDEX} |
StderrLocalFileName | String | 否 | 标准错误重定向本地文件名,支持三个占位符${BATCH_JOB_ID}、${BATCH_TASK_NAME}、${BATCH_TASK_INSTANCE_INDEX} |
InputMapping
名称 | 类型 | 是否必选 | 描述 |
---|---|---|---|
SourcePath | String | 是 | 源端路径 |
DestinationPath | String | 是 | 目的端路径 |
MountOptionParameter | String | 否 | 挂载配置项参数 |
OutputMapping
名称 | 类型 | 是否必选 | 描述 |
---|---|---|---|
SourcePath | String | 是 | 源端路径 |
DestinationPath | String | 是 | 目的端路径 |
OutputMappingConfig
名称 | 类型 | 是否必选 | 描述 |
---|---|---|---|
Scene | String | 是 | 存储类型,仅支持COS |
WorkerNum | Integer | 是 | 并行worker数量 |
WorkerPartSize | Integer | 是 | worker分块大小 |
EnvVar
名称 | 类型 | 是否必选 | 描述 |
---|---|---|---|
Name | String | 是 | 环境变量名称 |
Value | String | 是 | 环境变量取值 |
Authentication
名称 | 类型 | 是否必选 | 描述 |
---|---|---|---|
Scene | String | 是 | 授权场景,例如COS |
SecretId | String | 是 | SecretId |
SecretKey | String | 是 | SecretKey |
MountDataDisk
名称 | 类型 | 是否必选 | 描述 |
---|---|---|---|
FileSystemType | String | 否 | 文件系统类型,Linux系统下支持"EXT3"和"EXT4"两种,默认"EXT3";Windows系统下仅支持"NTFS" |
LocalPath | String | 是 | 挂载点,Linux系统合法路径,或Windows系统盘符,例如"H:" |
AgentRunningMode
名称 | 类型 | 是否必选 | 描述 |
---|---|---|---|
Scene | String | 是 | 场景类型,支持WINDOWS |
User | String | 是 | 运行Agent的User |
Session | String | 是 | 运行Agent的Session |
Dependence
名称 | 类型 | 是否必选 | 描述 |
---|---|---|---|
StartTask | String | 是 | 依赖关系的起点任务名称 |
EndTask | String | 是 | 依赖关系的起点任务名称 |
Notification
名称 | 类型 | 是否必选 | 描述 |
---|---|---|---|
TopicName | String | 是 | CMQ主题名字,要求主题名有效且关联订阅 |
EventConfigs | array of EventConfig objects | 是 | 事件配置 |
EventConfig
名称 | 类型 | 是否必选 | 描述 |
---|---|---|---|
EventName | String | 是 | 事件类型,具体取值详见“事件类型” |
EventVars | array of EventVar objects | 否 | 自定义键值对 |
EventName(事件类型) 取值范围
类型 | 描述 |
---|---|
JOB_RUNNING | 作业运行 |
JOB_SUCCEED | 作业完成 |
JOB_FAILED | 作业失败 |
JOB_FAILED_INTERRUPTED | 作业失败中断 |
TASK_RUNNING | 任务运行 |
TASK_SUCCEED | 任务完成 |
TASK_FAILED | 任务失败 |
TASK_FAILED_INTERRUPTED | 任务失败中断 |
TASK_INSTANCE_RUNNING | 任务实例运行 |
TASK_INSTANCE_SUCCEED | 任务实例完成 |
TASK_INSTANCE_FAILED | 任务实例失败 |
TASK_INSTANCE_FAILED_INTERRUPTED | 任务实例失败中断 |
EventVar
名称 | 类型 | 是否必选 | 描述 |
---|---|---|---|
Name | String | 是 | 自定义键 |
Value | String | 是 | 自定义值 |
TaskExecutionDependOn 取值范围
类型 | 描述 |
---|---|
PRE_TASK_SUCCEED | 表示前序任务必须成功,后序任务发起执行 |
PRE_TASK_AT_LEAST_PARTLY_SUCCEED | 表示前序任务执行完成并且至少部分成功,后序任务发起执行 |
PRE_TASK_FINISHED | 表示前序任务执行完成(可能成功或者失败),后序任务发起执行 |
{
"Job": {
"JobName": "dag job",
"JobDescription": "test dag job",
"Priority": 1,
"Tasks": [
{
"TaskName": "A",
"TaskInstanceNum": 1,
# other params
"Application": {
"Command": "python a.py",
"DeliveryForm": "PACKAGE",
"PackagePath": "http://batchbucket-appid.cosgz.myqcloud.com/app/app.tgz",
},
"ComputeEnv": {
"EnvType": "MANAGED",
"EnvData": {
"InstanceType": "S1.SMALL1",
"ImageId": "img-bq1gnde3",
},
},
"InputMappings": [
{
"SourcePath": "cos://batchbucket-appid.cosgz.myqcloud.com/input/",
"DestinationPath": "/data/input/",
"MountOptionParameter": "-oensure_diskfree=5120 -oallow_other -ononempty"
}
],
"OutputMappings": [
{
"SourcePath": "/data/output/",
"DestinationPath": "cos://batchbucket-appid.cosgz.myqcloud.com/output/"
}
],
"RedirectInfo": {
"StdoutRedirectPath": "cos://batchbucket-appid.cosgz.myqcloud.com/log/",
"StdoutRedirectFileName": "prefix.${BATCH_TASK_NAME}.${BATCH_TASK_INSTANCE_INDEX}.log",
"StderrRedirectPath": "cos://batchbucket-appid.cosgz.myqcloud.com/log/"
"StderrRedirectFileName": "prefix.project1.log"
},
"RedirectLocalInfo": {
"StdoutLocalPath": "/data/stdout/",
"StdoutLocalFileName": "stdout.${BATCH_TASK_NAME}.${BATCH_TASK_INSTANCE_INDEX}",
"StderrLocalPath": "/data/stderr/"
"StderrLocalFileName": "stderr.${BATCH_TASK_NAME}.${BATCH_TASK_INSTANCE_INDEX}"
},
"EnvVars": [
{
"Name": "Env1",
"Value": "Value1"
},
{
"Name": "Env2",
"Value": "Value2"
}
],
"Authentications": [
{
"Scene": "COS",
"SecretId": "xxx",
"SecretKey": "yyy"
}
],
"MaxRetryCount": 3,
"Timeout": 86400,
},
{
"TaskName": "B",
"TaskInstanceNum": 3,
# other params
"Application": {
"Command": "python b.py",
"DeliveryForm": "PACKAGE",
"PackagePath": "http://batchbucket-appid.cosgz.myqcloud.com/app/app.tgz",
},
"ComputeEnv": {
"EnvType": "MANAGED",
"EnvData": {
"InstanceType": "S1.SMALL1",
"ImageId": "img-bq1gnde3",
},
},
"InputMappings": [
{
"SourcePath": "cos://batchbucket-appid.cosgz.myqcloud.com/input/",
"DestinationPath": "/data/input/"
}
],
"OutputMappings": [
{
"SourcePath": "/data/output/",
"DestinationPath": "cos://batchbucket-appid.cosgz.myqcloud.com/output/"
}
],
"RedirectInfo": {
"StdoutRedirectPath": "cos://batchbucket-appid.cosgz.myqcloud.com/log/",
"StderrRedirectPath": "cos://batchbucket-appid.cosgz.myqcloud.com/log/"
},
"Authentications": [
{
"Scene": "COS",
"SecretId": "xxx",
"SecretKey": "yyy"
}
],
"MaxRetryCount": 3,
"Timeout": 86400,
},
{
"TaskName": "C",
"TaskInstanceNum": 1,
# other params
"Application": {
"Command": "python c.py",
"DeliveryForm": "PACKAGE",
"PackagePath": "http://batchbucket-appid.cosgz.myqcloud.com/app/app.tgz",
"Docker": {
"User": "batch",
"Password": "xxx",
"Server": "ccr.ccs.tencentyun.com",
"Image": "[namespace][repo]:[tag]"
}
},
"ComputeEnv": {
"EnvType": "MANAGED",
"EnvData": {
"InstanceType": "S1.SMALL1",
"ImageId": "img-bq1gnde3",
},
},
"InputMappings": [
{
"SourcePath": "cos://batchbucket-appid.cosgz.myqcloud.com/input/",
"DestinationPath": "/data/input/"
}
],
"OutputMappings": [
{
"SourcePath": "/data/output/",
"DestinationPath": "cos://batchbucket-appid.cosgz.myqcloud.com/output/"
}
],
"RedirectInfo": {
"StdoutRedirectPath": "cos://batchbucket-appid.cosgz.myqcloud.com/log/",
"StderrRedirectPath": "cos://batchbucket-appid.cosgz.myqcloud.com/log/"
},
"Authentications": [
{
"Scene": "COS",
"SecretId": "xxx",
"SecretKey": "yyy"
}
],
"MaxRetryCount": 3,
"Timeout": 86400,
}
],
"Dependences": [
{
"StartTask": "A",
"EndTask": "B",
},
{
"StartTask": "B",
"EndTask": "C",
}
],
"Notifications": [
{
"TopicName":"topic name",
"EventConfigs": [
{
"EventName":"JOB_RUNNING",
"EventVars": [
{
"Name":"name1",
"Value":"value1"
},
{
"Name":"name2",
"Value":"value2"
}
]
},
{
"EventName":"JOB_FAILED",
"EventVars": [
{
"Name":"name1",
"Value":"value1"
},
{
"Name":"name2",
"Value":"value2"
}
]
}
]
}
]
}
"Placement": {
"Zone": "ap-guangzhou-2",
"ProjectId": 1053241
},
"ClientToken": "xxxx"
}
3. 输出参数
参数名称 | 类型 | 描述 |
---|---|---|
JobId | String | 当通过本接口来提交作业时会返回该参数,表示一个作业ID。返回作业ID列表并不代表作业解析/运行成功,可根据 DescribeJob 接口查询其状态。 |
RequestId | String | 唯一请求ID。每次请求都会返回一个唯一的RequestId,当客户调用接口失败找后台研发人员处理时需提供该RequestId具体值。 |
# 接口正常返回示例
{
"Response": {
"JobId": "job-08gkkznp",
"RequestId": "eac6b301-a322-493a-8e36-83b295459397"
}
}
4. 错误码
以下错误码表仅列出了该接口的业务逻辑错误码。
错误码 | 描述 |
---|---|
InvalidBatchJobName.TooLong | 作业名称过长。 |
InvalidBatchJobDescription.TooLong | 作业描述过长。 |
InvalidBatchTaskName | 非法的任务名称。 |
InvalidBatchTaskName.TooLong | 任务名称过长。 |
UnsupportedBatchRemoteStorageSchemeType | 非法的存储类型。 |
UnsupportedBatchRemoteStoragePath | 非法的存储路径格式。 |
BatchComputeNotAllowed | 禁止使用批量计算服务。 |
BatchComputeDependenceUnfeasible | 禁止环状任务依赖关系。 |
AllowedOneAttributeInEnvIdAndComputeEnv | ComputeEnv 和 EnvId 必须指定一个(且只有一个)参数。 |
BatchComputeDependenceNotFoundTaskName | 找不到依赖任务定义。 |
BatchComputeTaskMaxRetryLimitExceeded | 重试次数过大。 |
BatchComputeCheckComputeEnvError | 计算环境校验失败。 |
InvalidNotificationEventName.Duplicate | 重复的消息通知事件名称。 |
InvalidNotificationTopicName | 非法的主题名称。 |
InvalidNotificationTopicName.TooLong | 主题名称过长。 |
UnsupportedBatchLocalPath | 非法的本地存储路径。 |
InvalidParameterValue.Negative | 非法的负值参数。 |
NoEnoughJobQuota | 作业配额不足。 |
InvalidCvmParameters | 非法的CVM参数。 |
InternalServerError | 内部服务错误。 |