Using sam local generate-event - AWS Serverless Application Model

Using sam local generate-event

Use the AWS Serverless Application Model Command Line Interface (AWS SAM CLI) sam local generate-event subcommand to generate event payload samples for supported AWS services. You can then modify and pass these events to local resources for testing.

An event is a JSON object that gets generated when an AWS service performs an action or task. These events contain specific information, such as the data that was processed or the timestamp of the event. Most AWS services generate events and each service’s events are formatted uniquely for its service.

Events generated by one service are passed to other services as an event source. For example, an item placed in an Amazon Simple Storage Service (Amazon S3) bucket can generate an event. This event can then be used as the event source for an AWS Lambda function to process the data further.

Events that you generate with sam local generate-event are formatted in the same structure as the actual events created by the AWS service. You can modify the contents of these events and use them to test resources in your application.

To use sam local generate-event, install the AWS SAM CLI by completing the following:

Before using sam local generate-event, we recommend a basic understanding of the following:

Generate sample events

Use the AWS SAM CLI sam local generate-event subcommand to generate events for supported AWS services.

To see a list of supported AWS services
  1. Run the following:

    $ sam local generate-event
  2. The list of supported AWS services will display. The following is an example:

    $ sam local generate-event ... Commands: alb alexa-skills-kit alexa-smart-home apigateway appsync batch cloudformation ...
To generate a local event
  1. Run sam local generate-event and provide the supported service name. This will display a list of event types that you can generate. The following is an example:

    $ sam local generate-event s3 Usage: sam local generate-event s3 [OPTIONS] COMMAND [ARGS]... Options: -h, --help Show this message and exit. Commands: batch-invocation Generates an Amazon S3 Batch Operations Invocation Event delete Generates an Amazon S3 Delete Event put Generates an Amazon S3 Put Event
  2. To generate the sample event, run sam local generate-event, providing the service and event type.

    $ sam local generate-event <service> <event>

    The following is an example:

    $ sam local generate-event s3 put { "Records": [ { "eventVersion": "2.0", "eventSource": "aws:s3", "awsRegion": "us-east-1", "eventTime": "1970-01-01T00:00:00.000Z", "eventName": "ObjectCreated:Put", "userIdentity": { "principalId": "EXAMPLE" }, "requestParameters": { "sourceIPAddress": "127.0.0.1" }, "responseElements": { "x-amz-request-id": "EXAMPLE123456789", "x-amz-id-2": "EXAMPLE123/5678abcdefghijklambdaisawesome/mnopqrstuvwxyzABCDEFGH" }, "s3": { "s3SchemaVersion": "1.0", "configurationId": "testConfigRule", "bucket": { "name": "example-bucket", "ownerIdentity": { "principalId": "EXAMPLE" }, "arn": "arn:aws:s3:::example-bucket" }, "object": { "key": "test/key", "size": 1024, "eTag": "0123456789abcdef0123456789abcdef", "sequencer": "0A1B2C3D4E5F678901" } } } ] }

These sample events contain placeholder values. You can modify these values to reference actual resources in your application or values to help with local testing.

To modify a sample event
  1. You can modify sample events at the command prompt. To see your options, run the following:

    $ sam local generate-event <service> <event> --help

    The following is an example:

    $ sam local generate-event s3 put --help Usage: sam local generate-event s3 put [OPTIONS] Options: --region TEXT Specify the region name you'd like, otherwise the default = us-east-1 --partition TEXT Specify the partition name you'd like, otherwise the default = aws --bucket TEXT Specify the bucket name you'd like, otherwise the default = example-bucket --key TEXT Specify the key name you'd like, otherwise the default = test/key --debug Turn on debug logging to print debug message generated by AWS SAM CLI and display timestamps. --config-file TEXT Configuration file containing default parameter values. [default: samconfig.toml] --config-env TEXT Environment name specifying default parameter values in the configuration file. [default: default] -h, --help Show this message and exit.
  2. Use any of these options at the command prompt to modify your sample event payload. The following is an example:

    $ sam local generate-event s3 put--bucket MyBucket { "Records": [ { "eventVersion": "2.0", "eventSource": "aws:s3", "awsRegion": "us-east-1", "eventTime": "1970-01-01T00:00:00.000Z", "eventName": "ObjectCreated:Put", "userIdentity": { "principalId": "EXAMPLE" }, "requestParameters": { "sourceIPAddress": "127.0.0.1" }, "responseElements": { "x-amz-request-id": "EXAMPLE123456789", "x-amz-id-2": "EXAMPLE123/5678abcdefghijklambdaisawesome/mnopqrstuvwxyzABCDEFGH" }, "s3": { "s3SchemaVersion": "1.0", "configurationId": "testConfigRule", "bucket": { "name": "MyBucket", "ownerIdentity": { "principalId": "EXAMPLE" }, "arn": "arn:aws:s3:::MyBucket" }, "object": { "key": "test/key", "size": 1024, "eTag": "0123456789abcdef0123456789abcdef", "sequencer": "0A1B2C3D4E5F678901" } } } ] }

Use generated events for local testing

Save your generated events locally and use other sam local subcommands to test.

To save your generated events locally
  • Run the following:

    $ sam local generate-event <service> <event> <event-option> > <filename.json>

    The following is an example of an event being saved as an s3.json file in the events folder of our project.

    sam-app$ sam local generate-event s3 put --bucket MyBucket > events/s3.json
To use a generated event for local testing
  • Pass the event with other sam local subcommands by using the --event option.

    The following is an example of using the s3.json event to invoke our Lambda function locally:

    sam-app$ sam local invoke --event events/s3.json S3JsonLoggerFunction Invoking src/handlers/s3-json-logger.s3JsonLoggerHandler (nodejs18.x) Local image is up-to-date Using local image: public.ecr.aws/lambda/nodejs:18-rapid-x86_64. Mounting /Users/.../sam-app/.aws-sam/build/S3JsonLoggerFunction as /var/task:ro,delegated, inside runtime container START RequestId: f4f45b6d-2ec6-4235-bc7b-495ec2ae0128 Version: $LATEST END RequestId: f4f45b6d-2ec6-4235-bc7b-495ec2ae0128 REPORT RequestId: f4f45b6d-2ec6-4235-bc7b-495ec2ae0128 Init Duration: 1.23 ms Duration: 9371.93 ms Billed Duration: 9372 ms Memory Size: 128 MB Max Memory Used: 128 MB

Learn more

For a list of all sam local generate-event options, see sam local generate-event.

For a demo of using sam local, see AWS SAM for local development. Testing AWS Cloud resources from local development environments in the Serverless Land Sessions with SAM series on YouTube.