Examples on this Site

This site is going to provide you a lot of examples to help you get the most out of AwsSum, however each example requires a fair bit of boilerplate so that we can bootstrap your program. So let's take a look at a complete program and then show you some boilerplate that you'll need for each example.

var fmt = require('fmt');
var awssum = require('awssum');
var amazon = awssum.load('amazon/amazon');
var S3 = awssum.load('amazon/s3').S3;

var env             = process.env;
var accessKeyId     = env.ACCESS_KEY_ID;
var secretAccessKey = env.SECRET_ACCESS_KEY;
var awsAccountId    = env.AWS_ACCOUNT_ID;

var s3 = new S3({
    'accessKeyId'     : accessKeyId,
    'secretAccessKey' : secretAccessKey,
    'region'          : amazon.US_EAST_1,
});

fmt.line();
fmt.title('Credentials');

fmt.field('Region',          s3.region());
fmt.field('EndPoint',        s3.host() );
fmt.field('AccessKeyId',     s3.accessKeyId().substr(0, 3) + '...' );
fmt.field('SecretAccessKey', s3.secretAccessKey().substr(0, 3) + '...' );
fmt.field('AwsAccountId',    s3.awsAccountId() );

fmt.line();

s3.ListBuckets(function(err, data) {
    fmt.title('Amazon:S3 - ListBuckets');
    fmt.dump(err,  'Error');
    fmt.dump(data, 'Data');
    fmt.line();
});

This would give output similar to the following:

-------------------------------------------------------------------------------
--- Credentials ---------------------------------------------------------------
Region               : us-east-1
EndPoint             : s3.amazonaws.com
AccessKeyId          : 0WC...
SecretAccessKey      : +/7...
AwsAccountId         : undefined
-------------------------------------------------------------------------------
--- Amazon:S3 - ListBuckets ---------------------------------------------------
Error : null
Data : { StatusCode: 200,
  Headers:
   { 'x-amz-id-2': 'rV+gG0bhM8Xn/x/AbKuld8omz0rd6bXmrIVo37i86jzj0q6POFxEXj3GVd43CV0d',
     'x-amz-request-id': 'ACAC6AC3A8197DFA',
     date: 'Sat, 01 Sep 2012 01:28:55 GMT',
     'content-type': 'application/xml',
     'transfer-encoding': 'chunked',
     server: 'AmazonS3' },
  Body:
   { ListAllMyBucketsResult:
      { '@': { xmlns: 'http://s3.amazonaws.com/doc/2006-03-01/' },
        Owner:
         { ID: '74c...',
           DisplayName: 'MyDisplayName' },
        Buckets:
         { Bucket:
            [ { Name: 'my-bucket-1',
                CreationDate: '2008-01-06T10:04:16.000Z' },
              { Name: 'another-bucket',
                CreationDate: '2008-03-09T08:27:30.000Z' },
              { Name: 'a-third-bucket',
                CreationDate: '2011-02-20T01:59:36.000Z' } ] } } } }
-------------------------------------------------------------------------------

Let's take each stanza one at a time.

Loading AwsSum and your Service

var fmt = require('fmt');
var awssum = require('awssum');
var amazon = awssum.load('amazon/amazon');
var S3 = awssum.load('amazon/s3').S3;

Here we're loading one helper module (fmt) and the relevant parts of AwsSum. In this case we're using the Amazon service (so we can get access to the region names) and the Amazon:S3 service.

Reading your Credentials from your Environment

var env             = process.env;
var accessKeyId     = env.ACCESS_KEY_ID;
var secretAccessKey = env.SECRET_ACCESS_KEY;
var awsAccountId    = env.AWS_ACCOUNT_ID;

For our examples, we're not going to past our AwsAccountId, AccessKeyId or SecretAccessKey here, so instead we're going to read them from the environment. In the case for Amazon, you should set these in your shell prior to running your program.

Creating the Service Object

var s3 = new S3({
    'accessKeyId'     : accessKeyId,
    'secretAccessKey' : secretAccessKey,
    'region'          : amazon.US_EAST_1,
});

Here we're creating the S3 object on which you can call your operations. If you need to call operations in a different region then you need to create another service object.

e.g. creating an SQS service object for us-west-1. Of course, you'd have to tell AwsSum to pre-load your SQS service prior to creating this service object.

var sqs = new Sqs({
    'accessKeyId'     : accessKeyId,
    'secretAccessKey' : secretAccessKey,
    'region'          : amazon.US_WEST_1,
});

Performing the Operation

s3.ListBuckets(function(err, data) {
    fmt.title('Amazon:S3 - ListBuckets');
    fmt.msg("listing all the buckets (no options given) - expecting success");
    fmt.dump(err,  'Error');
    fmt.dump(data, 'Data');
    fmt.line();
});

Don't let the fmt.* calls put you off (just npm install fmt to use them). fmt is a command line output module. Instead, we're just interested in err and data here. If err is defined, then something went wrong. If data is defined, then everything was fine. It's the standard way for Node.js callbacks. :)