Skip to content

Latest commit

 

History

History
executable file
·
69 lines (44 loc) · 4.72 KB

global-config-object.md

File metadata and controls

executable file
·
69 lines (44 loc) · 4.72 KB
Raw

Using the Global Configuration Object

There are two ways to configure the SDK:

  • Set the global configuration using AWS.Config.

  • Pass extra configuration information to a service object.

Setting global configuration with AWS.Config is often easier to get started, but service-level configuration can provide more control over individual services. The global configuration specified by AWS.Config provides default settings for service objects that you create subsequently, simplifying their configuration. However, you can update the configuration of individual service objects when your needs vary from the global configuration.

Setting Global Configuration

After you load the SDK, use the global variable, AWS, to access the SDK. You use this global access variable with the JavaScript API to interact with individual services. The SDK includes a global configuration object, AWS.Config, that you use to specify the SDK configuration settings required by your application.

Set your SDK configuration using AWS.Config by setting its properties according to your application needs. The following table summarizes AWS.Config properties commonly used to set the configuration of the SDK.

Configuration Options Description
credentials Required. Specifies the credentials used to determine access to services and resources.
region Required. Specifies the region in which requests for services are made.
maxRetries Optional. Specifies the maximum number of times a given request is retried.
logger Optional. Specifies a logger object to which debugging information is written.
update Optional. Updates the current configuration with new values.

For more information about the configuration object, see Class: AWS.Config in the API Reference.

Global Configuration Examples

Two properties of AWS.Config you must set to use the SDK are those that specify the region to use and the credentials that authorize your access to services. You can set these properties as part of the AWS.Config constructor, as shown in the following browser script example:

var myCredentials = new AWS.CognitoIdentityCredentials({IdentityPoolId:'IDENTITY_POOL_ID'});
var myConfig = new AWS.Config({
  credentials: myCredentials, region: 'us-west-2'
});

You can also set these properties after creating AWS.Config using the update method, as shown in the following example that updates the region:

myConfig = new AWS.Config();
myConfig.update({region: 'us-east-1'});

Setting Configuration Per Service

Each service that you use in the SDK for JavaScript is accessed through a service object that is part of the API for that service. For example, to access the Amazon S3 service you create the Amazon S3 service object. You can specify configuration settings that are specific to a service as part of the constructor for that service object. When you set configuration values on a service object, the constructor takes all of the configuration values used by AWS.Config, including credentials.

For example, if you need to access Amazon EC2 objects in multiple regions, create an EC2 service object for each region and then set the region configuration of each service object accordingly.

var ec2_regionA = new AWS.EC2({region: 'ap-southeast-2', maxRetries: 15, apiVersion: '2014-10-01'});
var ec2_regionB = new AWS.EC2({region: 'us-east-1', maxRetries: 15, apiVersion: '2014-10-01'});

You can also set configuration values specific to a service when configuring the SDK with AWS.Config. The global configuration object supports many service-specific configuration options. For more information about service-specific configuration, see Class: AWS.Config in the AWS SDK for JavaScript API Reference.

Immutable Configuration Data

Global configuration changes apply to requests for all newly created service objects. Newly created service objects are configured with the current global configuration data first and then any local configuration options. Updates you make to the global AWS.config object don't apply to previously created service objects.

Existing service objects must be manually updated with new configuration data or you must create and use a new service object that has the new configuration data. The following example creates a new Amazon S3 service object with new configuration data:

s3 = new AWS.S3(s3.config);