Object Storage Service:OSS SDK for Java 2.0 (プレビュー)

前提条件

Java 8 以降。

java -version コマンドを実行して、Java バージョンを確認できます。Java がインストールされていない場合、またはバージョンが Java 8 より前の場合は、Java をダウンロードしてインストールしてください。

SDK のインストール

Maven を使用して OSS SDK for Java V2 をインストールできます。

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>alibabacloud-oss-v2</artifactId>
    <version><!-- 最新のバージョン番号を指定します --></version>
</dependency>

mvn clean install -DskipTests -Dgpg.skip=true

アクセス認証情報の設定

RAM ユーザーの AccessKey ペアを環境変数として設定し、認証情報として使用します。

RAM コンソールで、アクセス用に RAM ユーザーと [永続的な AccessKey ペア] を作成します。 AccessKey ペアを保存し、ユーザーに AliyunOSSFullAccess 権限を付与します。

クライアントの初期化

リージョンを指定して OSSClient を初期化します。

• OSSClient は AutoCloseable を実装しています。try-with-resources 文を使用してインスタンスを作成すると、リソースは自動的に解放されるため、手動で close() を呼び出す必要はありません。

• OSSClient インスタンスの作成と破棄には時間がかかる場合があります。シングルトンパターンを使用して OSSClient インスタンスを再利用することを推奨します。このパターンを使用する場合、リソースリークを防ぐために、アプリケーションが終了する前に手動で close() を呼び出す必要があります。

  シングルトンパターン

  public class OssClientSingleton {
      private OssClientSingleton() {}
  
      private static class Holder {
          private static final OSSClient INSTANCE = OSSClient.newBuilder()
              .credentialsProvider(new EnvironmentVariableCredentialsProvider())
              .region("cn-hangzhou")
              .build();
      }
  
      public static OSSClient getInstance() {
          return Holder.INSTANCE;
      }
  
      // OSSClient インスタンスをクローズします。これは明示的に呼び出す必要があります。
      public static void shutdown() {
          try {
              getInstance().close();
          } catch (Exception e) {
              // クローズ例外を処理します。
          }
      }
  }
  

import com.aliyun.sdk.service.oss2.OSSClient;
import com.aliyun.sdk.service.oss2.OSSClientBuilder;
import com.aliyun.sdk.service.oss2.credentials.CredentialsProvider;
import com.aliyun.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider;
import com.aliyun.sdk.service.oss2.exceptions.ServiceException;
import com.aliyun.sdk.service.oss2.models.*;
import com.aliyun.sdk.service.oss2.paginator.ListBucketsIterable;

public class Example {
    public static void main(String[] args) {
        String region = "cn-hangzhou";

        CredentialsProvider provider = new EnvironmentVariableCredentialsProvider();
        OSSClientBuilder clientBuilder = OSSClient.newBuilder()
                .credentialsProvider(provider)
                .region(region);

        try (OSSClient client = clientBuilder.build()) {

            ListBucketsIterable paginator = client.listBucketsPaginator(
                    ListBucketsRequest.newBuilder()
                            .build());

            for (ListBucketsResult result : paginator) {
                for (BucketSummary info : result.buckets()) {
                    System.out.printf("bucket: name:%s, region:%s, storageClass:%s\n", info.name(), info.region(), info.storageClass());
                }
            }

        } catch (Exception e) {
//            ServiceException se = ServiceException.asCause(e);
//            if (se != null) {
//                System.out.printf("ServiceException: requestId:%s, errorCode:%s\n", se.requestId(), se.errorCode());
//            }
            System.out.printf("error:\n%s", e);
        }
    }
}

import com.aliyun.sdk.service.oss2.OSSAsyncClient;
import com.aliyun.sdk.service.oss2.credentials.CredentialsProvider;
import com.aliyun.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider;
import com.aliyun.sdk.service.oss2.exceptions.ServiceException;
import com.aliyun.sdk.service.oss2.models.*;

import java.util.concurrent.CompletableFuture;

public class ExampleAsync {
    public static void main(String[] args) {
        String region = "cn-hangzhou";
        CredentialsProvider provider = new EnvironmentVariableCredentialsProvider();

        try (OSSAsyncClient client = OSSAsyncClient.newBuilder()
                .region(region)
                .credentialsProvider(provider)
                .build()) {

            CompletableFuture<ListBucketsResult> future = client.listBucketsAsync(
                    ListBucketsRequest.newBuilder().build()
            );

            future.thenAccept(result -> {
                        for (BucketSummary info : result.buckets()) {
                            System.out.printf("bucket: name:%s, region:%s, storageClass:%s\n",
                                    info.name(), info.region(), info.storageClass());
                        }
                    })
                    .exceptionally(e -> {
//                ServiceException se = ServiceException.asCause(e);
//                if (se != null) {
//                    System.out.printf("Async ServiceException: requestId:%s, errorCode:%s\n",
//                            se.requestId(), se.errorCode());
//                }
                        System.out.printf("async error:\n%s\n", e);
                        return null;
                    });

            future.join();

        } catch (Exception e) {
            System.out.printf("main error:\n%s\n", e);
        }
    }
}

カスタムドメイン名の使用

デフォルトの OSS ドメイン名でアクセスすると、ファイルにアクセスできない、またはプレビューに失敗するなどの問題が発生する可能性があります。カスタムドメイン名を使用して OSS にアクセスすると、ブラウザで直接ファイルをプレビューしたり、CDN を使用してコンテンツ配信を高速化したりできます。

import com.aliyun.sdk.service.oss2.*;
import com.aliyun.sdk.service.oss2.credentials.*;

public class Example {
    public static void main(String[] args) {
        // 環境変数から認証情報を読み込み、ID 検証を行います。
        CredentialsProvider credentialsProvider = new EnvironmentVariableCredentialsProvider();

        // バケットが配置されているリージョンを指定します。例えば、中国 (杭州) の場合は、リージョンを cn-hangzhou に設定します。
        String region = "cn-hangzhou";

        // カスタムドメイン名を指定します。例えば、www.example-***.com。
        String endpoint = "https://www.example-***.com";

        // 設定情報を使用して OSS クライアントを作成します。
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region(region)
                .endpoint(endpoint)
                // 注意：useCName を true に設定して CNAME オプションを有効にしないと、カスタムドメイン名を使用できません。
                .useCName(true)
                .build()) {

            // 作成したクライアントを後続の操作で使用します...

        } catch (Exception e) {
            System.err.println("Error occurred: " + e.getMessage());
        }
    }
}

タイムアウト制御

import com.aliyun.sdk.service.oss2.*;
import com.aliyun.sdk.service.oss2.credentials.*;
import java.time.Duration;

public class Example {
    public static void main(String[] args) {
        // 環境変数から認証情報を読み込み、ID 検証を行います。
        CredentialsProvider credentialsProvider = new EnvironmentVariableCredentialsProvider();

        // バケットが配置されているリージョンを指定します。例えば、中国 (杭州) の場合は、リージョンを cn-hangzhou に設定します。
        String region = "cn-hangzhou";

        // 設定情報を使用して OSS クライアントを作成します。
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region(region)
                // 接続確立のタイムアウトを設定します。デフォルト値は 5 秒です。
                .connectTimeout(Duration.ofSeconds(30))
                // データの読み書きのタイムアウトを設定します。デフォルト値は 20 秒です。
                .readWriteTimeout(Duration.ofSeconds(30))
                .build()) {

            // 作成したクライアントを後続の操作で使用します...

        } catch (Exception e) {
            System.err.println("Error occurred: " + e.getMessage());
        }
    }
}

リトライポリシー

import com.aliyun.sdk.service.oss2.*;
import com.aliyun.sdk.service.oss2.credentials.*;
import com.aliyun.sdk.service.oss2.retry.*;
import java.time.Duration;

public class Example {
    public static void main(String[] args) {
        /*
         * SDK リトライポリシー設定の説明：
         *
         * デフォルトのリトライポリシー：
         * リトライポリシーが設定されていない場合、SDK は StandardRetryer をデフォルトのクライアント実装として使用します。
         * そのデフォルト設定は以下の通りです：
         * - maxAttempts: 最大試行回数を設定します。デフォルトは 3 です。
         * - maxBackoff: 最大バックオフ時間を秒単位で設定します。デフォルトは 20 秒です。
         * - baseDelay: 基本遅延時間を秒単位で設定します。デフォルトは 0.2 秒です。
         * - backoffDelayer: バックオフアルゴリズムを設定します。デフォルトは FullJitter バックオフアルゴリズムです。
         *   計算式：[0.0, 1.0) * min(2^attempts * baseDelay, maxBackoff)
         * - errorRetryables: リトライ可能なエラータイプ。HTTP ステータスコード、サービスエラーコード、クライアントエラーが含まれます。
         *
         * リトライ可能なエラーが発生した場合、提供された設定を使用して遅延させ、リクエストを再試行します。
         * リクエストの全体的なレイテンシは、リトライ回数とともに増加します。デフォルト設定が
         * シナリオの要件を満たさない場合は、リトライパラメーターを設定するか、リトライ実装を変更できます。
         */

        // 環境変数から認証情報を読み込み、ID 検証を行います。
        CredentialsProvider credentialsProvider = new EnvironmentVariableCredentialsProvider();

        // バケットが配置されているリージョンを指定します。例えば、中国 (杭州) の場合は、リージョンを cn-hangzhou に設定します。
        String region = "cn-hangzhou";

        // リトライポリシー設定の例：

        // 1. 最大リトライ回数をカスタマイズします (デフォルトは 3、ここでは 5 に設定)。
        Retryer customRetryer = StandardRetryer.newBuilder()
                .maxAttempts(5)
                .build();

        // 2. バックオフ遅延時間をカスタマイズします。
        // baseDelay を 0.5 秒 (デフォルト 0.2 秒)、maxBackoff を 25 秒 (デフォルト 20 秒) に調整します。
        // Retryer customRetryer = StandardRetryer.newBuilder()
        //         .backoffDelayer(new FullJitterBackoff(Duration.ofMillis(500), Duration.ofSeconds(25)))
        //         .build();

        // 3. バックオフアルゴリズムをカスタマイズします。
        // デフォルトの FullJitter アルゴリズムの代わりに、固定遅延バックオフアルゴリズムを使用し、毎回 2 秒遅延させます。
        // Retryer customRetryer = StandardRetryer.newBuilder()
        //         .backoffDelayer(new FixedDelayBackoff(Duration.ofSeconds(2)))
        //         .build();

        // 4. リトライポリシーを無効にします。
        // すべてのリトライ試行を無効にするには、NopRetryer 実装を使用します。
        // Retryer customRetryer = new NopRetryer();

        // 設定情報を使用して OSS クライアントを作成します。
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region(region)
                .retryer(customRetryer)
                .build()) {

            // 作成したクライアントを後続の操作で使用します...

        } catch (Exception e) {
            System.err.println("Error occurred: " + e.getMessage());
        }
    }
}

HTTP/HTTPS プロトコル

disableSsl(true) を使用して HTTPS プロトコルを無効にできます。

import com.aliyun.sdk.service.oss2.*;
import com.aliyun.sdk.service.oss2.credentials.*;

public class Example {
    public static void main(String[] args) {
        // 環境変数から認証情報を読み込み、ID 検証を行います。
        CredentialsProvider credentialsProvider = new EnvironmentVariableCredentialsProvider();

        // バケットが配置されているリージョンを指定します。例えば、中国 (杭州) の場合は、リージョンを cn-hangzhou に設定します。
        String region = "cn-hangzhou";

        // 設定情報を使用して OSS クライアントを作成します。
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region(region)
                // HTTPS リクエストを使用しないように設定します。
                .disableSsl(true)
                .build()) {

            // 作成したクライアントを後続の操作で使用します...

        } catch (Exception e) {
            System.err.println("Error occurred: " + e.getMessage());
        }
    }
}

内部エンドポイントの使用

内部エンドポイントを使用して同じリージョン内の OSS リソースにアクセスすることで、トラフィックコストを削減し、アクセス速度を向上させることができます。

import com.aliyun.sdk.service.oss2.*;
import com.aliyun.sdk.service.oss2.credentials.*;

public class Example {
    public static void main(String[] args) {
        // 環境変数から認証情報を読み込み、ID 検証を行います。
        CredentialsProvider credentialsProvider = new EnvironmentVariableCredentialsProvider();

        // 方法 1：リージョンを指定し、useInternalEndpoint を true に設定します。
        // バケットが配置されているリージョンを指定します。例えば、中国 (杭州) の場合は、リージョンを cn-hangzhou に設定します。
        String region = "cn-hangzhou";

        // // 方法 2：リージョンとエンドポイントを直接指定します。
        // // バケットが配置されているリージョンを指定します。例えば、中国 (杭州) の場合は、リージョンを cn-hangzhou に設定します。
        // String region = "cn-hangzhou";
        // // バケットのリージョンの内部エンドポイントを指定します。中国 (杭州) の場合、エンドポイントは 'oss-cn-hangzhou-internal.aliyuncs.com' です。
        // String endpoint = "oss-cn-hangzhou-internal.aliyuncs.com";

        // 設定情報を使用して OSS クライアントを作成します。
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region(region)
                .useInternalEndpoint(true)
                // .endpoint(endpoint) // 方法 2 を使用する場合は、この行のコメントを解除し、前の行をコメントアウトします。
                .build()) {

            // 作成したクライアントを後続の操作で使用します...

        } catch (Exception e) {
            System.err.println("Error occurred: " + e.getMessage());
        }
    }
}

転送アクセラレーションエンドポイントの使用

import com.aliyun.sdk.service.oss2.*;
import com.aliyun.sdk.service.oss2.credentials.*;

public class Example {
    public static void main(String[] args) {
        // 環境変数から認証情報を読み込み、ID 検証を行います。
        CredentialsProvider credentialsProvider = new EnvironmentVariableCredentialsProvider();

        // 方法 1：リージョンを指定し、useAccelerateEndpoint を true に設定します。
        // バケットが配置されているリージョンを指定します。例えば、中国 (杭州) の場合は、リージョンを cn-hangzhou に設定します。
        String region = "cn-hangzhou";

        // // 方法 2：リージョンと転送アクセラレーションエンドポイントを直接指定します。
        // // バケットが配置されているリージョンを指定します。例えば、中国 (杭州) の場合は、リージョンを cn-hangzhou に設定します。
        // String region = "cn-hangzhou";
        // // バケットのリージョンの転送アクセラレーションエンドポイントを指定します。例えば、'https://oss-accelerate.aliyuncs.com'。
        // String endpoint = "https://oss-accelerate.aliyuncs.com";

        // 設定情報を使用して OSS クライアントを作成します。
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region(region)
                .useAccelerateEndpoint(true)
                // .endpoint(endpoint) // 方法 2 を使用する場合は、この行のコメントを解除し、前の行をコメントアウトします。
                .build()) {

            // 作成したクライアントを後続の操作で使用します...

        } catch (Exception e) {
            System.err.println("Error occurred: " + e.getMessage());
        }
    }
}

プライベートドメインの使用

import com.aliyun.sdk.service.oss2.*;
import com.aliyun.sdk.service.oss2.credentials.*;

public class Example {
    public static void main(String[] args) {
        // 環境変数から認証情報を読み込み、ID 検証を行います。
        CredentialsProvider credentialsProvider = new EnvironmentVariableCredentialsProvider();

        // バケットが配置されているリージョンを指定します。例えば、中国 (杭州) の場合は、リージョンを cn-hangzhou に設定します。
        String region = "cn-hangzhou";

        // プライベートドメインを指定します。例えば：https://service.corp.example.com
        String endpoint = "https://service.corp.example.com";

        // 設定情報を使用して OSS クライアントを作成します。
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region(region)
                .endpoint(endpoint)
                .build()) {

            // 作成したクライアントを後続の操作で使用します...

        } catch (Exception e) {
            System.err.println("Error occurred: " + e.getMessage());
        }
    }
}

ガバメントクラウドのドメイン名の使用

次のサンプルコードは、Alibaba Gov Cloud ドメイン名を使用して OSSClient を設定する方法を示します。

import com.aliyun.sdk.service.oss2.*;
import com.aliyun.sdk.service.oss2.credentials.*;

public class Example {
    public static void main(String[] args) {
        // 環境変数から認証情報を読み込み、ID 検証を行います。
        CredentialsProvider credentialsProvider = new EnvironmentVariableCredentialsProvider();

        // リージョンとエンドポイントを指定します。
        // バケットが配置されているリージョンを指定します。中国 (北京) ガバメントクラウド 1 の場合、リージョンを cn-north-2-gov-1 に設定します。
        String region = "cn-north-2-gov-1";
        // バケットのリージョンの内部エンドポイントを指定します。中国 (北京) ガバメントクラウド 1 の場合、エンドポイントは 'https://oss-cn-north-2-gov-1-internal.aliyuncs.com' です。
        // HTTP プロトコルを指定するには、ドメインを 'http://oss-cn-north-2-gov-1-internal.aliyuncs.com' に設定します。
        String endpoint = "https://oss-cn-north-2-gov-1-internal.aliyuncs.com";

        // 設定情報を使用して OSS クライアントを作成します。
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region(region)
                .endpoint(endpoint)
                .build()) {

            // 作成したクライアントを後続の操作で使用します...

        } catch (Exception e) {
            System.err.println("Error occurred: " + e.getMessage());
        }
    }
}

カスタム HTTPClient の使用

標準の設定パラメーターが要件を満たさない場合は、カスタム HTTP クライアントを使用できます。

import com.aliyun.sdk.service.oss2.*;
import com.aliyun.sdk.service.oss2.credentials.*;
import com.aliyun.sdk.service.oss2.transport.HttpClient;
import com.aliyun.sdk.service.oss2.transport.HttpClientOptions;
import com.aliyun.sdk.service.oss2.transport.apache5client.Apache5HttpClientBuilder;
import java.time.Duration;

public class Example {
    public static void main(String[] args) {
        // 環境変数から認証情報を読み込み、ID 検証を行います。
        CredentialsProvider credentialsProvider = new EnvironmentVariableCredentialsProvider();

        // バケットが配置されているリージョンを指定します。例えば、中国 (杭州) の場合は、リージョンを cn-hangzhou に設定します。
        String region = "cn-hangzhou";

        // HTTP クライアントのパラメーターを設定します。
        HttpClientOptions httpClientOptions = HttpClientOptions.custom()
                // 接続タイムアウト。デフォルト値は 5 秒です。
                .connectTimeout(Duration.ofSeconds(30))
                // データの読み書きのタイムアウト。デフォルト値は 20 秒です。
                .readWriteTimeout(Duration.ofSeconds(30))
                // 最大接続数。デフォルト値は 1024 です。
                .maxConnections(2048)
                // 証明書検証をスキップするかどうかを指定します。デフォルトでは false です。
                .insecureSkipVerify(false)
                // HTTP リダイレクトを有効にするかどうかを指定します。デフォルトでは無効です。
                .redirectsEnabled(false)
                // プロキシサーバーを設定します。
                // .proxyHost("http://user:passswd@proxy.example-***.com")
                .build();

        // HTTP クライアントを作成し、HTTP クライアントパラメーターを渡します。
        HttpClient httpClient = Apache5HttpClientBuilder.create()
                .options(httpClientOptions)
                .build();

        // 設定情報を使用して OSS クライアントを作成します。
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region(region)
                .httpClient(httpClient)
                .build()) {

            // 作成したクライアントを後続の操作で使用します...

        } catch (Exception e) {
            System.err.println("Error occurred: " + e.getMessage());
        }
    }
}

カスタムアクセス認証情報の使用

前述の認証情報設定方法が要件を満たさない場合、認証情報の取得方法をカスタマイズできます。Java SDK はこの目的のために複数の実装方法をサポートしています。

Supplier インターフェイスによる実装

import com.aliyun.sdk.service.oss2.OSSClient;
import com.aliyun.sdk.service.oss2.credentials.Credentials;
import com.aliyun.sdk.service.oss2.credentials.CredentialsProvider;
import com.aliyun.sdk.service.oss2.credentials.CredentialsProviderSupplier;

public class OSSExample {
    public static void main(String[] args) {
        // カスタム認証情報プロバイダーを作成します。
        CredentialsProvider credentialsProvider = new CredentialsProviderSupplier(() -> {
            // TODO: カスタムの認証情報取得ロジックを実装します。
            
            // 長期的な認証情報を返します。
            return new Credentials("access_key_id", "access_key_secret");
            
            // STS トークンを返します (必要な場合)。
            // return new Credentials("sts_access_key_id", "sts_access_key_secret", "security_token");
        });
        
        // OSS クライアントを作成します。
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region("cn-hangzhou") // バケットが配置されているリージョンを指定します。
                .build()) {
            
            // 作成したクライアントを後続の操作で使用します...
            
        } catch (Exception e) {
            System.err.println("Operation failed: " + e.getMessage());
        }
    }
}

匿名アクセス

公開読み取り可能な OSS リソースにのみアクセスする必要がある場合は、認証情報を提供せずに匿名アクセスを使用できます。

import com.aliyun.sdk.service.oss2.OSSClient;
import com.aliyun.sdk.service.oss2.credentials.CredentialsProvider;
import com.aliyun.sdk.service.oss2.credentials.AnonymousCredentialsProvider;

public class OSSExample {
    public static void main(String[] args) {
        // 匿名認証情報プロバイダーを作成します。
        CredentialsProvider credentialsProvider = new AnonymousCredentialsProvider();
        
        // OSS クライアントを作成します。
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region("cn-hangzhou") // バケットが配置されているリージョンを指定します。
                .build()) {
            
            // 作成したクライアントを後続の操作で使用します...
            // 注意：匿名アクセスは公開読み取り権限を持つリソースにのみ使用できます。
            
        } catch (Exception e) {
            System.err.println("Operation failed: " + e.getMessage());
        }
    }
}