sam remote invoke - AWS Serverless Application Model
UsageArgumentsOptionsExample

sam remote invoke

This page provides reference information for the AWS Serverless Application Model Command Line Interface (AWS SAM CLI) sam remote invoke command.

The sam remote invoke command invokes supported resources in the AWS Cloud.

Usage

$ sam remote invoke <arguments> <options>

Arguments

Resource ID

The ID of the suppored resource to invoke.

This argument accepts the following values:

  • Amazon Resource Name (ARN) – The ARN of the resource.

    Tip

    Use sam list stack-outputs --stack-name <stack-name> to obtain the ARN of your resources.

  • Logical ID – The logical ID of the resource. You must also provide the AWS CloudFormation stack name using the --stack-name option.

  • Physical ID – The physical ID of the resource. This ID gets created when you deploy a resource using AWS CloudFormation.

    Tip

    Use sam list resources --stack-name <stack-name> to obtain the physical ID of your resources.

When you provide an ARN or physical ID:

If you provide an ARN or physical ID, do not provide a stack name. When the stack name is provided using the --stack-name option, or when the stack name is defined in your configuration file, the AWS SAM CLI will automatically process your resource ID as a logical ID value from the AWS CloudFormation stack.

When you don't provide a resource ID:

If you don't provide a resource ID, but do provide a stack name with the --stack-name option, the AWS SAM CLI will attempt to automatically invoke a resource in your AWS CloudFormation stack using the following logic:

  1. The AWS SAM CLI will identify resource types in the following order and move to the next step once the resource type is found in your stack:

    1. Lambda

    2. Step Functions

    3. Amazon SQS

    4. Kinesis Data Streams

  2. If the resource type has a single resource in your stack, the AWS SAM CLI will invoke it. If multiple resources of the resource type exists in your stack, the AWS SAM CLI will return an error.

The following are examples of what the AWS SAM CLI will do:

  • Stack that contains two Lambda functions and an Amazon SQS queue – The AWS SAM CLI will locate the Lambda resource type and return and error since the stack contains more than one Lambda function.

  • Stack that contains a Lambda function and two Amazon Kinesis Data Streams applications – The AWS SAM CLI will locate the Lambda function and invoke it since the stack contains a single Lambda resource.

  • Stack that contains a single Amazon SQS queue and two Kinesis Data Streams applications – The AWS SAM CLI will locate the Amazon SQS queue and invoke it since the stack contains a single Amazon SQS queue.

Options

--beta-features | --no-beta-features

Allow or deny beta features.

--config-env TEXT

Specify the environment to use from your AWS SAM CLI configuration file.

Default: default

--config-file FILENAME

Specify the path and file name of your configuration file.

For more information about configuration files, see Configuring the AWS SAM CLI.

Default: samconfig.toml at the root of your project directory.

--debug

Activate debug logging. This prints debug messages and timestamps generated by the AWS SAM CLI.

--event, -e TEXT

The event to send to the target resource.

--event-file FILENAME

The path to a file that contains the event to send to the target resource.

--help, -h

Show the help message and exit.

--output [ text | json ]

Output the results of your invocation in a specific output format.

json – The request metadata and resource response are returned in JSON structure. The response contains the full SDK output.

text – The request metadata is returned in text structure. The resource response is returned in the output format of the invoked resource.

--parameter

Additional Boto3 parameters that you can pass to the resource being invoked.

Amazon Kinesis Data Streams

The following additional parameters can be used to put a record in the Kinesis data stream:

  • ExplicitHashKey='string'

  • PartitionKey='string'

  • SequenceNumberForOrdering='string'

  • StreamARN='string'

For a description of each parameter, see Kinesis.Client.put_record.

AWS Lambda

The following additional parameters can be used to invoke a Lambda resource and receive a buffered response:

  • ClientContext='base64-encoded string'

  • InvocationType='[ DryRun | Event | RequestResponse ]'

  • LogType='[ None | Tail ]'

  • Qualifier='string'

The following additional parameters can be used to invoke a Lambda resource with response streaming:

  • ClientContext='base64-encoded string'

  • InvocationType='[ DryRun | RequestResponse ]'

  • LogType='[ None | Tail ]'

  • Qualifier='string'

For a description of each parameter, see the following:

Amazon Simple Queue Service (Amazon SQS)

The following additional parameters can be used to send a message to an Amazon SQS queue:

  • DelaySeconds=integer

  • MessageAttributes='json string'

  • MessageDeduplicationId='string'

  • MessageGroupId='string'

  • MessageSystemAttributes='json string'

For a description of each parameter, see SQS.Client.send_message.

AWS Step Functions

The following additional parameters can be used to start a state machine execution:

  • name='string'

  • traceHeader='string'

For a description of each parameter, see SFN.Client.start_execution.

--profile TEXT

The specific profile from your credential file to get AWS credentials.

--region TEXT

The AWS Region of the resource. For example, us-east-1.

--stack-name TEXT

The name of the AWS CloudFormation stack that the resource belongs to.

--test-event-name NAME

The name of the shareable test event to pass to your Lambda function.

Note

This option only supports Lambda functions.

Example

The following example invokes supported resources in the AWS Cloud and activates debug logging, which prints debug messages and timestamps generated by the AWS SAM CLI:

$ sam remote invoke--debug