Amazon S3 API Binding for Google Apps Script

Overview

This library provides a very simple API binding to use Amazon S3 from Google Apps Script. It includes put/delete buckets and put/get/delete objects (CRUD). Almost none of the advanced S3 options regarding either buckets or object operations are supported by this library.

I wrote this library with the motivation to have a key/value store capable of handling objects larger than the 100 KB size limit of Google’s ScriptDB. It’s probably limited by the size of requests that Google allows for the UrlFetch service, which I haven’t tested.

It provides an S3 object, representing the S3 service, which must be constructed with your AWS key and secret. That service has methods to put/delete buckets (by bucket name) and put/get/delete objects (by bucket name + object name). Object content is passed/returned as strings (keep track of the encodings yourself). Getting a non-existent object (AWS error code “NoSuchKey”) returns null.

Unexpected AWS errors result in exceptions (objects with name=”AwsError”).

To look at the code itself, you can read it in Apps Script editor.

Usage Example

 var s3 = S3.getInstance(awsAccessKeyId, awsSecretKey);
var blob = UrlFetchApp.fetch("http://www.google.com").getBlob();

s3.putObject("bucket", "googlehome", blob, {logRequests:true});

//and to get it back
 var fromS3 = s3.getObject("bucket", "googlehome");

Installation

You can link this library into a Google Apps Script using it’s project key:

MB4837UymyETXyn8cv3fNXZc9ncYTrHL9

If you don’t know how to link a library from the Apps Script editor, read Google Apps Scripts : Libraries – Using a Library.

Alternatively, you can make a copy of the project by opening it an choosing File –> Make a Copy.

Documentation

I find in-source documentation to be more reliable and easier to maintain than a webpage, so I’ll leave you with the comments in the source.  I’ve tried to document all the major bits, using Google’s jsDoc style.

License

The full version of the license can be found with the code, but here’s a quick summary: This code is provided as-is, with absolutely no warranty or assurance that it will not delete, corrupt, misplace, or expose your data. If you’re concerned about those risks, don’t use this library.  You can also read the code and, if you find something you don’t like, change it. That’s why they call it open source.

Contributing

Given limitations of Google’s version control system for Apps Script, I’ve put a copy of the source on Github at S3-for-Google-Apps-Script.  Send pull requests / create issues there and I’ll try to get to them, and periodically copy the changes back into the library hosted in Apps Script.

Testing

Run the tests of the library from a separate App Script instance as follows (replacing the environment properties with your own AWS access key / secret):

function runTests() {
 S3.setTestEnv({
   "awsAccessKeyId":"{{replace this with your access key}}",
   "awsSecretKey":"{{replace this with your secret}}",
 });
 S3.runTests();
 //if running in Spreadsheet context, you can uncomment this
 //Browser.msgBox("All tests passed");
}

Check View –> Logs to verify everything went OK, or see where in the tests it died.  If someone wants to point me to a JSUnit-equivalent for Google Apps Script, that’d be awesome. (or better yet, get Jasmine/Karma working for this).

5 thoughts on “Amazon S3 API Binding for Google Apps Script

    • Hi Todd – I haven’t tried that. From a quick look at those docs, it would seem that you could implement an STS client to retrieve the credentials for the assumed role, and then have to pass those credentials (accessKey, secret, possibly sessionToken) when you construct the S3 instance. Those credentials thereafter would be used to construct the auth header for the request.

Make a comment

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s