S3 Action Plugin

Actions

S3.CreateBucket(string AccessKey, string SecretKey, string BucketName, string Region = "us-east-1")

Description:

Creates a new Amazon S3 bucket.

AccessKey:

(string) The access key for the S3 account.

SecretKey:

(string) The secret (password) for the S3 access key.

BucketName:

(string) The name the bucket should receive on the S3 service. Bucket names must be unique worldwide.

Note:
Bucket names must be between 3 and 63 characters long.
Bucket names can consist only of lowercase letters, numbers, dots (.), and hyphens (-).
Bucket names must begin and end with a letter or number.
Bucket names must not be formatted as an IP address (for example, 192.168.5.4).
Bucket names must not start with the prefix xn--.
Bucket names must not end with the suffix -s3alias.

Region:

(string) The region where the bucket will be created. Suppress the parameter for default region (us-east-1), or provide one of the valid regions, such as "us-east-2", "us-west-1", "us-west-2", "af-south-1", "ap-east-1", "ap-south-1", "ap-northeast-1", "ap-northeast-2", "ap-northeast-3", "ca-central-1", "cn-north-1", "cn-northwest-1", "eu-central-1", "eu-west-1", "eu-west-2", "eu-west-3", "eu-south-1", "eu-north-1", "sa-east-1" or "me-south-1".

Returns:

(nothing) You can use Application.GetLastError() to determine whether this action failed, and why.

Example:

-- create a new bucket in São Paulo (sa-east-1)
S3.CreateBucket("XB62MKR20PLAQN8XXZNI", "a45cb919efb11bfa040345aad71101234f58eabcd7d7da1a141202109288712b", "XPTO-MyNewBucket-001", "sa-east-1");
error = Application.GetLastError();
if (error ~= 0) then
   Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
else
   Dialog.Message("Info", "Bucket was created.", MB_OK, MB_ICONINFORMATION);
end

S3.DeleteBucket(string AccessKey, string SecretKey, string BucketName, string Region = "us-east-1")

Description:

Deletes an existing Amazon S3 bucket.

AccessKey:

(string) The access key for the S3 account.

SecretKey:

(string) The secret (password) for the S3 access key.

BucketName:

(string) The name the bucket to be deleted.

Region:

(string) The region where the bucket will be deleted. You may suppress the parameter if the bucket was created in the default region (us-east-1), if not, provide one of the valid regions, such as "us-east-2", "us-west-1", "us-west-2", "af-south-1", "ap-east-1", "ap-south-1", "ap-northeast-1", "ap-northeast-2", "ap-northeast-3", "ca-central-1", "cn-north-1", "cn-northwest-1", "eu-central-1", "eu-west-1", "eu-west-2", "eu-west-3", "eu-south-1", "eu-north-1", "sa-east-1" or "me-south-1".

Returns:

(nothing) You can use Application.GetLastError() to determine whether this action failed, and why.

Note: Only empty buckets (without sub folders, or files/objects) can be deleted.

Example:

-- delete a new bucket in the default region
S3.DeleteBucket("XB62MKR20PLAQN8XXZNI", "a45cb919efb11bfa040345aad71101234f58eabcd7d7da1a141202109288712b", "MyEmptyBucket-123");
error = Application.GetLastError();
if (error ~= 0) then
   Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
else
   Dialog.Message("Info", "Bucket was deleted.", MB_OK, MB_ICONINFORMATION);
end

S3.DoesObjectExist(string AccessKey, string SecretKey, string BucketName, string FilePath, string Region = "us-east-1")

Description:

Determines if a remote object (file) exists.

AccessKey:

(string) The access key for the S3 account.

SecretKey:

(string) The secret (password) for the S3 access key.

BucketName:

(string) The name the bucket.

FilePath

(string) The path (folder name and filename) of the file to be checked online.

Region:

(string) The region where the object will be searched. You may suppress the parameter if the bucket was created in the default region (us-east-1), if not, provide one of the valid regions, such as "us-east-2", "us-west-1", "us-west-2", "af-south-1", "ap-east-1", "ap-south-1", "ap-northeast-1", "ap-northeast-2", "ap-northeast-3", "ca-central-1", "cn-north-1", "cn-northwest-1", "eu-central-1", "eu-west-1", "eu-west-2", "eu-west-3", "eu-south-1", "eu-north-1", "sa-east-1" or "me-south-1".

Returns:

(boolean) True if the file exists, false if the path was not found. You can use Application.GetLastError() to determine whether this action failed, and why.

Example:

-- checks if the file "myfile.txt" exists in a folder named "testfolder" in bucket "MyOwnBucket123"
if not S3.DoesObjectExist("XB62MKR20PLAQN8XXZNI", "a45cb919efb11bfa040345aad71101234f58eabcd7d7da1a141202109288712b", "MyOwnBucket123", "testfolder/myfile.txt") then
   Dialog.Message("Alert", "The file could not be found (or the region does not match the bucket).", MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end

S3.DownloadFile(string AccessKey, string SecretKey, string BucketName, string FilePath, string LocalPath, string Region = "us-east-1")

Description:

Downloads a file from the Amazon S3 service.

AccessKey:

(string) The access key for the S3 account.

SecretKey:

(string) The secret (password) for the S3 access key.

BucketName:

(string) The name the bucket.

FilePath

(string) The path (folder name and filename) of the file to be downloaded.

LocalPath

(string) The local path (folder name and filename) where the file should be saved locally.

Region:

(string) The region where the object will be searched. You may suppress the parameter if the bucket was created in the default region (us-east-1), if not, provide one of the valid regions, such as "us-east-2", "us-west-1", "us-west-2", "af-south-1", "ap-east-1", "ap-south-1", "ap-northeast-1", "ap-northeast-2", "ap-northeast-3", "ca-central-1", "cn-north-1", "cn-northwest-1", "eu-central-1", "eu-west-1", "eu-west-2", "eu-west-3", "eu-south-1", "eu-north-1", "sa-east-1" or "me-south-1".

Returns:

(boolean) True if download was successful, false if not. You can use Application.GetLastError() to determine whether this action failed, and why.

Example:

-- checks if the file "myfile.txt" exists in a folder named "testfolder" in bucket "MyOwnBucket123"
if S3.DoesObjectExist("XB62MKR20PLAQN8XXZNI", "a45cb919efb11bfa040345aad71101234f58eabcd7d7da1a141202109288712b", "MyOwnBucket123",
   "testfolder/myfile.txt") then
   bRes = S3.DownloadFile("XB62MKR20PLAQN8XXZNI", "a45cb919efb11bfa040345aad71101234f58eabcd7d7da1a141202109288712b", "MyOwnBucket123",
      "testfolder/myfile.txt", _TempFolder .. "\\".. "aws-s3-file.bin", sRegion);
   error = Application.GetLastError();
   if (error ~= 0) then
      Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
   else
      if bRes then
         Dialog.Message("Info", "Download finished successfully.");
      else
         Dialog.Message("Info", "Download failed.");
      end
   end
else
   -- cannot download, if file does not exist
   Dialog.Message("Alert", "The file could not be found (or the region does not match the bucket).", MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end

S3.GetBucketRegion(string AccessKey, string SecretKey, string BucketName, string Region = "us-east-1")

Description:

Determines the region of an existing bucket on Amazon S3.

AccessKey:

(string) The access key for the S3 account.

SecretKey:

(string) The secret (password) for the S3 access key.

BucketName:

(string) The name the bucket to be deleted.

Returns:

(string) The string of the region where the bucket is hosted, or nil if the action failed. If the string is empty (""), this means that the bucket is hosted in the default region ("us-east-1"). You can use Application.GetLastError() to determine whether this action failed, and why.

Example:

-- retrieve the region of a bucket
local sRegion = S3.GetBucketRegion("XB62MKR20PLAQN8XXZNI", "a45cb919efb11bfa040345aad71101234f58eabcd7d7da1a141202109288712b", "MyUnkownBucket-001");
error = Application.GetLastError();
if (error ~= 0) then
   Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
else
   if (#sRegion > 0) then
      -- returned string is not 0 in length
      Dialog.Message("Info", "Bucket is hosted at site " .. sRegion, MB_OK, MB_ICONINFORMATION);
   else
      -- empty string means default
      Dialog.Message("Info", "Bucket is hosted at site us-east-1", MB_OK, MB_ICONINFORMATION);
   end
end

S3.ListBuckets(string AccessKey, string SecretKey)

Description:

Retrieves the listing of the buckets for an Amazon S3 account.

AccessKey:

(string) The access key for the S3 account.

SecretKey:

(string) The secret (password) for the S3 access key.

Returns:

(table) A list with the names of the buckets found for the provided account, or nil if there are no buckets, or in case of an error. You can use Application.GetLastError() to determine whether this action failed, and why.

Example:

-- retrieve the list of buckets
local tList = S3.ListBuckets("XB62MKR20PLAQN8XXZNI", "a45cb919efb11bfa040345aad71101234f58eabcd7d7da1a141202109288712b");
error = Application.GetLastError();
if (error ~= 0) then
   Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
else
   if (tList ~= nil) then
      ListBox.DeleteItem("lbxBuckets", -1);
      for i = 1, #tList do
         ListBox.AddItem("lbxBuckets", tList[i], tList[i]);
      end
   end
end

S3.UploadFile(string AccessKey, string SecretKey, string BucketName, string SourceFile, string TargetFolder, string TargetName, string Region = "us-east-1")

Description:

Uploads a file to the Amazon S3 service.

AccessKey:

(string) The access key for the S3 account.

SecretKey:

(string) The secret (password) for the S3 access key.

BucketName:

(string) The name the bucket.

SourceFile

(string) The full path of the local file to be transferred to the cloud.

TargetFolder

(string) The name of the sub folder in the bucket, or an empty string "" if not needed.

TargetName

(string) The name of the file once uploaded.

Region:

(string) The region where the bucket resides. You may suppress the parameter if the bucket was created in the default region (us-east-1), if not, provide one of the valid regions, such as "us-east-2", "us-west-1", "us-west-2", "af-south-1", "ap-east-1", "ap-south-1", "ap-northeast-1", "ap-northeast-2", "ap-northeast-3", "ca-central-1", "cn-north-1", "cn-northwest-1", "eu-central-1", "eu-west-1", "eu-west-2", "eu-west-3", "eu-south-1", "eu-north-1", "sa-east-1" or "me-south-1".

Returns:

(nothing) You can use Application.GetLastError() to determine whether this action failed, and why.

Example:

-- uploads a local file to a folder in a bucket
S3.UploadFile("XB62MKR20PLAQN8XXZNI", "a45cb919efb11bfa040345aad71101234f58eabcd7d7da1a141202109288712b",
    "MyOwnBucket123", "C:\\User\\JohnDoe\\Desktop\\Document.txt", "testfolder", "publicfile.txt");
error = Application.GetLastError();
if (error ~= 0) then
   Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
else
   Dialog.Message("Success", "The file was uploaded.", MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end