sam remote invoke - Amazon Serverless Application Model
UsageArgumentsOptions
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

sam remote invoke

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

The sam remote invoke command invokes supported resources in the Amazon Web Services 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 Amazon 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 Amazon 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 Amazon SAM CLI will automatically process your resource ID as a logical ID value from the Amazon 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 Amazon SAM CLI will attempt to automatically invoke a resource in your Amazon CloudFormation stack using the following logic:

  1. The Amazon 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 Amazon SAM CLI will invoke it. If multiple resources of the resource type exists in your stack, the Amazon SAM CLI will return an error.

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

  • Stack that contains two Lambda functions and an Amazon SQS queue – The Amazon 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 Amazon 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 Amazon 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 Amazon 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 Amazon 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 Amazon 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.

Amazon 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.

Amazon 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 Amazon credentials.

--region TEXT

The Amazon Web Services Region of the resource. For example, us-east-1.

--stack-name TEXT

The name of the Amazon 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.