The name of the parameter to retrieve
Optionaloptions: NonNullable<(InferredFromOptionsType & SSMGetOptions)>Optional options to configure the provider
Optional maximum age of the value in the cache, in seconds (default: 5)
Optional flag to always fetch a new value from the store regardless if already available in cache (default: false)
Optional transform to be applied, can be json or binary
Optional additional options to pass to the AWS SDK v3 client, supports all options from GetParameterCommandInput | GetParameterCommandInput except Name
Optional flag to decrypt the value before returning it (default: false)
import { getParameter } from '@aws-lambda-powertools/parameters/ssm';
export const handler = async (): Promise<void> => {
// Retrieve a parameter
const parameter = await getParameter('/my-parameter');
};
Decryption
If you have encrypted parameters, you can use the decrypt option to automatically decrypt them.
import { getParameter } from '@aws-lambda-powertools/parameters/ssm';
export const handler = async (): Promise<void> => {
// Retrieve a parameter and decrypt it
const parameter = await getParameter('/my-parameter', { decrypt: true });
};
Caching
By default, the provider will cache parameters retrieved in-memory for 5 seconds.
You can adjust how long values should be kept in cache by using the maxAge parameter.
import { getParameter } from '@aws-lambda-powertools/parameters/ssm';
export const handler = async (): Promise<void> => {
// Retrieve a parameter and cache it for 10 seconds
const parameter = await getParameter('/my-parameter', { maxAge: 10 });
};
If instead you'd like to always ensure you fetch the latest parameter from the store regardless if already available in cache, use the forceFetch parameter.
import { getParameter } from '@aws-lambda-powertools/parameters/ssm';
export const handler = async (): Promise<void> => {
// Retrieve a parameter and always fetch the latest value
const parameter = await getParameter('/my-parameter', { forceFetch: true });
};
Transformations
For parameters stored as JSON you can use the transform argument for deserialization. This will return a JavaScript object instead of a string.
import { getParameter } from '@aws-lambda-powertools/parameters/ssm';
export const handler = async (): Promise<void> => {
// Retrieve a parameter and parse it as JSON
const parameter = await getParameter('/my-parameter', { transform: 'json' });
};
For parameters that are instead stored as base64-encoded binary data, you can use the transform argument set to binary for decoding. This will return a decoded string.
import { getParameter } from '@aws-lambda-powertools/parameters/ssm';
export const handler = async (): Promise<void> => {
// Retrieve a base64-encoded string and decode it
const parameter = await getParameter('/my-parameter', { transform: 'binary' });
};
Extra SDK options
When retrieving a parameter, you can pass extra options to the AWS SDK v3 for JavaScript client by using the sdkOptions parameter.
import { getParameter } from '@aws-lambda-powertools/parameters/ssm';
export const handler = async (): Promise<void> => {
// Retrieve a parameter and pass extra options to the AWS SDK v3 for JavaScript client
const parameter = await getParameter('/my-parameter', {
sdkOptions: {
WithDecryption: true,
},
});
};
This object accepts the same options as the AWS SDK v3 for JavaScript SSM GetParameter command.
Built-in provider class
For greater flexibility such as configuring the underlying SDK client used by built-in providers, you can use the SSMProvider class.
The Parameters utility provides an
SSMProviderthat allows to retrieve parameters from AWS Systems Manager.This utility supports AWS SDK v3 for JavaScript only. This allows the utility to be modular, and you to install only the SDK packages you need and keep your bundle size small.
Basic usage