Function getParameter

Example

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

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

Advanced usage

Decryption

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

Example

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 });
};
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 { 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 });
};
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 { 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 });
};
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 { 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' });
};
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 { 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' });
};
Copy

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.

Example

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,
    },
  });
};
Copy

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.

Options

• You can customize the retrieval of the value by passing options to the function:
• 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.

For more usage examples, see our documentation.