Cargo Lambda Invoke
The invoke subcommand helps you send requests to the local Lambda emulator, as well as remote functions. Before you use this command, you need to start the local emulator in a different terminal by calling the Watch subcommand.
The invoke subcommand sends raw JSON payloads to your Rust functions. The Rust Runtime for Lambda transforms those payloads into the Rust struct that your function receives. If the payload doesn't match the layout of the defined struct, the runtime will return a Serde deserialization error.
Rust functions implemented with lambda_http require the HTTP calls to be wrapped into the right JSON payloads. This is because AWS Lambda doesn't support HTTP calls natively. Services like Amazon API Gateway, Amazon Load Balancer, or Lambda Function URLs, receive the incoming HTTP calls and translate them to JSON payloads. lambda_http performs the opposite translation, so you can work with HTTP primitives.
You can find many examples of JSON payloads in the AWS Lambda Events repository. You can copy them directly, or use the --data-example flag to load them on demand.
The following video shows you how to use this subcommand:
Basic JSON calls
If your Rust project only includes one function, in the package's main.rs file, you can invoke it by sending the data that you want to process, without extra arguments. For example:
cargo lambda invoke --data-ascii "{ \"command\": \"hi\" }"cargo lambda invoke --data-ascii "{ \"command\": \"hi\" }"Multi function support
If your project includes more than one function, or the binary has a different name than the package, you must provide the name of the Lambda function that you want to invoke, and the payload that you want to send. If you don't know how to find your function's name, it can be in two places:
- If your Cargo.toml file includes a
[package]section, and it does not include a[[bin]]section, the function's name is in thenameattribute under the[package]section. - If your Cargo.toml file includes one or more
[[bin]]sections, the function's name is in thenameattribute under the[[bin]]section that you want to compile.
In the following example, basic-lambda is the function's name as indicated in the package's [[bin]] section:
cargo lambda invoke basic-lambda --data-ascii "{ \"command\": \"hi\" }"cargo lambda invoke basic-lambda --data-ascii "{ \"command\": \"hi\" }"Cargo-Lambda compiles functions on demand when they receive the first invocation. It's normal that the first invocation takes a long time if your code has not compiled with the host compiler before. After the first compilation, Cargo-Lambda will re-compile your code every time you make a change in it, without having to send any other invocation requests.
Ascii data
The --data-ascii flag allows you to send a payload directly from the command line:
cargo lambda invoke basic-lambda --data-ascii "{ \"command\": \"hi\" }"cargo lambda invoke basic-lambda --data-ascii "{ \"command\": \"hi\" }"File data
The --data-file flag allows you to read the payload from a file in your file system:
cargo lambda invoke basic-lambda --data-file examples/my-payload.jsoncargo lambda invoke basic-lambda --data-file examples/my-payload.jsonExample data
The --data-example flag allows you to fetch an example payload from the aws-lambda-events repository, and use it as your request payload. For example, if you want to use the example-apigw-request.json payload, you have to pass the name apigw-request into this flag:
cargo lambda invoke http-lambda --data-example apigw-requestcargo lambda invoke http-lambda --data-example apigw-requestAfter the first download, these examples are cached (in your system's user-local cache) in your home directory, under cargo-lambda/invoke-fixtures.
If you don't want to cache the example or want to ignore the file in the cache, add the flag --skip-cache to the command:
cargo lambda invoke http-lambda --data-example apigw-request --skip-cachecargo lambda invoke http-lambda --data-example apigw-request --skip-cacheRemote
The --remote flag allows you to send requests to a remote function deployed on AWS Lambda. This flag assumes that your AWS account has permission to call the lambda:invokeFunction operation. You can specify the region where the function is deployed, as well as any credentials profile that the command should use to authenticate you:
cargo lambda invoke --remote --data-example apigw-request http-lambdacargo lambda invoke --remote --data-example apigw-request http-lambdaVersioning
You can invoke different remote versions of the function by providing the version number or alias. Use the flag --qualifier to specify this version number or alias. For example, if you want to invoke a previous version of the function, you can use the following command:
cargo lambda invoke --remote --data-example apigw-request --qualifier 1 http-lambdacargo lambda invoke --remote --data-example apigw-request --qualifier 1 http-lambdaOutput format
The --output-format flag allows you to change the output formatting between plain text and pretty-printed JSON formatting. By default, all function outputs are printed as text.
cargo lambda invoke --remote --data-example apigw-request --output-format json http-lambdacargo lambda invoke --remote --data-example apigw-request --output-format json http-lambdaTLS support
The invoke subcommand supports TLS connections to the runtime if you want to send requests to the runtime securely. The TLS server started by the watch subcommand must be running with the same TLS certificate and key in order to use this feature.
To enable TLS, you need to provide the path to the TLS certificate and key files using the --tls-cert and --tls-key flags. The certificate and key files must be in PEM format.
cargo lambda invoke --data-example apigw-request --tls-cert cert.pem --tls-key key.pem http-lambdacargo lambda invoke --data-example apigw-request --tls-cert cert.pem --tls-key key.pem http-lambdaIf the root CA file is not specified, the local CA certificates on your system will be used to verify the TLS connection. You can use the --tls-ca flag to specify a custom root CA file.
cargo lambda invoke --data-example apigw-request --tls-cert cert.pem --tls-key key.pem --tls-ca ca.pem http-lambdacargo lambda invoke --data-example apigw-request --tls-cert cert.pem --tls-key key.pem --tls-ca ca.pem http-lambdaIf you want to use cURL to send requests to the runtime, you can use the following command:
curl https://<runtime-address> --cert cert.pem --key key.pem --cacert ca.pemcurl https://<runtime-address> --cert cert.pem --key key.pem --cacert ca.pem