You are viewing the documentation for an older major version of the AWS SDK for JavaScript.
The modular AWS SDK for JavaScript (v3), the latest major version of AWS SDK for JavaScript, is now stable and recommended for general use. For more information, see the Migration Guide and API Reference.

Class: AWS.Config

Inherits:
Object
  • Object
show all
Defined in:
lib/config.js

Overview

The main configuration class used by all service objects to set the region, credentials, and other options for requests.

By default, credentials and region settings are left unconfigured. This should be configured by the application before using any AWS service APIs.

In order to set global configuration options, properties should be assigned to the global AWS.config object.

IBM Unsupported

See Also:

Defined Under Namespace

Modules: keys

Constructor Summary collapse

General Configuration Options collapse

Service-Specific Config Options collapse

Managing Credentials collapse

Loading and Setting Configuration Options collapse

Constructor Details

new AWS.Config(options) ⇒ void

Creates a new configuration object. This is the object that passes option data along to service requests, including credentials, security, region information, and some service specific settings.

IBM Unsupported

Examples:

Creating a new configuration object with credentials and region

var config = new AWS.Config({
  accessKeyId: 'AKID', secretAccessKey: 'SECRET', region: 'us-west-2'
});

Options Hash (options):

  • accessKeyId (String) —

    your AWS access key ID.

  • secretAccessKey (String) —

    your AWS secret access key.

  • sessionToken (AWS.Credentials) —

    the optional AWS session token to sign requests with.

  • credentials (AWS.Credentials) —

    the AWS credentials to sign requests with. You can either specify this object, or specify the accessKeyId and secretAccessKey options directly.

  • credentialProvider (AWS.CredentialProviderChain) —

    the provider chain used to resolve credentials if no static credentials property is set.

  • region (String) —

    the region to send service requests to. See region for more information.

  • maxRetries (Integer) —

    the maximum amount of retries to attempt with a request. See maxRetries for more information.

  • maxRedirects (Integer) —

    the maximum amount of redirects to follow with a request. See maxRedirects for more information.

  • sslEnabled (Boolean) —

    whether to enable SSL for requests.

  • paramValidation (Boolean|map) —

    whether input parameters should be validated against the operation description before sending the request. Defaults to true. Pass a map to enable any of the following specific validation features:

    • min [Boolean] — Validates that a value meets the min constraint. This is enabled by default when paramValidation is set to true.
    • max [Boolean] — Validates that a value meets the max constraint.
    • pattern [Boolean] — Validates that a string value matches a regular expression.
    • enum [Boolean] — Validates that a string value matches one of the allowable enum values.
  • computeChecksums (Boolean) —

    whether to compute checksums for payload bodies when the service accepts it (currently supported in S3 only)

  • convertResponseTypes (Boolean) —

    whether types are converted when parsing response data. Currently only supported for JSON based services. Turning this off may improve performance on large response payloads. Defaults to true.

  • correctClockSkew (Boolean) —

    whether to apply a clock skew correction and retry requests that fail because of an skewed client clock. Defaults to false.

  • s3ForcePathStyle (Boolean) —

    whether to force path style URLs for S3 objects.

  • s3BucketEndpoint (Boolean) —

    whether the provided endpoint addresses an individual bucket (false if it addresses the root API endpoint). Note that setting this configuration option requires an endpoint to be provided explicitly to the service constructor.

  • s3DisableBodySigning (Boolean) —

    whether S3 body signing should be disabled when using signature version v4. Body signing can only be disabled when using https. Defaults to true.

  • retryDelayOptions (map) —

    A set of options to configure the retry delay on retryable errors. Currently supported options are:

    • base [Integer] — The base number of milliseconds to use in the exponential backoff for operation retries. Defaults to 100 ms for all services except DynamoDB, where it defaults to 50ms.
    • customBackoff [function] — A custom function that accepts a retry count and error and returns the amount of time to delay in milliseconds. If the result is a non-zero negative value, no further retry attempts will be made. The base option will be ignored if this option is supplied. The function is only called for retryable errors.
  • httpOptions (map) —

    A set of options to pass to the low-level HTTP request. Currently supported options are:

    • proxy [String] — the URL to proxy requests through
    • agent [http.Agent, https.Agent] — the Agent object to perform HTTP requests with. Used for connection pooling. Defaults to the global agent (http.globalAgent) for non-SSL connections. Note that for SSL connections, a special Agent object is used in order to enable peer certificate verification. This feature is only available in the Node.js environment.
    • connectTimeout [Integer] — Sets the socket to timeout after failing to establish a connection with the server after connectTimeout milliseconds. This timeout has no effect once a socket connection has been established.
    • timeout [Integer] — Sets the socket to timeout after timeout milliseconds of inactivity on the socket. Defaults to two minutes (120000).
    • xhrAsync [Boolean] — Whether the SDK will send asynchronous HTTP requests. Used in the browser environment only. Set to false to send requests synchronously. Defaults to true (async on).
    • xhrWithCredentials [Boolean] — Sets the "withCredentials" property of an XMLHttpRequest object. Used in the browser environment only. Defaults to false.
  • apiVersion (String, Date) —

    a String in YYYY-MM-DD format (or a date) that represents the latest possible API version that can be used in all services (unless overridden by apiVersions). Specify 'latest' to use the latest possible version.

  • apiVersions (map<String, String|Date>) —

    a map of service identifiers (the lowercase service class name) with the API version to use when instantiating a service. Specify 'latest' for each individual that can use the latest available version.

  • logger (#write, #log) —

    an object that responds to .write() (like a stream) or .log() (like the console object) in order to log information about requests

  • systemClockOffset (Number) —

    an offset value in milliseconds to apply to all signing times. Use this to compensate for clock skew when your system may be out of sync with the service time. Note that this configuration option can only be applied to the global AWS.config object and cannot be overridden in service-specific configuration. Defaults to 0 milliseconds.

  • signatureVersion (String) —

    the signature version to sign requests with (overriding the API configuration). Possible values are: 'v2', 'v3', 'v4'.

  • signatureCache (Boolean) —

    whether the signature to sign requests with (overriding the API configuration) is cached. Only applies to the signature version 'v4'. Defaults to true.

  • useFipsEndpoint (Boolean) —

    Enables FIPS compatible endpoints. Defaults to false.

  • useDualstackEndpoint (Boolean) —

    Enables IPv6 dualstack endpoint. Defaults to false.

Property Details

computeChecksums ⇒ Boolean (readwrite)

Returns whether to compute checksums for payload bodies when the service accepts it (currently supported in S3 only).

Returns:

  • (Boolean) —

    whether to compute checksums for payload bodies when the service accepts it (currently supported in S3 only).

convertResponseTypes ⇒ Boolean (readwrite)

Returns whether types are converted when parsing response data. Currently only supported for JSON based services. Turning this off may improve performance on large response payloads. Defaults to true.

Returns:

  • (Boolean) —

    whether types are converted when parsing response data. Currently only supported for JSON based services. Turning this off may improve performance on large response payloads. Defaults to true.

correctClockSkew ⇒ Boolean (readwrite)

Returns whether to apply a clock skew correction and retry requests that fail because of an skewed client clock. Defaults to false.

Returns:

  • (Boolean) —

    whether to apply a clock skew correction and retry requests that fail because of an skewed client clock. Defaults to false.

credentials ⇒ AWS.Credentials (readwrite)

Returns the AWS credentials to sign requests with.

Returns:

httpOptions ⇒ map (readwrite)

Returns A set of options to pass to the low-level HTTP request. Currently supported options are:

  • proxy [String] — the URL to proxy requests through
  • agent [http.Agent, https.Agent] — the Agent object to perform HTTP requests with. Used for connection pooling. Note that for SSL connections, a special Agent object is used in order to enable peer certificate verification. This feature is only supported in the Node.js environment.
  • connectTimeout [Integer] — Sets the socket to timeout after failing to establish a connection with the server after connectTimeout milliseconds. This timeout has no effect once a socket connection has been established.
  • timeout [Integer] — The number of milliseconds a request can take before automatically being terminated. Defaults to two minutes (120000).
  • xhrAsync [Boolean] — Whether the SDK will send asynchronous HTTP requests. Used in the browser environment only. Set to false to send requests synchronously. Defaults to true (async on).
  • xhrWithCredentials [Boolean] — Sets the "withCredentials" property of an XMLHttpRequest object. Used in the browser environment only. Defaults to false.

Returns:

  • (map) —

    A set of options to pass to the low-level HTTP request. Currently supported options are:

    • proxy [String] — the URL to proxy requests through
    • agent [http.Agent, https.Agent] — the Agent object to perform HTTP requests with. Used for connection pooling. Note that for SSL connections, a special Agent object is used in order to enable peer certificate verification. This feature is only supported in the Node.js environment.
    • connectTimeout [Integer] — Sets the socket to timeout after failing to establish a connection with the server after connectTimeout milliseconds. This timeout has no effect once a socket connection has been established.
    • timeout [Integer] — The number of milliseconds a request can take before automatically being terminated. Defaults to two minutes (120000).
    • xhrAsync [Boolean] — Whether the SDK will send asynchronous HTTP requests. Used in the browser environment only. Set to false to send requests synchronously. Defaults to true (async on).
    • xhrWithCredentials [Boolean] — Sets the "withCredentials" property of an XMLHttpRequest object. Used in the browser environment only. Defaults to false.

logger ⇒ #write, #log (readwrite)

Returns an object that responds to .write() (like a stream) or .log() (like the console object) in order to log information about requests.

Returns:

  • (#write, #log) —

    an object that responds to .write() (like a stream) or .log() (like the console object) in order to log information about requests

maxRedirects ⇒ Integer (readwrite)

Returns the maximum amount of redirects to follow for a service request. Defaults to 10.

Returns:

  • (Integer) —

    the maximum amount of redirects to follow for a service request. Defaults to 10.

maxRetries ⇒ Integer (readwrite)

Returns the maximum amount of retries to perform for a service request. By default this value is calculated by the specific service object that the request is being made to.

Returns:

  • (Integer) —

    the maximum amount of retries to perform for a service request. By default this value is calculated by the specific service object that the request is being made to.

paramValidation ⇒ Boolean|map (readwrite)

Returns whether input parameters should be validated against the operation description before sending the request. Defaults to true. Pass a map to enable any of the following specific validation features:

  • min [Boolean] — Validates that a value meets the min constraint. This is enabled by default when paramValidation is set to true.
  • max [Boolean] — Validates that a value meets the max constraint.
  • pattern [Boolean] — Validates that a string value matches a regular expression.
  • enum [Boolean] — Validates that a string value matches one of the allowable enum values.

Returns:

  • (Boolean|map) —

    whether input parameters should be validated against the operation description before sending the request. Defaults to true. Pass a map to enable any of the following specific validation features:

    • min [Boolean] — Validates that a value meets the min constraint. This is enabled by default when paramValidation is set to true.
    • max [Boolean] — Validates that a value meets the max constraint.
    • pattern [Boolean] — Validates that a string value matches a regular expression.
    • enum [Boolean] — Validates that a string value matches one of the allowable enum values.

region ⇒ AWS.Credentials (readwrite)

Returns The region to send service requests to.

Examples:

Set the global region setting to us-west-2

AWS.config.update({region: 'us-west-2'});

Returns:

See Also:

retryDelayOptions ⇒ map (readwrite)

Returns A set of options to configure the retry delay on retryable errors. Currently supported options are:

  • base [Integer] — The base number of milliseconds to use in the exponential backoff for operation retries. Defaults to 100 ms for all services except DynamoDB, where it defaults to 50ms.

  • customBackoff [function] — A custom function that accepts a retry count and error and returns the amount of time to delay in milliseconds. If the result is a non-zero negative value, no further retry attempts will be made. The base option will be ignored if this option is supplied. The function is only called for retryable errors.

Examples:

Set the base retry delay for all services to 300 ms

AWS.config.update({retryDelayOptions: {base: 300}});
// Delays with maxRetries = 3: 300, 600, 1200

Set a custom backoff function to provide delay values on retries

AWS.config.update({retryDelayOptions: {customBackoff: function(retryCount, err) {
  // returns delay in ms
}}});

Returns:

  • (map) —

    A set of options to configure the retry delay on retryable errors. Currently supported options are:

    • base [Integer] — The base number of milliseconds to use in the exponential backoff for operation retries. Defaults to 100 ms for all services except DynamoDB, where it defaults to 50ms.

    • customBackoff [function] — A custom function that accepts a retry count and error and returns the amount of time to delay in milliseconds. If the result is a non-zero negative value, no further retry attempts will be made. The base option will be ignored if this option is supplied. The function is only called for retryable errors.

s3 ⇒ AWS.Config, map (readwrite)

Returns Service-specific configuration options for AWS.S3.

Examples:

Bind parameters to all newly created S3 objects

AWS.config.s3 = { params: { /* ... */ } };

Override default endpoint URI for all newly created S3 objects

AWS.config.s3 = { endpoint: 'https://{service}.{region}.amazonaws.com' };

Use IPv6/IPv4 dualstack endpoint for all newly created S3 objects

AWS.config.s3 = { useDualstack: true };

Returns:

s3BucketEndpoint ⇒ Boolean (readwrite)

Note:

Setting this configuration option requires an endpoint to be provided explicitly to the service constructor.

Returns whether the provided endpoint addresses an individual bucket (false if it addresses the root API endpoint).

Returns:

  • (Boolean) —

    whether the provided endpoint addresses an individual bucket (false if it addresses the root API endpoint).

s3DisableBodySigning ⇒ Boolean (readwrite)

Returns whether to disable S3 body signing when using signature version v4. Body signing can only be disabled when using https. Defaults to true.

Returns:

  • (Boolean) —

    whether to disable S3 body signing when using signature version v4. Body signing can only be disabled when using https. Defaults to true.

s3ForcePathStyle ⇒ Boolean (readwrite)

Returns whether to force path style URLs for S3 objects.

Returns:

  • (Boolean) —

    whether to force path style URLs for S3 objects

signatureCache ⇒ Boolean (readwrite)

Returns whether the signature to sign requests with (overriding the API configuration) is cached. Only applies to the signature version 'v4'. Defaults to true.

Returns:

  • (Boolean) —

    whether the signature to sign requests with (overriding the API configuration) is cached. Only applies to the signature version 'v4'. Defaults to true.

signatureVersion ⇒ String (readwrite)

Returns the signature version to sign requests with (overriding the API configuration). Possible values are: 'v2', 'v3', 'v4'.

Returns:

  • (String) —

    the signature version to sign requests with (overriding the API configuration). Possible values are: 'v2', 'v3', 'v4'.

sslEnabled ⇒ Boolean (readwrite)

Returns whether SSL is enabled for requests.

Returns:

  • (Boolean) —

    whether SSL is enabled for requests

systemClockOffset ⇒ Number (readwrite)

Returns an offset value in milliseconds to apply to all signing times. Use this to compensate for clock skew when your system may be out of sync with the service time. Note that this configuration option can only be applied to the global AWS.config object and cannot be overridden in service-specific configuration. Defaults to 0 milliseconds.

Returns:

  • (Number) —

    an offset value in milliseconds to apply to all signing times. Use this to compensate for clock skew when your system may be out of sync with the service time. Note that this configuration option can only be applied to the global AWS.config object and cannot be overridden in service-specific configuration. Defaults to 0 milliseconds.

useAccelerateEndpoint ⇒ Boolean (readwrite)

Note:

This configuration option is only compatible with S3 while accessing dns-compatible buckets.

Returns Whether to use the Accelerate endpoint with the S3 service. Defaults to false.

Returns:

  • (Boolean) —

    Whether to use the Accelerate endpoint with the S3 service. Defaults to false.

useDualstackEndpoint ⇒ Boolean (readwrite)

Returns Enables IPv6 dualstack endpoint. Defaults to false.

Returns:

  • (Boolean) —

    Enables IPv6 dualstack endpoint. Defaults to false.

useFipsEndpoint ⇒ Boolean (readwrite)

Returns Enables FIPS compatible endpoints. Defaults to false.

Returns:

  • (Boolean) —

    Enables FIPS compatible endpoints. Defaults to false.

Method Details

getCredentials(callback) ⇒ void

Note:

If you configure the SDK with static or environment credentials, the credential data should already be present in credentials attribute. This method is primarily necessary to load credentials from asynchronous sources, or sources that can refresh credentials periodically.

Loads credentials from the configuration object. This is used internally by the SDK to ensure that refreshable AWS.Credentials objects are properly refreshed and loaded when sending a request. If you want to ensure that your credentials are loaded prior to a request, you can use this method directly to provide accurate credential data stored in the object.

Examples:

Getting your access key

AWS.config.getCredentials(function(err) {
  if (err) console.log(err.stack); // credentials not loaded
  else console.log("Access Key:", AWS.config.credentials.accessKeyId);
})

Callback (callback):

  • function(err) { ... }

    Called when the credentials have been properly set on the configuration object.

    Parameters:

    • err (Error) —

      if this is set, credentials were not successfully loaded and this error provides information why.

See Also:

getPromisesDependency() ⇒ void

Gets the promise dependency set by AWS.config.setPromisesDependency.

getToken(callback) ⇒ void

Note:

If you configure the SDK with static token, the token data should already be present in AWS.Config.token attribute. This method is primarily necessary to load token from asynchronous sources, or sources that can refresh token periodically.

Loads token from the configuration object. This is used internally by the SDK to ensure that refreshable AWS.Token objects are properly refreshed and loaded when sending a request. If you want to ensure that your token is loaded prior to a request, you can use this method directly to provide accurate token data stored in the object.

Examples:

Getting your access token

AWS.config.getToken(function(err) {
  if (err) console.log(err.stack); // token not loaded
  else console.log("Token:", AWS.config.token.token);
})

Callback (callback):

  • function(err) { ... }

    Called when the AWS.Config.token have been properly set on the configuration object.

    Parameters:

    • err (Error) —

      if this is set, token was not successfully loaded and this error provides information why.

See Also:

  • AWS.Config.token

loadFromPath(path) ⇒ AWS.Config

Note:

Loading configuration will reset all existing configuration on the object.

Note:

This feature is not supported in the browser environment of the SDK.

Loads configuration data from a JSON file into this config object.

Parameters:

  • path (String) —

    the path relative to your process's current working directory to load configuration from.

Returns:

  • (AWS.Config) —

    the same configuration object

setPromisesDependency(dep) ⇒ void

Sets the promise dependency the SDK will use wherever Promises are returned. Passing null will force the SDK to use native Promises if they are available. If native Promises are not available, passing null will have no effect.

Parameters:

  • dep (Constructor) —

    A reference to a Promise constructor

update(options, allowUnknownKeys = false) ⇒ void

Updates the current configuration object with new options.

Examples:

Update maxRetries property of a configuration object

config.update({maxRetries: 10});

Parameters:

  • options (Object) —

    a map of option keys and values.

  • allowUnknownKeys (Boolean) (defaults to: false) —

    whether unknown keys can be set on the configuration object. Defaults to false.

See Also: