CreateJob-阿里云帮助中心

Submit a job to run on a cluster. Specify the data source configuration, code source configuration, start command, and compute resource configuration for each node in the job.

Operation description

Before using this API, make sure you fully understand the billing model and pricing of PAI-DLC.

Important The total length of parameters passed to the CreateJob API (including system-generated parameters) must not exceed 65,536 bytes.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

paidlc:CreateJob

create

*All Resource

*

None

Request syntax

POST /api/v1/jobs HTTP/1.1

Request parameters

Parameter	Type	Required	Description	Example
body	object	No	Request body parameters.
DisplayName	string	Yes	Job name. Follow these naming rules: The name can be up to 256 characters long. Use only digits, letters, underscores (_), periods (.), and hyphens (-).	tf-mnist-test
JobType	string	Yes	Job type. Case-sensitive. Supported job types include the following: TFJob PyTorchJob MPIJob XGBoostJob OneFlowJob ElasticBatchJob SlurmJob RayJob DataJuicerJob Valid values: OneFlowJob : OneFlow PyTorchJob : PyTorch SlurmJob : Slurm XGBoostJob : XGBoost ElasticBatchJob : ElasticBatch MPIJob : MPIJob TFJob : Tensorflow RayJob : Ray	TFJob
JobSpecs	array	Yes	JobSpecs defines runtime configurations for the job, such as registry address, start command, node resource requests, and number of replicas. A DLC job consists of nodes of different types. Nodes of the same type share identical configurations, called a JobSpec. JobSpecs is an array that describes configurations for all node types.
	JobSpec	No	Runtime configuration for the job.
UserCommand	string	Yes	Start command for all job nodes.	python /root/code/mnist.py
DataSources	array<object>	No	List of data sources used by the job.
	object	No	List of all data sources used by this job. Each data source is mounted to a local directory inside the container of every node, based on the MountPath specified in the data source configuration. Processes in the job’s start command access each data source directly through its MountPath as a distributed file system.
DataSourceId	string	No	Data source ID. To find your data source ID, see ListDatasets.	d-cn9dl*******
MountPath	string	No	Mount path for this job. Optional. Defaults to the mount path defined in the data source.	/root/data
Uri	string	No	Data source path.	oss://bucket.oss-cn-hangzhou-internal.aliyuncs.com/path/
Options	string	No	Custom dataset mount properties. Currently supports only OSS.	{ "fs.oss.download.thread.concurrency": "10", "fs.oss.upload.thread.concurrency": "10", "fs.jindo.args": "-oattr_timeout=3 -oentry_timeout=0 -onegative_timeout=0 -oauto_cache -ono_symlink" }
DataSourceVersion	string	No
MountAccess	string	No
EnableCache	boolean	No
AccessPointId	string	No
RoleChain	string	No
CodeSource	object	No	Code source used by this job. Before starting job nodes, DLC automatically downloads the code configured in the code source and mounts it to a local directory in the container.
CodeSourceId	string	No	Code source ID. To get your code source ID, see ListCodeSources.	code-20210111103721-xxxxxxx
Branch	string	No	Branch of the code repository referenced by this job. Optional. Defaults to the branch configured in the code source.	master
Commit	string	No	Commit ID of the code to download for this job. Optional. Defaults to the CommitID configured in the code source.	44da109b5******
MountPath	string	No	Mount path for this job. Optional. Defaults to the mount path configured in the code source.	/root/data
UserVpc	object	No	User VPC configuration.
VpcId	string	No	ID of the user VPC.	vpc-abcdef****
SwitchId	string	No	ID of the user vSwitch. Optional. If left empty, the system automatically selects a suitable vSwitch based on inventory. You can also specify a vSwitch ID yourself.	vs-abcdef****
SecurityGroupId	string	No	ID of the user security group.	sg-abcdef****
ExtendedCIDRs	array	No	Extended CIDR blocks. If SwitchId is empty, you can omit this parameter. The system automatically retrieves all CIDR blocks under the VPC. If SwitchId is provided, you must specify this parameter. We recommend listing all CIDR blocks under the VPC.
	string	No	Extended CIDR block.	192.168.0.1/24
DefaultRoute	string	No	Default route. Valid values: eth0: Use the default network interface to access external networks through the public gateway. eth1: Use the user elastic network interface (ENI) to access external networks through a private gateway. For setup instructions, see Configure DSW instances to access the Internet through a dedicated public gateway.	eth0
ThirdpartyLibs	array	No	List of third-party Python libraries to install.
	string	No	Specify a third-party Python library with its version requirement, for example: `numpy==1.16.1`.	numpy==1.16.1
ThirdpartyLibDir	string	No	Folder name containing the requirements.txt file for Python third-party libraries. Before running the UserCommand, PAI-DLC retrieves requirements.txt from this folder and runs `pip install -r` to install the dependencies.	/root/code/
Envs	object	No	Environment variable configuration.
	string	No	An environment variable in the format: `Key=Value`. Important Environment variables must follow the POSIX standard.	ENABLE_DEBUG_MODE
JobMaxRunningTimeMinutes	integer	No	Maximum job runtime, in minutes.	1024
WorkspaceId	string	No	Workspace ID. To get your workspace ID, see ListWorkspaces.	ws-20210126170216-xxxxxxx
ResourceId	string	No	Resource group ID. Optional. If left empty, the job is submitted to the public resource group. If your workspace has bound resource quotas, you can specify the corresponding resource quota ID here. To find your resource quota ID, see Manage resource quotas.	rs-xxx
Priority	integer	No	Job priority. Optional. Default value is 1. Valid range is 1 to 9: 1 is the lowest priority. 9 is the highest priority.	8
Settings	JobSettings	No	Additional job parameter settings.
ElasticSpec	JobElasticSpec	No	This parameter is not supported yet. Ignore it.
DebuggerConfigContent	string	No	This parameter is not supported yet. Ignore it.	“”
Options	string	No	Additional job configuration. Use this parameter to adjust behaviors of mounted data sources. For example, if your job mounts an OSS data source, set this parameter to `fs.oss.download.thread.concurrency=4,fs.oss.download.queue.size=16` to override JindoFS default settings.	key1=value1,key2=value2
SuccessPolicy	string	No	Success policy for distributed multi-node jobs. Currently supported only for multi-node TensorFlow jobs. ChiefWorker: The job succeeds if the Chief pod completes successfully. AllWorkers (default): The job succeeds only if all Worker pods complete successfully.	AllWorkers
CredentialConfig	CredentialConfig	No	Access credential configuration.
Accessibility	string	No	Job visibility. Valid values: PUBLIC: Visible to everyone in this workspace. PRIVATE: Visible only to you and administrators in this workspace.	PRIVATE
TemplateId	string	No	Job template ID.	tplabc1234567
TemplateVersion	integer	No	Job template version.	1
Description	string	No
SchedulingStrategy	string	No		Auto
CustomEnvs	array<object>	No
	object	No
Key	string	No
Value	string	No
Visible	string	No

Response elements

Element	Type	Description	Example
	object	Returns a JSON-formatted string.
JobId	string	ID of the job created by this request.	dlc7*******
RequestId	string	ID of this request, used for diagnostics and support.	473469C7-AA6F-4DC5-B3DB-xxxxxxx

Examples

Success response

JSON format

{
  "JobId": "dlc7*******",
  "RequestId": "473469C7-AA6F-4DC5-B3DB-xxxxxxx"
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.