Create and Configure an S3 Bucket Create the Amazon S3 Client List Buckets List Objects Download an Object Upload an Object

Amazon Simple Storage Service (S3)

Amazon Simple Storage Service (Amazon S3), provides developers and IT teams with secure, durable, highly-scalable object storage. Unity developers can take advantage of S3 to dynamically load assets used by their games. This can make games initially download quicker from app stores.

For more information about S3, see Amazon S3.

For information about AWS S3 Region availability, see AWS Service Region Availability.

Note

Some of the samples in this document assume the use of a text box variable called ResultText to display trace output.

Create and Configure an S3 Bucket

Amazon S3 stores your resources in Amazon S3 buckets - cloud storage containers that live in a specific region. Each Amazon S3 bucket must have a globally unique name. You can use the Amazon S3 Console to create a bucket.

Create an S3 Bucket

Sign in to the Amazon S3 console and click Create Bucket.
Enter a bucket name, select a region, and click Create.

Set Permissions for S3

The default IAM role policy grants your application access to Amazon Mobile Analytics and Amazon Cognito Sync. In order for your Cognito identity pool to access Amazon S3, you must modify the identity pool’s roles.

Go to the Identity and Access Management Console and click Roles in the left-hand pane.
Type your identity pool name into the search box. Two roles will be listed: one for unauthenticated users and one for authenticated users.
Click the role for unauthenticated users (it will have unauth appended to your identity pool name).
Click Create Role Policy, select Policy Generator, and then click Select.
On the Edit Permissions page, enter the settings shown in the following image, replacing the Amazon Resource Name (ARN) with your own. The ARN of an S3 bucket looks like arn:aws:s3:::examplebucket/* and is composed of the region in which the bucket is located and the name of the bucket. The settings shown below will give your identity pool full to access to all actions for the specified bucket.

Click the Add Statement button and then click Next Step.
The Wizard will show you the configuration that you generated. Click Apply Policy.

For more information on granting access to S3, see Granting Access to an Amazon S3 Bucket.

Upload Files from the Console

To upload a test file to your bucket:

In the S3 console, in your bucket view, click Upload.
Click Add Files and select a test file to upload. For this tutorial, we’ll assume you’re uploading an image called myImage.jpg.
With your test image selected, click Start Upload.

(optional) Configure the Signature Version for S3 Requests

Every interaction with Amazon S3 is either authenticated or anonymous. AWS uses the Signature Version 4 or Signature Version 2 algorithms to authenticate calls to the service.

All new AWS regions created after January 2014 only support Signature Version 4. However, many older regions still support Signature Version 4 and Signature Version 2 requests.

If your bucket is in one of the regions that does not support Signature Version 2 requests as listed on this page, you must set the AWSConfigsS3.UseSignatureVersion4 property to “true”.

For more information on AWS Signature versions, see Authenticating Requests (AWS Signature Version 4).

Create the Amazon S3 Client

To use Amazon S3, we first need to create an AmazonS3Client instance which takes a reference to the CognitoAWSCredentials instance you created previously:


AmazonS3Client S3Client = new AmazonS3Client (credentials);

The AmazonS3Client class is the entry point to the high-level S3 API.

List Buckets

To list the buckets in an AWS account call the AmazonS3Client.ListBucketsAsync method as shown in the following sample code:


// ResultText is a label used for displaying status information
ResultText.text = "Fetching all the Buckets";
 Client.ListBucketsAsync(new ListBucketsRequest(), (responseObject) =>
 {
     ResultText.text += "\n";
     if (responseObject.Exception == null)
     {
         ResultText.text += "Got Response \nPrinting now \n";
         responseObject.Response.Buckets.ForEach((s3b) =>
         {
             ResultText.text += string.Format("bucket = {0}, created date = {1} \n",
             s3b.BucketName, s3b.CreationDate);
         });
     }
     else
     {
         ResultText.text += "Got Exception \n";
     }
 });

List Objects

To list all of the objects in a bucket call the AmazonS3Client.ListObjectsAsync method as shown in the following sample code:


// ResultText is a label used for displaying status information
ResultText.text = "Fetching all the Objects from " + S3BucketName;

var request = new ListObjectsRequest()
{
    BucketName = S3BucketName
};

Client.ListObjectsAsync(request, (responseObject) =>
{
    ResultText.text += "\n";
    if (responseObject.Exception == null)
    {
        ResultText.text += "Got Response \nPrinting now \n";
        responseObject.Response.S3Objects.ForEach((o) =>
        {
            ResultText.text += string.Format("{0}\n", o.Key);
        });
    }
    else
    {
        ResultText.text += "Got Exception \n";
    }
});

Download an Object

To download an object, create a GetObjectRequest, specifying the bucket name and key and pass the object to a call to Client.GetObjectAsync:


private void GetObject()
{
    ResultText.text = string.Format("fetching {0} from bucket {1}",
    SampleFileName, S3BucketName);
    Client.GetObjectAsync(S3BucketName, SampleFileName, (responseObj) =>
    {
       string data = null;
       var response = responseObj.Response;
       if (response.ResponseStream != null)
       {
          using (StreamReader reader = new StreamReader(response.ResponseStream))
          {
             data = reader.ReadToEnd();
          }

          ResultText.text += "\n";
          ResultText.text += data;
       }
  });
}

GetObjectAsync takes an instance of the GetObjectRequest, a callback, and an AsyncOptions instance. The callback must be of type: AmazonServiceCallback<GetObjectRequest, GetObjectResponse>. The AsyncOptions instance is optional. If specified, it determines if the callback will run on the main thread.

Upload an Object

To upload an object, write your object to a stream, create a new PostObjectRequest and specify the key, bucket name and stream data.

The AWS SDK for Unity uses the WWW HTTP client which does not support the HTTP PUT operation. In order to upload an object to your S3 bucket, you need to use S3’s Browser Post, as shown below.


public void PostObject(string fileName)
{
    ResultText.text = "Retrieving the file";

    var stream = new FileStream(Application.persistentDataPath +
    Path.DirectorySeparatorChar + fileName,
    FileMode.Open, FileAccess.Read, FileShare.Read);

    ResultText.text += "\nCreating request object";
    var request = new PostObjectRequest()
    {
        Bucket = S3BucketName,
        Key = fileName,
        InputStream = stream,
        CannedACL = S3CannedACL.Private
    };

    ResultText.text += "\nMaking HTTP post call";

    Client.PostObjectAsync(request, (responseObj) =>
    {
        if (responseObj.Exception == null)
        {
            ResultText.text += string.Format("\nobject {0} posted to bucket {1}",
            responseObj.Request.Key, responseObj.Request.Bucket);
        }
        else
        {
            ResultText.text += "\nException while posting the result object";
            ResultText.text += string.Format("\n receieved error {0}",
            responseObj.Response.HttpStatusCode.ToString());
        }
    });
}

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Amazon Mobile Analytics

Amazon DynamoDB