CreateStateMachineAlias
Creates an alias for a state machine that points to one or two versions of the same state machine. You can set your application to call StartExecution with an alias and update the version the alias uses without changing the client's code.
You can also map an alias to split StartExecution requests between two
versions of a state machine. To do this, add a second RoutingConfig
object in the
routingConfiguration
parameter. You must also specify the percentage of
execution run requests each version should receive in both RoutingConfig
objects.
Step Functions randomly chooses which version runs a given execution based on the
percentage you specify.
To create an alias that points to a single version, specify a single
RoutingConfig
object with a weight
set to 100.
You can create up to 100 aliases for each state machine. You must delete unused aliases using the DeleteStateMachineAlias API action.
CreateStateMachineAlias
is an idempotent API. Step Functions bases the
idempotency check on the stateMachineArn
, description
,
name
, and routingConfiguration
parameters. Requests that contain
the same values for these parameters return a successful idempotent response without creating
a duplicate resource.
Related operations:
Request Syntax
{
"description": "string
",
"name": "string
",
"routingConfiguration": [
{
"stateMachineVersionArn": "string
",
"weight": number
}
]
}
Request Parameters
For information about the parameters that are common to all actions, see Common Parameters.
The request accepts the following data in JSON format.
- description
-
A description for the state machine alias.
Type: String
Length Constraints: Maximum length of 256.
Required: No
- name
-
The name of the state machine alias.
To avoid conflict with version ARNs, don't use an integer in the name of the alias.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 80.
Pattern:
^(?=.*[a-zA-Z_\-\.])[a-zA-Z0-9_\-\.]+$
Required: Yes
- routingConfiguration
-
The routing configuration of a state machine alias. The routing configuration shifts execution traffic between two state machine versions.
routingConfiguration
contains an array ofRoutingConfig
objects that specify up to two state machine versions. Step Functions then randomly choses which version to run an execution with based on the weight assigned to eachRoutingConfig
.Type: Array of RoutingConfigurationListItem objects
Array Members: Minimum number of 1 item. Maximum number of 2 items.
Required: Yes
Response Syntax
{
"creationDate": number,
"stateMachineAliasArn": "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.
- creationDate
-
The date the state machine alias was created.
Type: Timestamp
- stateMachineAliasArn
-
The Amazon Resource Name (ARN) that identifies the created state machine alias.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 256.
Errors
For information about the errors that are common to all actions, see Common Errors.
- ConflictException
-
Updating or deleting a resource can cause an inconsistent state. This error occurs when there're concurrent requests for DeleteStateMachineVersion, PublishStateMachineVersion, or UpdateStateMachine with the
publish
parameter set totrue
.HTTP Status Code: 409
HTTP Status Code: 400
- InvalidArn
-
The provided Amazon Resource Name (ARN) is not valid.
HTTP Status Code: 400
- InvalidName
-
The provided name is not valid.
HTTP Status Code: 400
- ResourceNotFound
-
Could not find the referenced resource.
HTTP Status Code: 400
- ServiceQuotaExceededException
-
The request would cause a service quota to be exceeded.
HTTP Status Code: 402
HTTP Status Code: 400
- StateMachineDeleting
-
The specified state machine is being deleted.
HTTP Status Code: 400
- ValidationException
-
The input does not 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: