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.ClientOpens in a new tab. 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 an Amazon Web Services S3 bucket:
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,endPoint)
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 S3 buckets, 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 an S3 bucket, you can leave this argument empty to use the default credential provider chainOpens in a new tab.
-
region is the region containing the buckets you want to work with. For a list of AWS regions, see Amazon Regions, Availability Zones, and Local ZonesOpens in a new tab.
-
tSC, which is returned by reference, is the status code returned by the method call.
-
endPoint is an optional endpoint for AWS PrivateLinkOpens in a new tab.
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.BucketInfoOpens in a new tab object to represent the details about a bucket. When you call GetBucketInfo(), the details about the specified bucket are returned in an instance of %Net.Cloud.Storage.BucketInfoOpens in a new tab object. Likewise, a call to ListBuckets() returns all of the available buckets in a collection of these 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.BucketInfoOpens in a new tab.
For convenience, the %Net.Cloud.Storage.BucketInfoOpens in a new tab class includes a method that allows you to put the details of a bucket into JSON format; the method is toJSON().
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.BlobInfoOpens in a new tab object to represent the details about a blob. When you call GetBlobInfo(), the details about the specified blob are returned in an instance of %Net.Cloud.Storage.BlobInfoOpens in a new tab object. Likewise, a call to ListBlobs() returns all of the available blobs in a collection of these 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.BlobInfoOpens in a new tab.
For convenience, the %Net.Cloud.Storage.BlobInfoOpens in a new tab class includes a method that allows you to put the details of a blob into JSON format: toJSON().
Uploading Blobs
The cloud storage APIs allow you to upload data and files to cloud storage from InterSystems IRIS®. 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 an S3 bucket, 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 an S3 bucket 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()
Single Method for Uploading Blobs
The cloud storage APIs allow you to upload data and files to cloud storage without using an interoperability production. These class methods allow you to make a single call which will create a client, upload the blob, then close the client:
For example, to upload a file to Amazon S3, you could include:
Set bucketName = "s3-bucket"
Set blobName = "s3-object-blob"
Set credentials = "/home/AWSCredentials"
Set region = "us-east-1"
Set filePath = "/usr/file.jpg"
Set status = ##class(%Net.Cloud.Storage.Client).SingleUploadBlobFromFile(, 0,
credentials, region, bucketName, blobName, filePath)
Single Method for 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. These class methods allow you to make a single call which will create a client, download the blob, then close the client:
Set bucketName = "s3-bucket"
Set blobName = "s3-object-blob"
Set credentials = "/home/AWSCredentials"
Set region = "us-east-1"
Set status = ##class(%Net.Cloud.Storage.Client).SingleDownloadBlobToStream(, 0,
credentials, region, bucketName, blobName)
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 an S3 bucket, 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()