Function getParametersByName

Example

import { getParametersByName } from '@aws-lambda-powertools/parameters/ssm';

export const handler = async (): Promise<void> => {
  // Retrieve parameters and cache them for 10 seconds
  const parameters = await getParametersByName({
    '/my-parameter-1': {}, // Use default options
    '/my-parameter-2': { maxAge: 10 }, // Cache for 10 seconds
  });
};
Copy

Advanced usage

Decryption

If you have encrypted parameters, you can use the decrypt option to automatically decrypt them.

Example

import { getParametersByName } from '@aws-lambda-powertools/parameters/ssm';

export const handler = async (): Promise<void> => {
  // Retrieve parameters and decrypt them
  const parameters = await getParametersByName({
    '/my-parameter-1': {}, // Use default options
    '/my-parameter-2': {}, // Use default options
  }, { decrypt: true });
};
Copy

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.

Example

import { getParametersByName } from '@aws-lambda-powertools/parameters/ssm';

export const handler = async (): Promise<void> => {
  // Retrieve parameters and cache them for 10 seconds
  const parameters = await getParametersByName({
    '/my-parameter-1': {}, // Use default options
    '/my-parameter-2': {}, // Use default options
  }, { maxAge: 10 });
};
Copy

Alternatively, if you need more granular control over caching each parameter, you can pass it in the options object.

Example

import { getParametersByName } from '@aws-lambda-powertools/parameters/ssm';

export const handler = async (): Promise<void> => {
  // Retrieve parameters and cache them individually
  const parameters = await getParametersByName({
    '/my-parameter-1': { maxAge: 10 }, // Cache for 10 seconds
    '/my-parameter-2': { maxAge: 20 }, // Cache for 20 seconds
  });
};
Copy

If instead you'd like to always ensure you fetch the latest values from the store regardless if already available in cache, use the forceFetch parameter.

Example

import { getParametersByName } from '@aws-lambda-powertools/parameters/ssm';

export const handler = async (): Promise<void> => {
  // Retrieve parameters and pass extra options to skip cache
  const parameters = await getParametersByName({
    '/my-parameter-1': {}, // Use default options
    '/my-parameter-2': {}, // Use default options
  }, { forceFetch: true });
};
Copy

Transformations

For parameters stored as JSON you can use the transform argument for deserialization. This will return a JavaScript objects instead of a strings. 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 decoded strings for each parameter.

Example

import { getParametersByName } from '@aws-lambda-powertools/parameters/ssm';

export const handler = async (): Promise<void> => {
  // Retrieve parameters and pass extra options to transform them
  const parameters = await getParametersByName({
    '/my-parameter-1': {}, // Use default options (no transformation)
    '/my-parameter-2': { transform: 'json' }, // Parse the value as JSON
    '/my-parameter-3': { transform: 'binary' }, // Parse the value as base64-encoded binary data
  });
};
Copy

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.

Options

• You can customize the retrieval of the value by passing options to both the function and the parameter:
• maxAge - The maximum age of the value in cache before fetching a new one (in seconds) (default: 5)
• forceFetch - Whether to always fetch a new value from the store regardless if already available in cache
• transform - Whether to transform the value before returning it. Supported values: json, binary
• sdkOptions - Extra options to pass to the AWS SDK v3 for JavaScript client
• decrypt - Whether to decrypt the value before returning it

throwOnError decides whether to throw an error if a parameter is not found:

• A) Default fail-fast behavior: Throws a GetParameterError error upon any failure.
• B) Gracefully aggregate all parameters that failed under "_errors" key.

It transparently uses GetParameter and/or getParametersByName depending on decryption requirements.

                               ┌────────────────────────┐
                           ┌───▶  Decrypt entire batch  │─────┐
                           │   └────────────────────────┘     │     ┌────────────────────┐
                           │                                  ├─────▶ getParametersByName API  │
   ┌──────────────────┐    │   ┌────────────────────────┐     │     └────────────────────┘
   │   Split batch    │─── ┼──▶│ No decryption required │─────┘
   └──────────────────┘    │   └────────────────────────┘
                           │                                        ┌────────────────────┐
                           │   ┌────────────────────────┐           │  GetParameter API  │
                           └──▶│Decrypt some but not all│───────────▶────────────────────┤
                               └────────────────────────┘           │ getParametersByName API  │
                                                                    └────────────────────┘
Copy

For more usage examples, see our documentation.