Skip to main content

クラウド・ストレージ API

ObjectScript コードは、一連の低レベル APIを呼び出すことで、クラウド・ストレージ・プロバイダにデータをアップロードしたり、ここからデータをダウンロード、あるいは削除することができ、ユーザは相互運用プロダクションを使用することなく、クラウド・ストレージにアクセスできます。コードは、クライアントを作成し、クライアントのメソッドを呼び出して、BLOB のアップロードや削除などのアクションを実行することで、クラウド・ストレージ・プロバイダとやり取りします。このクラウド・ストレージ・クライアントのクラスは、%Net.Cloud.Storage.ClientOpens in a new tab です。これは、各クラウド・ストレージ・プロバイダで同じクラスです。

クラウド・ストレージ API は簡単に使用できます。例えば、Amazon Web Services 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()

クライアントの作成

クラウド・ストレージ・プロバイダのバケットと BLOB を処理する前に、コードで次の構文を使用してクラウド・ストレージ・クライアントを作成する必要があります。

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

説明 ：

  • javaServer は、インターシステムズの Java 用外部サーバ (Java ゲートウェイとも呼ばれます) の名前です。カスタムのサーバを作成するのではなく、既定の Java 外部サーバを使用するには、この引数を空のままにします。

  • provider は、このクライアントでアクセスするクラウド・ストレージ・プロバイダを示す整数です。S3 バケットの場合、0 を使用します。

  • credentialsFile は、クラウド・ストレージ・プロバイダにアクセスするために使用される認証情報を含むファイルです。このファイルは、プロバイダの仕様に従った形式にする必要があります。S3 バケットにアクセスする場合は、この引数を空のままにして、既定の認証情報プロバイダ・チェーンOpens in a new tabを使用できます。

  • region は、連携させるバケットを含むリージョンです。AWS リージョンのリストは、"リージョン、アベイラビリティーゾーン、および Local ZonesOpens in a new tab" を参照してください。

  • 参照によって返される tSC は、このメソッド呼び出しで返されるステータス・コードです。

  • endPoint は、AWS PrivateLinkOpens in a new tab のオプションのエンドポイントです。

クライアントの終了

プロバイダのバケットと BLOB の処理が終了したら、必ず Close() メソッドを使用して作成したクライアントを閉じます。次に、例を示します。

 Do myClient.Close()

バケットとの連携

クラウド・ストレージ・クライアントには、プロバイダのバケット (BLOB 用のストレージ・コンテナ) と連携するように設計されている一連のメソッドが含まれています。これらのメソッドのシグニチャは以下のとおりです。

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)

例えば、バケットに関する詳細を取得するため、ストレージ・クライアントを作成するには、以下を入力します。

 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()

バケットの詳細

クラウド・ストレージ・クライアントは、%Net.Cloud.Storage.BucketInfoOpens in a new tab オブジェクトを使用して、バケットに関する詳細を表します。GetBucketInfo() を呼び出すと、指定したバケットの詳細が、%Net.Cloud.Storage.BucketInfoOpens in a new tab オブジェクトのインスタンスに返されます。同様に、ListBuckets() を呼び出すと、これらのオブジェクトのコレクション内の使用可能なすべてのバケットが返され、ユーザは各バケットの詳細にアクセスできます。使用可能なバケットの詳細については、%Net.Cloud.Storage.BucketInfoOpens in a new tab のプロパティを参照してください。

便宜上、%Net.Cloud.Storage.BucketInfoOpens in a new tab クラスには、バケット詳細を JSON 形式にできるメソッド toJSON() が含まれています。

BLOB 情報の取得

クラウド・ストレージ・クライアントは、次のメソッドを使用して、特定のバケット内の BLOB に関する情報を取得します。

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

クライアントは、BLOB のコンテンツをダウンロードするには、別のメソッドを指定します。

例えば、サイズなどの特定の BLOB に関する詳細を取得する場合、以下を入力します。

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 の詳細

クラウド・ストレージ・クライアントは、%Net.Cloud.Storage.BlobInfoOpens in a new tab オブジェクトを使用して、BLOB に関する詳細を表します。GetBlobInfo() を呼び出すと、指定した BLOB の詳細が、%Net.Cloud.Storage.BlobInfoOpens in a new tab オブジェクトのインスタンスに返されます。同様に、ListBlobs() を呼び出すと、これらのオブジェクトのコレクション内の使用可能なすべての BLOB が返され、ユーザは各 BLOB の詳細にアクセスできます。使用可能な BLOB の詳細については、%Net.Cloud.Storage.BlobInfoOpens in a new tab のプロパティを参照してください。

便宜上、%Net.Cloud.Storage.BlobInfoOpens in a new tab クラスには、BLOB の詳細を JSON 形式にできるメソッド toJSON() が含まれています。

BLOB のアップロード

クラウド・ストレージ API により、InterSystems IRIS® からクラウド・ストレージにデータやファイルをアップロードできます。BLOB データのソースに応じて、以下の任意のメソッドを使用し、BLOB をクラウド・ストレージ・プロバイダにアップロードできます。

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)

例えば、ファイルを S3 バケットにアップロードするには、以下を含めます。

 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()

BLOB のダウンロード

InterSystems IRIS で使用するため、クラウド・ストレージ API を使用して、クラウド・ストレージ・プロバイダからデータをダウンロードできます。さまざまなメソッドが利用可能で、データのターゲット・フォーマットを選択できます。

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

例えば、S3 バケットから BLOB をダウンロードし、ストリームに格納するには、以下を入力します。

 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()

BLOB をアップロードするための単一のメソッド

クラウド・ストレージ API により、相互運用プロダクションを使用せずに、クラウド・ストレージにデータやファイルをアップロードできます。これらのクラス・メソッドにより、クライアントを作成し、BLOB をアップロードして、クライアントを閉じる単一の呼び出しを行うことができます。

例えば、ファイルを Amazon S3 にアップロードするには、以下を含めます。

 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)

BLOB をダウンロードするための単一のメソッド

InterSystems IRIS で使用するため、クラウド・ストレージ API を使用して、クラウド・ストレージ・プロバイダからデータをダウンロードできます。これらのクラス・メソッドにより、クライアントを作成し、BLOB をダウンロードして、クライアントを閉じる単一の呼び出しを行うことができます。

 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)

BLOB の削除

他のクラウド・ストレージ API と同様、クラウド・ストレージから BLOB を削除する方法は単純です。必要なのは、削除する BLOB の名前のみ (格納されているバケットを含む) です。 

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

例えば、S3 バケットから BLOB を削除するには、以下を入力します。

 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()

署名付き BLOB の操作

%Net.Cloud.Storage.ClientOpens in a new tab には、署名付き BLOB の生成と操作で使用するメソッドが用意されています。そのメソッドは以下のとおりです。

GeneratePresignedURL()
Method GeneratePresignedUrl(bucketName As %String, 
                            blobName As %String, 
                            duration As %BigInt, 
                            method As %String, 
                            metadata As %String = "") As %String

署名付き URL を生成します。引数は以下のとおりです。

  • bucketName ： バケットを指定します。

  • blobName ： BLOB を指定します。

  • duration ： URL の有効時間をミリ秒で指定します。

  • method ：使用する URL メソッドを指定します。指定できるメソッドは、クラウド・ストレージ・プロバイダによって異なります。

    • Amazon S3 では、DELETE、GET、HEAD、PATCH、POST、PUT を指定できます。

    • Azure では、"acdrw" (ADD、CREATE、DELETE、READ、WRITE) の一部を指定できます。

    • GCS では、DELETE、GET、HEAD、OPTIONS、POST、PUT を指定できます。

  • metadata ： ユーザ・メタデータを JSON 文字列で指定します。以下の点に注意してください。

    • Amazon S3 では、URL を生成するときにユーザ・メタデータを指定する必要があり、その後で変更はできません。プロパティ名には接頭語 x-amx-meta- が付加されます

    • Azure では、署名付き URL を生成するときにユーザ・メタデータを指定しても無視されます。

    • GCS では、URL を生成するときにユーザ・メタデータを指定する必要があり、その後で変更はできません。プロパティ名には接頭語 x-goog-meta- が付加されます。この場合、生成される署名にはユーザ・メタデータ情報が含まれます。

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

指定された BLOB のユーザ・メタデータを JSON 文字列で返します。引数は以下のとおりです。

  • bucketName ： バケットを指定します。

  • blobName ： BLOB を指定します。

このメタデータでは、プロパティ名に接頭語が付加されません。

GetBlobMetadataWithPresignedUrl()
ClassMethod GetBlobMetadataWithPresignedUrl(presignedUrl As %String, 
                                            Output metadata As %String,
                                            javaServer As %RawString = "") As %Status

署名付き URL でアクセスできる BLOB から、メタデータを JSON 文字列で取得します。引数は以下のとおりです。

  • presignedUrl ： 署名付き URL です。

  • metadata ： 出力に JSON 文字列で返されるメタデータです。

  • javaServer ： 使用する Java 外部言語サーバの名前です。

このメソッドの実行を続行する前に、そこから返されるステータス値を確認する必要があります。

UploadBlobWithPresignedUrl()
ClassMethod UploadBlobWithPresignedUrl(presignedUrl As %String, 
                                       input As %Stream.Object, 
                                       metadataJson As %String = ""
                                       javaServer As %RawString = "") As %Status

署名付き URL でアクセスできる指定の BLOB にデータをアップロードします。引数は以下のとおりです。

  • presignedUrl ： 署名付き URL です。

  • input ： アップロードするデータを保持している、%Stream.ObjectOpens in a new tab のインスタンスです。

  • metadataJson ： 必要に応じて指定する、JSON 文字列によるメタデータです。以下の点に注意してください。

    • Amazon S3 では、ここでユーザ・メタデータを指定することはできません。ユーザ・メタデータは、URL を生成するときにのみ指定できます。

    • Azure では、プロパティ名に接頭語 x-ms-meta- が付加されます。また、値を BlockBlob としたプロパティ x-ms-blob-type を追加する必要があります。

    • GCS では、ユーザ・メタデータは、署名付き URL を生成するときに指定したメタデータと全面的に同じであることが必要です。

  • javaServer ： 使用する Java 外部言語サーバの名前です。

このメソッドの実行を続行する前に、そこから返されるステータス値を確認する必要があります。

DownloadBlobWithPresignedUrl()
ClassMethod DownloadBlobWithPresignedUrl(presignedUrl As %String, 
                                         start As %BigInt = "", 
                                         end As %BigInt = "", 
                                         Output outStream As %Stream.GlobalBinary,
															 javaServer As %RawString = "") As %Status

署名付き URL でアクセスできる指定の BLOB からデータをダウンロードします。引数は以下のとおりです。

  • presignedUrl ： 署名付き URL です。

  • start ： BLOB の中でダウンロードする領域の先頭が占める位置です。BLOB の先頭の位置は 0 です。この引数が負の値であると、0 として扱われます。この引数が空の文字列であると、BLOB 全体がダウンロードされます。

  • end ： BLOB の中でダウンロードする領域の末尾が占める位置です。この引数が負の値であると、ダウンロードする領域の末尾は BLOB の末尾です。この引数が空の文字列であると、BLOB 全体がダウンロードされます。

  • output ： 出力としてダウンロードされて返されたデータを保持している %Stream.ObjectOpens in a new tab のインスタンスです。

  • javaServer ： 使用する Java 外部言語サーバの名前です。

このメソッドの実行を続行する前に、そこから返されるステータス値を確認する必要があります。


Previous sectionクラウド・アダプタの設定
FeedbackOpens in a new tab