Uploading to Cloud Storages

Uploading to Amazon S3

When you create an account in the Amazon Web Service (AWS) you obtain your Access Key Id and Secret Access Key. These parameters are used for authentication purposes:

• AWS Access Key Id identifies your AWS account. This key is included in every AWS request to identify the user;
• Secret Access Key is never included into requests and used to sign AWS requests. Each request must contain a valid signature calculated using the Secret Access Key, otherwise authentication will fail.

To store objects Amazon S3 uses buckets which are quite similar to Internet domain names and must be unique within the Amazon S3. For example, if the object named myphotos/holiday.jpg is stored in the mybucket bucket, the URL to access this object is http://mybucket.s3.amazonaws.com/myphotos/holiday.jpg. Every bucket has an associated access control list used to verify whether the sender is able to access this bucket. Each object represents a file and metadata stored within a bucket using a unique key. A bucket and key together uniquely identify each object stored in the Amazon S3.

In the simplest case, to create a new Amazon S3 object you need to send the POST request which identifies the sender and defines the object to be created. It means that Image Uploader can be used for this purpose. So, to implement this functionality you can take an advantage of one of the following approaches.

Using Image Uploader Embedding Scripts Library

This approach is more complicated but can be used with any Image Uploader supported server platform. It lies in using the AmazonS3Extender class defined in the iuembed.AmazonS3.js file of the JavaScript library. However, before you initialize this class instance you should prepare additional data required for uploading to Amazon S3 storage: the security policy and signature.

The policy is a UTF-8 and Base64 encoded JSON document which specifies the date when this policy expires and conditions the request must meet. The expiration date must be in ISO8601 GMT date format. The conditions are used to validate the uploaded object and include definitions for access control list, bucket, key, and metadata fields (both default and custom).

Here is the code sample that creates a policy document which expires in 100 minutes and defines an access control list option, bucket name, uploaded file, two default fields (width and height), and one custom (author).

private string ConstructPolicy()
{
    StringBuilder policy = new StringBuilder();
    DateTime expDate = DateTime.Now.ToUniversalTime().AddSeconds(6000);

    policy.AppendLine("{ \"expiration\": \"" + expDate.ToString("s") + ".000Z\"");
    policy.AppendLine(", \"conditions\": [");
    policy.AppendLine(" {\"acl\": \"" + _acl + "\" }");
    policy.AppendLine(" , {\"bucket\": \"" + _bucket + "\" }");
    policy.AppendLine(" , {\"success_action_status\": \"200\"}");
    policy.AppendLine(" , [\"starts-with\", \"$key\", \"\"]");

    policy.AppendLine(" , [\"starts-with\", \"$x-amz-meta-width\", \"\"]");
    policy.AppendLine(" , [\"starts-with\", \"$x-amz-meta-height\", \"\"]");
    policy.AppendLine(" , [\"starts-with\", \"$x-amz-meta-author\", \"\"]");
                
    policy.AppendLine("]");
    policy.AppendLine("}");

    return policy.ToString();
} 

To create a signature encode your policy document using UTF-8 and then encode these bytes using Base64. After that sign the policy with your Secret Access Key using HMAC SHA-1 and encode the SHA-1 signature using Base64. See the code sample below, it demonstrates how to create a signature in .NET.

public string CreateSignature()
{
    //Policy and signature
    string policy = this.ConstructPolicy();

    //Step 1. Encode the policy using UTF-8.
    byte[] pb = new byte[policy.Length];
    pb = System.Text.Encoding.UTF8.GetBytes(policy);

    //Step 2. Encode those UTF-8 bytes using Base64.
    _policyB64 = Convert.ToBase64String(pb);

    //Step 3. Sign the policy with your Secret Access Key using HMAC SHA-1.
    System.Security.Cryptography.HMACSHA1 hmac = new System.Security.Cryptography.HMACSHA1();
    hmac.Key = System.Text.Encoding.UTF8.GetBytes(_secretAccessKey);

    byte[] signb = hmac.ComputeHash(System.Text.Encoding.UTF8.GetBytes(_policyB64));

    //Step 4. Encode the SHA-1 signature using Base64.
    _signature = Convert.ToBase64String(signb);
}

Then initialize an AmazonS3Extender object and specify your AWSAccessKeyId and bucket using the setAWSAccessKeyId and setBucket properties. However, if you have a host name associated with an Amazon S3 bucket you should additionally specify this host name using the setBucketHostName property.

<script type="text/javascript" src="iuembed.js">  </script>  
<script type="text/javascript" src="iuembed.AmazonS3.js">  </script>                  
<script type="text/javascript">
var iu = new ImageUploaderWriter("ImageUploader", 600, 500);

// ...Other params...
 
var as3 = new AmazonS3Extender(iu);
as3.setAWSAccessKeyId(_AWSAccessKeyId);
as3.setBucket(_bucket);
as3.setBucketHostName("http://yourdomain.com/");

// ...Other params...

iu.writeHtml();
</script>

Then configure the extender to send a file and metadata in accordance with the policy constructed before. In the case if Image Uploader uploads a source file use the AmazonS3Extender.getSourceFile property to access and configure it to upload to Amazon S3 storage. If Image Uploader uploads a thumbnail use the AmazonS3Extender.getThumbnail1, AmazonS3Extender.getThumbnail2, or AmazonS3Extender.getThumbnail3 property depending on what thumbnail is configured. For the uploaded file (a source or thumbnail) the following properties should be initialized:

• setAcl specifies an access control list (should be equal to the acl value defined in the policy).
• setKey specifies a key of Amazon S3 object to be created. Here you can use the ${filename} variable to set a filename provided by the user.
• setPolicy specifies a policy constructed and encoded before.
• setSignature specifies a signature.

Use the addPredefinedProperty and addProperty methods to add predefined and custom metadata fields respectively. Fields added with these methods should be defined in the policy. For example, if you use the policy from the sample above use the following code to add corresponding metadata fields.

var as3 = new AmazonS3Extender(iu);

// ...Other params...

as3.getSourceFile().setAcl(_acl);
as3.getSourceFile().setKey("${filename}");
as3.getSourceFile().setPolicy(_policy);
as3.getSourceFile().setSignature(_signature);

as3.getSourceFile().addPredefinedProperty("Width", "Width_[ItemIndex]");
as3.getSourceFile().addPredefinedProperty("Height", "Height_[ItemIndex]");
as3.getSourceFile().addProperty("Author", "John Smith");

See the Amazon S3 Documentation for the detailed information on how to upload files to Amazon S3 using POST.

Using Image Uploader ASP.NET Control

This approach is simpler, but applicable for ASP.NET applications only. This approach releases you from necessity to prepare the policy and signature yourself as well as familiarize with the Amazon S3 API. You just need to perform the following steps to force Image Uploader to upload files directly to Amazon S3 storage.

1. Initialize an AmazonS3Extender object.
2. Specify your AWSAccessKeyId, secretAccessKey, and bucket as values of the AWSAccessKeyId, SecretAccessKey, and Bucket properties.
3. Access the uploaded file using the SourceFile, Thumbnail1, Thumbnail2, or Thumbnail3 property.
4. Specify acl and key for this file. Use the Acl and Key properties for it.
5. Add as many metadata fields as you like by adding PredefinedMetaProperty and CustomMetaProperty objects to the MetaProperties list.

<%@ Page Language="C#" AutoEventWireup="true" %>

<%@ Register assembly="Aurigma.ImageUploader" namespace="Aurigma.ImageUploader" tagprefix="aur" %>
<%@ Register assembly="Aurigma.ImageUploader" namespace="Aurigma.ImageUploader.AmazonS3" tagprefix="aur" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
	<title>Untitled Page</title>
</head>
<body>
    <form id="form1" runat="server">

		<aur:ImageUploader ID="ImageUploader1" runat="server" 
			width="600" height="400" />
		
		<aur:AmazonS3Extender ID="AmazonS3Extender1" runat="server" 
			ImageUploaderID="ImageUploader1" 
			AWSAccessKeyId="<%$ _AWSAccessKeyId %>"
			SecretAccessKey="<%$ _SecretAccessKey %>"
			Bucket="<%$ _Bucket %>"			
		>
			<SourceFile Acl="<%$ _acl %>" Key="${filename}">
				<aur:PredefinedMetaProperty Name="imagewidth"  Field="Width_[ItemIndex]" />
				<aur:PredefinedMetaProperty Name="imageheight"  Field="Height_[ItemIndex]" />
				<aur:CustomMetaProperty Name="author" Value="John Smith" />
			</SourceFile>			
		</aur:AmazonS3Extender>
   </form>
</body>
</html>

Using Image Uploader PHP Library

The present approach is to use Image Uploader PHP library to upload files to Amazon S3 storage. To implement this functionality the PHP library exposes the same name classes and the same object model as the ASP.NET control (see the section above). So, to extend Image Uploader with a direct upload to Amazon S3 storage, follow the steps below:

1. Create an AmazonS3Extender object.
2. Specify your AWSAccessKeyId, bucket, and secretAccessKey as values of the setAWSAcceccKeyId($value), setBucket($value), and setSecretAccessKey($value) properties respectively.
3. Retrieve the uploaded file represented by the FileSettings class using the getSourceFile(), getThumbnail1(), getThumbnail2(), or getThumbnail3() property.
4. Set acl and key for this file. To do it, use the setAcl($value) and setKey($value) properties of the FileSettings class.
5. Add as many metadata fields as you like by adding PredefinedMetaProperty and CustomMetaProperty objects to the collection of metadata fields using the FileSettings::addMetaProperty($metaProperty) method.

<?php
require_once '../ImageUploaderPHP/Main.php';
require_once '../ImageUploaderPHP/AmazonS3Extender.class.php';
?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <title>Amazon S3 Demo</title>
</head>
<body>
  <?php
    $iu = new ImageUploader('ImageUploader1', 650, 400);

    $as3 = new AmazonS3Extender($iu);
    $as3->setAWSAcceccKeyId($amazon_AWSAccessKeyId);
    $as3->setBucket($amazon_Bucket);
    $as3->setSecretAccessKey($amazon_SecretAccessKey);
    $as3->getSourceFile()->setAcl($acl);
    $as3->getSourceFile()->setKey($destination_folder .'${filename}');
	$as3->getSourceFile()->addMetaProperty(new PredefinedMetaProperty("imagewidth", "Width_[ItemIndex]"));
	$as3->getSourceFile()->addMetaProperty(new PredefinedMetaProperty("imageheight", "Height_[ItemIndex]"));
	$as3->getSourceFile()->addMetaProperty(new CustomMetaProperty("author", "John Smith"));

    $iu->render();
  ?>
</body>
</html>

Uploading to Nirvanix

In the common case, to access Nirvanix storage you must provide the username and password you are registered in the service with. Another access parameter is the application key which represents an identifier of the application you are going to access.

By analogy with Amazon S3, to configure Image Uploader to upload files to the Nirvanix service you may use one of the following approaches.

Using Image Uploader Embedding Scripts Library

This approach is more flexible but requires you to be familiarized with the Nirvanix API. All you need in this case is to send at least two requests to the Nirvanix service, parse returned XML responses, and instantiate a NirvanixExtender object. Each request represents a call to a corresponding Nirvanix method. The URL format for requests is:

http(s)://services.nirvanix.com/ws/{NameSpace}/MethodName.ashx?name=value&name2=value2

When you call some method you get a response in XML format. The default XML response for methods which do not return data is:

<Response>
  <ResponseCode>0</ResponseCode>
</Response>

So, with the NirvanixExtender you can configure Image Uploader to send files directly to the Nirvanix storage from any HTTP-compliant server platform. To implement this functionality go through the following steps:

1. Call the Login method with your appKey, userName, and password:

   /ws/Authentication/Login.ashx?appKey=your_key&userName=your_name&password=your_password

2. Retrieve the sessionToken from the returned response.

3. Call the GetStorageNodeExtended method with the sessionToken obtained on the previous step, size of the file to be uploaded, and the destination folder:

   /ws/IMFS/GetStorageNodeExtended.ashx?sessionToken=your_token&sizeBytes=filesize&destFolderPath=path

4. Retrieve the uploadHost and uploadToken from the returned response.

5. Add a NirvanixExtender object to your Image Uploader configuration. Pass the uploadToken and uploadHost returned by the GetStorageNodeExtended method and the destination folder to this object. Use the setUploadToken, setUploadHost, and setDestFolderPath properties for it.

   Note

   The destination folder passed to the GetStorageNodeExtended method must be equal to the one specified with the setDestFolderPath property.

   JavaScript

   <script type="text/javascript" src="iuembed.js">  </script>  
   <script type="text/javascript" src="iuembed.Nirvanix.js">  </script>                  
   <script type="text/javascript">
   var iu = new ImageUploaderWriter("ImageUploader", 600, 500);
   
   // ...Other params...
    
   var ne = new NirvanixExtender(iu);
   ne.setUploadToken(_uploadToken);
   ne.setUploadHost(_uploadHost);
   ne.setDestFolderPath(_destFolderPath);
   
   // ...Other params...
   
   iu.writeHtml();
   </script>

Using Image Uploader ASP.NET Control

This approach is simpler than the first described. Here you do not need to call Nirvanix methods directly; the ASP.NET control obtains the required data itself. Thus, you just need to initialize a NirvanixExtender object and specify your appKey, userName, and password as values of the corresponding properties. See the code sample below.

<%@ Page Language="C#" AutoEventWireup="true" %>

<%@ Register assembly="Aurigma.ImageUploader" namespace="Aurigma.ImageUploader" tagprefix="cc1" %>
<%@ Register assembly="Aurigma.ImageUploader" namespace="Aurigma.ImageUploader.Nirvanix" tagprefix="cc2" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
    <title>Untitled Page</title>
</head>
<body>
    <form id="form1" runat="server">

    <cc1:ImageUploader ID="ImageUploader1" runat="server" 
		Width="600" Height="400" />

	<cc2:NirvanixExtender ID="NirvanixExtender1" runat="server" ImageUploaderID="ImageUploader1" 
		DestFolderPath="/upload/"
		AppKey="<%$ _appKey %>" 
		Password="<%$ _password %>" 
		Username="<%$ _username %>" />

	</form>
</body>
</html>

Using Image Uploader PHP Library

By analogy with Image Uploader ASP.NET control, PHP library includes the NirvanixExtender class to extend Image Uploader with direct upload to Nirvanix storage. To implement this functionality just set your appKey, userName, and password as values of the setAppKey($value), setUsername($value), and setPassword($value) properties.

<?php
require_once '../ImageUploaderPHP/Main.php';
require_once '../ImageUploaderPHP/NirvanixExtender.class.php';
?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <title>Nirvanix Demo</title>
</head>
<body>
 <?php
    $iu = new ImageUploader('ImageUploader1', 650, 400);

    $nvx = new NirvanixExtender($iu);
    $nvx->setAppKey($nirvanix_app_key);
    $nvx->setUsername($nirvanix_username);
    $nvx->setPassword($nirvanix_password);
    $nvx->setDestFolderPath($destination_folder);
    
	$iu->render();
 ?>
</body>
</html>

See Also

Reference

• AmazonS3Extender Class
• FileSettings Class
• PredefinedMetaProperty Class
• CustomMetaProperty Class
• NirvanixExtender Class
• AppKey Property
• Password Property
• Username Property
• AmazonS3Extender PHP Class
• NirvanixExtender PHP Class

Samples

• Amazon S3 Demo Sample
• Amazon S3 Images Demo Sample
• Nirvanix Demo Sample

Manual

• Image Uploader Extenders