Menu
AWS Batch
API Reference (API Version 2016-08-10)

RegisterJobDefinition

Registers an AWS Batch job definition.

Request Syntax

POST /v1/registerjobdefinition HTTP/1.1 Content-type: application/json { "containerProperties": { "command": [ "string" ], "environment": [ { "name": "string", "value": "string" } ], "image": "string", "jobRoleArn": "string", "memory": number, "mountPoints": [ { "containerPath": "string", "readOnly": boolean, "sourceVolume": "string" } ], "privileged": boolean, "readonlyRootFilesystem": boolean, "ulimits": [ { "hardLimit": number, "name": "string", "softLimit": number } ], "user": "string", "vcpus": number, "volumes": [ { "host": { "sourcePath": "string" }, "name": "string" } ] }, "jobDefinitionName": "string", "parameters": { "string" : "string" }, "retryStrategy": { "attempts": number }, "type": "string" }

URI Request Parameters

The request does not use any URI parameters.

Request Body

The request accepts the following data in JSON format.

containerProperties

An object with various properties specific for container-based jobs. This parameter is required if the type parameter is container.

Type: ContainerProperties object

Required: No

jobDefinitionName

The name of the job definition to register. Up to 128 letters (uppercase and lowercase), numbers, hyphens, and underscores are allowed.

Type: String

Required: Yes

parameters

Default parameter substitution placeholders to set in the job definition. Parameters are specified as a key-value pair mapping. Parameters in a SubmitJob request override any corresponding parameter defaults from the job definition.

Type: String to string map

Required: No

retryStrategy

The retry strategy to use for failed jobs that are submitted with this job definition. Any retry strategy that is specified during a SubmitJob operation overrides the retry strategy defined here.

Type: RetryStrategy object

Required: No

type

The type of job definition.

Type: String

Valid Values: container

Required: Yes

Response Syntax

HTTP/1.1 200 Content-type: application/json { "jobDefinitionArn": "string", "jobDefinitionName": "string", "revision": number }

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

jobDefinitionArn

The Amazon Resource Name (ARN) of the job definition.

Type: String

jobDefinitionName

The name of the job definition.

Type: String

revision

The revision of the job definition.

Type: Integer

Errors

ClientException

These errors are usually caused by a client action, such as using an action or resource on behalf of a user that doesn't have permissions to use the action or resource, or specifying an identifier that is not valid.

HTTP Status Code: 400

ServerException

These errors are usually caused by a server issue.

HTTP Status Code: 500

Examples

In the following example or examples, the Authorization header contents (AUTHPARAMS) must be replaced with an AWS Signature Version 4 signature. For more information about creating these signatures, see Signature Version 4 Signing Process in the AWS General Reference.

You only need to learn how to sign HTTP requests if you intend to manually create them. When you use the AWS Command Line Interface (AWS CLI) or one of the AWS SDKs to make requests to AWS, these tools automatically sign the requests for you with the access key that you specify when you configure the tools. When you use these tools, you don't need to learn how to sign requests yourself.

Example

This example registers a job definition for a simple container job.

Sample Request

POST /v1/registerjobdefinition HTTP/1.1 Host: batch.us-east-1.amazonaws.com Accept-Encoding: identity Content-Length: 153 Authorization: AUTHPARAMS X-Amz-Date: 20161128T215526Z User-Agent: aws-cli/1.11.21 Python/2.7.12 Darwin/16.1.0 botocore/1.4.78 { "containerProperties": { "image": "busybox", "command": [ "sleep", "10" ], "vcpus": 1, "memory": 128 }, "type": "container", "jobDefinitionName": "sleep10" }

Sample Response

HTTP/1.1 200 OK Content-Type: application/json Content-Length: 127 Connection: keep-alive Date: Mon, 28 Nov 2016 21:55:27 GMT x-amzn-RequestId: 5f0a08ec-b5b5-11e6-90ed-f72854f7eb90 X-Amzn-Trace-Id: Root=1-583ca7ce-bda1f338231616471b2efced X-Cache: Miss from cloudfront Via: 1.1 7a06af51e583997d8673ab89482dd45a.cloudfront.net (CloudFront) X-Amz-Cf-Id: Y14HPNWWcKgm1U0wJPfLBzLDvrMSdyuHo4GMi0oQwI0ukruLpi0nFw== { "jobDefinitionName": "sleep10", "jobDefinitionArn": "arn:aws:batch:us-east-1:012345678910:job-definition/sleep10:1", "revision": 1 }

Example

This example registers a job definition for a simple container job with retries.

Sample Request

POST /v1/registerjobdefinition HTTP/1.1 Host: batch-beta.us-east-1.amazonaws.com Accept-Encoding: identity Content-Length: 320 Authorization: AUTHPARAMS X-Amz-Date: 20170327T145208Z User-Agent: aws-cli/1.11.66 Python/2.7.10 Darwin/16.4.0 botocore/1.5.29 { "containerProperties": { "mountPoints": [], "image": "amazonlinux", "environment": [], "vcpus": 1, "command": [ "/bin/bash", "-c", "exit $AWS_BATCH_JOB_ATTEMPT" ], "volumes": [], "memory": 2, "ulimits": [] }, "retryStrategy": { "attempts": 3 }, "jobDefinitionName": "EchoAttemptNumber", "parameters": {}, "type": "container" }

Sample Response

HTTP/1.1 200 OK Date: Mon, 27 Mar 2017 14:51:58 GMT Content-Type: application/json Content-Length: 147 Connection: keep-alive x-amzn-RequestId: edbe4e89-12fc-11e7-a2c6-31d9fbe506fc X-Amzn-Trace-Id: Root=1-58d9270e-56b3c6e2a91e74ef4c35a9c5 X-Cache: Miss from cloudfront Via: 1.1 861b49a34b383ce3ac4ea8b7117b8953.cloudfront.net (CloudFront) X-Amz-Cf-Id: l3zCxHtlIx4c1-RN2vkqIlpSbU9tsZNxfMSg6oIf700wg1BX0V5f_A== { "jobDefinitionName": "EchoAttemptNumber", "jobDefinitionArn": "arn:aws:batch:us-east-1:012345678910:job-definition/EchoAttemptNumber:1", "revision": 1 }

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the following: