提交作业

最近更新时间:2018-03-21 18:03:55

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 内部服务错误。