Skip to main content

Cloud Storage APIs

Your ObjectScript code can upload, download, and delete data from a cloud storage provider by calling a set of low-level APIs, allowing you to access cloud storage without using an interoperability production. Your code interacts with the cloud storage provider by creating a client, then calling the client’s methods to perform actions like uploading a blob or deleting a blob. The class for this cloud storage client is %Net.Cloud.Storage.Client. It is the same class for each cloud storage provider.

The cloud storage APIs are simple to use. For example, the following code is all you need to upload a file to Amazon S3:

Set bucketName = "s3-bucket"
Set blobName = "s3-object-blob"
// Create Cloud Storage Client for S3
Set myClient = ##class(%Net.Cloud.Storage.Client).CreateClient(,0,"/home/AWSCredentials", "us-east-1", .tSC)

// Upload file to S3	
If myClient.BucketExists(bucketName){
  Do myClient.UploadBlobFromFile(bucketName, blobName, "/usr/file.jpg")
}
// Close client
Do myClient.Close()

Creating a Client

Before working with a cloud storage provider’s buckets and blobs, your code must create a cloud storage client using the following syntax:

Set myClient = ##class(%Net.Cloud.Storage.Client).CreateClient(javaServer,
	provider,credentialsFile,region,.tSC)

Where:

  • javaServer is the name of an InterSystems external server for Java (also known as a Java gateway). To use the default Java external server rather than creating a custom one, simply leave this argument empty.

  • provider is an integer that indicates which cloud storage provider is being accessed with the client. For Amazon S3, use 0.

  • credentialsFile is a file that contains the credentials used to access the cloud storage provider. The file must be formatted according to the provider’s specifications. If you are accessing Amazon S3, you can leave this argument empty to use the default credential provider chain.

  • region is the region containing the buckets you want to work with. For a list of S3 regions, see Amazon Regions, Availability Zones, and Local Zones.

  • .tSC receives the status code returned by the method call.

Closing a Client

Once you are done working with a provider’s buckets and blobs, be sure to use the Close() method to close the client that you created. For example:

Do myClient.Close()

Working with Buckets

The cloud storage client includes a set of methods designed to work with a provider’s buckets, which are the storage containers for blobs. The signatures of these methods are:

Method BucketExists(bucketName As %String) As %Boolean
Method GetBucketInfo(bucketName As %String) As BucketInfo
Method ListBuckets() As %ListOfObjects
Method CreateBucket(bucketName As %String)
Method DeleteBucket(bucketName As %String)

For example, to create a cloud storage client in order to retrieve details about a bucket, enter:

Set bucketName = "s3-bucket"
Set myClient = ##class(%Net.Cloud.Storage.Client).CreateClient(,0,"/home/AWSCredentials", "us-east-1", .tSC)
Set bucketDetails = myClient.GetBucketInfo(bucketName)
Do myClient.Close()

Bucket Details

The cloud storage client uses a %Net.Cloud.Storage.BucketInfo object to represent the details about a bucket. When you call GetBucketInfo(), the details about the specified bucket are returned in a BucketInfo object. Likewise, a call to ListBuckets() returns all of the available buckets in a collection of BucketInfo objects, allowing you to access details about each bucket. To learn more about what bucket details are available, see the properties of %Net.Cloud.Storage.BucketInfo.

For convenience, the BucketInfo class includes a method that allows you to put the details of a bucket into JSON format. Once you have the BucketInfo object for a bucket, call its toJSON() method.

Retrieving Blob Information

The cloud storage client uses the following methods to retrieve information about blobs in a particular bucket:

Method BlobExists(bucketName As %String, blobName As %String) As %Boolean
Method GetBlobInfo(bucketName As %String, blobName As %String) As BlobInfo
Method ListBlobs(bucketName As %String) As %ListOfObjects

The client provides separate methods to download the content of a blob.

As an example, if you wanted to retrieve details about a particular blob, like its size, you could enter:

Set bucketName = "s3-bucket"
Set blobName = "s3-object-blob"
Set myClient = ##class(%Net.Cloud.Storage.Client).CreateClient(,0,"/home/AWSCredentials", "us-east-1", .tSC)
Set blobDetails = myClient.GetBlobInfo(bucketName, blobName)
Do myClient.Close()

Blob Details

The cloud storage client uses a %Net.Cloud.Storage.BlobInfo object to represent the details about a blob. When you call GetBlobInfo(), the details about the specified blob are returned in a BlobInfo object. Likewise, a call to ListBlobs() returns all of the available blobs in a collection of BlobInfo objects, allowing you to access details about each blob. To learn more about what blob details are available, see the properties of %Net.Cloud.Storage.BlobInfo.

For convenience, the BlobInfo class includes a method that allows you to put the details of a blob into JSON format. Once you have the BlobInfo object for a blob, call its toJSON() method.

Uploading Blobs

The cloud storage APIs allow you to upload data and files to cloud storage without using an interoperability production. You can use any of the following methods to upload blobs to a cloud storage provider, depending on the source of the blob’s data:

Method UploadBlobFromString(bucketName As %String, blobName As %String, content As %String)
Method UploadBlobFromFile(bucketName As %String, blobName As %String, filePath As %String)
Method UploadBlobFromStream(bucketName As %String, blobName As %String, stream As %GlobalBinaryStream)

For example, to upload a file to Amazon S3, you could include:

Set bucketName = "s3-bucket"
Set blobName = "s3-object-blob"
Set myClient = ##class(%Net.Cloud.Storage.Client).CreateClient(,0,"/home/AWSCredentials", "us-east-1", .tSC)
Do myClient.UploadBlobFromFile(bucketName, blobName, "/usr/file.jpg")
Do myClient.Close()

Downloading Blobs

You can use the cloud storage APIs to download data from a cloud storage provider in order to work with it in InterSystems IRIS. Various methods are available, allowing you to choose the target format of the data:

Method DownloadBlobToString(bucketName As %String, blobName As %String) As %String
Method DownloadBlobToFile(bucketName As %String, blobName As %String, filePath As %String)
Method DownloadBlobToStream(bucketName As %String, blobName As %String) As %GlobalBinaryStream

For example, to download a blob from Amazon S3 and store it in a Stream, enter:

Set bucketName = "s3-bucket"
Set blobName = "s3-object-blob"
Set myClient = ##class(%Net.Cloud.Storage.Client).CreateClient(,0,"/home/AWSCredentials", "us-east-1", .tSC)
Set IRISStream = myClient.DownloadBlobToStream(bucketName, blobName)
Do myClient.Close()

Deleting Blobs

Like the other cloud storage APIs, the method to delete a blob from cloud storage is straightforward. All it requires is the name of the blob you want to delete, including the bucket where it is stored.

Method DeleteBlob(bucketName As %String, blobName As %String)

For example, to delete a blob from Amazon S3, enter:

Set bucketName = "s3-bucket"
Set blobName = "s3-object-blob"
Set myClient = ##class(%Net.Cloud.Storage.Client).CreateClient(,0,"/home/AWSCredentials", "us-east-1", .tSC)
Do myClient.DeleteBlob(bucketName, blobName)
Do myClient.Close()
Feedback