Class SSMProvider

Example

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

const parametersProvider = new SSMProvider();

export const handler = async (): Promise<void> => {
  // Retrieve a parameter from SSM
  const parameter = await parametersProvider.get('/my-parameter');
};
Copy

If you want to retrieve a parameter without customizing the provider, you can use the getParameter function instead.

You can also retrieve parameters at once. If you want to get multiple parameters under the same path, you can use the getMultiple method.

Example

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

const parametersProvider = new SSMProvider();

export const handler = async (): Promise<void> => {
 // Retrieve multiple parameters by path from SSM
 const parameters = await parametersProvider.getMultiple('/my-parameters-path');
};
Copy

If you don't need to customize the provider, you can also use the getParameters function instead.

If instead you want to retrieve multiple parameters by name, you can use the getParametersByName method.

Example

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

const parametersProvider = new SSMProvider();

export const handler = async (): Promise<void> => {
  // Retrieve multiple parameters by name from SSM
  const parameters = await parametersProvider.getParametersByName({
    '/my-parameter-1': {}, // Use default options
    '/my-parameter-2': { transform: 'json' }, // Parse the value as JSON
  });
};
Copy

If you don't need to customize the provider, you can also use the getParametersByName function instead.

Advanced usage

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 { SSMProvider } from '@aws-lambda-powertools/parameters/ssm';

const parametersProvider = new SSMProvider();

export const handler = async (): Promise<void> => {
  // Retrieve a parameter and cache it for 10 seconds
  const parameter = await parametersProvider.get('/my-parameter', { maxAge: 10 });
  // Retrieve multiple parameters by path and cache them for 20 seconds
  const parameters = await parametersProvider.getMultiple('/my-parameters-path', { maxAge: 20 });
};
Copy

When using the getParametersByName method, you can set a different maxAge for each parameter or set a default maxAge for all parameters.

Example

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

const parametersProvider = new SSMProvider();

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

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.

Example

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

const parametersProvider = new SSMProvider();

export const handler = async (): Promise<void> => {
  // Retrieve a parameter and skip cache
  const parameter = await parametersProvider.get('/my-parameter', { forceFetch: true });
  // Retrieve multiple parameters and skip cache
  const parameters = await parametersProvider.getMultiple('/my-parameters-path', { forceFetch: true });
};
Copy

Likewise, you can use the forceFetch parameter with the getParametersByName method both for individual parameters and for all parameters.

Decryption

If you want to retrieve a parameter that is encrypted, you can use the decrypt parameter. This parameter is compatible with get, getMultiple and getParametersByName.

Example

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

const parametersProvider = new SSMProvider();

export const handler = async (): Promise<void> => {
  // Retrieve a parameter and decrypt it
  const parameter = await parametersProvider.get('/my-parameter', { decrypt: true });
  // Retrieve multiple parameters and decrypt them
  const parameters = await parametersProvider.getMultiple('/my-parameters-path', { decrypt: true });
};
Copy

Transformations

For parameters stored as JSON you can use the transform argument for deserialization. This will return a JavaScript object instead of a string.

Example

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

const parametersProvider = new SSMProvider();

export const handler = async (): Promise<void> => {
  // Retrieve a parameter and parse it as JSON
  const parameter = await parametersProvider.get('/my-parameter', { transform: 'json' });
  // Retrieve multiple parameters and parse them as JSON
  const parameters = await parametersProvider.getMultiple('/my-parameters-path', { transform: 'json' });
};
Copy

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.

Example

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

const parametersProvider = new SSMProvider();

export const handler = async (): Promise<void> => {
  // Retrieve a base64-encoded string and decode it
  const parameter = await parametersProvider.get('/my-parameter', { transform: 'binary' });
  // Retrieve multiple base64-encoded strings and decode them
  const parameters = await parametersProvider.getMultiple('/my-parameters-path', { transform: 'binary' });
};
Copy

Both type of transformations are compatible also with the getParametersByName method.

Extra SDK options

When retrieving parameters, you can pass extra options to the AWS SDK v3 for JavaScript client by using the sdkOptions parameter.

Example

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

const parametersProvider = new SSMProvider();

export const handler = async (): Promise<void> => {
  // Retrieve a parameter and pass extra options to the AWS SDK v3 for JavaScript client
  const parameter = await parametersProvider.get('/my-parameter', {
    sdkOptions: {
      WithDecryption: true,
    },
  });
};
Copy

The objects accept the same options as respectively the AWS SDK v3 for JavaScript GetParameter command and the AWS SDK v3 for JavaScript GetParametersByPath command.

Customize AWS SDK v3 for JavaScript client

By default, the provider will create a new SSM client using the default configuration.

You can customize the client by passing a custom configuration object to the provider.

Example

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

const parametersProvider = new SSMProvider({
  clientConfig: { region: 'eu-west-1' },
});
Copy

This object accepts the same options as the AWS SDK v3 for JavaScript SSM client constructor.

Otherwise, if you want to use a custom client altogether, you can pass it to the provider.

Example

import { SSMProvider } from '@aws-lambda-powertools/parameters/ssm';
import { SSMClient } from '@aws-sdk/client-ssm';

const client = new SSMClient({ region: 'eu-west-1' });
const parametersProvider = new SSMProvider({
  awsSdkV3Client: client,
});
Copy

This object must be an instance of the AWS SDK v3 for JavaScript SSM client.

For more usage examples, see our documentation.