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} |
名称 |
类型 |
是否必选 |
描述 |
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,
"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,
"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,
"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 |
内部服务错误。 |