Using Force for Amazon Web Services

Abstract

This document is intended to be a developer's guide on how to use Force.com for Amazon Web Services. The following sections walk you through a few of the samples to show how you can leverage the toolkit and extend it for your Force.com applications.

Prerequisites

Before proceeding, please make sure you have properly installed and setup Force.com for Amazon Web Services as documented here Installing Force.com for Amazon Web Services. That includes installing the AppExchange package, completing the post-installation steps, and creating a Force.com IDE project for the org where you installed the Toolkit.

How the Toolkit accesses the Amazon Web Service (AWS) account key and secret

This section walks you through how the toolkit enables Force.com to send authenticated amazon web service calls with your Amazon Web Service account key and secret.

The first step is entering in your Amazon Web Service (AWS) key and secret into Force.com. If you remember back to the Setup instructions, it walked you through entering in your AWS account key and secret as a record in the AWS Credentials custom object. By storing the AWS Account information in a custom object, you could extend the toolkit to use different AWS accounts for different processes. Or for different AWS services (S3, EC2). This also avoids having to hardcode your AWS in the Apex Code. To read the instructions on setting up your AWS credentials in the custom object: Click here

Secondly, the apex code that comprises the Toolkit code base can be easily modified to query the AWS Credentials custom object to retrieve the key and secret. That means the key and secret are not coded into the Apex Class. Instead, the Name of the AWS Credential record you created in the custom object is set in the Apex Class. To read the instructions on modifying the Apex Code to reference the proper AWS credential record: Click here

Code Walkthrough

Let's take one of the S3 examples provided in the toolkit and walk through each step. Below is the order of execution starting from when a user clicks on the "S3 Examples" tab in the browser and it resulting in a Amazon Web Service being initiated.

  1. First, the user clicks on the tab labeled 'S3 Samples'. This causes a Visualforce page, AWS_S3_Examples, to load in the browser. That visualforce page uses a custom controller (which is an Apex Class). The highlighted portion below illustrates the apex method that is invoked when this Visualforce page is rendered.

  2. Inside the AWS_S3_ExampleController.cls, there is a method, constructor(), that was invoked when the Visualforce page was rendered as discussed above. The first line of apex code in that method invokes an Apex query to get AWS Key and Secret from the AWSKey__c custom object. It queries by the Name which is specified in the AWS_S3_ExampleController.cls in the string variable, AWSCredentialName. Below are two screenshots to highlight the two portions of the AWS_S3_ExampleController apex class that was just described.
    Modify this string variable to the Name of the AWS Credential record


The highlighted line of code performs an apex query to get the key and secret from the custom object


And that is it to provide Force.com for Amazon Web Services with the AWS key and secret. The toolkit contains all of the required logic to send the key, secret, and other signature attributes to the Amazon Web Services.

How the Toolkit creates a new bucket in the AWS Account (CreateBucket API)

This section will walk you through how to invoke the Amazon S3 web service, CreateBucket, to create a new bucket on your AWS S3 account.

The following steps will continue where the previous section left off. At this point, the 'S3 Examples' tab has been loaded and the AWS_S3_ExampleController custom controller has been initialized. If not, simply click on the 'S3 Examples' tab.

1. The user enters in the desired bucket name to create in the 'S3 Examples' user interface and clicks the button, 'Create Bucket'



2. When that button is clicked, the Visualforce page executes the Action associated with the <apex:commandButton>. The Action is an apex method in the custom controller.



3. In this case, it executes the createBucket() method in the controller class, AWS_S3_ExampleController.cls. And that method calls the calls another method in the S3 Apex Class, which is ultimately the toolkit class that invokes the web service calls to/from AWS.



4. Lastly, the S3 apex class finally invokes the CreateBucket API to Amazon S3. The highlighted code below is the exact point where Apex makes a web service call to Amazon. Upon response, the AWS_S3_ExampleController handles the results or exceptions and ultimately re-renders the Visualforce page accordingly.



Understanding how the Toolkit supports Uploading large files

Force.com for Amazon Web Services provides a user interface to upload large files (> 100 kb) through the POST protocol. As shown below, the POST protocol architecture directly links the web browser to the Amazon S3 service. It does not send the upload request through a web server, in this case, the Force.com servers.




Code Walkthrough

Included in Force.com for Amazon Web Services, there is built in support for uploading large files, storing them on Amazon S3, and displaying them from within Force.com. Below are steps to walk you through that example.

  1. First, start off by clicking on the 'AWS S3 Object' tab and click the 'New' button to create a new record. Instead of being navigated to the standard Force.com edit page, you should be in a custom Visualforce page which can be determined by looking at the URL. It should contain /apex/news3object.
    NOTE: If not, please make sure the Action Override has been set on the AWS S3 Object as detailed here: Installing_Force_for_Amazon_Web_Services#Post-Installation:_Configure_Action_Override
  2. Next, select the desired bucket, enter in the key name to be stored in S3, and select the proper Content type from the drop-down. Click 'Continue'

  3. Now, select the file to upload and click the 'Send to Amazon' button.

  4. When the 'Send to Amazon' button was clicked, the custom controller which enables all of the logic of this Visualforce user interface will be initiated. Lastly, an HTML FORM POST is executed from the browser sending the object to S3 to be uploaded. Upon response, the Visualforce page is refreshed and now displays the S3-hosted object inline within the page. To see the code for this HTML FORM post, check out the S3FormController.cls apex class.



NOTE: Force.com for Amazon Web Services does support uploading objects through the S3 SOAP API. It has a limit of uploading objects with a maximum size of 100 KB due to the maximum size of a single Apex web service request. To see the apex code for this functionality, see the S3.cls apex class, putObjectInline_ACL method.

Related Content


Retrieved from "http://wiki.developerforce.com/page/Using_Force_for_Amazon_Web_Services"