Request Syntax Request Parameters Response Syntax Response Elements Errors See Also

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 of RoutingConfig 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 each RoutingConfig.

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 to true.

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