Amazon EMR Serverless
EMR Serverless API Reference
API Version 2021-07-13
Amazon EMR Serverless: EMR Serverless API Reference
Copyright © Amazon Web Services, Inc. and/or its affiliates. All rights reserved.
Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be affiliated with, connected to, or sponsored by Amazon.
Table of Contents
... vi
Welcome ... 1
Actions ... 2
CancelJobRun ... 3
Request Syntax ... 3
URI Request Parameters ... 3
Request Body ... 3
Response Syntax ... 3
Response Elements ... 3
Errors ... 4
See Also ... 4
CreateApplication ... 5
Request Syntax ... 5
URI Request Parameters ... 5
Request Body ... 5
Response Syntax ... 6
Response Elements ... 7
Errors ... 7
See Also ... 8
DeleteApplication ... 9
Request Syntax ... 9
URI Request Parameters ... 9
Request Body ... 9
Response Syntax ... 9
Response Elements ... 9
Errors ... 9
See Also ... 10
GetApplication ... 11
Request Syntax ... 11
URI Request Parameters ... 11
Request Body ... 11
Response Syntax ... 11
Response Elements ... 12
Errors ... 12
See Also ... 12
GetJobRun ... 14
Request Syntax ... 14
URI Request Parameters ... 14
Request Body ... 14
Response Syntax ... 14
Response Elements ... 15
Errors ... 15
See Also ... 16
ListApplications ... 17
Request Syntax ... 17
URI Request Parameters ... 17
Request Body ... 17
Response Syntax ... 17
Response Elements ... 17
Errors ... 18
See Also ... 18
ListJobRuns ... 19
Request Syntax ... 19
URI Request Parameters ... 19
Request Body ... 19
Response Syntax ... 19
Response Elements ... 20
Errors ... 20
See Also ... 20
StartApplication ... 22
Request Syntax ... 22
URI Request Parameters ... 22
Request Body ... 22
Response Syntax ... 22
Response Elements ... 22
Errors ... 23
See Also ... 23
StartJobRun ... 24
Request Syntax ... 24
URI Request Parameters ... 24
Request Body ... 25
Response Syntax ... 25
Response Elements ... 25
Errors ... 26
See Also ... 26
StopApplication ... 28
Request Syntax ... 28
URI Request Parameters ... 28
Request Body ... 28
Response Syntax ... 28
Response Elements ... 28
Errors ... 29
See Also ... 29
UpdateApplication ... 30
Request Syntax ... 30
URI Request Parameters ... 30
Request Body ... 30
Response Syntax ... 31
Response Elements ... 32
Errors ... 32
See Also ... 32
Data Types ... 33
Application ... 34
Contents ... 34
See Also ... 35
ApplicationStateTransitionInfo ... 37
Contents ... 37
See Also ... 37
ApplicationSummary ... 38
Contents ... 38
See Also ... 39
Configuration ... 40
Contents ... 40
See Also ... 40
ConfigurationOverrides ... 41
Contents ... 41
See Also ... 41
Hive ... 42
Contents ... 42
See Also ... 42
InitialCapacityConfig ... 43
Contents ... 43
See Also ... 43
JobDriver ... 44
Contents ... 44
See Also ... 44
JobRun ... 45
Contents ... 45
See Also ... 47
JobRunSummary ... 48
Contents ... 48
See Also ... 50
MaximumAllowedResources ... 51
Contents ... 51
See Also ... 51
MonitoringConfiguration ... 52
Contents ... 52
See Also ... 52
S3MonitoringConfiguration ... 53
Contents ... 53
See Also ... 53
SparkSubmit ... 54
Contents ... 54
See Also ... 54
WorkerResourceConfig ... 55
Contents ... 55
See Also ... 55
Common Parameters ... 56
Common Errors ... 58
Amazon EMR Serverless is in preview release and is subject to change. To use EMR Serverless in preview, follow the sign up steps at https://pages.awscloud.com/EMR-Serverless-Preview.html. The only Region that EMR Serverless currently supports is us-east-1, so make sure to set all region parameters to this value. All Amazon S3 buckets used with EMR Serverless must also be created in us-east-1.
Welcome
Amazon EMR Serverless is a new deployment option for Amazon EMR. EMR Serverless provides a serverless runtime environment that simplifies running analytics applications using the latest open source frameworks such as Apache Spark and Apache Hive. With EMR Serverless, you don’t have to configure, optimize, secure, or operate clusters to run applications with these frameworks.
The API reference to Amazon EMR Serverless is emr-serverless. The emr-serverless prefix is used in the following scenarios:
• It is the prefix in the CLI commands for Amazon EMR Serverless. For example, aws emr-serverless start-job-run.
• It is the prefix before IAM policy actions for Amazon EMR Serverless. For example, "Action":
["emr-serverless:StartJobRun"]. For more information, see Policy actions for Amazon EMR Serverless.
• It is the prefix used in Amazon EMR Serverless service endpoints. For example, emr-serverless.us- east-2.amazonaws.com.
This document was last published on March 6, 2022.
Actions
The following actions are supported:
• CancelJobRun (p. 3)
• CreateApplication (p. 5)
• DeleteApplication (p. 9)
• GetApplication (p. 11)
• GetJobRun (p. 14)
• ListApplications (p. 17)
• ListJobRuns (p. 19)
• StartApplication (p. 22)
• StartJobRun (p. 24)
• StopApplication (p. 28)
• UpdateApplication (p. 30)
CancelJobRun
CancelJobRun
Cancels a job run.
Request Syntax
DELETE /applications/applicationId/jobruns/jobRunId HTTP/1.1
URI Request Parameters
The request uses the following URI parameters.
applicationId (p. 3)
The ID of the application on which the job run will be canceled.
Length Constraints: Minimum length of 1. Maximum length of 64.
Pattern: ^[0-9a-z]+$
Required: Yes jobRunId (p. 3)
The ID of the job run to cancel.
Length Constraints: Minimum length of 1. Maximum length of 64.
Pattern: ^[0-9a-z]+$
Required: Yes
Request Body
The request does not have a request body.
Response Syntax
HTTP/1.1 200
Content-type: application/json { "applicationId": "string", "jobRunId": "string"
}
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.
applicationId (p. 3)
The output contains the application ID on which the job run is cancelled.
Errors
Type: String
Length Constraints: Minimum length of 1. Maximum length of 64.
Pattern: ^[0-9a-z]+$
jobRunId (p. 3)
The output contains the ID of the cancelled job run.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 64.
Pattern: ^[0-9a-z]+$
Errors
For information about the errors that are common to all actions, see Common Errors (p. 58).
InternalServerException
Request processing failed because of an error or failure with the service.
HTTP Status Code: 500 ResourceNotFoundException
The specified resource was not found.
HTTP Status Code: 404 ValidationException
The input fails to satisfy the constraints specified by an AWS service.
HTTP Status Code: 400
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3
CreateApplication
CreateApplication
Creates an application.
Request Syntax
POST /applications HTTP/1.1 Content-type: application/json { "clientToken": "string", "initialCapacity": { "string" : {
"resourceConfiguration": { "cpu": "string",
"disk": "string", "memory": "string"
},
"workerCount": number }
},
"maximumCapacity": { "cpu": "string", "disk": "string", "memory": "string"
},
"name": "string",
"releaseLabel": "string", "type": "string"
}
URI Request Parameters
The request does not use any URI parameters.
Request Body
The request accepts the following data in JSON format.
clientToken (p. 5)
The client idempotency token of the application to create. Its value must be unique for each request.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 64.
Pattern: ^[A-Za-z0-9._-]+$
Required: Yes initialCapacity (p. 5)
The capacity to initialize when the application is created.
Type: String to InitialCapacityConfig (p. 43) object map
Map Entries: Minimum number of 0 items. Maximum number of 10 items.
Response Syntax
Key Length Constraints: Minimum length of 1. Maximum length of 50.
Key Pattern: ^[a-zA-Z]+[-_]*[a-zA-Z]+$
Required: No maximumCapacity (p. 5)
The maximum capacity to allocate when the application is created. This is cumulative across all workers at any given point in time, not just when an application is created. No new resources will be created once any one of the defined limits is hit.
Type: MaximumAllowedResources (p. 51) object Required: No
name (p. 5)
The specified name of the application.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 64.
Pattern: ^[A-Za-z0-9._/#-]+$
Required: Yes releaseLabel (p. 5)
The EMR release version associated with the application.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 64.
Pattern: ^[A-Za-z0-9._/-]+$
Required: Yes type (p. 5)
The type of application you want to start, such as Spark or Hive.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 64.
Pattern: ^(SPARK)|(HIVE)$
Required: Yes
Response Syntax
HTTP/1.1 200
Content-type: application/json { "applicationId": "string", "arn": "string",
"name": "string"
Response Elements
}
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.
applicationId (p. 6)
The output contains the application ID.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 64.
Pattern: ^[0-9a-z]+$
arn (p. 6)
The output contains the ARN of the application.
Type: String
Length Constraints: Minimum length of 60. Maximum length of 1024.
Pattern: ^arn:(aws[a-zA-Z0-9-]*):emr-serverless:.+:(\d{12}):\/applications\/
[0-9a-zA-Z]+$
name (p. 6)
The output contains the name of the application.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 64.
Pattern: ^[A-Za-z0-9._/#-]+$
Errors
For information about the errors that are common to all actions, see Common Errors (p. 58).
ConflictException
The request could not be processed because of conflict in the current state of the resource.
HTTP Status Code: 409 InternalServerException
Request processing failed because of an error or failure with the service.
HTTP Status Code: 500 ValidationException
The input fails to satisfy the constraints specified by an AWS service.
HTTP Status Code: 400
See Also
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3
DeleteApplication
DeleteApplication
Deletes an application. An application has to be in a stopped or created state in order to be deleted.
Request Syntax
DELETE /applications/applicationId HTTP/1.1
URI Request Parameters
The request uses the following URI parameters.
applicationId (p. 9)
The ID of the application that will be deleted.
Length Constraints: Minimum length of 1. Maximum length of 64.
Pattern: ^[0-9a-z]+$
Required: Yes
Request Body
The request does not have a request body.
Response Syntax
HTTP/1.1 200
Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.
Errors
For information about the errors that are common to all actions, see Common Errors (p. 58).
InternalServerException
Request processing failed because of an error or failure with the service.
HTTP Status Code: 500 ResourceNotFoundException
The specified resource was not found.
HTTP Status Code: 404 ValidationException
The input fails to satisfy the constraints specified by an AWS service.
See Also
HTTP Status Code: 400
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3
GetApplication
GetApplication
Displays detailed information about a specified application.
Request Syntax
GET /applications/applicationId HTTP/1.1
URI Request Parameters
The request uses the following URI parameters.
applicationId (p. 11)
The ID of the application that will be described.
Length Constraints: Minimum length of 1. Maximum length of 64.
Pattern: ^[0-9a-z]+$
Required: Yes
Request Body
The request does not have a request body.
Response Syntax
HTTP/1.1 200
Content-type: application/json { "application": {
"applicationId": "string", "arn": "string",
"createdAt": number, "initialCapacity": { "string" : {
"resourceConfiguration": { "cpu": "string",
"disk": "string", "memory": "string"
},
"workerCount": number }
},
"lastStateTransitionInfo": { "currentState": "string", "previousState": "string", "reasonForTransition": "string", "transitionedAt": number
},
"lastUpdatedAt": number, "maximumCapacity": { "cpu": "string", "disk": "string",
Response Elements
"memory": "string"
},
"name": "string",
"releaseLabel": "string", "status": "string", "type": "string"
}}
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.
application (p. 11)
The output displays information about the specified application.
Type: Application (p. 34) object
Errors
For information about the errors that are common to all actions, see Common Errors (p. 58).
InternalServerException
Request processing failed because of an error or failure with the service.
HTTP Status Code: 500 ResourceNotFoundException
The specified resource was not found.
HTTP Status Code: 404 ValidationException
The input fails to satisfy the constraints specified by an AWS service.
HTTP Status Code: 400
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3
See Also
GetJobRun
GetJobRun
Displays detailed information about a job run.
Request Syntax
GET /applications/applicationId/jobruns/jobRunId HTTP/1.1
URI Request Parameters
The request uses the following URI parameters.
applicationId (p. 14)
The ID of the application on which the job run is submitted.
Length Constraints: Minimum length of 1. Maximum length of 64.
Pattern: ^[0-9a-z]+$
Required: Yes jobRunId (p. 14)
The ID of the job run.
Length Constraints: Minimum length of 1. Maximum length of 64.
Pattern: ^[0-9a-z]+$
Required: Yes
Request Body
The request does not have a request body.
Response Syntax
HTTP/1.1 200
Content-type: application/json {
"jobRun": {
"applicationId": "string", "arn": "string",
"configurationOverrides": { "applicationConfiguration": [ {
"classification": "string", "configurations": [ "Configuration"
],
"properties": { "string" : "string"
} } ],
Response Elements
"monitoringConfiguration": { "s3MonitoringConfiguration": { "logUri": "string"
} } },
"createdAt": number, "createdBy": "string", "executionRole": "string", "jobDriver": {
"hive": {
"initQueryFile": "string", "parameters": "string", "query": "string"
},
"sparkSubmit": {
"entryPoint": "string",
"entryPointArguments": [ "string" ], "sparkSubmitParameters": "string"
} },
"jobRunId": "string", "releaseLabel": "string", "state": "string",
"stateDetails": "string", "updatedAt": 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.
jobRun (p. 14)
The output displays information about the job run.
Type: JobRun (p. 45) object
Errors
For information about the errors that are common to all actions, see Common Errors (p. 58).
InternalServerException
Request processing failed because of an error or failure with the service.
HTTP Status Code: 500 ResourceNotFoundException
The specified resource was not found.
HTTP Status Code: 404 ValidationException
The input fails to satisfy the constraints specified by an AWS service.
HTTP Status Code: 400
See Also
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3
ListApplications
ListApplications
Lists applications based on a set of parameters.
Request Syntax
GET /applications?maxResults=maxResults&nextToken=nextToken HTTP/1.1
URI Request Parameters
The request uses the following URI parameters.
maxResults (p. 17)
The maximum number of applications that can be listed.
Valid Range: Minimum value of 1. Maximum value of 50.
nextToken (p. 17)
The token for the next set of application results.
Length Constraints: Minimum length of 1. Maximum length of 1024.
Pattern: ^[A-Za-z0-9_=-]+$
Request Body
The request does not have a request body.
Response Syntax
HTTP/1.1 200
Content-type: application/json {
"applications": [ {
"arn": "string", "createdAt": number, "id": "string",
"lastUpdatedAt": number, "name": "string",
"releaseLabel": "string", "status": "string", "type": "string"
} ],
"nextToken": "string"
}
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
Errors
The following data is returned in JSON format by the service.
applications (p. 17)
The output lists the specified applications.
Type: Array of ApplicationSummary (p. 38) objects nextToken (p. 17)
The output displays the token for the next set of application results. This is required for pagination and is available as a response of the previous request.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 1024.
Pattern: ^[A-Za-z0-9_=-]+$
Errors
For information about the errors that are common to all actions, see Common Errors (p. 58).
InternalServerException
Request processing failed because of an error or failure with the service.
HTTP Status Code: 500 ValidationException
The input fails to satisfy the constraints specified by an AWS service.
HTTP Status Code: 400
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3
ListJobRuns
ListJobRuns
Lists job runs based on a set of parameters.
Request Syntax
GET /applications/applicationId/jobruns?maxResults=maxResults&nextToken=nextToken HTTP/1.1
URI Request Parameters
The request uses the following URI parameters.
applicationId (p. 19)
The ID of the application for which to list the job run.
Length Constraints: Minimum length of 1. Maximum length of 64.
Pattern: ^[0-9a-z]+$
Required: Yes maxResults (p. 19)
The maximum number of job runs that can be listed.
Valid Range: Minimum value of 1. Maximum value of 50.
nextToken (p. 19)
The token for the next set of job run results.
Length Constraints: Minimum length of 1. Maximum length of 1024.
Pattern: ^[A-Za-z0-9_=-]+$
Request Body
The request does not have a request body.
Response Syntax
HTTP/1.1 200
Content-type: application/json {
"jobRuns": [ {
"applicationId": "string", "arn": "string",
"createdAt": number, "createdBy": "string", "executionRole": "string", "id": "string",
"releaseLabel": "string", "state": "string",
Response Elements
"stateDetails": "string", "stateUpdatedAt": number, "type": "string"
} ],
"nextToken": "string"
}
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.
jobRuns (p. 19)
The output lists information about the specified job runs.
Type: Array of JobRunSummary (p. 48) objects nextToken (p. 19)
The output displays the token for the next set of job run results. This is required for pagination and is available as a response of the previous request.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 1024.
Pattern: ^[A-Za-z0-9_=-]+$
Errors
For information about the errors that are common to all actions, see Common Errors (p. 58).
InternalServerException
Request processing failed because of an error or failure with the service.
HTTP Status Code: 500 ValidationException
The input fails to satisfy the constraints specified by an AWS service.
HTTP Status Code: 400
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
See Also
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3
StartApplication
StartApplication
Starts a specified application and initializes initial capacity if configured.
Request Syntax
POST /applications/applicationId/start HTTP/1.1
URI Request Parameters
The request uses the following URI parameters.
applicationId (p. 22)
The ID of the application to start.
Length Constraints: Minimum length of 1. Maximum length of 64.
Pattern: ^[0-9a-z]+$
Required: Yes
Request Body
The request does not have a request body.
Response Syntax
HTTP/1.1 200
Content-type: application/json {
"stateTransitionInfo": { "currentState": "string", "previousState": "string", "reasonForTransition": "string", "transitionedAt": 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.
stateTransitionInfo (p. 22)
The output displays information about the most recent application state transition.
Type: ApplicationStateTransitionInfo (p. 37) object
Errors
Errors
For information about the errors that are common to all actions, see Common Errors (p. 58).
InternalServerException
Request processing failed because of an error or failure with the service.
HTTP Status Code: 500 ResourceNotFoundException
The specified resource was not found.
HTTP Status Code: 404 ValidationException
The input fails to satisfy the constraints specified by an AWS service.
HTTP Status Code: 400
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3
StartJobRun
StartJobRun
Starts a job run.
Request Syntax
POST /applications/applicationId/jobruns HTTP/1.1 Content-type: application/json
{
"clientToken": "string", "configurationOverrides": { "applicationConfiguration": [ {
"classification": "string", "configurations": [ "Configuration"
],
"properties": { "string" : "string"
} } ],
"monitoringConfiguration": { "s3MonitoringConfiguration": { "logUri": "string"
} } },
"executionRoleArn": "string", "jobDriver": {
"hive": {
"initQueryFile": "string", "parameters": "string", "query": "string"
},
"sparkSubmit": {
"entryPoint": "string",
"entryPointArguments": [ "string" ], "sparkSubmitParameters": "string"
} } }
URI Request Parameters
The request uses the following URI parameters.
applicationId (p. 24)
The ID of the application on which to run the job.
Length Constraints: Minimum length of 1. Maximum length of 64.
Pattern: ^[0-9a-z]+$
Required: Yes
Request Body
Request Body
The request accepts the following data in JSON format.
clientToken (p. 24)
The client idempotency token of the job run to start. Its value must be unique for each request.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 64.
Pattern: ^[A-Za-z0-9._-]+$
Required: Yes
configurationOverrides (p. 24)
The configuration overrides for the job run.
Type: ConfigurationOverrides (p. 41) object Required: No
executionRoleArn (p. 24)
The execution role ARN for the job run.
Type: String
Length Constraints: Minimum length of 20. Maximum length of 2048.
Pattern: ^arn:(aws[a-zA-Z0-9-]*):iam::(\d{12})?:(role((\u002F)|(\u002F[\u0021-
\u007F]+\u002F))[\w+=,.@-]+)$
Required: Yes jobDriver (p. 24)
The job driver for the job run.
Type: JobDriver (p. 44) object Required: No
Response Syntax
HTTP/1.1 200
Content-type: application/json { "applicationId": "string", "arn": "string",
"jobRunId": "string"
}
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.
Errors
applicationId (p. 25)
This output displays the application ID on which the job run was submitted.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 64.
Pattern: ^[0-9a-z]+$
arn (p. 25)
The output lists the execution role ARN of the job run.
Type: String
Length Constraints: Minimum length of 60. Maximum length of 1024.
Pattern: ^arn:(aws[a-zA-Z0-9-]*):emr-serverless:.+:(\d{12}):\/applications\/
[0-9a-zA-Z]+\/jobruns\/[0-9a-zA-Z]+$
jobRunId (p. 25)
The output contains the ID of the started job run.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 64.
Pattern: ^[0-9a-z]+$
Errors
For information about the errors that are common to all actions, see Common Errors (p. 58).
ConflictException
The request could not be processed because of conflict in the current state of the resource.
HTTP Status Code: 409 InternalServerException
Request processing failed because of an error or failure with the service.
HTTP Status Code: 500 ResourceNotFoundException
The specified resource was not found.
HTTP Status Code: 404 ValidationException
The input fails to satisfy the constraints specified by an AWS service.
HTTP Status Code: 400
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
See Also
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3
StopApplication
StopApplication
Stops a specified application and releases initial capacity if configured. All scheduled and running jobs must be completed or cancelled before stopping an application.
Request Syntax
POST /applications/applicationId/stop HTTP/1.1
URI Request Parameters
The request uses the following URI parameters.
applicationId (p. 28)
The ID of the application to stop.
Length Constraints: Minimum length of 1. Maximum length of 64.
Pattern: ^[0-9a-z]+$
Required: Yes
Request Body
The request does not have a request body.
Response Syntax
HTTP/1.1 200
Content-type: application/json {
"stateTransitionInfo": { "currentState": "string", "previousState": "string", "reasonForTransition": "string", "transitionedAt": 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.
stateTransitionInfo (p. 28)
The output displays information about the most recent application state transition.
Type: ApplicationStateTransitionInfo (p. 37) object
Errors
Errors
For information about the errors that are common to all actions, see Common Errors (p. 58).
InternalServerException
Request processing failed because of an error or failure with the service.
HTTP Status Code: 500 ResourceNotFoundException
The specified resource was not found.
HTTP Status Code: 404 ValidationException
The input fails to satisfy the constraints specified by an AWS service.
HTTP Status Code: 400
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3
UpdateApplication
UpdateApplication
Updates a specified application. An application has to be in a stopped or created state in order to be updated.
Request Syntax
PATCH /applications/applicationId HTTP/1.1 Content-type: application/json
{ "clientToken": "string", "initialCapacity": { "string" : {
"resourceConfiguration": { "cpu": "string",
"disk": "string", "memory": "string"
},
"workerCount": number }
},
"maximumCapacity": { "cpu": "string", "disk": "string", "memory": "string"
} }
URI Request Parameters
The request uses the following URI parameters.
applicationId (p. 30)
The ID of the application to update.
Length Constraints: Minimum length of 1. Maximum length of 64.
Pattern: ^[0-9a-z]+$
Required: Yes
Request Body
The request accepts the following data in JSON format.
clientToken (p. 30)
The client idempotency token of the application to update. Its value must be unique for each request.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 64.
Pattern: ^[A-Za-z0-9._-]+$
Response Syntax
Required: Yes initialCapacity (p. 30)
The capacity to initialize when the application is updated.
Type: String to InitialCapacityConfig (p. 43) object map
Map Entries: Minimum number of 0 items. Maximum number of 10 items.
Key Length Constraints: Minimum length of 1. Maximum length of 50.
Key Pattern: ^[a-zA-Z]+[-_]*[a-zA-Z]+$
Required: No
maximumCapacity (p. 30)
The maximum capacity to allocate when the application is updated. This is cumulative across all workers at any given point in time during the lifespan of the application. No new resources will be created once any one of the defined limits is hit.
Type: MaximumAllowedResources (p. 51) object Required: No
Response Syntax
HTTP/1.1 200
Content-type: application/json { "application": {
"applicationId": "string", "arn": "string",
"createdAt": number, "initialCapacity": { "string" : {
"resourceConfiguration": { "cpu": "string",
"disk": "string", "memory": "string"
},
"workerCount": number }
},
"lastStateTransitionInfo": { "currentState": "string", "previousState": "string", "reasonForTransition": "string", "transitionedAt": number
},
"lastUpdatedAt": number, "maximumCapacity": { "cpu": "string", "disk": "string", "memory": "string"
},
"name": "string",
"releaseLabel": "string", "status": "string", "type": "string"
}
Response Elements
}
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.
application (p. 31)
Information about the updated application.
Type: Application (p. 34) object
Errors
For information about the errors that are common to all actions, see Common Errors (p. 58).
InternalServerException
Request processing failed because of an error or failure with the service.
HTTP Status Code: 500 ResourceNotFoundException
The specified resource was not found.
HTTP Status Code: 404 ValidationException
The input fails to satisfy the constraints specified by an AWS service.
HTTP Status Code: 400
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3
Data Types
The EMR Serverless Web Service API contains several data types that various actions use. This section describes each data type in detail.
Note
The order of each element in a data type structure is not guaranteed. Applications should not assume a particular order.
The following data types are supported:
• Application (p. 34)
• ApplicationStateTransitionInfo (p. 37)
• ApplicationSummary (p. 38)
• Configuration (p. 40)
• ConfigurationOverrides (p. 41)
• Hive (p. 42)
• InitialCapacityConfig (p. 43)
• JobDriver (p. 44)
• JobRun (p. 45)
• JobRunSummary (p. 48)
• MaximumAllowedResources (p. 51)
• MonitoringConfiguration (p. 52)
• S3MonitoringConfiguration (p. 53)
• SparkSubmit (p. 54)
• WorkerResourceConfig (p. 55)
Application
Application
Information about an application. EMR Serverless uses applications to run jobs.
Contents
applicationId
The ID of the application.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 64.
Pattern: ^[0-9a-z]+$
Required: Yes arn
The ARN of the application.
Type: String
Length Constraints: Minimum length of 60. Maximum length of 1024.
Pattern: ^arn:(aws[a-zA-Z0-9-]*):emr-serverless:.+:(\d{12}):\/applications\/
[0-9a-zA-Z]+$
Required: Yes createdAt
The date and time when the application run was created.
Type: Timestamp Required: Yes initialCapacity
The initial capacity of the application.
Type: String to InitialCapacityConfig (p. 43) object map
Map Entries: Minimum number of 0 items. Maximum number of 10 items.
Key Length Constraints: Minimum length of 1. Maximum length of 50.
Key Pattern: ^[a-zA-Z]+[-_]*[a-zA-Z]+$
Required: No lastStateTransitionInfo
Information about the most recent application state transition.
Type: ApplicationStateTransitionInfo (p. 37) object Required: No
lastUpdatedAt
The date and time when the application run was last updated.
See Also
Type: Timestamp Required: Yes maximumCapacity
The maximum capacity of the application. This is cumulative across all workers at any given point in time during the lifespan of the application is created. No new resources will be created once any one of the defined limits is hit.
Type: MaximumAllowedResources (p. 51) object Required: No
name
The name of the application.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 64.
Pattern: ^[A-Za-z0-9._/#-]+$
Required: Yes releaseLabel
The EMR release version associated with the application.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 64.
Pattern: ^[A-Za-z0-9._/-]+$
Required: Yes status
The state of the application.
Type: String
Valid Values: CREATING | CREATED | STARTING | STARTED | STOPPING | STOPPED | TERMINATED
Required: Yes type
The type of application, such as Spark or Hive.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 64.
Pattern: ^(SPARK)|(HIVE)$
Required: Yes
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
See Also
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3
ApplicationStateTransitionInfo
ApplicationStateTransitionInfo
Information about the most recent application state transition.
Contents
currentState
Information about the current state of the application.
Type: String
Valid Values: CREATING | CREATED | STARTING | STARTED | STOPPING | STOPPED | TERMINATED
Required: Yes previousState
Information about the previous state of the application.
Type: String
Valid Values: CREATING | CREATED | STARTING | STARTED | STOPPING | STOPPED | TERMINATED
Required: No reasonForTransition
Reason for the recent application state transition.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 256.
Pattern: .*\S.*
Required: No transitionedAt
The date and time when the application last state transitioned.
Type: Timestamp Required: Yes
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3
ApplicationSummary
ApplicationSummary
The summary of attributes associated with an application.
Contents
arn
The ARN of the application.
Type: String
Length Constraints: Minimum length of 60. Maximum length of 1024.
Pattern: ^arn:(aws[a-zA-Z0-9-]*):emr-serverless:.+:(\d{12}):\/applications\/
[0-9a-zA-Z]+$
Required: Yes createdAt
The date and time when the application was created.
Type: Timestamp Required: Yes id
The ID of the application.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 64.
Pattern: ^[0-9a-z]+$
Required: Yes lastUpdatedAt
The date and time when the application was last updated.
Type: Timestamp Required: Yes name
The name of the application.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 64.
Pattern: ^[A-Za-z0-9._/#-]+$
Required: Yes releaseLabel
The EMR release version associated with the application.
Type: String
See Also
Length Constraints: Minimum length of 1. Maximum length of 64.
Pattern: ^[A-Za-z0-9._/-]+$
Required: Yes status
The state of the application.
Type: String
Valid Values: CREATING | CREATED | STARTING | STARTED | STOPPING | STOPPED | TERMINATED
Required: Yes type
The type of application, such as Spark or Hive.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 64.
Pattern: ^(SPARK)|(HIVE)$
Required: Yes
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3
Configuration
Configuration
A configuration specification to be used when provisioning an application. A configuration consists of a classification, properties, and optional nested configurations. A classification refers to an application- specific configuration file. Properties are the settings you want to change in that file.
Contents
classification
The classification within a configuration.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 1024.
Pattern: .*\S.*
Required: Yes configurations
A list of additional configurations to apply within a configuration object.
Type: Array of Configuration (p. 40) objects
Array Members: Minimum number of 0 items. Maximum number of 100 items.
Required: No properties
A set of properties specified within a configuration classification.
Type: String to string map
Map Entries: Minimum number of 0 items. Maximum number of 100 items.
Key Length Constraints: Minimum length of 1. Maximum length of 1024.
Key Pattern: .*\S.*
Value Length Constraints: Minimum length of 1. Maximum length of 1024.
Value Pattern: .*\S.*
Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3
ConfigurationOverrides
ConfigurationOverrides
A configuration specification to be used to override existing configurations.
Contents
applicationConfiguration
The override configurations for the application.
Type: Array of Configuration (p. 40) objects
Array Members: Minimum number of 0 items. Maximum number of 100 items.
Required: No
monitoringConfiguration
The override configurations for monitoring.
Type: MonitoringConfiguration (p. 52) object Required: Yes
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3
Hive
Hive
The configurations for the Hive job driver.
Contents
initQueryFile
The query file for the Hive job run.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 256.
Pattern: (?!\s*$)(^[^';|\u0026\u003C\u003E*?`$(){}\[\]!#\\]*$) Required: No
parameters
The parameters for the Hive job run.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 102400.
Pattern: (?!\s*$)(^[^';|\u0026\u003C\u003E*?`$(){}\[\]!#\\]*$) Required: No
query
The query for the Hive job run.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 10280.
Pattern: (?!\s*$)(^[^';|\u0026\u003C\u003E*?`$(){}\[\]!#\\]*$) Required: Yes
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3
InitialCapacityConfig
InitialCapacityConfig
The initial capacity configuration per worker.
Contents
resourceConfiguration
The resource configuration of the initial capacity configuration.
Type: WorkerResourceConfig (p. 55) object Required: Yes
workerCount
The number of workers in the initial capacity configuration.
Type: Long
Valid Range: Minimum value of 1. Maximum value of 1000000.
Required: Yes
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3
JobDriver
JobDriver
The driver that the job runs on.
Contents
hive
The job driver parameters specified for Hive.
Type: Hive (p. 42) object Required: No
sparkSubmit
The job driver parameters specified for Spark.
Type: SparkSubmit (p. 54) object Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3
JobRun
JobRun
Information about a job run. A job run is a unit of work, such as a Spark JAR, Hive query, or SparkSQL query, that you submit to an EMR Serverless application.
Contents
applicationId
The ID of the application the job is running on.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 64.
Pattern: ^[0-9a-z]+$
Required: Yes arn
The execution role ARN of the job run.
Type: String
Length Constraints: Minimum length of 60. Maximum length of 1024.
Pattern: ^arn:(aws[a-zA-Z0-9-]*):emr-serverless:.+:(\d{12}):\/applications\/
[0-9a-zA-Z]+\/jobruns\/[0-9a-zA-Z]+$
Required: Yes configurationOverrides
The configuration settings that are used to override default configuration.
Type: ConfigurationOverrides (p. 41) object Required: No
createdAt
The date and time when the job run was created.
Type: Timestamp Required: Yes createdBy
The user who created the job run.
Type: String
Length Constraints: Minimum length of 20. Maximum length of 2048.
Pattern: ^arn:(aws[a-zA-Z0-9-]*):(iam|sts)::(\d{12})?:[\w/+=,.@-]+$
Required: Yes executionRole
The execution role ARN of the job run.
Contents
Type: String
Length Constraints: Minimum length of 20. Maximum length of 2048.
Pattern: ^arn:(aws[a-zA-Z0-9-]*):iam::(\d{12})?:(role((\u002F)|(\u002F[\u0021-
\u007F]+\u002F))[\w+=,.@-]+)$
Required: Yes jobDriver
The job driver for the job run.
Type: JobDriver (p. 44) object Required: Yes
jobRunId
The ID of the job run.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 64.
Pattern: ^[0-9a-z]+$
Required: Yes releaseLabel
The EMR release version associated with the application your job is running on.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 64.
Pattern: ^[A-Za-z0-9._/-]+$
Required: Yes state
The state of the job run.
Type: String
Valid Values: SUBMITTED | PENDING | SCHEDULED | RUNNING | SUCCESS | FAILED | CANCELLING | CANCELLED
Required: Yes stateDetails
The state details of the job run.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 256.
Pattern: .*\S.*
Required: Yes updatedAt
The date and time when the job run was updated.
See Also
Type: Timestamp Required: Yes
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3
JobRunSummary
JobRunSummary
The summary of attributes associated with a job run.
Contents
applicationId
The ID of the application the job is running on.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 64.
Pattern: ^[0-9a-z]+$
Required: Yes arn
The ARN of the job run.
Type: String
Length Constraints: Minimum length of 60. Maximum length of 1024.
Pattern: ^arn:(aws[a-zA-Z0-9-]*):emr-serverless:.+:(\d{12}):\/applications\/
[0-9a-zA-Z]+\/jobruns\/[0-9a-zA-Z]+$
Required: Yes createdAt
The date and time when the job run was created.
Type: Timestamp Required: Yes createdBy
The user who created the job run.
Type: String
Length Constraints: Minimum length of 20. Maximum length of 2048.
Pattern: ^arn:(aws[a-zA-Z0-9-]*):(iam|sts)::(\d{12})?:[\w/+=,.@-]+$
Required: Yes executionRole
The execution role ARN of the job run.
Type: String
Length Constraints: Minimum length of 20. Maximum length of 2048.
Pattern: ^arn:(aws[a-zA-Z0-9-]*):iam::(\d{12})?:(role((\u002F)|(\u002F[\u0021-
\u007F]+\u002F))[\w+=,.@-]+)$
Contents
Required: Yes id
The ID of the job run.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 64.
Pattern: ^[0-9a-z]+$
Required: Yes releaseLabel
The EMR release version associated with the application your job is running on.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 64.
Pattern: ^[A-Za-z0-9._/-]+$
Required: Yes state
The state of the job run.
Type: String
Valid Values: SUBMITTED | PENDING | SCHEDULED | RUNNING | SUCCESS | FAILED | CANCELLING | CANCELLED
Required: Yes stateDetails
The state details of the job run.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 256.
Pattern: .*\S.*
Required: Yes stateUpdatedAt
The date and time when the job run was last updated.
Type: Timestamp Required: Yes type
The type of job run, such as Spark or Hive.
Type: String Required: No
See Also
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3
MaximumAllowedResources
MaximumAllowedResources
The maximum allowed cumulative resources for an application. No new resources will be created once the limit is hit.
Contents
cpu
The maximum allowed CPU for an application.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 15.
Pattern: ^[1-9][0-9]*(\s)?(vCPU|vcpu|VCPU)?$
Required: Yes disk
The maximum allowed disk for an application.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 15.
Pattern: ^[1-9][0-9]*(\s)?(GB|gb|gB|Gb)$
Required: No memory
The maximum allowed resources for an application.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 15.
Pattern: ^[1-9][0-9]*(\s)?(GB|gb|gB|Gb)?$
Required: Yes
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3
MonitoringConfiguration
MonitoringConfiguration
The configuration setting for monitoring.
Contents
s3MonitoringConfiguration
The Amazon S3 configuration for monitoring log publishing.
Type: S3MonitoringConfiguration (p. 53) object Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3
S3MonitoringConfiguration
S3MonitoringConfiguration
The Amazon S3 configuration for monitoring log publishing. You can configure your jobs to send log information to Amazon S3.
Contents
logUri
The Amazon S3 destination URI for log publishing.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 10280.
Pattern: [\u0020-\uD7FF\uE000-\uFFFD\uD800\uDBFF-\uDC00\uDFFF\r\n\t]*
Required: Yes
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3
SparkSubmit
SparkSubmit
The configurations for the Spark submit job driver.
Contents
entryPoint
The entry point for the Spark submit job run.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 256.
Pattern: (?!\s*$)(^[^';|\u0026\u003C\u003E*?`$(){}\[\]!#\\]*$) Required: Yes
entryPointArguments
The arguments for the Spark submit job run.
Type: Array of strings
Length Constraints: Minimum length of 1. Maximum length of 10280.
Pattern: (?!\s*$)(^[^';|\u0026\u003C\u003E*?`$(){}\[\]!#\\]*$) Required: No
sparkSubmitParameters
The parameters for the Spark submit job run.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 102400.
Pattern: (?!\s*$)(^[^';|\u0026\u003C\u003E*?`$(){}\[\]!#\\]*$) Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3
WorkerResourceConfig
WorkerResourceConfig
The cumulative configuration requirements for every worker instance of the worker type.
Contents
cpu
The CPU requirements for every worker instance of the worker type.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 15.
Pattern: ^[1-9][0-9]*(\s)?(vCPU|vcpu|VCPU)?$
Required: Yes disk
The disk requirements for every worker instance of the worker type.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 15.
Pattern: ^[1-9][0-9]*(\s)?(GB|gb|gB|Gb)$
Required: No memory
The memory requirements for every worker instance of the worker type.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 15.
Pattern: ^[1-9][0-9]*(\s)?(GB|gb|gB|Gb)?$
Required: Yes
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3
Common Parameters
The following list contains the parameters that all actions use for signing Signature Version 4 requests with a query string. Any action-specific parameters are listed in the topic for that action. For more information about Signature Version 4, see Signature Version 4 Signing Process in the Amazon Web Services General Reference.
Action
The action to be performed.
Type: string Required: Yes Version
The API version that the request is written for, expressed in the format YYYY-MM-DD.
Type: string Required: Yes X-Amz-Algorithm
The hash algorithm that you used to create the request signature.
Condition: Specify this parameter when you include authentication information in a query string instead of in the HTTP authorization header.
Type: string
Valid Values: AWS4-HMAC-SHA256 Required: Conditional
X-Amz-Credential
The credential scope value, which is a string that includes your access key, the date, the region you are targeting, the service you are requesting, and a termination string ("aws4_request"). The value is expressed in the following format: access_key/YYYYMMDD/region/service/aws4_request.
For more information, see Task 2: Create a String to Sign for Signature Version 4 in the Amazon Web Services General Reference.
Condition: Specify this parameter when you include authentication information in a query string instead of in the HTTP authorization header.
Type: string
Required: Conditional X-Amz-Date
The date that is used to create the signature. The format must be ISO 8601 basic format (YYYYMMDD'T'HHMMSS'Z'). For example, the following date time is a valid X-Amz-Date value:
20120325T120000Z.
Condition: X-Amz-Date is optional for all requests; it can be used to override the date used for signing requests. If the Date header is specified in the ISO 8601 basic format, X-Amz-Date is
not required. When X-Amz-Date is used, it always overrides the value of the Date header. For more information, see Handling Dates in Signature Version 4 in the Amazon Web Services General Reference.
Type: string
Required: Conditional X-Amz-Security-Token
The temporary security token that was obtained through a call to AWS Security Token Service (AWS STS). For a list of services that support temporary security credentials from AWS Security Token Service, go to AWS Services That Work with IAM in the IAM User Guide.
Condition: If you're using temporary security credentials from the AWS Security Token Service, you must include the security token.
Type: string
Required: Conditional X-Amz-Signature
Specifies the hex-encoded signature that was calculated from the string to sign and the derived signing key.
Condition: Specify this parameter when you include authentication information in a query string instead of in the HTTP authorization header.
Type: string
Required: Conditional X-Amz-SignedHeaders
Specifies all the HTTP headers that were included as part of the canonical request. For more information about specifying signed headers, see Task 1: Create a Canonical Request For Signature Version 4 in the Amazon Web Services General Reference.
Condition: Specify this parameter when you include authentication information in a query string instead of in the HTTP authorization header.
Type: string
Required: Conditional
Common Errors
This section lists the errors common to the API actions of all AWS services. For errors specific to an API action for this service, see the topic for that API action.
AccessDeniedException
You do not have sufficient access to perform this action.
HTTP Status Code: 400 IncompleteSignature
The request signature does not conform to AWS standards.
HTTP Status Code: 400 InternalFailure
The request processing has failed because of an unknown error, exception or failure.
HTTP Status Code: 500 InvalidAction
The action or operation requested is invalid. Verify that the action is typed correctly.
HTTP Status Code: 400 InvalidClientTokenId
The X.509 certificate or AWS access key ID provided does not exist in our records.
HTTP Status Code: 403 InvalidParameterCombination
Parameters that must not be used together were used together.
HTTP Status Code: 400 InvalidParameterValue
An invalid or out-of-range value was supplied for the input parameter.
HTTP Status Code: 400 InvalidQueryParameter
The AWS query string is malformed or does not adhere to AWS standards.
HTTP Status Code: 400 MalformedQueryString
The query string contains a syntax error.
HTTP Status Code: 404 MissingAction
The request is missing an action or a required parameter.
HTTP Status Code: 400
MissingAuthenticationToken
The request must contain either a valid (registered) AWS access key ID or X.509 certificate.
HTTP Status Code: 403 MissingParameter
A required parameter for the specified action is not supplied.
HTTP Status Code: 400 NotAuthorized
You do not have permission to perform this action.
HTTP Status Code: 400 OptInRequired
The AWS access key ID needs a subscription for the service.
HTTP Status Code: 403 RequestExpired
The request reached the service more than 15 minutes after the date stamp on the request or more than 15 minutes after the request expiration date (such as for pre-signed URLs), or the date stamp on the request is more than 15 minutes in the future.
HTTP Status Code: 400 ServiceUnavailable
The request has failed due to a temporary failure of the server.
HTTP Status Code: 503 ThrottlingException
The request was denied due to request throttling.
HTTP Status Code: 400 ValidationError
The input fails to satisfy the constraints specified by an AWS service.
HTTP Status Code: 400
