Amazon Simple Storage Service (S3)

Amazon Simple Storage Service (S3) provides a storage service for any amount of data.

Refer to Amazon Simple Storage Service User Guide for general guidance using S3.

API Access

The IS3Client interface and its implementation TS3Client provides direct access to S3 operations.

Model Access

The IS3Bucket/TS3Bucket models can be used to represent a bucket and make calls to operations relating to that bucket. For example:

var
   Bucket: IS3Bucket;
begin
  // Instantiate a bucket.
  Bucket := TS3Bucket.Create('my-bucket');

  // Work with the bucket.
  for var LObject in Bucket.Objects do
  begin
    // Do something with each object.
  end;
end;

The IS3Object/TS3Object models can be used to represent an object in a bucket and make calls to operations relating to that object.

var
  LObject: IS3Object;
begin
  LObject := TS3Object.Create('my-bucket', 'my-object');
  LObject.DownloadFile('/path/to/file');
end;

Uploading Objects

There are several ways to upload an object to Amazon S3 and the correct way depends on a number of factors. To simplify this, utility classes TS3FileUploader and TS3StreamUploader simplify the process of uploading files and streams respectively.

When using the IS3Object model, the easiest way is to use the UploadFile and UploadStream functions.

Downloading Objects

When downloading objects, by default, the request is performed in-memory and the response content is read off of the response object. For example:

var
  Client: IS3Client;
  Request: IS3GetObjectRequest;
  Response: IS3GetObjectResponse;
begin
  Client := TS3Client.Create;
  Request := TS3GetObjectRequest.Create('my-bucket', 'my-large-object');
  Response := Client.GetObject(Request);
  // Do something with Response.Body
end;

When dealing with large objects working in memory constrained environments, or 32-bit builds, this will cause problems. In such scenarios, or in cases when you intend to write the content to a file, be sure to set the ResponseTarget before making the request to direct the response content appropriately. For example:

var
  Client: IS3Client;
  Request: IS3GetObjectRequest;
  Response: IS3GetObjectResponse;
begin
  Client := TS3Client.Create;
  Request := TS3GetObjectRequest.Create('my-bucket', 'my-large-object');
  Request.ResponseTarget := TS3GetObjectTarget.ToFile('PathToFile');
  Response := Client.GetObject(Request);
  // The response content will be written to the ResponseTarget and Response.Body will not be set.
end;

Note the use of the factory class TS3GetObjectTarget to construct a response target. The factory has 3 convenient methods for generating response targets: ToFile, ToStream, and ToTemporaryFile.

Pre-signing Requests

Requests can be pre-signed for later execution using the utility classes IS3Presigner/TS3Presigner. This can be useful for generating URLs for use on websites or other external resources that don't have direct access to valid credentials.

var
  Request: IS3GetObjectRequest;
  Presigner: IS3Presigner;
  PresignerRequest: IS3PresignerRequest;
  PresignedUrl: string;
begin
  // Create an S3 request.
  Request := TS3GetObjectRequest.Create('my-bucket', 'my-object');

  // Wrap the request inside a pre-signing request.
  PresignerRequest := TS3PresignerRequest.Create(Request);

  // Create a presigner and ask it to pre-sign the request.
  Presigner := TS3Presigner.Create;
  PresignedUrl := Presigner.PresignedUrl(PresignerRequest);
end;

To specify credentials for a pre-signed URL, you can construct a TS3Presigner with some initialized IS3Options. Additional pre-signing specific options such as expiration can be configured on the IS3PresignerRequest. One such option to be aware of is the SignedPayload flag which, when set to false, allows generating PutObject requests without knowing the expected content payload.

Waiters

Waiters are utility classes that help wait on conditions you expect to come true. For example, if you know a bucket does not currently exist but will shortly, you can use a TS3BucketExistsWaiter like:

var
  S3: IS3Client;
  Waiter: IS3BucketWaiter;
begin
  S3 := TS3Client.Create;
  Waiter := TS3BucketExistsWaiter.Create(S3);
  var Result := Waiter.Wait('a-bucket-name');
  if Result.IsSuccessful then
  begin
    // Bucket exists.
  end;
end;

Available waiters:

Waiter Class	Purpose
TS3BucketExistsWaiter	Waits for a bucket to exist.
TS3BucketNotExistsWaiter	Waits for a bucket to not exist.
TS3ObjectExistsWaiter	Waits for an object to exist.
TS3ObjectNotExistsWaiter	Waits for an object to not exist.