Java で Amazon S3 からファイルをインポート
Amazon S3 オブジェクトをローカルファイルにインポートするには、AWS SDK for Java v2 の getObject とファイルレスポンストランスフォーマーを使います。以下のインポーターは一時領域にダウンロードし、信頼できる SHA-256 チェックサムを検証して、ダウンロード全体が検証に合格した後にのみ保存先を公開します。標準の非同期クライアント、AWS CRT クライアント、S3 Transfer Manager にも対応しています。
Amazon S3 と Java の概要
この例では、汎用 S3 バケットから既知のキーを一つ取得します。バケットのリージョン、そのオブジェクトの読み取り権限、および発行元が提供した、またはアップロード前の元ファイルから計算した SHA-256 が必要です。ダウンロード中はオブジェクトを変更しないでください。チェックサムは、空のオブジェクトやバイナリファイルも含め、インポート対象として意図したバイト列を識別します。
AWS SDK v2 のセットアップ
コマンドは Linux 上の Bash、C.UTF-8 ロケール、別途インストールした JDK と Maven を使用します。UTF-8 ロケールにより、キーやファイル名の引数に含まれる非 ASCII 文字をそのまま扱えます。テスト済みのバージョンは OpenJDK 21.0.12.1、Maven 3.10.0、AWS SDK v2 2.55.13、AWS CRT 0.48.5 です。以下の依存関係はテストを再現できるようバージョンを固定しています。更新時には AWS SDK のリリースを確認してください。
.mvn ディレクトリを持つ Maven チェックアウトの外に、新しいプロジェクトを作成してください。Maven はそのディレクトリの JVM オプション、拡張機能、コマンドオプションを継承することがあります。以下を貼り付けて実行すると、ファイルの作成前にツールを確認し、継承された設定があれば処理を拒否します。シェルの現在のディレクトリは変わりません。s3-import がすでに存在する場合は、そのファイルを削除せず、別の新しいディレクトリを使ってください。
(
for tool in java javac mvn; do
command -v "$tool" >/dev/null || {
printf 'Missing prerequisite: %s\n' "$tool" >&2
exit 1
}
done
parent="$PWD"
while :; do
[ ! -e "$parent/.mvn" ] || {
printf 'Use a directory outside the enclosing Maven configuration.\n' >&2
exit 1
}
[ "$parent" != / ] || break
parent="${parent%/*}"
[ -n "$parent" ] || parent=/
done
mkdir s3-import && mkdir -p s3-import/src/main/java
)
以下の完全な pom.xml を s3-import/ に保存してください。BOM によって SDK モジュールのバージョンを統一します。CRT は独自のバージョンを使います。依存関係プラグインは、Java ランチャーに必要なランタイム JAR をコピーします。
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>example</groupId>
<artifactId>s3-import</artifactId>
<version>1.0.0</version>
<properties>
<maven.compiler.release>21</maven.compiler.release>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>software.amazon.awssdk</groupId>
<artifactId>bom</artifactId>
<version>2.55.13</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<dependencies>
<dependency>
<groupId>software.amazon.awssdk</groupId>
<artifactId>s3</artifactId>
</dependency>
<dependency>
<groupId>software.amazon.awssdk</groupId>
<artifactId>s3-transfer-manager</artifactId>
</dependency>
<dependency>
<groupId>software.amazon.awssdk.crt</groupId>
<artifactId>aws-crt</artifactId>
<version>0.48.5</version>
</dependency>
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-nop</artifactId>
<version>1.7.36</version>
<scope>runtime</scope>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.14.1</version>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-dependency-plugin</artifactId>
<version>3.8.1</version>
<executions>
<execution>
<phase>package</phase>
<goals><goal>copy-dependencies</goal></goals>
<configuration><includeScope>runtime</includeScope></configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>
AWS 認証情報の設定
組織で既存の AWS ログインまたはランタイムロールを使って認証情報を設定してください。このプログラムは SDK のデフォルト認証情報プロバイダーチェーンを使い、Java システムプロパティ、環境変数、共有プロファイル、ランタイムロールを確認します。環境変数で一時認証情報を指定するには、AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY、AWS_SESSION_TOKEN の三つすべてが必要です。Java ソースや Maven ファイルには保存しないでください。
この例の依存関係は、環境変数による認証情報と基本的な共有プロファイルに対応しています。SSO または AssumeRole で認証情報を取得するプロファイルでは、sso、ssooidc、sts などの対応する SDK モジュールも、BOM のバージョンで必要です。インポーターの実行前に、そのログインを完了してください。
AWS リージョンの設定
バケットのリージョンを、us-east-1 のようにプログラムの第2引数で渡します。各クライアントは Region.of(regionName) を使うため、シェルや共有プロファイルのリージョンには依存しません。キー引数は s3:// URL ではなく、S3 キーそのものです。スペースやパーセント記号を自分で URL エンコードしないでください。
S3 からのファイルのインポート
以下を s3-import/src/main/java/S3FileImporter.java として保存してください。
import java.io.IOException;
import java.io.InputStream;
import java.nio.file.FileAlreadyExistsException;
import java.nio.file.Files;
import java.nio.file.LinkOption;
import java.nio.file.Path;
import java.security.MessageDigest;
import java.util.HexFormat;
import java.util.Set;
import java.util.concurrent.CompletionException;
import software.amazon.awssdk.core.async.AsyncResponseTransformer;
import software.amazon.awssdk.core.sync.ResponseTransformer;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3AsyncClient;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.GetObjectRequest;
import software.amazon.awssdk.services.s3.model.S3Exception;
import software.amazon.awssdk.transfer.s3.S3TransferManager;
import software.amazon.awssdk.transfer.s3.model.DownloadFileRequest;
public class S3FileImporter {
public static void main(String[] args) {
try {
run(args);
} catch (Exception error) {
Throwable cause = error;
while (cause instanceof CompletionException && cause.getCause() != null) {
cause = cause.getCause();
}
if (cause instanceof S3Exception s3Error) {
System.err.println("S3 download failed (HTTP " + s3Error.statusCode() + ").");
} else if (cause instanceof IOException || cause instanceof IllegalArgumentException) {
System.err.println(cause.getMessage());
} else {
System.err.println("Download failed; check credentials, connectivity, and local disk space.");
}
System.exit(1);
}
}
private static void run(String[] args) throws Exception {
if (args.length != 6 || !Set.of("sync", "async", "crt", "transfer").contains(args[0])) {
throw new IllegalArgumentException(
"Usage: S3FileImporter <sync|async|crt|transfer> <region> <bucket> <key> <destination> <sha256>");
}
String expectedHash = args[5];
if (!expectedHash.matches("[0-9a-fA-F]{64}")) {
throw new IllegalArgumentException("Supply the original object's 64-digit SHA-256.");
}
Path destination = Path.of(args[4]).toAbsolutePath();
if (Files.exists(destination, LinkOption.NOFOLLOW_LINKS)) {
throw new FileAlreadyExistsException("Destination already exists: " + destination);
}
GetObjectRequest request = GetObjectRequest.builder().bucket(args[2]).key(args[3]).build();
Region region = Region.of(args[1]);
Path stagingDirectory = Files.createTempDirectory(destination.getParent(), ".s3-import-");
Path stagedFile = stagingDirectory.resolve("object.bin");
try {
download(args[0], region, request, stagedFile);
if (!sha256(stagedFile).equalsIgnoreCase(expectedHash)) {
throw new IOException("SHA-256 mismatch; destination was not published.");
}
Files.move(stagedFile, destination);
System.out.println("Downloaded " + Files.size(destination) + " bytes to " + destination);
} finally {
Files.deleteIfExists(stagedFile);
Files.delete(stagingDirectory);
}
}
private static void download(String mode, Region region, GetObjectRequest request, Path file) {
if (mode.equals("sync")) {
try (S3Client client = S3Client.builder().region(region)
.overrideConfiguration(c -> c.retryStrategy(r -> r.maxAttempts(1))).build()) {
client.getObject(request, ResponseTransformer.toFile(file));
}
return;
}
if (mode.equals("async")) {
try (S3AsyncClient client = S3AsyncClient.builder().region(region)
.overrideConfiguration(c -> c.retryStrategy(r -> r.maxAttempts(1))).build()) {
client.getObject(request, AsyncResponseTransformer.toFile(file)).join();
}
return;
}
try (S3AsyncClient client = S3AsyncClient.crtBuilder().region(region)
.minimumPartSizeInBytes(8L * 1024 * 1024).maxConcurrency(2)
.retryConfiguration(r -> r.numRetries(0)).build()) {
if (mode.equals("crt")) {
client.getObject(request, AsyncResponseTransformer.toFile(file)).join();
} else {
try (S3TransferManager manager = S3TransferManager.builder().s3Client(client).build()) {
manager.downloadFile(DownloadFileRequest.builder()
.getObjectRequest(request).destination(file).build()).completionFuture().join();
}
}
}
}
private static String sha256(Path file) throws Exception {
MessageDigest digest = MessageDigest.getInstance("SHA-256");
try (InputStream input = Files.newInputStream(file)) {
byte[] buffer = new byte[8192];
int count;
while ((count = input.read(buffer)) != -1) {
digest.update(buffer, 0, count);
}
}
return HexFormat.of().formatHex(digest.digest());
}
}
s3-import/ 内でビルドし、同期処理を実行してください。バケット、キー、リージョン、チェックサムを対象オブジェクトの値に置き換えます。保存先の親ディレクトリは存在している必要があり、保存先自体は新規である必要があります。クラスパスを引用符で囲むことで、ワイルドカードの展開を Java に任せます。
mvn -B package &&
LC_ALL=C.UTF-8 java -cp 'target/classes:target/dependency/*' S3FileImporter \
sync us-east-1 your-bucket-name 'path/to/your/file.bin' \
'./downloaded-file.bin' 'REPLACE_WITH_ORIGINAL_SHA256'
コマンドが成功すると、ダウンロードしたバイト数と保存先を表示し、ステータスゼロで終了します。チェックサムの検証は、SDK がファイルを完成させた後、Files.move が公開する前に実行されます。ファイル全体を読み取るため、ファイルの存在、一部のデータの取得、future の完了だけでは不十分です。ダウンロードしたファイル自体のハッシュを期待値のチェックサムとして使わないでください。
例外処理
保存先の拒否、チェックサムの不一致、SDK の障害、ローカル I/O エラーが発生すると、コマンドはステータス一で終了します。ダウンロードまたはチェックサムの検証の失敗を捕捉すると、一時ファイルを削除し、新しい最終保存先は残しません。既存の保存先は保持されます。同じ保存先へのダウンロードは順番に実行してください。この例では、同時に公開する処理間の調整は行いません。
キーが存在しない場合、呼び出し元が s3:ListBucket も持っていれば、S3 は 404 を返します。その権限がない場合は 403 を返すことがあります。したがって、403 ではキーが存在しないのか、アクセスが拒否されたのかを区別できません。GetObject の権限ルールに従って、正確なキーと権限を確認してください。チェックサムが一致しない場合は、発行元のハッシュとオブジェクトが変更されていないことを確認し、新しい保存先で再試行してください。認証情報やネットワークの障害では、その前提条件を修正してからコマンドを再実行してください。例外が表示された場合、インポートが成功したと判断しないでください。
S3 クライアントの種類
プログラムの第1引数だけを変更し、新しい保存先を使ってモードを選択します。
同期クライアント(S3Client)
sync は、ファイルレスポンストランスフォーマーが完了するまで
getObject 内でブロックします。オブジェクトを一つインポートするコマンドの出発点として適しています。
非同期クライアント(S3AsyncClient)
async は、標準の Java 非同期クライアントを使います。アプリケーションでは、その future によってダウンロード中もほかの処理を続行できます。このコマンドは、ファイルの検証、クライアントのクローズ、終了の前に
join() を呼び出します。そうしなければ、インポートの完了前にプロセスが終了するおそれがあります。
高性能クライアント(AWS CRT)
crt は、AWS CRT ベースの S3 クライアントを使います。これは、大きなオブジェクトをバイト範囲単位で取得できる
S3AsyncClient の実装です。ネイティブ依存関係は Maven ビルドに含まれています。設定オプションは標準クライアントより少なくなっています。性能を理由に選択する前に、実際のワークロードで測定してください。これらのコマンドは特定の転送速度を保証しません。
パフォーマンスの最適化
ディスクへのストリーミング
四つのモードはいずれも、オブジェクト全体を Java のバイト配列に読み込まず、ファイルを保存先に使います。SHA-256 の検証でも固定サイズのバッファーで読み取ります。オブジェクト全体を保存できるディスク容量と、書き込み可能な保存先ディレクトリを用意してください。プロセスが強制終了した場合は、再試行する前に、残された .s3-import-* ディレクトリを確認して削除してください。Java の finally ブロックでは、強制終了されたプロセスの後処理はできません。
マルチパートダウンロード
transfer は、明示的に指定した CRT クライアントで
S3 Transfer Managerを使います。大きなダウンロードでは、並列のバイト範囲リクエストを利用できます。この例では、最小パートサイズを 8 MiB、最大接続数を二つに設定しています。これらはダウンロード範囲であり、S3 マルチパートアップロードではありません。チェックサムの検証前にマネージャーの完了 future を待機し、クライアントより先にマネージャーを閉じます。
このデモでは再試行を無効にしているため、リクエストの失敗は呼び出し元に報告されます。アプリケーションでは、標準と CRT のビルダーが同じ設定を受け付けると考えず、選択したクライアントに合わせて、回数などに上限のある再試行ポリシーとタイムアウトを選んでください。そうしないと、低速な接続でダウンロードが待機し続けることがあります。このプログラムは転送全体の期限を設定していません。
IAM 権限
汎用バケット内の既知のキーの現行バージョンを取得するには、オブジェクト ARN に対して s3:GetObject を許可します。このインポーターにバケットの一覧取得は不要です。たとえば、AWS 管理者に以下のポリシーを必要なオブジェクトに合わせて調整してもらってください。
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "s3:GetObject",
"Resource": "arn:aws:s3:::your-bucket-name/path/to/your/file.bin"
}
]
}
この手順では、S3 管理キーで暗号化され、すぐに取得できるオブジェクトを前提としています。アーカイブされたオブジェクトは復元が必要な場合があり、KMS 暗号化では追加のキー権限が必要になります。これらの場合は、S3 ユーザーガイドの権限マッピングを参照してください。このプログラムは、特定のバージョン ID の指定や SSE-C キーの処理は行いません。
ベストプラクティス
インポートする各オブジェクトとともに、信頼できるチェックサムを保持してください。後でこのコマンドをジョブに組み込む場合は、ゼロ以外の終了ステータスをスケジューラーに返し、後続の処理には検証済みの最終保存先だけを読み取らせてください。発行元が同じ場所のオブジェクトを置き換える場合は、変更されないキーを選ぶか、バージョンを考慮した取得処理を追加してください。
S3 オブジェクトをマネージドのファイル処理ワークフローにインポートするには、Transloadit の S3 Import Robot と Java SDK を参照してください。
