cURL と署名付き PUT URL で MinIO にファイルをアップロード
ローカルファイルを MinIO にエクスポートするには、単一のバケットとオブジェクトキーに対して署名付き PUT URL を生成し、curl --upload-file でファイルを送信します。この手順ではローカルサーバーを構築してバケットを作成し、アップロードしたオブジェクトをダウンロードして、元のファイルとバイト列が一致することを確認します。
URL が許可する操作の把握
MinIO は S3 互換の HTTP API を公開しています。SDK がアクセスキーとシークレットキーでリクエストに署名し、cURL がその署名を使ってバイト列を送信します。SDK と mc コマンドラインクライアントはツールであり、別々の認証方式ではありません。
署名付き URL はベアラー認証情報です。この例の URL を持つ人は誰でも、10分間、指定されたオブジェクトキーに PUT でき、異なるバイト列への置換も行えます。特定のローカルファイルの内容を認証するものではありません。シェル履歴、ログ、共有メッセージに残さないでください。POST ポリシーを使うフォームアップロードは別の操作です。SDK の署名付き PUT 操作を使用してください。
ローカルデモの準備
MinIO コミュニティリポジトリは2026年4月25日にアーカイブされ、現在はメンテナンスされていないと明記されています。以下の固定バージョンのソースビルドはローカルでの互換性テスト用であり、新規の本番デプロイに推奨するものではありません。本番環境ではメンテナンスされているサービスを使用し、その認証と TLS の要件に従ってください。
前提条件
Linux に Bash、cURL、Go 1.26.8、およびパッチ適用済みの Node.js 24 または 26 LTS
リリースを用意してください。この手順は2026年11月6日に、Node.js 24.22.2 と 26.13.0、別途インストールした Corepack 0.34.5、Yarn 4.12.0 でテストしました。Node.js のリリーススケジュールを確認し、最新のパッチを適用してください。2026年10月のセキュリティ更新は両方の LTS 系列に適用されます。Node.js 26 のように Corepack が含まれていない場合は、インストール手順に従って別途インストールしてください。この例では Node 組み込みの TypeScript サポートを使います。.mts ファイルは、親プロジェクトが CommonJS でも ES モジュールとして実行されます。サーバーは RELEASE.2025-10-15T17-29-55Z、JavaScript SDK は
minio@8.0.7 に固定しています。サーバーのビルドにはネットワークアクセス、Go の依存関係用のディスク容量、数分のコンパイル時間が必要です。
書き込み可能なディレクトリから始めてください。次のブロックは新しい
minio-curl-demo ディレクトリを作成し、専用の SDK をインストールします。同名のディレクトリが存在する場合は処理を拒否します。ロックファイルにより、独立した Yarn プロジェクトになります。パッケージとキャッシュの設定によって、インストール先をそのディレクトリ内に限定します。親シェルの作業ディレクトリは変わりません。
(
mkdir minio-curl-demo &&
cd minio-curl-demo &&
printf '%s\n' '{"name":"minio-curl-demo","private":true,"packageManager":"yarn@4.12.0","dependencies":{"minio":"8.0.7"}}' > package.json &&
touch yarn.lock &&
printf 'nodeLinker: node-modules\nenableGlobalCache: false\n' > .yarnrc.yml &&
env COREPACK_HOME="$PWD/.corepack" YARN_IGNORE_PATH=1 \
YARN_GLOBAL_FOLDER="$PWD/.yarn/global" corepack yarn install
)
初期設定
固定バージョンのサーバーソースをビルドし、デモの bin ディレクトリに配置します。前のブロックと同じ親ディレクトリから実行してください。コンパイルに失敗した場合は、ここで中止してください。以前のビルドで残ったバイナリを起動しないでください。
(
cd minio-curl-demo &&
mkdir bin data certs go-path go-cache tmp &&
env GOENV=off GOWORK=off GOTOOLCHAIN=local \
GOPATH="$PWD/go-path" GOCACHE="$PWD/go-cache" GOTMPDIR="$PWD/tmp" \
GOBIN="$PWD/bin" go install github.com/minio/minio@RELEASE.2025-10-15T17-29-55Z
)
その親ディレクトリで Bash ターミナルを二つ開き、両方に以下の設定を貼り付けてください。ポートが使用中の場合は、未使用のポートを二つ選び、両方のターミナルで同じ値を使ってください。認証情報は意図的に公開したデモ用の値です。ループバック接続のみのこのサーバーでだけ使用してください。
export MINIO_API_PORT=19000
export MINIO_CONSOLE_PORT=19001
export MINIO_ENDPOINT="http://127.0.0.1:${MINIO_API_PORT}"
export MINIO_ACCESS_KEY='curl-demo-admin'
export MINIO_SECRET_KEY='local-demo-only-password'
最初のターミナルで、サーバーをフォアグラウンドで起動します。二つ目のターミナルを使う間も、サーバーを実行したままにしてください。終了時は最初のターミナルで Ctrl+C を押して停止します。シェルは継続し、オブジェクトは minio-curl-demo/data に残ります。証明書ディレクトリを明示することで、この HTTP デモがホームディレクトリ内の証明書に依存しないようにしています。
(
cd minio-curl-demo &&
MINIO_ROOT_USER="$MINIO_ACCESS_KEY" MINIO_ROOT_PASSWORD="$MINIO_SECRET_KEY" \
./bin/minio server ./data --address "127.0.0.1:${MINIO_API_PORT}" \
--console-address "127.0.0.1:${MINIO_CONSOLE_PORT}" --certs-dir ./certs
)
バケットと署名処理の作成
以下の TypeScript ファイルをそれぞれ minio-curl-demo 内に保存してください。共通クライアントは、エンドポイントがパスプレフィックスや埋め込みの認証情報を含まないオリジンであることを検証します。リージョンはこのローカルサーバーに合わせています。既存のデプロイでは、実際のリージョンとバケットにスコープを限定した認証情報を使用してください。ここで使うルート認証情報は、非公開デモのプロビジョニング専用です。
minio-client.mts として保存してください。
import { Client } from 'minio'
export function createClient(): Client {
const { MINIO_ENDPOINT, MINIO_ACCESS_KEY, MINIO_SECRET_KEY } = process.env
if (!MINIO_ENDPOINT || !MINIO_ACCESS_KEY || !MINIO_SECRET_KEY) {
throw new Error('Set the endpoint and credentials')
}
const endpoint = new URL(MINIO_ENDPOINT)
if (!['http:', 'https:'].includes(endpoint.protocol) || endpoint.username ||
endpoint.password || endpoint.pathname !== '/' || endpoint.search || endpoint.hash) {
throw new Error('Use an HTTP or HTTPS origin without credentials or a path prefix')
}
return new Client({
endPoint: endpoint.hostname,
port: Number(endpoint.port || (endpoint.protocol === 'https:' ? 443 : 80)),
useSSL: endpoint.protocol === 'https:',
accessKey: MINIO_ACCESS_KEY,
secretKey: MINIO_SECRET_KEY,
region: 'us-east-1',
})
}
prepare-bucket.mts として保存してください。URL に署名するだけではバケットは作成されません。この処理で作成します。
import { createClient } from './minio-client.mts'
async function main(): Promise<void> {
const [bucket, ...extra] = process.argv.slice(2)
if (!bucket || extra.length) throw new Error('Usage: node prepare-bucket.mts BUCKET')
const client = createClient()
if (!(await client.bucketExists(bucket))) await client.makeBucket(bucket, 'us-east-1')
console.log(`Bucket ready: ${bucket}`)
}
main().catch(() => {
console.error('Bucket setup failed; check the server, credentials, and bucket name')
process.exitCode = 1
})
二つ目のターミナルでバケットを作成します。成功すると Bucket ready: curl-demo と表示されます。サーバーの準備ができていない場合は、起動メッセージを待ってからコマンドを再実行してください。
(cd minio-curl-demo && node prepare-bucket.mts curl-demo)
署名付き URL の生成
presign.mts として保存してください。PUT または GET に署名し、cURL の設定行を出力します。アップロードと検証のコマンドは、この設定行を標準入力経由で渡します。どちらの操作も有効期限は600秒です。SDK API リファレンスに、これら二つの異なるメソッドが記載されています。
import { createClient } from './minio-client.mts'
async function main(): Promise<void> {
const [method, bucket, key, ...extra] = process.argv.slice(2)
if (!bucket || !key || extra.length || !['put', 'get'].includes(method ?? '')) {
throw new Error('Usage: node presign.mts put|get BUCKET KEY')
}
const client = createClient()
const url = method === 'put'
? await client.presignedPutObject(bucket, key, 600)
: await client.presignedGetObject(bucket, key, 600)
console.log(`url = ${JSON.stringify(url)}`)
}
main().catch(() => {
console.error('Signing failed; check the method, bucket, key, endpoint, and credentials')
process.exitCode = 1
})
記録されるターミナルでは、署名処理を単独で実行しないでください。出力に署名付き URL が含まれます。SDK がオブジェクトキーをエンコードします。元のキーを署名処理に渡し、生成された URL のホスト、ポート、パス、クエリ文字列を変更しないでください。
ファイルのアップロードと結果の記録
デモディレクトリ内に upload.sh として保存してください。Bash で実行し、source で読み込まないでください。通常のローカルファイル、バケット、明示的なオブジェクトキーを受け取ります。空のファイルも有効です。- や -report.bin のようなファイル名には
./ を付け、cURL の標準入力ではなくファイルとして識別されるようにしてください。
#!/usr/bin/env bash
set -euo pipefail
if [ "$#" -ne 3 ] || [ ! -f "$1" ] || [ ! -r "$1" ] || [ "$1" = '-' ]; then
printf 'Usage: bash upload.sh FILE BUCKET KEY (readable regular file)\n' >&2
exit 1
fi
file=$1
bucket=$2
key=$3
configuration=$(node presign.mts put "$bucket" "$key") || exit 1
if printf '%s\n' "$configuration" |
curl -q --config - --globoff --path-as-is --fail --silent \
--connect-timeout 5 --max-time 120 --upload-file "$file" \
--output /dev/null --write-out 'HTTP %{http_code}\n' 2>/dev/null |
tee -a upload.log; then
printf 'Uploaded %s to %s/%s\n' "$file" "$bucket" "$key"
else
printf 'Upload or status logging failed for %s; verify the object before retrying\n' "$file" >&2
exit 1
fi
cURL の最初のオプションを -q にすることで、呼び出し元の
.curlrc を無視します。--config - は標準入力から URL を読み込み、cURL のプロセス引数に URL が残らないようにします。--globoff はファイル名の角括弧と波括弧をリテラルとして扱います。--fail は
HTTP で拒否された転送を失敗とし、pipefail は転送やログ記録の失敗をパイプライン経由でも保持します。代入処理では署名処理の成否を個別に確認します。スクリプトは転送の生の診断情報を抑制し、レスポンス本文や URL ではなく HTTP ステータスだけを記録します。設定構文とオプションについては、cURL マニュアルを参照してください。
二つ目のターミナルで、親ディレクトリから次を実行してください。ローカルのデモファイル sample.txt を作成または置換し、スペースとプラス記号を含むキーでアップロードします。
(
cd minio-curl-demo &&
printf 'hello, MinIO\n' > sample.txt &&
bash upload.sh sample.txt curl-demo 'exports/sample + 1.txt'
)
HTTP 200 に続いて Uploaded sample.txt to curl-demo/exports/sample + 1.txt と表示されることを確認してください。バケットではバージョニングが無効です。既存のキーへの PUT が成功すると、以前のバイト列が置き換わります。古いオブジェクトを保持する場合は、新しいキーを選んでください。URL の期限切れ、署名の不正、バケットの不在の場合は、Uploaded メッセージを表示せずに失敗する必要があります。
保存されたバイト列のダウンロードと比較
HTTP 200 は、サーバーが PUT を受け付けたことを示します。保存されたオブジェクトは、署名付き GET で別途確認してください。このブロックは downloaded.txt に書き込み、ダウンロードが進むと既存のローカルファイルを置き換えてから、sample.txt と比較します。比較に成功すると Verified identical bytes と表示されます。
(
set -euo pipefail
cd minio-curl-demo || exit 1
configuration=$(node presign.mts get curl-demo 'exports/sample + 1.txt') || exit 1
if printf '%s\n' "$configuration" |
curl -q --config - --globoff --path-as-is --fail --silent \
--connect-timeout 5 --max-time 120 --output downloaded.txt 2>/dev/null; then
cmp sample.txt downloaded.txt && printf 'Verified identical bytes\n'
else
printf 'Download failed; check the object and signing configuration\n' >&2
exit 1
fi
)
アップロード失敗の診断
署名に失敗する場合は、環境設定とスクリプトの三つの引数をすべて確認してください。https://storage.example.com/minio/ のようにプロキシのパスプレフィックスを含むエンドポイントは拒否されます。サービスの S3 API のオリジンを使用し、リモートエンドポイントには HTTPS を使用してください。
HTTP 000 は、HTTP レスポンスを取得できなかったことを意味します。設定したポートでサーバーが動作していること、ファイルを読み取れること、証明書が信頼されていることを確認してください。リモートへのアップロードを成功させるために証明書検証を無効にしないでください。HTTP 403 は、署名の不正や期限切れ、認証情報の誤り、権限の拒否、時計の不一致を示す場合があります。HTTP 404 はバケットの不在を示す場合があります。署名処理は、存在しないバケットの URL も生成できます。
ログ記録の失敗は、サーバーがオブジェクトを保存した後にも発生し得ます。たとえば、upload.log がディレクトリだったり、書き込み不可だったりする場合です。スクリプトはステータスを記録できなかったため失敗を報告します。再試行するか判断する前に GET で確認してください。クライアントが切断された場合も、結果が不明なままになることがあります。同じキーを再利用すると、すでに受け付けられたオブジェクトを置き換える可能性があります。
次の手順の選択
このスクリプトは、転送の制限時間を120秒として、単一のファイルを単一の PUT で送信します。マルチパートアップロード、再開可能な転送、ディレクトリ同期は実装していません。これらの処理には必要な動作を備えた SDK やストレージクライアントを使い、置換ポリシーを確認してください。AWS 固有のバッチワークフローについては、cURL と AWS CLI による Amazon S3 へのバッチエクスポートを参照してください。
ご自身での運用は避けたいですか?
Transloadit は、単一の API 呼び出し内の処理の一環として、S3、Azure、Google Cloud などにファイルをエクスポートします。
