curl と AWS CLI による Amazon S3 へのファイル一括エクスポート
小さな AWS SDK 署名プログラムで PUT 用の署名付き URL を生成し、curl で各ファイルを Amazon S3 にアップロードします。以下の Bash スクリプトは、隠しファイルや空のファイルを含め、ディレクトリ直下の通常ファイルをエクスポートします。選択したファイルが一つでも失敗すると、失敗を報告します。AWS CLI は認証情報の確認と独立したダウンロード検証に使います。aws s3 presign 自体が署名するのはダウンロードであり、アップロードではありません。
前提条件
この例は、Bash、GNU stat、file、curl、AWS CLI v2、Corepack がインストールされた Linux を対象とします。Node.js は 24.x 系の 24.15 以降、または Node.js 26.x を使用してください。これは例を実行するための前提条件であり、AWS SDK の最小実行環境要件ではありません。Node はビルド手順なしで TypeScript の署名プログラムを実行します。AWS CLI が未インストールの場合は、インストールガイドに従ってください。
署名プログラムは Node.js 24.15.0、26.0.0、26.5.0、26.8.1 で確認済みです。アップロード全体では AWS SDK 3.1148.0、Yarn 4.12.0、AWS CLI 2.37.10、curl 8.22.0 を使用します。以下の依存関係のバージョン固定は、この構成を再現するためのものです。既存の CLI をダウングレードする必要はありません。
既存の汎用 S3 バケット、そのリージョン、出力先プレフィックスにアクセスできる認証済みの
AWS プロファイルも必要です。組織で既存のログイン手順を使用してください。CLI と SDK はどちらも AWS_PROFILE を参照します。環境変数でセッション認証情報を渡す場合は、AWS_SESSION_TOKEN を含めてください。これらのスクリプトに認証情報を記述しないでください。
署名用の二つの依存関係を持つ独立したプロジェクトを作成します。このブロックはシェルの元のディレクトリを維持し、プロジェクトディレクトリが既存の場合は処理を拒否します。
(
set -euo pipefail
for tool in node corepack aws curl file stat; do
command -v "$tool" >/dev/null || { echo "Missing prerequisite: $tool" >&2; exit 1; }
done
mkdir s3-batch-export
printf '%s\n' '{"private":true,"type":"module","packageManager":"yarn@4.12.0"}' \
> s3-batch-export/package.json
printf 'nodeLinker: node-modules\n' > s3-batch-export/.s3-batch-export.yarnrc.yml
touch s3-batch-export/yarn.lock
cd -- s3-batch-export
YARN_RC_FILENAME=.s3-batch-export.yarnrc.yml corepack yarn add --exact \
@aws-sdk/client-s3@3.1148.0 @aws-sdk/s3-request-presigner@3.1148.0
)
空の yarn.lock により、独立した Yarn プロジェクトになります。指定した設定ファイルにより、上位の .yarnrc.yml ファイルを継承せずにインストールできます。作成後にインストールが失敗した場合は、新しいディレクトリを調べ、その中で同じ YARN_RC_FILENAME=… corepack yarn add コマンドを再実行してください。mkdir の再実行や既存プロジェクトの削除はしないでください。インストールが成功したら、以降の例を実行するためにそのディレクトリに移動します。
cd -- s3-batch-export
構成要素の理解
Amazon S3 はスケーラブルなオブジェクトストアです。pre-signed URL は、実行者に AWS 認証情報を公開せずに、特定の一種類の S3 リクエストを実行する期限付きの権限を付与します。署名の対象は HTTP メソッド、バケットとキー、有効期限、署名対象として選択したヘッダーです。そのため、GET 用に署名した URL を PUT として再利用することはできません。
これは一度限りのトークンではありません。有効期限が切れるまでは URL を再利用でき、PUT が成功すると、そのキーのオブジェクトが置き換えられます。ログ、シェルのトレース、共有するターミナル出力に含めないでください。AWS の署名付きアップロードガイドで、これらの権限と置き換えの動作を説明しています。
AWS CLI の presign コマンドは
GET リクエストを認可します。その出力では curl -T を認可できません。PUT に署名するには、操作を指定できる署名プログラムが必要です。@aws-sdk/s3-request-presignerがその役割を担います。AWS CLI は実行者の ID を確認し、アップロードしたバイト列を取得します。curl は転送を実行します。
必要な IAM 権限の付与
署名自体はローカルで計算するため、URL の生成時には権限が確認されません。重要なのは署名者自身の権限です。署名付き URL が使われるときに、S3 は署名した ID のポリシーを評価するためです。たとえば、次のように出力先に範囲を限定した権限をバケット管理者に依頼してください。
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["s3:PutObject"],
"Resource": "arn:aws:s3:::your-bucket-name/exports/*"
}
]
}
アップロードには s3:PutObject が必要です。後述の独立したダウンロード検証には、そのプレフィックスに対する s3:GetObject も必要です。バケットポリシーや暗号化キーのポリシーによって、追加の要件が課される場合があります。
your-bucket-name を使用するバケットに、exports/ を選択したプレフィックスに置き換えてください。
AWS SDK による PUT 用署名付き URL の生成
次の内容を presign-put.ts として保存します。URL を一つ出力して終了するため、後でシェルのループから簡単に呼び出せます。
// presign-put.ts - print a pre-signed URL that authorizes PUT, and only PUT.
import { parseArgs } from 'node:util'
import { PutObjectCommand, S3Client } from '@aws-sdk/client-s3'
import { getSignedUrl } from '@aws-sdk/s3-request-presigner'
const { values } = parseArgs({
options: {
bucket: { type: 'string' },
key: { type: 'string' },
region: { type: 'string' },
'content-type': { type: 'string', default: 'application/octet-stream' },
'expires-in': { type: 'string', default: '3600' },
},
})
const { bucket, key, region } = values
if (!bucket || !key || !region) {
throw new Error('Usage: node presign-put.ts --bucket B --key K --region R [--content-type T]')
}
const expiresIn = Number(values['expires-in'])
// SigV4 caps a pre-signed URL at 7 days. Reject longer values here rather than
// relying on the SDK's generic expiry error; fractional values are rejected too.
if (!Number.isInteger(expiresIn) || expiresIn < 1 || expiresIn > 604800) {
throw new Error(`--expires-in must be between 1 and 604800 seconds, got: ${values['expires-in']}`)
}
const client = new S3Client({
region,
maxAttempts: 1,
// curl supplies the body later; omit optional checksum metadata here.
requestChecksumCalculation: 'WHEN_REQUIRED',
})
const url = await getSignedUrl(
client,
new PutObjectCommand({ Bucket: bucket, Key: key, ContentType: values['content-type'] }),
{
expiresIn,
// Require the uploader to send the Content-Type used when signing.
signableHeaders: new Set(['content-type']),
},
)
console.log(url)
実行します。
node presign-put.ts \
--bucket your-bucket-name \
--key exports/localfile.txt \
--region your-region \
--content-type text/plain \
--expires-in 3600
バケット、キー、リージョンを実際の値に置き換えてください。URL のクエリ文字列には署名と有効期限が含まれます。シークレットキーは含まれませんが、URL を持つ人は誰でも、有効期限が切れるまで対象の一つのオブジェクトに繰り返し書き込めます。そのため、ログに残さないでください。
--expires-in は上限であり、保証ではありません。IAM ロール、SSO セッション、または sts:AssumeRole の一時認証情報で署名すると、その認証情報が失効した時点で URL は使えなくなります。指定した有効期限よりもかなり早く失効することがよくあります。
生成された URL の X-Amz-SignedHeaders は content-type;host です。これは curl が正確に再現する必要のあるリストです。異なる Content-Type を送信するか、ヘッダーを省略すると、署名は無効になります。SigV4 の有効期限の上限は 7日(604,800秒)です。
curl によるファイルのアップロード
curl の -T フラグで、アップロードするローカルファイルを指定します。--retry を追加すると、一時的なネットワーク障害に強くなります。ここでは Content-Type ヘッダーを省略できません。署名対象のヘッダーなので、署名プログラムに渡した --content-type と一致する必要があります。サブシェルにより、既存の Bash セッションに貼り付けた場合でも、厳格なエラー処理の適用範囲をこの例の中に限定します。
(
set -euo pipefail
CONTENT_TYPE=$(file -b --mime-type -- ./localfile.txt)
# Sign for that exact type, then send that exact type
URL=$(node presign-put.ts \
--bucket your-bucket-name \
--key exports/localfile.txt \
--region your-region \
--content-type "$CONTENT_TYPE")
if status=$(curl --disable -fsS --globoff --retry 3 --retry-delay 2 \
--connect-timeout 10 --max-time 300 --retry-max-time 300 \
-T ./localfile.txt \
-H "Content-Type: $CONTENT_TYPE" \
-o /dev/null -w '%{http_code}' \
"$URL") && [[ "$status" =~ ^2[0-9][0-9]$ ]]; then
echo 'Upload completed.'
else
echo 'Upload failed: expected an HTTP 2xx response.' >&2
exit 1
fi
)
./localfile.txt をファイルパスに、バケットとリージョンを実際の値に置き換えてください。--disable は呼び出し元の .curlrc を無視します。--globoff はファイル名の波括弧と角括弧を文字どおりに扱います。-f により、HTTP エラー時に curl は非ゼロで終了し、成功時のように S3 の XML エラー本文を出力しません。-sS は実際のエラーを表示しつつ、進捗メーターを抑制します。明示的な 2xx の確認では、-f だけではエラー扱いにならないリダイレクトも拒否します。-L は追加しないでください。リダイレクトをたどると署名対象のリクエストが変わります。各試行の制限時間はデータ転送を含めて 300秒なので、正常なファイルでも低速な場合は失敗することがあります。再試行のスケジューリングも 300秒後に停止しますが、開始済みの再試行はさらに 300秒間実行できます。応答が不確かな場合は、再試行する前に出力先を確認してください。これらの転送、再試行、ファイル名のオプションは、curl マニュアルで説明しています。
ファイルの一括エクスポートの自動化
次の内容を batch-export.sh として、presign-put.ts と同じディレクトリに保存します。一度に一つずつファイルを処理し、個別の失敗後も処理を続けます。選択したファイルが一つでも失敗すると、非ゼロで終了します。ディレクトリとシンボリックリンクはスキップし、UTF-8 のファイル名を受け付けます。空のディレクトリは、ファイル数ゼロの成功したバッチとして扱います。実行中は入力ディレクトリを変更しないでください。
#!/usr/bin/env bash
set -euo pipefail # Exit on error, undefined variable, or pipe failure
export LC_ALL=C AWS_MAX_ATTEMPTS=1 AWS_PAGER=""
trap 'echo "Batch interrupted; inspect uploaded objects before retrying." >&2; exit 130' INT
trap 'echo "Batch interrupted; inspect uploaded objects before retrying." >&2; exit 143' TERM
BUCKET="your-bucket-name"
EXPIRE=3600 # URL validity in seconds (1 hour)
FILES_DIR="/path/to/your/files" # Directory containing files to upload
REGION="your-region" # Your S3 bucket region
PRESIGN="./presign-put.ts" # The signer from the previous section
PREFIX="${S3_PREFIX:-exports/}" # Use a separate prefix for this batch
TRANSFER_SECONDS="${S3_TRANSFER_SECONDS:-300}"
# --- pre-flight checks ---
if [[ ! -d "$FILES_DIR" || ! -r "$FILES_DIR" || ! -x "$FILES_DIR" ]]; then
echo "Error: Directory '$FILES_DIR' must exist and be readable/searchable." >&2
exit 1
fi
if [[ ! -f "$PRESIGN" ]]; then
echo "Error: Signer '$PRESIGN' not found. See the previous section." >&2
exit 1
fi
for tool in aws node curl file stat; do
command -v "$tool" >/dev/null || { echo "Missing prerequisite: $tool" >&2; exit 1; }
done
if [[ ! "$TRANSFER_SECONDS" =~ ^[1-9][0-9]*$ ]]; then
echo "Error: S3_TRANSFER_SECONDS must be a positive integer." >&2
exit 1
fi
# Verify the credentials the signer will pick up are present and valid.
if ! caller_arn=$(aws sts get-caller-identity --query Arn --output text 2>/dev/null); then
echo "Error: AWS credentials are not configured properly or are invalid." >&2
echo "Check your selected AWS profile or session credentials." >&2
exit 1
fi
echo "AWS credentials verified for: $caller_arn"
echo "Starting batch export from '$FILES_DIR' to bucket '$BUCKET' in region '$REGION'..."
# --- processing loop ---
failed=0
uploaded=0
# dotglob: a hidden file is an ordinary object to S3, and silently leaving
# .env.example behind is data loss. nullglob: an empty directory must not run
# the loop once with a literal '*'.
shopt -s dotglob nullglob
for file in "$FILES_DIR"/*; do
filename=${file##*/}
# Test for a symlink before -f, which follows them: a link inside FILES_DIR
# would otherwise upload bytes from outside it, under a name from inside it.
if [[ -L "$file" ]]; then
echo " Skipping '$filename': symbolic link."
continue
fi
# Skip directories and anything else that is not a regular file.
[[ -f "$file" ]] || continue
echo "Processing '$filename'..."
# Node's argv decoding is lossy for malformed UTF-8; reject before signing a key.
if ! printf '%s' "$filename" | node --input-type=module -e \
'import { readFileSync } from "node:fs"; new TextDecoder("utf-8", {fatal:true}).decode(readFileSync(0))' \
2>/dev/null; then
echo " Error: Filename is not valid UTF-8." >&2
failed=$((failed + 1))
continue
fi
if [[ ! -r "$file" ]] || ! file_size=$(stat -c%s -- "$file"); then
echo " Error: Cannot read or inspect '$filename'." >&2
failed=$((failed + 1))
continue
fi
# This example limits each single PUT to 5 GiB; use multipart for larger files.
if ((file_size > 5368709120)); then
echo " Skipping '$filename': $((file_size / 1024 / 1024)) MiB exceeds this script’s 5 GiB limit." >&2
echo " Use 'aws s3 cp' instead, which switches to multipart automatically." >&2
failed=$((failed + 1))
continue
fi
if ! content_type=$(file -b --mime-type -- "$file"); then
echo " Error: Cannot determine Content-Type for '$filename'." >&2
failed=$((failed + 1))
continue
fi
echo " Signing a PUT for '$filename' (Content-Type: $content_type)..."
if ! url=$(node "$PRESIGN" \
--bucket "$BUCKET" \
--key "$PREFIX$filename" \
--region "$REGION" \
--content-type "$content_type" \
--expires-in "$EXPIRE"); then
echo " Error: Failed to sign a URL for '$filename'." >&2
failed=$((failed + 1))
continue
fi
echo " Uploading '$filename'..."
# The Content-Type must match the signature. curl -f does not reject redirects;
# require a completed 2xx upload without replaying a signed body at another URL.
if status=$(curl --disable -fsS --globoff --retry 3 --retry-delay 2 \
--connect-timeout 10 --max-time "$TRANSFER_SECONDS" --retry-max-time "$TRANSFER_SECONDS" \
-T "$file" \
-H "Content-Type: $content_type" \
-o /dev/null -w '%{http_code}' \
"$url") && [[ "$status" =~ ^2[0-9][0-9]$ ]]; then
echo " Successfully uploaded '$filename'."
uploaded=$((uploaded + 1))
else
echo " Error: Failed to upload '$filename'." >&2
failed=$((failed + 1))
fi
done
echo "Batch export completed: $uploaded uploaded, $failed failed."
# Surface partial failure to the caller: 'set -e' cannot do this for us, because
# every failure above was deliberately caught so the loop could continue.
if ((failed > 0)); then
exit 1
fi
スクリプト内のバケット、入力ディレクトリ、リージョンを置き換え、このプロジェクトから実行します。
bash batch-export.sh
二つのファイルが成功した場合、サマリーは次のとおりです:Batch export completed: 2 uploaded, 0 failed.
転送に失敗すると、後続のファイルが成功しても失敗件数に加算されます。入力ディレクトリが存在しないか読み取れない場合は、転送開始前に失敗します。S3_PREFIX は exports/ を上書きします。末尾のスラッシュを含めてください。名前に含まれる空白、角括弧、パーセント記号、絵文字、改行は保持されます。不正な UTF-8 の名前は、Node の文字列引数を通して確実に対応付けられないため、失敗として数えます。
このスクリプトはファイルサイズを 5 GiB に制限し、単一アップロードと同じ 300秒の転送・再試行制限を使用します。転送が遅い場合は S3_TRANSFER_SECONDS を大きくしてください。各ファイルの試行回数は、最初のリクエストを含めて最大四回です。再試行ではファイル全体を再送し、中断した PUT を再開するわけではありません。中断された場合、スクリプトは完了サマリーを出力せずに非ゼロを返します。完了済みのオブジェクトは残ります。また、応答が失われてもオブジェクトは確定済みの場合があるため、再実行前にプレフィックスを確認してください。
アップロードは、同じキーを持つ既存のオブジェクトを置き換えます。バッチを分離するには新しいプレフィックスを使用してください。入れ子のディレクトリはフラット化せずにスキップします。バッチを繰り返すと、成功したキーが置き換えられ、無関係なキーは削除されません。
既知のファイルをダウンロードし、バイト列を比較して独立に検証します。次の処理は新しいローカルディレクトリを作成し、既存のファイルは変更しません。
(
set -euo pipefail
command -v cmp >/dev/null || { echo 'Missing prerequisite: cmp' >&2; exit 1; }
mkdir s3-download-check || exit $?
aws s3api get-object --bucket your-bucket-name --key exports/localfile.txt \
--region your-region s3-download-check/localfile.txt >/dev/null || exit $?
cmp -- ./localfile.txt s3-download-check/localfile.txt || exit $?
echo 'Downloaded bytes match.'
)
バッチ全体を検証するときは、想定するすべてのファイルを比較してください。成功件数だけでは、ファイルの欠落や誤ったオブジェクトを検出できません。ダウンロードに失敗した場合は、この検証用の部分的なダウンロードディレクトリだけを調べて削除し、ブロックを再実行してください。
セキュリティのベストプラクティスの適用
署名する ID のアクセス範囲をバッチのプレフィックスに限定し、転送に十分な URL の有効期間を選んでください。一時認証情報は --expires-in より早く失効する場合があると、AWS の署名付き URL ガイドで説明されています。スクリプトはバケットポリシーや暗号化設定を変更しません。カスタマーマネージド KMS キーを使用するバケットでは、アップロード前に、管理者が必要なキーへのアクセス権を付与していることを確認してください。
Content-Type への署名で拘束するのはそのヘッダーであり、ファイルの内容や安全性ではありません。URL を持つ人は誰でも、同じヘッダーで異なるバイト列を送信できます。独立したダウンロード検証は、誤ったオブジェクトをうっかり比較することを防ぎますが、URL にコンテンツ検証ポリシーを持たせるものではありません。
よくある問題のトラブルシューティング
- 認証情報の確認に失敗する: 既存のログインを更新し、
AWS_PROFILEまたはセッションの環境変数を確認してください。aws sts get-caller-identityが成功すると CLI の呼び出し元を特定できますが、S3 が書き込みを許可することの証明にはなりません。署名プログラムも独自に認証情報を解決します。 - アップロードが HTTP 403 を返す: バケットのリージョン、キー、URL の有効期限、署名者の権限、署名対象の正確な
Content-Typeを確認してください。アップロードのブロックは意図的に S3 の応答本文を破棄するため、汎用的な失敗通知だけでは原因を特定できません。診断中も署名付き URL をログに記録しないでください。AWS のアップロードのトラブルシューティングガイドで、これらの確認を説明しています。 - 転送がタイムアウトする: サイズ制限未満の正常なファイルにも制限時間が適用されます。オブジェクトを確認し、適切であれば転送の制限時間を調整して、新しい URL で再実行してください。再試行を増やしても認証エラーは解消しません。
- サイズ超過でファイルがスキップされる: このスクリプトは、単一 PUT の上限を 5 GiB に制限します。それより大きなファイルにはマルチパート対応クライアントを使用してください。
より大きなファイルには、aws s3 cpでマルチパートアップロードを行えます。これは認証情報を使用する別の転送であり、署名付きの curl リクエストではありません。
aws s3 cp ./large_file.zip s3://your-bucket-name/exports/large_file.zip --region your-region
まとめ
最初のファイルエクスポートには新しいプレフィックスを使用し、既知のオブジェクトをダウンロードしてバイト列を確認してください。バッチが完了したと判断する前に、スクリプトの終了ステータスも確認してください。このオープンソースのワークフローは、署名と転送を分離しながら部分的な失敗を可視化します。
すでにファイルを Transloadit で処理している場合は、🤖 /s3/store Robot で、Step の結果を、同じ Assembly 内で S3 にエクスポートできます。
ご自身での運用は避けたいですか?
Transloadit は、単一の API 呼び出し内の処理の一環として、S3、Azure、Google Cloud などにファイルをエクスポートします。
