Java で MinIO からファイルをインポート
MinIO オブジェクトを一時ファイルにダウンロードし、レスポンスを読み取って閉じた後で、指定された保存先に配置します。この Java コマンドは既存の保存先を変更せず、インポートに失敗するとステータス 1 で終了します。ローカルデモでは、既知のバイナリデータを先にアップロードするため、インポーターが実際に保存した内容を確認できます。
Java 環境のセットアップ
この手順では、セルフホスト型のエンドポイントと、正確に指定した単一のオブジェクトキーに MinIO Java SDK を使用します。AWS の認証情報、リージョン、転送マネージャーの動作については、別記事の Amazon S3 Java ガイドを参照してください。
Linux、Bash、OpenJDK 21.0.12.1、Maven 3.9.16 を使用してください。この例では MinIO Java SDK 9.0.3を使用します。Maven は SDK とビルドプラグインを Maven Central からダウンロードします。Maven が別の Java バージョンを使用する場合は、JAVA_HOME に
JDK のインストール先を設定してください。
使い捨てのローカルデモには、AWS Signature V4 対応の cURL と、PATH 上の minio サーバーバイナリも必要です。再現実行では cURL 8.22.0 と、リビジョン 9e49d5e7a648 からビルドした MinIO を使用しました。MinIO Community Edition はアーカイブされ、メンテナンスが終了しています。このテスト環境はローカルでの学習用であり、新規の本番環境への導入を推奨するものではありません。すでに MinIO サービスを管理している場合は、そのサービスでインポーターを直接使用できます。
書き込み可能な親ディレクトリを選んでください。そこで次のブロックを貼り付けると、新しいプロジェクトが作成され、シェルは親ディレクトリにとどまります。minio-import がすでに存在する場合は、その内部に書き込む前に停止します。
(
set -eu
mkdir minio-import
cd minio-import
mkdir -p .mvn src/main/java
printf '<settings xmlns="http://maven.apache.org/SETTINGS/1.2.0"/>\n' > settings.xml
)
次のファイルを minio-import 内に保存してください。専用の .mvn ディレクトリにより、Maven が上位プロジェクトの
.mvn 設定を使用しないようにします。ランチャーは空の設定とプロジェクト内の .m2 リポジトリを使用するため、通常の Maven 依存関係キャッシュは更新しません。
MinIO Java SDK の統合
次の完全な pom.xml を保存してください。コンパイラーのリリースとプラグインのバージョンを明示しているため、上位の親 POM は不要です。OkHttp 5 では Maven で JVM アーティファクトを明示する必要があります。ここでの okhttp-jvm は、SDK が使用するバージョンと一致します。
<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>minio-import</artifactId>
<version>1.0</version>
<properties>
<maven.compiler.release>21</maven.compiler.release>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>
<dependencies>
<dependency>
<groupId>io.minio</groupId>
<artifactId>minio</artifactId>
<version>9.0.3</version>
</dependency>
<dependency>
<groupId>com.squareup.okhttp3</groupId>
<artifactId>okhttp-jvm</artifactId>
<version>5.3.2</version>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-resources-plugin</artifactId>
<version>3.3.1</version>
</plugin>
<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.9.0</version>
</plugin>
</plugins>
</build>
</project>
MinIO からファイルをインポートする手順
次の内容を src/main/java/MinIOFileImporter.java として保存してください。引数は、バケット、正確なオブジェクトキー、ローカルの保存先です。キーは reports/April report.bin のように、保存されているとおりに渡してください。URL に変換したり、自分でパーセントエンコードしたりしないでください。
import io.minio.GetObjectArgs;
import io.minio.GetObjectResponse;
import io.minio.MinioClient;
import io.minio.errors.ErrorResponseException;
import java.io.IOException;
import java.nio.file.FileAlreadyExistsException;
import java.nio.file.Files;
import java.nio.file.LinkOption;
import java.nio.file.Path;
import java.nio.file.StandardCopyOption;
public class MinIOFileImporter {
public static void main(String[] args) {
try {
long bytes = download(args);
System.out.println("Imported " + bytes + " bytes.");
} catch (FileAlreadyExistsException e) {
System.err.println("Destination exists; choose a new path.");
System.exit(1);
} catch (ErrorResponseException e) {
System.err.println("Storage refused the download (HTTP " + e.response().code() + ").");
System.exit(1);
} catch (Exception e) {
System.err.println("Import failed (" + e.getClass().getSimpleName() + "). Check configuration, network, and disk.");
System.exit(1);
}
}
private static String required(String name) {
String value = System.getenv(name);
if (value == null || value.isBlank()) {
throw new IllegalArgumentException("Missing " + name);
}
return value;
}
private static long download(String[] args) throws Exception {
if (args.length != 3 || args[0].isBlank() || args[1].isEmpty() || args[2].isBlank()) {
throw new IllegalArgumentException("Expected bucket, object key, and destination");
}
String endpoint = required("MINIO_ENDPOINT");
String region = required("MINIO_REGION");
String accessKey = required("MINIO_ACCESS_KEY");
String secretKey = required("MINIO_SECRET_KEY");
Path destination = Path.of(args[2]).toAbsolutePath();
if (Files.exists(destination, LinkOption.NOFOLLOW_LINKS)) {
throw new FileAlreadyExistsException(destination.toString());
}
if (!Files.isDirectory(destination.getParent())) {
throw new IOException("Destination parent must already exist");
}
Path staged = Files.createTempFile(destination.getParent(), ".minio-", ".part");
try {
long copied;
try (MinioClient client = MinioClient.builder()
.endpoint(endpoint).region(region).credentials(accessKey, secretKey).build()) {
client.setTimeout(10_000, 30_000, 30_000);
try (GetObjectResponse response = client.getObject(
GetObjectArgs.builder().bucket(args[0]).object(args[1]).build())) {
String length = response.headers().get("Content-Length");
if (length == null) throw new IOException("Missing Content-Length");
long expected = Long.parseLong(length);
copied = Files.copy(response, staged, StandardCopyOption.REPLACE_EXISTING);
if (expected < 0 || copied != expected) {
throw new IOException("Incomplete response body");
}
}
}
Files.move(staged, destination);
return copied;
} finally {
Files.deleteIfExists(staged);
}
}
}
SDK の getObject の契約では、返されたレスポンスを閉じる必要があります。ここでは、配置前にレスポンスとクライアントの両方を閉じます。空のオブジェクトも有効で、0 バイトのファイルが生成されます。長さの比較で不完全な本文を検出しますが、これは独立したチェックサムではなく、サーバーが意図した内容を保存したことの証明でもありません。
download.sh をプロジェクトルートに保存し、必ずそのディレクトリから実行してください。このスクリプトは、提示したクラスをビルドし、実行時の依存関係をコピーしてから Java を起動します。以前にコンパイルしたクラスが残っていても、ビルドに失敗するとシェルは停止します。
#!/usr/bin/env bash
set -eu
if [ ! -d .mvn ] || [ ! -f settings.xml ] || [ ! -f src/main/java/MinIOFileImporter.java ]; then
printf 'Run download.sh from the minio-import project root.\n' >&2
exit 1
fi
if [ "$#" -ne 3 ]; then
printf 'Usage: bash download.sh BUCKET OBJECT_KEY DESTINATION\n' >&2
exit 1
fi
MAVEN_SKIP_RC=1 MAVEN_ARGS= MAVEN_OPTS= MAVEN_BASEDIR="$PWD" \
mvn --batch-mode --no-transfer-progress --settings settings.xml \
--global-settings settings.xml -Dmaven.repo.local="$PWD/.m2" \
compile dependency:copy-dependencies -DincludeScope=runtime
java -cp 'target/classes:target/dependency/*' MinIOFileImporter "$@"
自分で管理するローカルディレクトリを使用し、保存先ごとにインポーターを一つだけ実行してください。移動処理では、Java の移動ポリシーに従い、REPLACE_EXISTING を指定しません。この逐次処理の構成は、同時配置やクラッシュ時の永続性を保証しません。処理済みの転送エラーでは、ステージングファイルを削除し、保存先ファイルは存在しない状態になります。JVM が強制終了されると、.minio-*.part ファイルが残ることがあります。削除するのは、インポーターが停止したと確認した後にしてください。配置時やクリーンアップ時にファイルシステム障害が発生した場合は、再試行前にディレクトリの確認が必要になることがあります。
ローカルオブジェクトをアップロードからダウンロードまで検証
demo.sh をプロジェクトルートに保存してください。このスクリプトは、使い捨ての認証情報でプライベートなループバックサーバーを起動し、cURL で八バイトのバイナリテストデータをアップロードして、download.sh を呼び出します。確認用にテストデータ、サーバーログ、サーバーデータ、ダウンロードしたファイルを保持し、終了時にサーバーを停止します。公開デモエンドポイントには接続しません。
#!/usr/bin/env bash
set -eu
port=${1:-19000}
case "$port" in ''|*[!0-9]*) printf 'Supply a numeric local port.\n' >&2; exit 1;; esac
if [ "$port" -lt 1024 ] || [ "$port" -gt 65535 ]; then
printf 'Use a local port from 1024 through 65535.\n' >&2
exit 1
fi
if [ ! -f download.sh ] || [ ! -d .mvn ]; then
printf 'Run demo.sh from the minio-import project root.\n' >&2
exit 1
fi
command -v minio >/dev/null
command -v curl >/dev/null
mkdir demo-data
mkdir demo-certs
export MINIO_ENDPOINT="http://127.0.0.1:$port" MINIO_REGION=us-east-1
export MINIO_ACCESS_KEY=local-demo MINIO_SECRET_KEY=local-demo-secret
MINIO_ROOT_USER="$MINIO_ACCESS_KEY" MINIO_ROOT_PASSWORD="$MINIO_SECRET_KEY" \
MINIO_BROWSER=off minio server demo-data --certs-dir demo-certs \
--address "127.0.0.1:$port" \
> demo-server.log 2>&1 &
server_pid=$!
stop_server() {
kill "$server_pid" 2>/dev/null || :
wait "$server_pid" 2>/dev/null || :
}
trap stop_server EXIT
trap 'exit 130' INT
trap 'exit 143' TERM
ready=0
for attempt in {1..100}; do
if ! kill -0 "$server_pid" 2>/dev/null; then
printf 'MinIO startup failed; inspect demo-server.log.\n' >&2
exit 1
fi
if grep -q '^API:' demo-server.log && \
curl -fsS --max-time 1 "$MINIO_ENDPOINT/minio/health/ready" >/dev/null 2>&1; then
ready=1
break
fi
sleep 0.1
done
if [ "$ready" -ne 1 ]; then
printf 'MinIO did not become ready; inspect demo-server.log.\n' >&2
exit 1
fi
printf '\000\377MinIO\n' > sample.bin
curl -fsS --max-time 10 --aws-sigv4 'aws:amz:us-east-1:s3' \
--user "$MINIO_ACCESS_KEY:$MINIO_SECRET_KEY" -X PUT "$MINIO_ENDPOINT/demo-bucket"
curl -fsS --max-time 10 --aws-sigv4 'aws:amz:us-east-1:s3' \
--user "$MINIO_ACCESS_KEY:$MINIO_SECRET_KEY" --upload-file sample.bin \
"$MINIO_ENDPOINT/demo-bucket/fixtures/sample.bin"
bash download.sh demo-bucket 'fixtures/sample.bin' ./downloaded.bin
cmp sample.bin downloaded.bin
printf 'Verified downloaded.bin against sample.bin.\n'
cURL の --aws-sigv4 オプションは、Java ダウンローダーとは独立して、テスト用のバケット作成リクエストとアップロードリクエストに署名します。未使用のローカルポートを選び、親ディレクトリで次を貼り付けてください。
(cd minio-import && bash demo.sh 19000)
Maven のビルド出力の後に、次の行が表示され、終了ステータスが 0 になるはずです。
Imported 8 bytes.
Verified downloaded.bin against sample.bin.
デモ全体を再実行すると、mkdir demo-data で停止し、以前のファイルを保持したまま失敗を返します。デモ全体を再度実行するには、新しいプロジェクトディレクトリを使用してください。インポーター自体も、既存の downloaded.bin を拒否します。再試行を成功させるために、そのファイルを削除することはありません。
既存の MinIO エンドポイントの使用
プロセスの環境変数で MINIO_ENDPOINT、MINIO_REGION、MINIO_ACCESS_KEY、MINIO_SECRET_KEY を指定してください。選択したオブジェクトに対して s3:GetObject 権限を持つ認証情報を使用します。Web コンソールのアドレスではなく、S3 API エンドポイントを使用してください。リージョンはサーバーと一致させてください。上記の HTTP とルート認証情報は、ループバックのテスト環境専用です。管理しているサービスでは、HTTPS と組織の認証情報管理の仕組みを使用してください。トラストストアのエラーを回避するために証明書の検証を無効にしないでください。
環境を設定したら、バケットとキーを既存のオブジェクトのものに置き換え、プロジェクトルートで次を貼り付けてください。
bash download.sh my-bucket 'reports/April report.bin' './April report.bin'
よくある例外への対処
ステータス 0 は、レスポンス全体の読み取り、リソースのクローズ、保存先への配置が完了したことを示します。ステータス 1 はコマンドの失敗を示します。診断情報には、意図的に認証情報、レスポンス本文、スタックトレースを含めていません。HTTP 404 は、バケットまたは正確に指定したキーが存在しないことを示す場合があります。HTTP 403 は、認証情報が無効であるか、オブジェクトへのアクセスが拒否されたことを示す場合があります。ローカルパスのエラーや不完全な転送も失敗になります。
接続タイムアウトは 10 秒、読み取りと書き込みのタイムアウトは 30 秒で、SDK のミリ秒単位のタイムアウトパラメーターを使用します。これらは個々の操作のタイムアウトであり、ダウンロード全体の期限ではありません。アプリケーション側の再試行ループはありません。一時的な障害の後は、保存先ファイルが存在しない状態でコマンド全体を再実行してください。各試行では新しいステージングファイルを作成します。getObject だけを再試行しても、本文の読み取り中に起きた失敗には対応できません。
トラブルシューティング
接続の拒否
API のホストとポート、サーバーが起動しているか、マシンから到達できるかを確認してください。ローカルデモでは、demo-server.log を確認してください。ポートが使用中の場合は、別のテスト環境を起動する前に変更する必要があります。ビルドに失敗するとダウンロードは実行されないため、まず Maven の診断内容に対処してください。
アクセスの拒否
アカウントのオブジェクト権限、リージョン、キーの大文字と小文字および記号を正確に確認してください。インポーターはプレフィックスの一覧取得や、最初に一致したオブジェクトの選択は行いません。保存先がすでに存在する場合は、未検証の以前の結果を削除せず、新しいローカルファイル名を選んでください。
ホスト型の処理パイプラインにデータを渡すインポートには、🤖 /minio/import Robot という別の統合方法もあります。上記のローカルコマンドは、独自の Java ワークフロー向けにファイルを生成します。
