aws-sdk 2.0.1 → 2.0.5

package/doc-src/guide/node-configuring.md

@@ -0,0 +1,272 @@
+# @title Configuring the SDK in Node.js
+
+# Configuring the SDK in Node.js
+
+## The Configuration Object
+
+Configuration in the SDK can be done in two ways:
+
+1. Global configuration on `AWS.config`, or,
+2. Passing extra configuration to a service object
+
+Setting global configuration with `AWS.config` is often easier to get up
+and running with, but service level configuration can provide much more control
+over your requests. Both of these configuration mechanisms are discussed.
+
+## Global Configuration (`AWS.config`)
+
+By default, you can set global configuration by updating the `AWS.config` object with
+new settings. The most common settings are:
+
+1. `accessKeyId`, `secretAccessKey`, `sessionToken` — for credential management
+2. `region` — to set the region for requests
+3. `sslEnabled` — whether SSL is enabled or not
+4. `maxRetries` — to control the number of retries for a request
+5. `logger` — a logger object to write debug information to. Set to `process.stdout`
+   to get logging information about service requests.
+
+More configuration settings can be found in the
+[API reference documentation](http://docs.aws.amazon.com/AWSJavaScriptSDK/latest/frames.html).
+
+The only things you *need* to set in order to use the SDK are credentials and
+the region value. Let's discuss how to do that.
+
+### Setting AWS Credentials
+
+<p class="note">Remember, if you set your AWS credentials in the shared
+  credentials file or via environment variables, the AWS SDK for Node.js will
+  automatically detect them, and you will not need to perform any manual
+  credential configuration in your application.
+</p>
+
+Credentials are the most important thing you need to set when using any AWS SDK.
+Credentials can be set globally on the `AWS.config` object or per service by
+passing the credential information to the service object directly.
+
+There are a few ways to load credentials. Here they are, in order of
+recommendation:
+
+1. Loaded from IAM Roles for Amazon EC2 (if running on EC2),
+2. Loaded from the shared credentials file (`~/.aws/credentials`),
+3. Loaded from environment variables,
+4. Loaded from a JSON file on disk,
+5. Hardcoded in your application
+
+We do not recommend that you hard-code your AWS credentials in your application;
+however, it is reasonable to temporarily hard-code credential information
+in small personal scripts or for testing purposes.
+
+#### Credentials from the Shared Credentials File (`~/.aws/credentials`)
+
+By default, the SDK will automatically search the shared credentials file
+for credentials when loading. If you use this file for other SDKs and tools
+(like the CLI), you do not need to take any extra steps to configure
+credentials in the SDK.
+
+You may configure credentials for multiple access keys in the same shared
+configuration file using *profiles*. This is discussed in the last part of
+this section.
+
+##### Creating the Shared Credentials File
+
+If you do not already have a shared credentials file, you can create one in
+your home directory, specifically inside of `~/.aws/credentials`. Create and
+open the file, and add the following text, filling in the
+`<YOUR_ACCESS_KEY_ID>` and `<YOUR_SECRET_ACCESS_KEY>` values:
+
+```
+[default]
+aws_access_key_id = <YOUR_ACCESS_KEY_ID>
+aws_secret_access_key = <YOUR_SECRET_ACCESS_KEY>
+```
+
+The `[default]` heading defines credentials for the "default" profile. You
+can define credentials for other profiles too. This is discussed in the next
+section.
+
+Once this file is saved, the SDK will load these credentials without any
+extra configuration.
+
+##### Using Profiles with the SDK
+
+It is possible to have credential information for multiple access keys in the
+same shared configuration file. You can make use of different credentials
+through the use of "profiles". Each profile maps to a set of credentials.
+For example, multiple profiles could be configured like so:
+
+```
+[default] ; the default profile
+aws_access_key_id = ...
+aws_secret_access_key = ...
+
+[personal-account] ; my "personal-account" profile
+aws_access_key_id = ...
+aws_secret_access_key = ...
+
+[work-stuff] ; work profile
+aws_access_key_id = ...
+aws_secret_access_key = ...
+```
+
+By default, the SDK checks the `AWS_PROFILE` environment variable for the
+profile name to use. If no `AWS_PROFILE` variable is set in your environment,
+the SDK will use the "default" profile.
+
+In the above case, we could use `AWS_PROFILE=work-stuff`
+to load our work credentials when using the SDK. If we had some `script.js`
+file that used the SDK, we could run it with those credentials by typing:
+
+```
+$ AWS_PROFILE=work-stuff node script.js
+```
+
+It is also possible to explicitly select the profile using the SDK, either
+by setting `process.env.AWS_PROFILE` prior to loading the SDK, or by selecting
+the credential provider manually:
+
+```js
+var credentials = new AWS.SharedIniFileCredentials({profile: 'work-stuff'});
+AWS.config.credentials = credentials;
+```
+
+#### Credentials from Environment Variables
+
+By default, the SDK will automatically detect AWS credentials
+set in your environment and use them for requests. This means that if you
+properly set your environment variables, you do not need to manage credentials
+in your application at all.
+
+The keys that the SDK looks for are as follows:
+
+```plain
+AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN (optional)
+```
+
+Alternately, the SDK can accept the `AMAZON_` prefix instead:
+
+```plain
+AMAZON_ACCESS_KEY_ID, AMAZON_SECRET_ACCESS_KEY, AMAZON_SESSION_TOKEN (optional)
+```
+
+#### Credentials from Disk
+
+You can also load configuration and credentials from disk using
+`AWS.config.loadFromPath` by passing a file to a JSON document
+containing the configuration data. For example, if you had a file
+named 'config.json' with the contents:
+
+```javascript
+{ "accessKeyId": "akid", "secretAccessKey": "secret", "region": "us-east-1" }
+```
+
+You can load the JSON data using the command:
+
+```javascript
+AWS.config.loadFromPath('./config.json');
+```
+
+Note that the `loadFromPath` method clobbers all existing configuration on
+the object. If you are adding extra configuration, make sure you add it
+after this call.
+
+#### Hard-Coding Credentials
+
+<p class="note">We recommend you <strong>not</strong> hard-code
+  credentials inside an application. Use this method only for
+  small personal scripts or for testing purposes.
+</p>
+
+You can hard-code credentials by passing the credential information to the
+configuration object using `AWS.config.update()`:
+
+```javascript
+AWS.config.update({accessKeyId: 'akid', secretAccessKey: 'secret'});
+```
+
+### Setting the Region
+
+The AWS SDK for Node.js doesn't select the region by default. You can choose
+a region similarly to setting credentials by either loading from disk or
+using `AWS.config.update()`:
+
+```javascript
+AWS.config.update({region: 'us-west-1'});
+```
+
+### Locking API Versions
+
+<p class="note">For more information on API version locking in the SDK, see the
+{file:node-services.md Working With Services} section.
+</p>
+
+You can globally configure a set of API versions to use for each service by
+specifying the `apiVersions` parameter in `AWS.config`. For example,
+you can choose to set specific versions of the DynamoDB and EC2 services,
+while selecting the "latest" version of Redshift:
+
+```javascript
+AWS.config.apiVersions = {
+  dynamodb: '2011-12-05',
+  ec2: '2013-02-01',
+  redshift: 'latest'
+}
+```
+
+Note that by default, the SDK will use the "latest" available API version
+when constructing a service.
+
+You can also lock all services at a specific point in time by using a "fuzzy
+version":
+
+```javascript
+// Try to use latest available APIs before this date
+AWS.config.apiVersion = '2012-05-04';
+```
+
+### Configuring a Proxy
+
+If you cannot connect to the internet directly, the SDK supports the use of
+HTTP or HTTPS proxies through global or per-service configuration options. To
+set a proxy, pass the `proxy` option to the `httpOptions` setting of your
+config object. This is how you could set a global proxy:
+
+```javascript
+AWS.config.update({
+  httpOptions: {
+    proxy: 'http://localhost:8080'
+  }
+});
+
+var s3 = new AWS.S3();
+s3.getObject({Bucket: 'bucket', Key: 'key'}, function (err, data) {
+  console.log(err, data);
+});
+```
+
+## Service-Specific Configuration
+
+Occasionally, you might want to apply configuration only to one service.
+For instance, you want to use multiple EC2 objects in different regions.
+You can do this by passing configuration data directly to the service object 
+constructor:
+
+```javascript
+var ec2 = new AWS.EC2({region: 'ap-southeast-2', maxRetries: 15});
+```
+
+Note that the constructor takes all of the same configuration data as the
+`AWS.config` object described above, including credential information.
+
+## Immutable Configuration Data
+
+Global configuration changes apply to all requests for all *newly* created
+services. Any newly created service will merge its local options on top of
+the global configuration data at the time of creation. This means that any
+future updates to the global `AWS.config` object will *not* apply to existing
+service objects. These services would have to be manually updated with the new
+configuration data, or recreated using the following command (assuming an
+existing `s3` service object):
+
+```javascript
+s3 = new AWS.S3(s3.config);
+```

package/doc-src/guide/node-examples.md

@@ -0,0 +1,341 @@
+# @title Examples Using Node.js
+
+# Examples Using Node.js
+
+All of these examples assume that the AWS library is required,
+credentials are loaded via environment variables (`AWS_ACCESS_KEY_ID`
+and `AWS_SECRET_ACCESS_KEY`), and the region is set via 
+`AWS.config.update({region: 'us-west-2'});` or the `AWS_REGION` environment
+variable.
+
+The common preamble code can be summarized as follows:
+
+```javascript
+var AWS = require('aws-sdk');
+AWS.config.region = 'us-west-2';
+```
+
+## Basic Usage Example
+
+The following example shows basic usage of the SDK:
+
+```javascript
+// Load the AWS SDK for Node.js
+var AWS = require('aws-sdk');
+
+/**
+ * Don't hard-code your credentials!
+ * Export the following environment variables instead:
+ *
+ * export AWS_ACCESS_KEY_ID='AKID'
+ * export AWS_SECRET_ACCESS_KEY='SECRET'
+ */
+
+// Set your region for future requests.
+AWS.config.region = 'us-west-2';
+
+// Create a bucket using bound parameters and put something in it.
+// Make sure to change the bucket name from "myBucket" to something unique.
+var s3bucket = new AWS.S3({params: {Bucket: 'myBucket'}});
+s3bucket.createBucket(function() {
+  var data = {Key: 'myKey', Body: 'Hello!'};
+  s3bucket.putObject(data, function(err, data) {
+    if (err) {
+      console.log("Error uploading data: ", err);
+    } else {
+      console.log("Successfully uploaded data to myBucket/myKey");
+    }
+  });
+});
+```
+
+## Amazon Elastic Compute Cloud (Amazon EC2)
+
+### Amazon EC2: Creating an Instance with Tags (`runInstances`, `createTags`)
+
+The Amazon EC2 API has two distinct operations for creating instances and
+attaching tags to instances. In order to create an instance with tags, you can
+call both of these operations in series. The following example adds a "Name"
+tag to a new instance, which the Amazon EC2 console recognizes and displays
+in the Name field of the instance list.
+
+```javascript
+var ec2 = new AWS.EC2();
+
+var params = {
+  ImageId: 'ami-1624987f', // Amazon Linux AMI x86_64 EBS
+  InstanceType: 't1.micro',
+  MinCount: 1, MaxCount: 1
+};
+
+// Create the instance
+ec2.runInstances(params, function(err, data) {
+  if (err) { console.log("Could not create instance", err); return; }
+
+  var instanceId = data.Instances[0].InstanceId;
+  console.log("Created instance", instanceId);
+
+  // Add tags to the instance
+  params = {Resources: [instanceId], Tags: [
+    {Key: 'Name', Value: instanceName}
+  ]};
+  ec2.createTags(params, function(err) {
+    console.log("Tagging instance", err ? "failure" : "success");
+  });
+});
+```
+
+Note that you can add up to 10 tags to an instance, and they can be all added
+in a single call to `createTags`.
+
+## Amazon Simple Storage Service (Amazon S3)
+
+### Amazon S3: List All of Your Buckets (listBuckets)
+
+The following example lists all buckets associated with your AWS account:
+
+```javascript
+var s3 = new AWS.S3();
+s3.listBuckets(function(err, data) {
+  for (var index in data.Buckets) {
+    var bucket = data.Buckets[index];
+    console.log("Bucket: ", bucket.Name, ' : ', bucket.CreationDate);
+  }
+});
+```
+
+### Amazon S3: Create a New Bucket and Object (createBucket, putObject)
+
+The following example puts the string 'Hello!' inside the
+object 'myKey' of bucket 'myBucket':
+
+```javascript
+var s3 = new AWS.S3({params: {Bucket: 'myBucket', Key: 'myKey'}});
+s3.createBucket(function() {
+  s3.putObject({Body: 'Hello!'}, function() {
+    console.log("Successfully uploaded data to myBucket/myKey");
+  });
+});
+```
+
+### Amazon S3: Streaming Objects to Files on Disk (getObject)
+
+You can use the `createReadStream()` method on a request object to
+get a handle to a stream object which supports piping raw HTTP
+body data to a file. This is especially useful when streaming
+objects to streams like filesystem objects. The following example
+shows how you can stream an object from Amazon S3 directly to a file
+on disk:
+
+```javascript
+var s3 = new AWS.S3();
+var params = {Bucket: 'myBucket', Key: 'myImageFile.jpg'};
+var file = require('fs').createWriteStream('/path/to/file.jpg');
+s3.getObject(params).createReadStream().pipe(file);
+```
+
+Alternatively, you can register an 'httpData' event listener on
+the request object to access each chunk of data received across
+the wire (as Buffer objects):
+
+```javascript
+var s3 = new AWS.S3();
+var params = {Bucket: 'myBucket', Key: 'myImageFile.jpg'};
+var file = require('fs').createWriteStream('/path/to/file.jpg');
+
+s3.getObject(params).
+on('httpData', function(chunk) { file.write(chunk); }).
+on('httpDone', function() { file.end(); }).
+send();
+```
+
+### Amazon S3: Getting a pre-signed URL for a getObject operation (getSignedUrl)
+
+A pre-signed URL allows you to give one-off access to other users who may not
+have direct access to execute the operations. Pre-signing generates a valid
+URL signed with your credentials that any user can access. By default, the SDK
+sets all URLs to expire within 15 minutes, but this value can be adjusted.
+
+To generate a simple pre-signed URL that allows any user to view the contents
+of a private object in a bucket you own, you can use the following call to
+`getSignedUrl()`:
+
+```javascript
+var params = {Bucket: 'myBucket', Key: 'myKey'};
+s3.getSignedUrl('getObject', params, function (err, url) {
+  console.log("The URL is", url);
+});
+```
+
+The `getSignedUrl()` operation can also be called synchronously, when the
+callback is omitted. When it is called without a callback, the return value is
+the pre-signed URL. The above example can be re-written synchronously as:
+
+```javascript
+var params = {Bucket: 'myBucket', Key: 'myKey'};
+var url = s3.getSignedUrl('getObject', params);
+console.log("The URL is", url);
+```
+
+Note that this method should only be called synchronously if you can guarantee
+that your credentials are already loaded (or defined statically). In general,
+it is safe to use this method synchronously unless you are using EC2 IAM roles
+or another custom asynchronous credential provider.
+
+### Amazon S3: Getting a pre-signed URL for a PUT operation with a specific payload
+
+If a Body parameter is passed to the payload of a pre-signed PUT object
+operation and checksums are being computed, the SDK will generate the URL
+with a Content-MD5 representing the expected payload contents. You can use
+this functionality to generate pre-signed PUT operations that require a specific
+payload to be uploaded by the consumer of the URL. To generate such a URL,
+simply provide a Body property to the parameter list:
+
+```javascript
+var s3 = new AWS.S3({computeChecksums: true}); // this is the default setting
+var params = {Bucket: 'myBucket', Key: 'myKey', Body: 'EXPECTED CONTENTS'};
+var url = s3.getSignedUrl('putObject', params);
+console.log("The URL is", url);
+```
+
+You can also omit the Body parameter to generate a URL that allows a user to
+write any contents to the given object:
+
+```javascript
+var params = {Bucket: 'myBucket', Key: 'myKey'};
+var url = s3.getSignedUrl('putObject', params);
+console.log("The URL is", url);
+```
+
+### Amazon S3: Controlling Expires time with pre-signed URLs
+
+As mentioned above, pre-signed URLs will expire in 15 minutes by default
+when generated by the SDK. This value is adjustable with the `Expires`
+parameter, an integer representing the number of seconds that the URL will be
+valid, and can be set with any call to `getSignedUrl()`:
+
+```javascript
+// This URL will expire in one minute (60 seconds)
+var params = {Bucket: 'myBucket', Key: 'myKey', Expires: 60};
+var url = s3.getSignedUrl('getObject', params);
+console.log("The URL is", url);
+```
+
+## Amazon DynamoDB
+
+### Amazon DynamoDB: Listing Tables (listTables)
+
+The following example will list all tables in a DynamoDB instance:
+
+```javascript
+var db = new AWS.DynamoDB();
+db.listTables(function(err, data) {
+  console.log(data.TableNames);
+});
+```
+
+## Amazon Glacier
+
+### Amazon Glacier: Creating a Vault
+
+The following example creates a vault named "YOUR_VAULT_NAME":
+
+```javascript
+var glacier = new AWS.Glacier();
+glacier.createVault({vaultName: 'YOUR_VAULT_NAME'}, function(err) {
+  if (!err) console.log("Created vault!")
+});
+```
+
+### Amazon Glacier: Uploading an Archive
+
+<p class="note"><em>Note: this example assumes you have already created a vault
+named "YOUR_VAULT_NAME".</em>
+</p>
+
+The following example will upload a single Buffer object as an entire archive.
+The SDK will automatically compute the tree hash checksum for the data being
+uploaded, though you can override it by passing your own `checksum` parameter.
+
+```javascript
+var glacier = new AWS.Glacier(),
+    vaultName = 'YOUR_VAULT_NAME',
+    buffer = new Buffer(2.5 * 1024 * 1024); // 2.5MB buffer
+
+var params = {vaultName: vaultName, body: buffer};
+glacier.uploadArchive(params, function(err, data) {
+  if (err) console.log("Error uploading archive!", err);
+  else console.log("Archive ID", data.archiveId);
+});
+```
+
+### Amazon Glacier: Multi-part Upload
+
+<p class="note">
+  <em>Note: this example assumes you have already created a vault
+named "YOUR_VAULT_NAME".</em>
+</p>
+
+The following example will create a multi-part upload out of 1MB chunks of a
+Buffer object. Note that a complete SHA-256 tree hash is manually computed
+using the `computeChecksums` method:
+
+```javascript
+var glacier = new AWS.Glacier(),
+    vaultName = 'YOUR_VAULT_NAME',
+    buffer = new Buffer(2.5 * 1024 * 1024), // 2.5MB buffer
+    partSize = 1024 * 1024, // 1MB chunks,
+    numPartsLeft = Math.ceil(buffer.length / partSize),
+    startTime = new Date(),
+    params = {vaultName: vaultName, partSize: partSize.toString()};
+
+// Compute the complete SHA-256 tree hash so we can pass it
+// to completeMultipartUpload request at the end
+var treeHash = glacier.computeChecksums(buffer).treeHash;
+
+// Initiate the multi-part upload
+console.log('Initiating upload to', vaultName);
+glacier.initiateMultipartUpload(params, function (mpErr, multipart) {
+  if (mpErr) { console.log('Error!', mpErr.stack); return; }
+  console.log("Got upload ID", multipart.uploadId);
+
+  // Grab each partSize chunk and upload it as a part
+  for (var i = 0; i < buffer.length; i += partSize) {
+    var end = Math.min(i + partSize, buffer.length),
+        partParams = {
+          vaultName: vaultName,
+          uploadId: multipart.uploadId,
+          range: 'bytes ' + i + '-' + (end-1) + '/*',
+          body: buffer.slice(i, end)
+        };
+
+    // Send a single part
+    console.log('Uploading part', i, '=', partParams.range);
+    glacier.uploadMultipartPart(partParams, function(multiErr, mData) {
+      if (multiErr) return;
+      console.log("Completed part", this.request.params.range);
+      if (--numPartsLeft > 0) return; // complete only when all parts uploaded
+
+      var doneParams = {
+        vaultName: vaultName,
+        uploadId: multipart.uploadId,
+        archiveSize: buffer.length.toString(),
+        checksum: treeHash // the computed tree hash
+      };
+
+      console.log("Completing upload...");
+      glacier.completeMultipartUpload(doneParams, function(err, data) {
+        if (err) {
+          console.log("An error occurred while uploading the archive");
+          console.log(err);
+        } else {
+          var delta = (new Date() - startTime) / 1000;
+          console.log('Completed upload in', delta, 'seconds');
+          console.log('Archive ID:', data.archiveId);
+          console.log('Checksum:  ', data.checksum);
+        }
+      });
+    });
+  }
+});
+```

package/doc-src/guide/node-intro.md

@@ -0,0 +1,32 @@
+# @title AWS SDK for Node.js
+
+# Getting Started with the SDK in Node.js
+
+## Installing with npm
+
+The preferred way to install the AWS SDK for JavaScript in Node.js is to
+use the [npm](http://npmjs.org) package manager for Node.js. To install the SDK,
+simply type the following into a terminal window:
+
+```sh
+npm install aws-sdk
+```
+
+## Loading the SDK
+
+After you've installed the SDK, you can require the AWS package in your node
+application using `require()`:
+
+```javascript
+var AWS = require('aws-sdk');
+```
+
+## Next Steps
+
+Now that you have installed and loaded the SDK, continue on to learn how to
+configure and use the SDK to make requests to API operations on services.
+
+* {file:node-configuring.md Configuring the SDK}
+* {file:node-services.md Working with Services}
+* {file:node-making-requests.md Making Requests}
+* {file:node-examples.md Common Examples}