SFN / Client / create_state_machine

create_state_machine#

SFN.Client.create_state_machine(**kwargs)#

Creates a state machine. A state machine consists of a collection of states that can do work ( Task states), determine to which states to transition next ( Choice states), stop an execution with an error ( Fail states), and so on. State machines are specified using a JSON-based, structured language. For more information, see Amazon States Language in the Step Functions User Guide.

If you set the publish parameter of this API action to true, it publishes version 1 as the first revision of the state machine.

For additional control over security, you can encrypt your data using a customer-managed key for Step Functions state machines. You can configure a symmetric KMS key and data key reuse period when creating or updating a State Machine. The execution history and state machine definition will be encrypted with the key applied to the State Machine.

Note

This operation is eventually consistent. The results are best effort and may not reflect very recent updates and changes.

Note

CreateStateMachine is an idempotent API. Subsequent requests won’t create a duplicate resource if it was already created. CreateStateMachine’s idempotency check is based on the state machine name, definition, type, LoggingConfiguration, TracingConfiguration, and EncryptionConfiguration The check is also based on the publish and versionDescription parameters. If a following request has a different roleArn or tags, Step Functions will ignore these differences and treat it as an idempotent request of the previous. In this case, roleArn and tags will not be updated, even if they are different.

Request Syntax

response = client.create_state_machine(
    name='string',
    definition='string',
    roleArn='string',
    type='STANDARD'|'EXPRESS',
    loggingConfiguration={
        'level': 'ALL'|'ERROR'|'FATAL'|'OFF',
        'includeExecutionData': True|False,
        'destinations': [
            {
                'cloudWatchLogsLogGroup': {
                    'logGroupArn': 'string'
                }
            },
        ]
    },
    tags=[
        {
            'key': 'string',
            'value': 'string'
        },
    ],
    tracingConfiguration={
        'enabled': True|False
    },
    publish=True|False,
    versionDescription='string',
    encryptionConfiguration={
        'kmsKeyId': 'string',
        'kmsDataKeyReusePeriodSeconds': 123,
        'type': 'AWS_OWNED_KEY'|'CUSTOMER_MANAGED_KMS_KEY'
    }
)

Parameters:

name (string) –
[REQUIRED]

The name of the state machine.

A name must not contain:
- white space
- brackets < > { } [ ]
- wildcard characters ? *
- special characters " # % \ ^ | ~ ` $ & , ; : /
- control characters ( U+0000-001F, U+007F-009F)
To enable logging with CloudWatch Logs, the name should only contain 0-9, A-Z, a-z, - and _.
definition (string) –
[REQUIRED]

The Amazon States Language definition of the state machine. See Amazon States Language.
roleArn (string) –
[REQUIRED]

The Amazon Resource Name (ARN) of the IAM role to use for this state machine.
type (string) – Determines whether a Standard or Express state machine is created. The default is STANDARD. You cannot update the type of a state machine once it has been created.
loggingConfiguration (dict) –
Defines what execution history events are logged and where they are logged.

Note
By default, the level is set to OFF. For more information see Log Levels in the Step Functions User Guide.
- level (string) –
  
  Defines which category of execution history events are logged.
- includeExecutionData (boolean) –
  
  Determines whether execution data is included in your log. When set to false, data is excluded.
- destinations (list) –
  
  An array of objects that describes where your execution history events will be logged. Limited to size 1. Required, if your log level is not set to OFF.
  - (dict) –
    - cloudWatchLogsLogGroup (dict) –
      
      An object describing a CloudWatch log group. For more information, see AWS::Logs::LogGroup in the CloudFormation User Guide.
      - logGroupArn (string) –
        
        The ARN of the the CloudWatch log group to which you want your logs emitted to. The ARN must end with :*
tags (list) –
Tags to be added when creating a state machine.

An array of key-value pairs. For more information, see Using Cost Allocation Tags in the Amazon Web Services Billing and Cost Management User Guide, and Controlling Access Using IAM Tags.

Tags may only contain Unicode letters, digits, white space, or these symbols: _ . : / = + - @.
- (dict) –
  
  Tags are key-value pairs that can be associated with Step Functions state machines and activities.
  
  An array of key-value pairs. For more information, see Using Cost Allocation Tags in the Amazon Web Services Billing and Cost Management User Guide, and Controlling Access Using IAM Tags.
  
  Tags may only contain Unicode letters, digits, white space, or these symbols: _ . : / = + - @.
  - key (string) –
    
    The key of a tag.
  - value (string) –
    
    The value of a tag.
tracingConfiguration (dict) –
Selects whether X-Ray tracing is enabled.
- enabled (boolean) –
  
  When set to true, X-Ray tracing is enabled.
publish (boolean) – Set to true to publish the first version of the state machine during creation. The default is false.
versionDescription (string) – Sets description about the state machine version. You can only set the description if the publish parameter is set to true. Otherwise, if you set versionDescription, but publish to false, this API action throws ValidationException.
encryptionConfiguration (dict) –
Settings to configure server-side encryption.
- kmsKeyId (string) –
  
  An alias, alias ARN, key ID, or key ARN of a symmetric encryption KMS key to encrypt data. To specify a KMS key in a different Amazon Web Services account, you must use the key ARN or alias ARN.
- kmsDataKeyReusePeriodSeconds (integer) –
  
  Maximum duration that Step Functions will reuse data keys. When the period expires, Step Functions will call GenerateDataKey. Only applies to customer managed keys.
- type (string) – [REQUIRED]
  
  Encryption type

Return type:

dict

Returns:

Response Syntax

{
    'stateMachineArn': 'string',
    'creationDate': datetime(2015, 1, 1),
    'stateMachineVersionArn': 'string'
}

Response Structure

(dict) –
- stateMachineArn (string) –
  
  The Amazon Resource Name (ARN) that identifies the created state machine.
- creationDate (datetime) –
  
  The date the state machine is created.
- stateMachineVersionArn (string) –
  
  The Amazon Resource Name (ARN) that identifies the created state machine version. If you do not set the publish parameter to true, this field returns null value.

Exceptions

SFN.Client.exceptions.InvalidArn
SFN.Client.exceptions.InvalidDefinition
SFN.Client.exceptions.InvalidName
SFN.Client.exceptions.InvalidLoggingConfiguration
SFN.Client.exceptions.InvalidTracingConfiguration
SFN.Client.exceptions.StateMachineAlreadyExists
SFN.Client.exceptions.StateMachineDeleting
SFN.Client.exceptions.StateMachineLimitExceeded
SFN.Client.exceptions.StateMachineTypeNotSupported
SFN.Client.exceptions.TooManyTags
SFN.Client.exceptions.ValidationException
SFN.Client.exceptions.ConflictException
SFN.Client.exceptions.InvalidEncryptionConfiguration
SFN.Client.exceptions.KmsAccessDeniedException
SFN.Client.exceptions.KmsThrottlingException