2024/07/25 - AWS Step Functions - 8 updated api methods
Changes This release adds support to customer managed KMS key encryption in AWS Step Functions.
{'encryptionConfiguration': {'kmsDataKeyReusePeriodSeconds': 'integer',
'kmsKeyId': 'string',
'type': 'AWS_OWNED_KEY | '
'CUSTOMER_MANAGED_KMS_KEY'}}
Creates an activity. An activity is a task that you write in any programming language and host on any machine that has access to Step Functions. Activities must poll Step Functions using the GetActivityTask API action and respond using SendTask* API actions. This function lets Step Functions know the existence of your activity and returns an identifier for use in a state machine and when polling from the activity.
Note
This operation is eventually consistent. The results are best effort and may not reflect very recent updates and changes.
Note
CreateActivity is an idempotent API. Subsequent requests won’t create a duplicate resource if it was already created. CreateActivity 's idempotency check is based on the activity name . If a following request has different tags values, Step Functions will ignore these differences and treat it as an idempotent request of the previous. In this case, tags will not be updated, even if they are different.
See also: AWS API Documentation
Request Syntax
client.create_activity(
name='string',
tags=[
{
'key': 'string',
'value': 'string'
},
],
encryptionConfiguration={
'kmsKeyId': 'string',
'kmsDataKeyReusePeriodSeconds': 123,
'type': 'AWS_OWNED_KEY'|'CUSTOMER_MANAGED_KMS_KEY'
}
)
string
[REQUIRED]
The name of the activity to create. This name must be unique for your Amazon Web Services account and region for 90 days. For more information, see Limits Related to State Machine Executions in the Step Functions Developer Guide .
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 _.
list
The list of tags to add to a resource.
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.
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
dict
Response Syntax
{
'activityArn': 'string',
'creationDate': datetime(2015, 1, 1)
}
Response Structure
(dict) --
activityArn (string) --
The Amazon Resource Name (ARN) that identifies the created activity.
creationDate (datetime) --
The date the activity is created.
{'encryptionConfiguration': {'kmsDataKeyReusePeriodSeconds': 'integer',
'kmsKeyId': 'string',
'type': 'AWS_OWNED_KEY | '
'CUSTOMER_MANAGED_KMS_KEY'}}
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.
See also: AWS API Documentation
Request Syntax
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'
}
)
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 _.
string
[REQUIRED]
The Amazon States Language definition of the state machine. See Amazon States Language.
string
[REQUIRED]
The Amazon Resource Name (ARN) of the IAM role to use for this state machine.
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.
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 :*
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.
dict
Selects whether X-Ray tracing is enabled.
enabled (boolean) --
When set to true , X-Ray tracing is enabled.
boolean
Set to true to publish the first version of the state machine during creation. The default is false .
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 .
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
dict
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.
{'encryptionConfiguration': {'kmsDataKeyReusePeriodSeconds': 'integer',
'kmsKeyId': 'string',
'type': 'AWS_OWNED_KEY | '
'CUSTOMER_MANAGED_KMS_KEY'}}
Describes an activity.
Note
This operation is eventually consistent. The results are best effort and may not reflect very recent updates and changes.
See also: AWS API Documentation
Request Syntax
client.describe_activity(
activityArn='string'
)
string
[REQUIRED]
The Amazon Resource Name (ARN) of the activity to describe.
dict
Response Syntax
{
'activityArn': 'string',
'name': 'string',
'creationDate': datetime(2015, 1, 1),
'encryptionConfiguration': {
'kmsKeyId': 'string',
'kmsDataKeyReusePeriodSeconds': 123,
'type': 'AWS_OWNED_KEY'|'CUSTOMER_MANAGED_KMS_KEY'
}
}
Response Structure
(dict) --
activityArn (string) --
The Amazon Resource Name (ARN) that identifies the activity.
name (string) --
The name of the activity.
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 _.
creationDate (datetime) --
The date the activity is created.
encryptionConfiguration (dict) --
Settings for configured 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) --
Encryption type
{'includedData': 'ALL_DATA | METADATA_ONLY'}
Provides information about a state machine execution, such as the state machine associated with the execution, the execution input and output, and relevant execution metadata. If you've redriven an execution, you can use this API action to return information about the redrives of that execution. In addition, you can use this API action to return the Map Run Amazon Resource Name (ARN) if the execution was dispatched by a Map Run.
If you specify a version or alias ARN when you call the StartExecution API action, DescribeExecution returns that ARN.
Note
This operation is eventually consistent. The results are best effort and may not reflect very recent updates and changes.
Executions of an EXPRESS state machine aren't supported by DescribeExecution unless a Map Run dispatched them.
See also: AWS API Documentation
Request Syntax
client.describe_execution(
executionArn='string',
includedData='ALL_DATA'|'METADATA_ONLY'
)
string
[REQUIRED]
The Amazon Resource Name (ARN) of the execution to describe.
string
If your state machine definition is encrypted with a KMS key, callers must have kms:Decrypt permission to decrypt the definition. Alternatively, you can call DescribeStateMachine API with includedData = METADATA_ONLY to get a successful response without the encrypted definition.
dict
Response Syntax
{
'executionArn': 'string',
'stateMachineArn': 'string',
'name': 'string',
'status': 'RUNNING'|'SUCCEEDED'|'FAILED'|'TIMED_OUT'|'ABORTED'|'PENDING_REDRIVE',
'startDate': datetime(2015, 1, 1),
'stopDate': datetime(2015, 1, 1),
'input': 'string',
'inputDetails': {
'included': True|False
},
'output': 'string',
'outputDetails': {
'included': True|False
},
'traceHeader': 'string',
'mapRunArn': 'string',
'error': 'string',
'cause': 'string',
'stateMachineVersionArn': 'string',
'stateMachineAliasArn': 'string',
'redriveCount': 123,
'redriveDate': datetime(2015, 1, 1),
'redriveStatus': 'REDRIVABLE'|'NOT_REDRIVABLE'|'REDRIVABLE_BY_MAP_RUN',
'redriveStatusReason': 'string'
}
Response Structure
(dict) --
executionArn (string) --
The Amazon Resource Name (ARN) that identifies the execution.
stateMachineArn (string) --
The Amazon Resource Name (ARN) of the executed stated machine.
name (string) --
The name of the execution.
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 _.
status (string) --
The current status of the execution.
startDate (datetime) --
The date the execution is started.
stopDate (datetime) --
If the execution ended, the date the execution stopped.
input (string) --
The string that contains the JSON input data of the execution. Length constraints apply to the payload size, and are expressed as bytes in UTF-8 encoding.
inputDetails (dict) --
Provides details about execution input or output.
included (boolean) --
Indicates whether input or output was included in the response. Always true for API calls.
output (string) --
The JSON output data of the execution. Length constraints apply to the payload size, and are expressed as bytes in UTF-8 encoding.
Note
This field is set only if the execution succeeds. If the execution fails, this field is null.
outputDetails (dict) --
Provides details about execution input or output.
included (boolean) --
Indicates whether input or output was included in the response. Always true for API calls.
traceHeader (string) --
The X-Ray trace header that was passed to the execution.
mapRunArn (string) --
The Amazon Resource Name (ARN) that identifies a Map Run, which dispatched this execution.
error (string) --
The error string if the state machine execution failed.
cause (string) --
The cause string if the state machine execution failed.
stateMachineVersionArn (string) --
The Amazon Resource Name (ARN) of the state machine version associated with the execution. The version ARN is a combination of state machine ARN and the version number separated by a colon (:). For example, stateMachineARN:1 .
If you start an execution from a StartExecution request without specifying a state machine version or alias ARN, Step Functions returns a null value.
stateMachineAliasArn (string) --
The Amazon Resource Name (ARN) of the state machine alias associated with the execution. The alias ARN is a combination of state machine ARN and the alias name separated by a colon (:). For example, stateMachineARN:PROD .
If you start an execution from a StartExecution request with a state machine version ARN, this field will be null.
redriveCount (integer) --
The number of times you've redriven an execution. If you have not yet redriven an execution, the redriveCount is 0. This count is only updated if you successfully redrive an execution.
redriveDate (datetime) --
The date the execution was last redriven. If you have not yet redriven an execution, the redriveDate is null.
The redriveDate is unavailable if you redrive a Map Run that starts child workflow executions of type EXPRESS .
redriveStatus (string) --
Indicates whether or not an execution can be redriven at a given point in time.
For executions of type STANDARD , redriveStatus is NOT_REDRIVABLE if calling the RedriveExecution API action would return the ExecutionNotRedrivable error.
For a Distributed Map that includes child workflows of type STANDARD , redriveStatus indicates whether or not the Map Run can redrive child workflow executions.
For a Distributed Map that includes child workflows of type EXPRESS , redriveStatus indicates whether or not the Map Run can redrive child workflow executions. You can redrive failed or timed out EXPRESS workflows only if they're a part of a Map Run. When you redrive the Map Run, these workflows are restarted using the StartExecution API action.
redriveStatusReason (string) --
When redriveStatus is NOT_REDRIVABLE , redriveStatusReason specifies the reason why an execution cannot be redriven.
For executions of type STANDARD , or for a Distributed Map that includes child workflows of type STANDARD , redriveStatusReason can include one of the following reasons:
State machine is in DELETING status .
Execution is RUNNING and cannot be redriven .
Execution is SUCCEEDED and cannot be redriven .
Execution was started before the launch of RedriveExecution .
Execution history event limit exceeded .
Execution has exceeded the max execution time .
Execution redrivable period exceeded .
For a Distributed Map that includes child workflows of type EXPRESS , redriveStatusReason is only returned if the child workflows are not redrivable. This happens when the child workflow executions have completed successfully.
{'includedData': 'ALL_DATA | METADATA_ONLY'}
Response {'encryptionConfiguration': {'kmsDataKeyReusePeriodSeconds': 'integer',
'kmsKeyId': 'string',
'type': 'AWS_OWNED_KEY | '
'CUSTOMER_MANAGED_KMS_KEY'}}
Provides information about a state machine's definition, its IAM role Amazon Resource Name (ARN), and configuration.
A qualified state machine ARN can either refer to a Distributed Map state defined within a state machine, a version ARN, or an alias ARN.
The following are some examples of qualified and unqualified state machine ARNs:
The following qualified state machine ARN refers to a Distributed Map state with a label mapStateLabel in a state machine named myStateMachine . arn:partition:states:region:account-id:stateMachine:myStateMachine/mapStateLabel
Note
If you provide a qualified state machine ARN that refers to a Distributed Map state , the request fails with ValidationException .
The following qualified state machine ARN refers to an alias named PROD . arn:<partition>:states:<region>:<account-id>:stateMachine:<myStateMachine:PROD>
Note
If you provide a qualified state machine ARN that refers to a version ARN or an alias ARN, the request starts execution for that version or alias.
The following unqualified state machine ARN refers to a state machine named myStateMachine . arn:<partition>:states:<region>:<account-id>:stateMachine:<myStateMachine>
This API action returns the details for a state machine version if the stateMachineArn you specify is a state machine version ARN.
Note
This operation is eventually consistent. The results are best effort and may not reflect very recent updates and changes.
See also: AWS API Documentation
Request Syntax
client.describe_state_machine(
stateMachineArn='string',
includedData='ALL_DATA'|'METADATA_ONLY'
)
string
[REQUIRED]
The Amazon Resource Name (ARN) of the state machine for which you want the information.
If you specify a state machine version ARN, this API returns details about that version. The version ARN is a combination of state machine ARN and the version number separated by a colon (:). For example, stateMachineARN:1 .
string
If your state machine definition is encrypted with a KMS key, callers must have kms:Decrypt permission to decrypt the definition. Alternatively, you can call the API with includedData = METADATA_ONLY to get a successful response without the encrypted definition.
Note
When calling a labelled ARN for an encrypted state machine, the includedData = METADATA_ONLY parameter will not apply because Step Functions needs to decrypt the entire state machine definition to get the Distributed Map state’s definition. In this case, the API caller needs to have kms:Decrypt permission.
dict
Response Syntax
{
'stateMachineArn': 'string',
'name': 'string',
'status': 'ACTIVE'|'DELETING',
'definition': 'string',
'roleArn': 'string',
'type': 'STANDARD'|'EXPRESS',
'creationDate': datetime(2015, 1, 1),
'loggingConfiguration': {
'level': 'ALL'|'ERROR'|'FATAL'|'OFF',
'includeExecutionData': True|False,
'destinations': [
{
'cloudWatchLogsLogGroup': {
'logGroupArn': 'string'
}
},
]
},
'tracingConfiguration': {
'enabled': True|False
},
'label': 'string',
'revisionId': 'string',
'description': 'string',
'encryptionConfiguration': {
'kmsKeyId': 'string',
'kmsDataKeyReusePeriodSeconds': 123,
'type': 'AWS_OWNED_KEY'|'CUSTOMER_MANAGED_KMS_KEY'
}
}
Response Structure
(dict) --
stateMachineArn (string) --
The Amazon Resource Name (ARN) that identifies the state machine.
If you specified a state machine version ARN in your request, the API returns the version ARN. The version ARN is a combination of state machine ARN and the version number separated by a colon (:). For example, stateMachineARN:1 .
name (string) --
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 _.
status (string) --
The current status of the state machine.
definition (string) --
The Amazon States Language definition of the state machine. See Amazon States Language.
If called with includedData = METADATA_ONLY , the returned definition will be {} .
roleArn (string) --
The Amazon Resource Name (ARN) of the IAM role used when creating this state machine. (The IAM role maintains security by granting Step Functions access to Amazon Web Services resources.)
type (string) --
The type of the state machine ( STANDARD or EXPRESS ).
creationDate (datetime) --
The date the state machine is created.
For a state machine version, creationDate is the date the version was created.
loggingConfiguration (dict) --
The LoggingConfiguration data type is used to set CloudWatch Logs options.
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 :*
tracingConfiguration (dict) --
Selects whether X-Ray tracing is enabled.
enabled (boolean) --
When set to true , X-Ray tracing is enabled.
label (string) --
A user-defined or an auto-generated string that identifies a Map state. This parameter is present only if the stateMachineArn specified in input is a qualified state machine ARN.
revisionId (string) --
The revision identifier for the state machine.
Use the revisionId parameter to compare between versions of a state machine configuration used for executions without performing a diff of the properties, such as definition and roleArn .
description (string) --
The description of the state machine version.
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) --
Encryption type
{'includedData': 'ALL_DATA | METADATA_ONLY'}
Response {'encryptionConfiguration': {'kmsDataKeyReusePeriodSeconds': 'integer',
'kmsKeyId': 'string',
'type': 'AWS_OWNED_KEY | '
'CUSTOMER_MANAGED_KMS_KEY'}}
Provides information about a state machine's definition, its execution role ARN, and configuration. If a Map Run dispatched the execution, this action returns the Map Run Amazon Resource Name (ARN) in the response. The state machine returned is the state machine associated with the Map Run.
Note
This operation is eventually consistent. The results are best effort and may not reflect very recent updates and changes.
This API action is not supported by EXPRESS state machines.
See also: AWS API Documentation
Request Syntax
client.describe_state_machine_for_execution(
executionArn='string',
includedData='ALL_DATA'|'METADATA_ONLY'
)
string
[REQUIRED]
The Amazon Resource Name (ARN) of the execution you want state machine information for.
string
If your state machine definition is encrypted with a KMS key, callers must have kms:Decrypt permission to decrypt the definition. Alternatively, you can call the API with includedData = METADATA_ONLY to get a successful response without the encrypted definition.
dict
Response Syntax
{
'stateMachineArn': 'string',
'name': 'string',
'definition': 'string',
'roleArn': 'string',
'updateDate': datetime(2015, 1, 1),
'loggingConfiguration': {
'level': 'ALL'|'ERROR'|'FATAL'|'OFF',
'includeExecutionData': True|False,
'destinations': [
{
'cloudWatchLogsLogGroup': {
'logGroupArn': 'string'
}
},
]
},
'tracingConfiguration': {
'enabled': True|False
},
'mapRunArn': 'string',
'label': 'string',
'revisionId': 'string',
'encryptionConfiguration': {
'kmsKeyId': 'string',
'kmsDataKeyReusePeriodSeconds': 123,
'type': 'AWS_OWNED_KEY'|'CUSTOMER_MANAGED_KMS_KEY'
}
}
Response Structure
(dict) --
stateMachineArn (string) --
The Amazon Resource Name (ARN) of the state machine associated with the execution.
name (string) --
The name of the state machine associated with the execution.
definition (string) --
The Amazon States Language definition of the state machine. See Amazon States Language.
roleArn (string) --
The Amazon Resource Name (ARN) of the IAM role of the State Machine for the execution.
updateDate (datetime) --
The date and time the state machine associated with an execution was updated. For a newly created state machine, this is the creation date.
loggingConfiguration (dict) --
The LoggingConfiguration data type is used to set CloudWatch Logs options.
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 :*
tracingConfiguration (dict) --
Selects whether X-Ray tracing is enabled.
enabled (boolean) --
When set to true , X-Ray tracing is enabled.
mapRunArn (string) --
The Amazon Resource Name (ARN) of the Map Run that started the child workflow execution. This field is returned only if the executionArn is a child workflow execution that was started by a Distributed Map state.
label (string) --
A user-defined or an auto-generated string that identifies a Map state. This field is returned only if the executionArn is a child workflow execution that was started by a Distributed Map state.
revisionId (string) --
The revision identifier for the state machine. The first revision ID when you create the state machine is null.
Use the state machine revisionId parameter to compare the revision of a state machine with the configuration of the state machine used for executions without performing a diff of the properties, such as definition and roleArn .
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) --
Encryption type
{'includedData': 'ALL_DATA | METADATA_ONLY'}
Starts a Synchronous Express state machine execution. StartSyncExecution is not available for STANDARD workflows.
Note
StartSyncExecution will return a 200 OK response, even if your execution fails, because the status code in the API response doesn't reflect function errors. Error codes are reserved for errors that prevent your execution from running, such as permissions errors, limit errors, or issues with your state machine code and configuration.
Note
This API action isn't logged in CloudTrail.
See also: AWS API Documentation
Request Syntax
client.start_sync_execution(
stateMachineArn='string',
name='string',
input='string',
traceHeader='string',
includedData='ALL_DATA'|'METADATA_ONLY'
)
string
[REQUIRED]
The Amazon Resource Name (ARN) of the state machine to execute.
string
The name of the execution.
string
The string that contains the JSON input data for the execution, for example:
"input": "{\"first_name\" : \"test\"}"
Note
If you don't include any JSON input data, you still must include the two braces, for example: "input": "{}"
Length constraints apply to the payload size, and are expressed as bytes in UTF-8 encoding.
string
Passes the X-Ray trace header. The trace header can also be passed in the request payload.
string
If your state machine definition is encrypted with a KMS key, callers must have kms:Decrypt permission to decrypt the definition. Alternatively, you can call the API with includedData = METADATA_ONLY to get a successful response without the encrypted definition.
dict
Response Syntax
{
'executionArn': 'string',
'stateMachineArn': 'string',
'name': 'string',
'startDate': datetime(2015, 1, 1),
'stopDate': datetime(2015, 1, 1),
'status': 'SUCCEEDED'|'FAILED'|'TIMED_OUT',
'error': 'string',
'cause': 'string',
'input': 'string',
'inputDetails': {
'included': True|False
},
'output': 'string',
'outputDetails': {
'included': True|False
},
'traceHeader': 'string',
'billingDetails': {
'billedMemoryUsedInMB': 123,
'billedDurationInMilliseconds': 123
}
}
Response Structure
(dict) --
executionArn (string) --
The Amazon Resource Name (ARN) that identifies the execution.
stateMachineArn (string) --
The Amazon Resource Name (ARN) that identifies the state machine.
name (string) --
The name of the execution.
startDate (datetime) --
The date the execution is started.
stopDate (datetime) --
If the execution has already ended, the date the execution stopped.
status (string) --
The current status of the execution.
error (string) --
The error code of the failure.
cause (string) --
A more detailed explanation of the cause of the failure.
input (string) --
The string that contains the JSON input data of the execution. Length constraints apply to the payload size, and are expressed as bytes in UTF-8 encoding.
inputDetails (dict) --
Provides details about execution input or output.
included (boolean) --
Indicates whether input or output was included in the response. Always true for API calls.
output (string) --
The JSON output data of the execution. Length constraints apply to the payload size, and are expressed as bytes in UTF-8 encoding.
Note
This field is set only if the execution succeeds. If the execution fails, this field is null.
outputDetails (dict) --
Provides details about execution input or output.
included (boolean) --
Indicates whether input or output was included in the response. Always true for API calls.
traceHeader (string) --
The X-Ray trace header that was passed to the execution.
billingDetails (dict) --
An object that describes workflow billing details, including billed duration and memory use.
billedMemoryUsedInMB (integer) --
Billed memory consumption of your workflow, in MB.
billedDurationInMilliseconds (integer) --
Billed duration of your workflow, in milliseconds.
{'encryptionConfiguration': {'kmsDataKeyReusePeriodSeconds': 'integer',
'kmsKeyId': 'string',
'type': 'AWS_OWNED_KEY | '
'CUSTOMER_MANAGED_KMS_KEY'}}
Updates an existing state machine by modifying its definition , roleArn , loggingConfiguration , or EncryptionConfiguration . Running executions will continue to use the previous definition and roleArn . You must include at least one of definition or roleArn or you will receive a MissingRequiredParameter error.
A qualified state machine ARN refers to a Distributed Map state defined within a state machine. For example, the qualified state machine ARN arn:partition:states:region:account-id:stateMachine:stateMachineName/mapStateLabel refers to a Distributed Map state with a label mapStateLabel in the state machine named stateMachineName .
A qualified state machine ARN can either refer to a Distributed Map state defined within a state machine, a version ARN, or an alias ARN.
The following are some examples of qualified and unqualified state machine ARNs:
The following qualified state machine ARN refers to a Distributed Map state with a label mapStateLabel in a state machine named myStateMachine . arn:partition:states:region:account-id:stateMachine:myStateMachine/mapStateLabel
Note
If you provide a qualified state machine ARN that refers to a Distributed Map state , the request fails with ValidationException .
The following qualified state machine ARN refers to an alias named PROD . arn:<partition>:states:<region>:<account-id>:stateMachine:<myStateMachine:PROD>
Note
If you provide a qualified state machine ARN that refers to a version ARN or an alias ARN, the request starts execution for that version or alias.
The following unqualified state machine ARN refers to a state machine named myStateMachine . arn:<partition>:states:<region>:<account-id>:stateMachine:<myStateMachine>
After you update your state machine, you can set the publish parameter to true in the same action to publish a new version. This way, you can opt-in to strict versioning of your state machine.
Note
Step Functions assigns monotonically increasing integers for state machine versions, starting at version number 1.
Note
All StartExecution calls within a few seconds use the updated definition and roleArn . Executions started immediately after you call UpdateStateMachine may use the previous state machine definition and roleArn .
See also: AWS API Documentation
Request Syntax
client.update_state_machine(
stateMachineArn='string',
definition='string',
roleArn='string',
loggingConfiguration={
'level': 'ALL'|'ERROR'|'FATAL'|'OFF',
'includeExecutionData': True|False,
'destinations': [
{
'cloudWatchLogsLogGroup': {
'logGroupArn': 'string'
}
},
]
},
tracingConfiguration={
'enabled': True|False
},
publish=True|False,
versionDescription='string',
encryptionConfiguration={
'kmsKeyId': 'string',
'kmsDataKeyReusePeriodSeconds': 123,
'type': 'AWS_OWNED_KEY'|'CUSTOMER_MANAGED_KMS_KEY'
}
)
string
[REQUIRED]
The Amazon Resource Name (ARN) of the state machine.
string
The Amazon States Language definition of the state machine. See Amazon States Language.
string
The Amazon Resource Name (ARN) of the IAM role of the state machine.
dict
Use the LoggingConfiguration data type to set CloudWatch Logs options.
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 :*
dict
Selects whether X-Ray tracing is enabled.
enabled (boolean) --
When set to true , X-Ray tracing is enabled.
boolean
Specifies whether the state machine version is published. The default is false . To publish a version after updating the state machine, set publish to true .
string
An optional description of the state machine version to publish.
You can only specify the versionDescription parameter if you've set publish to true .
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
dict
Response Syntax
{
'updateDate': datetime(2015, 1, 1),
'revisionId': 'string',
'stateMachineVersionArn': 'string'
}
Response Structure
(dict) --
updateDate (datetime) --
The date and time the state machine was updated.
revisionId (string) --
The revision identifier for the updated state machine.
stateMachineVersionArn (string) --
The Amazon Resource Name (ARN) of the published state machine version.
If the publish parameter isn't set to true , this field returns null.