Learning to use AWS service SDK integrations in Step Functions

AWS Step Functions integrates with AWS services, so you can call service's API actions from your workflows. You can use Step Functions' AWS SDK integrations to call almost any AWS service's API actions from your state machine. You can also use Step Functions' Optimized integrations, each of which has been customized to provide special functionality for your workflow.

Some services or SDKs may not be available as AWS SDK integrations, either temporarily or permanently. Recently released services may not have SDK interactions available until a later update. Some services require customized configuration, such as specifying a customer-specific endpoint, which may be more suitable for an optimized integration. Other SDKs are unsuitable for use in a workflow, such as those for streaming audio or video. Finally, some services may be withheld until they pass certain internal validations performed by Step Functions.

Using AWS SDK service integrations

To use AWS SDK integrations, you specify the service name and API call and, optionally, a service integration pattern.

You can call AWS SDK services directly from the Amazon States Language in the Resource field of a task state. To do this, use the following syntax:

arn:aws:states:::aws-sdk:serviceName:apiAction.[serviceIntegrationPattern]

For example, for Amazon EC2, you might use arn:aws:states:::aws-sdk:ec2:describeInstances. This would return output as defined for the Amazon EC2 describeInstances API call.

If an AWS SDK integration encounters an error, the resulting Error field will be composed of the service name and the error name, separated by a period character: ServiceName.ErrorName. Both the service name and error name are in Pascal case. You can also see the service name, in lowercase, in the Task state's Resource field. You can find the potential error names in the target service's API reference documentation.

For example, you might use the arn:aws:states:::aws-sdk:acmpca:deleteCertificateAuthority AWS SDK integration. The AWS Private Certificate Authority API Reference indicates that the DeleteCertificateAuthority API action can result in a ResourceNotFoundException, for example. To handle this error, you would thus specify the Error AcmPca.ResourceNotFoundException in your Task state's Retriers or Catchers. For more information on error handling in Step Functions, see Handling errors in Step Functions workflows.

Step Functions cannot autogenerate IAM policies for AWS SDK integrations. After you create your state machine, you will need to navigate to the IAM console and configure your role policies. See How Step Functions generates IAM policies for integrated services for more information.

See the Gather Amazon S3 bucket info using AWS SDK service integrations tutorial for an example of how to use AWS SDK integrations.

Supported AWS SDK service integrations

The following table lists the AWS SDK service integrations supported by Step Functions. The Task state resource column lists the syntax to call a specific API action when using the integration for the service specified in the Service name column on the left. The Date supported column provides information about the dates on which the service integration was supported. In addition, the Exception prefix column on the right, lists the exception prefixes for each service integration. These exception prefixes are present in the exceptions that are generated when you erroneously perform an AWS SDK service integration with Step Functions.

Unsupported API actions for supported services

The following table lists the unsupported API actions for AWS SDK service integrations. The right column contains the API actions that are currently not supported for the service listed in the left column.

Deprecated AWS SDK service integrations

The following AWS SDK service integrations are now deprecated: