概念

同期コールを行うには、同期クライアントのインスタンスを作成します。同期クライアントの一般的なパターンでは、Exampleという名前のサービスに対して、ExampleServiceという名前のインタフェースが存在し、同期クライアント実装はExampleServiceClientと呼ばれます。次に、オブジェクト・ストレージ・クライアントを作成する例を示します:

AuthenticationDetailsProvider provider = ...;
ObjectStorage clientWithDefaultClientConfig = new ObjectStorageClient(provider);
clientWithDefaultClientConfig.setRegion(Region.US_ASHBURN_1);

ClientConfiguration clientConfig = ...;
ObjectStorage clientWithExplicitClientConfig = new ObjectStorageClient(provider, clientConfig);
clientWithExplicitClientConfig.setRegion(Region.US_ASHBURN_1);

同期コールは、レスポンスが可能になるまでブロックされます。すべてのSDK APIでは、そのAPIからコンテンツが返されるかかどうかには関係なく、レスポンス・オブジェクトが返されます。通常、レスポンス・オブジェクトには少なくともリクエストIDが含まれます。これは、特定のリクエストについてOracleサポートに連絡する際に使用できます。

ObjectStorage client = ...;
GetBucketResponse response = client.getBucket(
    GetBucketRequest.builder().namespaceName("myNamespace").bucketName("myBucket").build());
String requestId = response.getOpcRequestId();
Bucket bucket = response.getBucket();
System.out.println(requestId);
System.out.println(bucket.getName());

非同期コールを行うには、非同期クライアントのインスタンスを作成します。非同期クライアントの一般的なパターンでは、Exampleという名前のサービスに対して、ExampleServiceAsyncという名前のインタフェースが存在し、非同期クライアント実装はExampleServiceAsyncClientと呼ばれます。次に、オブジェクト・ストレージ・クライアントを作成する例を示します:

AuthenticationDetailsProvider provider = ...;
ObjectStorageAsync clientWithDefaultClientConfig = new ObjectStorageAsyncClient(provider);
clientWithDefaultClientConfig.setRegion(Region.US_ASHBURN_1);
 
ClientConfiguration clientConfig = ...;
ObjectStorageAsync clientWithExplicitClientConfig = new ObjectStorageAsyncClient(provider, clientConfig);
clientWithExplicitClientConfig.setRegion(Region.US_ASHBURN_1);

非同期コールはすぐに返されます。成功か失敗にかかわらずコールが完了したときに起動するAsyncHandlerを指定する必要があります。

ObjectStorageAsync client = ...;
 
AsyncHandler<GetBucketRequest, GetBucketResponse> handler = new AsyncHandler<GetBucketRequest, GetBucketResponse>() {
        @Override
        public void onSuccess(GetBucketRequest request, GetBucketResponse response) {
            String requestId = response.getOpcRequestId();
            Bucket bucket = response.getBucket();
            System.out.println(requestId);
            System.out.println(bucket.getName());
        }

        @Override
        public void onError(GetBucketRequest request, Throwable error) {
            error.printStackTrace();
        }
};
 
Future<GetBucketResponse> future = client.getBucket(
        GetBucketRequest.builder().namespaceName("myNamespace").bucketName("myBucket").build(),
        handler);

SDKで提供されるウェイタを使用すると、特定のリソースが目的の状態に到達するまでコードが待機するようにできます。ウェイタは、ブロッキング方式または非ブロッキング方式(非同期コールバックを使用)で呼び出すことができ、目的の状態に到達するかタイムアウトが超過するまで待機します。ウェイタによってポーリング・ロジックが抽象化されます。これがなければ、ユーザーが、使いやすい1つのメソッド・コールとしてロジックを記述する必要があります。

ウェイタはサービス・クライアント(client.getWaiters())を介して取得されます。Get<Resource>Requestと目的のライフサイクル状態の両方がwaiters.for<Resource>メソッドに渡されます。例:

public static Instance waitForInstanceProvisioningToComplete(  ComputeClient computeClient, String instanceId) throws Exception {
        
    ComputeWaiters waiters = computeClient.getWaiters();
    GetInstanceResponse response = waiters.forInstance(
        GetInstanceRequest.builder().instanceId(instanceId).build(),
        Instance.LifecycleState.Running)
    .execute();
        
    return response.getInstance();
}

各waiters.for<Resource>メソッドには2つのバージョンがあります:

• 1つのバージョンではデフォルトのポーリング値が使用されます。例:

  waiters.forInstance(GetInstanceRequest, LifecycleState)

• もう一方のバージョンでは、待機時間およびポーリング試行間隔をユーザーが完全に制御できます。例:

  waiters.forInstance(GetInstanceRequest, LifecycleState, TerminationStrategy, DelayStrategy)

クライアントは、初期化されるときにスレッドセーフになります。エンドポイントを設定したら、複数のスレッドでクライアントを安全に使用し、そこでメソッドを同時にコールできます。

クライアントは、同時スレッド全体でも単一のスレッド内でも、複数のリクエストに対して再利用できます。環境のリソースが制約されないかぎり、クライアントをすぐにクローズする必要があるのは、スコープ外になる場合のみです。

オブジェクト・ストレージ・サービスではマルチパート・アップロードがサポートされています。ラージ・オブジェクトをパートに分割することでラージ・オブジェクトのアップロードが容易になります。SDK for Javaでは、高度なユースケース向けのRawマルチパート・アップロード操作と、マルチパート・アップロードAPIを使用する高レベル・アップロード・クラスがサポートされています。マルチパート・アップロードの使用では、マルチパート・アップロード操作で使用されるAPIへのリンクが示されています。高レベルのマルチパート・アップロードは、UploadManagerを使用して実装されます。これは、ラージ・オブジェクトをパートに分割し、パートを並列でアップロードした後で、パートを再結合してストレージでコミットします。

UploadObjectの例では、オブジェクト・ストレージ・サービスとの相互作用を簡略化するため、UploadManagerを使用して、アップロード用にオブジェクトを自動的にパート分割する方法を示します。

バージョン2.10.0以降、SDK for Javaはデフォルトで、失敗した特定のSDK操作を再試行するよう構成されています。SDKによって、再試行の回数、SDKが操作を再試行する条件、操作の再試行を停止するタイミングなど、再試行の処理方法に使用する戦略を指定できます。これらのパラメータは、クライアント・レベルおよび個々のリクエスト・レベルで設定できます。

デフォルトで再試行が有効になっているサービス操作を確認するには、SDKのサービス操作の説明を参照してください。

SDKでデフォルトで再試行されるのは、HTTPレスポンス・ステータス・コードが409 (IncorrectStateエラー・コードあり)、429、500、502、503、504の操作、タイムアウト・エラー(HTTP接続および読取りタイムアウトなど)、リクエスト接続エラー、リクエスト例外およびサーキット・ブレーカ例外です。

最新のデフォルトの再試行構成と再試行可能なエラーのリストは、Githubで参照できます。

デフォルトの再試行の無効化

デフォルトの再試行機能をオプトアウトするには、次を実行します:

1. 環境変数OCI_SDK_DEFAULT_RETRY_ENABLEDをfalseに設定して、デフォルトの再試行をグローバルに無効化します

2. 特定のクライアント・インスタンスのデフォルトの再試行をオーバーライドします。この例では、objectStorageClientのデフォルトの再試行をオーバーライドしています。

   ClientConfiguration clientConfiguration =
           ClientConfiguration.builder()
                   .retryConfiguration(RetryConfiguration.builder().terminationStrategy(new MaxAttemptsTerminationStrategy(1))
                           .build())
                   .build();

   ObjectStorage objectStorageClient = ObjectStorageClient.builder().configuration(clientConfiguration).build(provider);
   

3. 特定のリクエスト・インスタンスのデフォルトの再試行をオーバーライドします。この例では、putObjectRequestの再試行をオーバーライドしています:

   PutObjectRequest putObjectRequest =
           PutObjectRequest.builder()
                   .putObjectBody(stream)
                   .bucketName(bucketName)
                   .objectName(objectName)
                   .namespaceName(namespace)
                   .retryConfiguration(RetryConfiguration.builder().terminationStrategy(new MaxAttemptsTerminationStrategy(1)).build())
                   .build();

再試行動作の優先順位

バージョン2.10.0以降、SDK for Javaでは、デフォルトのSDKサーキット・ブレーカが有効になっているサービス・クライアント向けに、サーキット・ブレーカがデフォルトでサポートされています。サーキット・ブレーカを使用すると、特定の失敗のしきい値に達した後、サービスにリクエストが送信されないようにすることで、クライアントがサービスに負荷をかけるのを防ぐことができます。

デフォルトのサーキット・ブレーカでは、再試行可能なすべてのエラーは、そのサーキット・ブレーカの失敗として処理されます。どのサービス・クライアントでサーキット・ブレーカが有効になっているかを確認するには、SDKでサービス・クライアントの説明を参照してください。

サーキット・ブレーカの構成

次のパラメータで、サーキット・ブレーカを定義します:

デフォルトのサーキット・ブレーカ構成

デフォルトのサーキット・ブレーカ構成は次のとおりです:

デフォルトのサーキット・ブレーカの無効化

デフォルトのサーキット・ブレーカ機能をオプトアウトするには、次のいずれかを実行します:

サーキット・ブレーカの動作の優先順位

クライアント・レベルで明示的に定義したサーキット・ブレーカ構成は、グローバルのデフォルトのサーキット・ブレーカ構成、およびそのクライアントの環境レベルのオーバーライドをオーバーライドします。

サーキット・ブレーカおよびデフォルトのサーキット・ブレーカ構成の詳細は、Githubのこの例を参照してください。

Rawリクエストは役に立ちます。場合によっては必要です。一般的なユースケースは、独自のHTTPクライアントを使用して、代替エンドポイントへのOCI認証リクエストを作成する場合、およびSDKで現在サポートされていないOCI APIに対してリクエストを作成する場合です。SDK for Javaで公開されるDefaultRequestSignerクラスを使用して、標準以外のリクエストのRequestSignerインスタンスを作成できます。

GitHubのRawリクエストの例では、次の方法が示されています:

• 認証プロバイダとリクエスト署名者を作成します
• HTTPクライアント(この例ではJersey)と統合してリクエストを認証します

サービス・エンドポイントは3つの方法で設定できます。

• サービス・インスタンスに対してsetEndpoint()をコールします。こうすると、完全なホスト名(たとえばhttps://www.example.com)を指定できます。
• サービス・インスタンスに対してsetRegion()をコールします。こうすると、指定したリージョンのサービスに適切なホスト名が選択されます。ただし、設定したリージョンでサービスがサポートされていない場合は、SDK for Javaからエラーが返されます。
• 構成ファイルでリージョンを渡します。詳細は、SDKおよびCLIの構成ファイルを参照してください。

サービス・インスタンスは、様々なリージョンとの通信には使用できないことに注意してください。様々なリージョンへのリクエストを行う必要がある場合は、複数のサービス・インスタンスを作成します。

列挙型に基づいた条件ロジックがある場合は、上位互換性を確保するためにコードでUnknownEnumValueケースを処理してください。一部のレスポンス・フィールドは列挙型ですが、将来的には、個々のサービスで返される値が、そのフィールドの既存の列挙型で対応されなくなる可能性があります。この可能性に対処するため、列挙型のすべてのレスポンス・フィールドには、UnknownEnumValueという名前の追加の値があります。サービスから返された値が、使用しているバージョンのSDKで認識されない場合、レスポンス・フィールドにこの値が設定されます。

新リージョン発表の前にリリースされたSDKのバージョンを使用している場合は、そのリージョンにアクセスするための対処方法を使用できます。

リージョンとは、限定された地理的領域のことです。リージョンの詳細と指定方法は、リージョンおよび可用性ドメインを参照してください。

レルムは、エンティティを共有する一連のリージョンです。ネットワーク・アドレスの最後にあるドメイン名を見ると、レルムがわかります。たとえば、xyz.abc.123.oraclecloud.comのレルムは、oraclecloud.comです。

最初にRegion.registerをコールして新しいリージョンを登録する必要があります。その後、構成ファイルを使用するか、setRegionメソッドをコールして、リージョンを設定できます。

AuthenticationDetailsProvider provider =
        new ConfigFileAuthenticationDetailsProvider(configurationFilePath, profile);

IdentityClient client = IdentityClient.builder()
        .endpoint("https://identity.ca-toronto-1.oraclecloud.com")
        .build(provider);

InstancePrincipalsAuthenticationDetailsProvider provider = InstancePrincipalsAuthenticationDetailsProvider.builder()
        .federationEndpoint("https://auth.ca-toronto-1.oraclecloud.com/v1/x509")
        .build();

IdentityClient identityClient = IdentityClient.builder()
        .endpoint("https://identity.ca-toronto-1.oraclecloud.com")
        .build(provider);

一部のAPIではページ区切りされた結果セットが返されるため、さらにアイテムがないか確認して、必要であれば次のページをフェッチする必要があります。これは、手動で行うことも、イテレータを使用して行うこともできます。

ObjectStorage client = ...;
 
ListBucketsRequest.Builder builder =
    ListBucketsRequest.builder().namespaceName(namespace);
String nextPageToken = null;
do {
    builder.page(nextPageToken);
    ListBucketsResponse listResponse = client.listBuckets(builder.build());
    List<Bucket> buckets = listResponse.getItems();
    // handle buckets
    nextPageToken = listResponse.getOpcNextPage();
} while (nextPageToken != null);

クライアント側の暗号化では、クライアント側のデータを、ローカルに格納する前、または他のOracle Cloud Infrastructureサービスでデータを使用する前に暗号化できます。

クライアント側の暗号化を使用するには、キー管理サービスを使用してマスター暗号化キー(MEK)を作成する必要があります。これは、CreateKeyまたはImportKey操作を使用して行います。

MEKは、各ペイロードを暗号化するデータ暗号化キー(DEK)の生成に使用されます。このDEKの暗号化されたコピー(MEKで暗号化済)およびその他のメタデータの断片は、復号化に使用できるように、SDKによって返される暗号化されたペイロードに含まれます。

// String encryption example
			
final byte[] plainText = "Hello World".getBytes();
String masterKeyId = "OCID....";
Map<String, String> context = Collections.singletonMap("Example", "value");
 
OciCrypto ociCrypto = new OciCrypto();
KmsMasterKey kmsMasterKey = new KmsMasterKey(authenticationProvider, Region.US_ASHBURN_1.getRegionId(), vaultId, masterKeyId);
KmsMasterKeyProvider kmsMasterKeyProvider = new KmsMasterKeyProvider(kmsMasterKey);
 
//  Encrypt the data and embed the master key ID in the header
final OciCryptoResult encryptResult = ociCrypto.encryptData(kmsMasterKeyProvider, plainText, context);
final byte[] cipherText = encryptResult.getResult();
 
//  Decrypt the data
final OciCryptoResult decryptResult = ociCrypto.decryptData(kmsMasterKeyProvider, cipherText);

// Create Encryption file stream
FileInputStream in = new FileInputStream(srcFile);
OciCrypto ociCrypto = new OciCrypto();
KmsMasterKey kmsMasterKey = new KmsMasterKey(authenticationProvider, Region.US_ASHBURN_1.getRegionId(), vaultId, masterKeyId);
KmsMasterKeyProvider kmsMasterKeyProvider = new KmsMasterKeyProvider(kmsMasterKey);
OciCryptoInputStream encryptingStream = ociCrypto.createEncryptingStream(kmsMasterKeyProvider, in);
 
// Write the encrypted data to file
FileOutputStream out = new FileOutputStream(srcFile + ".encrypted");
IOUtils.copy(encryptingStream, out);
encryptingStream.close();
out.close();
 
// For decryption, no need to pass key info
KmsMasterKeyProvider kmsMasterKeyProvider = new KmsMasterKeyProvider(authenticationProvider);
// Create the Decryption file stream.
in = new FileInputStream(srcFile + ".encrypted");
OciCryptoInputStream decryptingStream = ociCrypto.createDecryptingStream(kmsMasterKeyProvider, in);
 
 
// Return the plaintext data
out = new FileOutputStream(srcFile + ".decrypted");
IOUtils.copy(decryptingStream, out);
decryptingStream.close();
out.close();

例外を処理するとき、原因となったHTTPリクエストに関する詳細(ステータス・コードやタイムアウトなど)を取得できます。getOpcRequestIdメソッドを使用して、BmcExceptionを処理する際にリクエストIDを取得することもできます。

この例では、BmcExceptionを処理してリクエストIDを出力するtry-catchブロックを示します。

ObjectStorage client = ...;
try {
    GetBucketResponse response = client.getBucket(
	        GetBucketRequest.builder().namespaceName("myNamespace").bucketName("myBucket").build());
    String requestId = response.getOpcRequestId();
    System.out.println(requestId);
} catch (BmcException e) {
    String requestId = e.getOpcRequestId();
    System.out.println(requestId);
    e.printStackTrace();
}

SDK for Javaの例外は実行時例外(未チェック)であるため、メソッド・シグネチャには示されません。すべてのAPIでBmcExceptionがスローされる可能性があります。