Node.js でファイルを Amazon S3 にエクスポートする完全ガイド
単一アップロードには PutObjectCommand、マルチパートアップロードには
@aws-sdk/lib-storage の Upload を使用します。以下の CLI はローカルファイルを Amazon S3 にエクスポートし、生成されたオブジェクトをダウンロードして、SHA-256、サイズ、メタデータを検証してから成功を報告します。どちらのアップロード方法でも、アップロードまたは検証が失敗すると、失敗を示す終了ステータスを返します。
前提条件
Linux 上の Bash、Node.js、別途インストールした Corepack、既存の非公開の汎用 S3 バケットが必要です。この例は Node.js 24.21.0 と 26.8.1、Corepack 0.36.0、Yarn 4.12.0、AWS SDK パッケージ 3.1149.0 でテストしています。メンテナンス中の Node.js 24 LTS または 26 リリースを使用してください。これらはテスト済みのバージョンであり、SDK 自体の最小要件ではありません。Node.js 26 には Corepack が同梱されていません。
通常のローカルファイルを使用し、検証が終わるまで内容を変更しないでください。CLI の呼び出し時にはパスを引用符で囲んでください。空白、リテラルのパーセント記号、補助 Unicode 文字に対応しています。Unicode 置換文字 U+FFFD を含むパスは、その文字を正当に含むファイル名であっても拒否されます。Node.js はネイティブ引数の不正なバイト列をこの文字に置換することがあり、異なる二つのファイル名を区別できなくなるためです。このようなファイルは、この CLI を使う前に名前を変更してください。
所有するプレフィックス内で未使用のオブジェクトキーを選んでください。この例では既存のオブジェクトの置き換えを拒否します。認証情報には、アップロード用の s3:PutObject、検証用の s3:GetObject、マルチパート処理の失敗後のクリーンアップ用の s3:AbortMultipartUpload が必要です。
AWS 認証情報の設定
SDK はデフォルトの認証情報プロバイダーチェーンを使用します。ローカルでは既存の認証済み AWS プロファイルを、AWS 上では IAM ロールを使用してください。一時的な環境認証情報も使用できます。その場合、アクセスキーとシークレットキーに加えて
AWS_SESSION_TOKEN が必要です。認証情報をプログラムに埋め込んだり、プロジェクトと一緒にコミットしたりしないでください。
以下のコマンドは、バケットのリージョンを AWS_REGION から読み取ります。名前付き共有プロファイルを使う場合は、コマンドを実行するシェルで
AWS_PROFILE を設定してください。認証情報の有効期限が切れた場合は、通常の認証手順で更新してから再試行してください。この例ではバケットの作成や IAM の設定は行いません。
AWS SDK のインストールと使用方法
新しい s3-export プロジェクトを作成するディレクトリで、このブロックを貼り付けてください。ファイルを作成する前に各実行可能ファイルを確認し、サブシェルで実行するため、呼び出し元のディレクトリとオプションは変更されません。s3-export ディレクトリが既に存在する場合は、ファイルを上書きする前にセットアップを停止します。
(
set -eu
command -v node >/dev/null || { printf 'Install Node.js first.\n' >&2; exit 1; }
command -v corepack >/dev/null || { printf 'Install Corepack first.\n' >&2; exit 1; }
mkdir s3-export
cd s3-export
cat > package.json <<'JSON'
{
"name": "s3-export",
"private": true,
"type": "module",
"packageManager": "yarn@4.12.0",
"dependencies": {
"@aws-sdk/client-s3": "3.1149.0",
"@aws-sdk/lib-storage": "3.1149.0"
}
}
JSON
touch yarn.lock
corepack yarn install
)
ローカルのマニフェストとロックファイルにより、npm や Yarn のプロジェクト内でも、この子プロジェクトには独自のパッケージ境界とモジュール境界が設定されます。ただし、Yarn はホームおよび上位ディレクトリの適用対象となる
.yarnrc.yml 設定を引き続き読み取ります。s3-export で corepack yarn --version を実行し、実際のバージョンが 4.12.0 であることを確認してください。継承した yarnPath、レジストリ、ネットワークのポリシーがインストールを妨げる場合は、プロジェクト所有者とポリシーを調整するか、その設定の影響を受けないディレクトリを使用してください。無断で回避しないでください。
プロジェクト作成後にインストールが失敗した場合は、ファイルを残し、呼び出し元からインストールを再試行してください。
(cd s3-export && corepack yarn install)
以下のプログラム全体を s3-export/export.ts として保存してください。
import { createHash } from 'node:crypto'
import { createReadStream } from 'node:fs'
import { stat } from 'node:fs/promises'
import { Readable } from 'node:stream'
import {
GetObjectCommand,
PutObjectCommand,
S3Client,
S3ServiceException,
type PutObjectCommandInput,
} from '@aws-sdk/client-s3'
import { Upload } from '@aws-sdk/lib-storage'
class ReaderError extends Error {}
async function digest(source: AsyncIterable<Uint8Array>): Promise<{ bytes: number; sha256: string }> {
const hash = createHash('sha256')
let bytes = 0
for await (const chunk of source) {
bytes += chunk.byteLength
hash.update(chunk)
}
return { bytes, sha256: hash.digest('hex') }
}
async function main(): Promise<{ bucket: string; key: string; bytes: number; sha256: string }> {
const [mode, file, bucket, key, ...extra] = process.argv.slice(2)
if (!['put', 'multipart', 'verify'].includes(mode ?? '') || !file || !bucket || !key || extra.length) {
throw new ReaderError('Usage: export.ts put|multipart|verify FILE BUCKET KEY')
}
if (file.includes('\uFFFD')) {
throw new ReaderError('FILE must not contain U+FFFD; rename the file before exporting it.')
}
const region = process.env.AWS_REGION
if (!region) throw new ReaderError('Set AWS_REGION to the bucket’s region.')
const info = await stat(file)
if (!info.isFile()) throw new ReaderError('FILE must be a regular file.')
const expected = await digest(createReadStream(file))
if (expected.bytes !== info.size) throw new ReaderError('The input changed while being read.')
const client = new S3Client({ region, maxAttempts: 1 })
try {
if (mode !== 'verify') {
const body = createReadStream(file)
try {
const params: PutObjectCommandInput = {
Bucket: bucket,
Key: key,
Body: body,
ContentLength: expected.bytes,
ContentType: 'application/octet-stream',
Metadata: { sha256: expected.sha256 },
ServerSideEncryption: 'AES256',
IfNoneMatch: '*',
}
if (mode === 'put') {
await client.send(new PutObjectCommand(params))
} else {
const upload = new Upload({
client,
params,
queueSize: 2,
leavePartsOnError: false,
})
upload.on('httpUploadProgress', ({ loaded, total }) => {
console.error(`Transferred ${loaded ?? 0}/${total ?? expected.bytes} bytes`)
})
await upload.done()
}
} finally {
body.destroy()
}
}
const stored = await client.send(new GetObjectCommand({ Bucket: bucket, Key: key }))
if (!(stored.Body instanceof Readable)) throw new ReaderError('No readable S3 response body.')
const actual = await digest(stored.Body)
if (
actual.bytes !== expected.bytes ||
actual.sha256 !== expected.sha256 ||
stored.ContentLength !== expected.bytes ||
stored.Metadata?.sha256 !== expected.sha256 ||
stored.ContentType !== 'application/octet-stream' ||
stored.ServerSideEncryption !== 'AES256'
) {
throw new ReaderError('Stored bytes or metadata do not match the input.')
}
return { bucket, key, ...actual }
} finally {
client.destroy()
}
}
main()
.then((outcome) => console.log(JSON.stringify(outcome)))
.catch((error: unknown) => {
if (error instanceof ReaderError) {
console.error(error.message)
} else {
const reason = error instanceof S3ServiceException ? error.name : 'LocalError'
console.error(`Export failed (${reason}). Check the file, region, credentials, and permissions.`)
}
process.exitCode = 1
})
s3-export があるディレクトリで、以下を実行してください。リージョン、バケット、キーは実際の保存先に置き換えてください。最初の貼り付けで sample.txt を作成し、アップロードを実行します。そのローカルファイルが既に存在する場合、Bash は上書きを拒否します。ブロックはゼロ以外の終了コードで終了し、既存の内容を保持してアップロードコマンドをスキップします。
(
cd s3-export &&
(set -C; printf 'S3 export example\n' > sample.txt) &&
AWS_REGION=us-east-1 corepack yarn node export.ts put sample.txt YOUR_BUCKET exports/sample.txt
)
既存のサンプルを新しいキーにアップロードするには、s3-export でブロック内の最後のコマンドだけを実行し、exports/sample.txt を未使用のキーに置き換えてください。以前のアップロードが成功した可能性がある場合は、まず
verify コマンドで、再アップロードせずに元のキーを調べてください。
実行が成功すると、正確なバケット、キー、バイト数、SHA-256 を含む JSON を出力します。検証ではそのキーからオブジェクトを読み戻します。ETag やアップロードのレスポンスをローカルファイルのチェックサムとして扱うことはありません。ダウンロードには追加のリクエスト料金がかかり、すべてのバイトを再度読み取ります。
マルチパートアップロードによる大容量ファイルの処理
マルチパートヘルパーは、ストリームをバッファーに格納するパートに分割します。長さが既知の入力では、パート数の上限を考慮して、少なくとも 5 MiB のパートサイズを選択します。queueSize: 2 は同時に二つのパートをアップロードできます。ファイル全体をメモリに読み込むわけではありません。空のファイルを含む小さな入力には、代わりに単一の PUT を使用します。
同じプログラムを使用し、put を
multipart に置き換えてください。
(
cd s3-export &&
AWS_REGION=us-east-1 corepack yarn node export.ts multipart /path/to/large-file.zip YOUR_BUCKET exports/large-file.zip
)
進捗は stderr に出力されます。全バイトの転送を示す進捗イベントでも、完了を意味しません。プログラムは upload.done() を待機してから、保存されたオブジェクトを検証します。leavePartsOnError: false は、パートのアップロードが失敗した後にアップロードを中止するようヘルパーに要求します。この固定バージョンでは、キーの衝突を含む
CompleteMultipartUpload
のエラーが発生すると、未完了のアップロードが残ります。バケット所有者に、そのアップロードの調査と中止を依頼してください。プロセスの終了によってもパートが残ることがあります。
S3 は単一の PUT で最大 5 GB、マルチパートアップロードで最大 50 TB を許容しますが、JavaScript ヘルパーとその最大パート数だけでは、サービスのすべての最大サイズへの対応が確認できるわけではありません。5 TB を超えるオブジェクトについては、AWS のアップロードガイドで、Java、Python、または AWS CLI の S3 Transfer Manager を使用するよう案内されています。このチュートリアルでは小さなテストデータで単一アップロードとマルチパートアップロードの動作を検証します。50 TB の転送手順ではありません。
セキュリティのベストプラクティス
バケットを非公開に保ち、アクセス範囲を対象のプレフィックスに限定してください。このプログラムのアップロード、検証、およびヘルパーのマルチパート中止操作については、管理者がバケットとプレフィックスを置き換えて、次のオブジェクトレベルのポリシーを付与できます。
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["s3:PutObject", "s3:GetObject", "s3:AbortMultipartUpload"],
"Resource": "arn:aws:s3:::YOUR_BUCKET/exports/*"
}
]
}
これらの権限は、マルチパート操作の要件と
GetObject の要件に従っています。ただし、バケットポリシーによってリクエストが拒否されることはあります。プログラムは HTTPS を使用し、AES256 で
S3 管理の暗号化を明示的に要求します。公開 ACL は要求しません。SSE-KMS を必須とするバケットには、別の暗号化設定と適切な KMS 権限が必要です。この例に広範な権限を追加するのではなく、そのバケットのポリシーに従ってください。
エラー処理と再試行
IfNoneMatch: '*' 条件は、アップロードの最終書き込み時に既存のキーを拒否します。衝突すると失敗を返し、既存のオブジェクトを保持します。他者のデータを削除せず、新しいキーを使用してください。どちらのアップロードモードでも、認証情報が拒否された場合や、指定したファイルが存在しない場合は失敗します。
maxAttempts: 1 は、SDK の各リクエストの試行回数を一回に設定します。この回数には最初のリクエストも含まれるため、値を増やすと再試行が許可されます。単一 PUT で消費されたストリームは、そのまま再送できません。マルチパートヘルパーはパートをバッファーに保持するため、SDK はそのパートのリクエストを再試行できます。CLI 全体を再試行すると、新しいストリームを開きます。アップロードが失敗しても保存結果が不確かなことがあり、アップロード成功後に検証が失敗することもあります。再試行する前に、そのキーを正確に指定して調べてください。再アップロードせずに検証するには、次を実行してください。
(
cd s3-export &&
AWS_REGION=us-east-1 corepack yarn node export.ts verify sample.txt YOUR_BUCKET exports/sample.txt
)
このコマンドは現在のローカルファイルとバイト列およびメタデータを照合し、一致しない場合はゼロ以外の終了コードで終了します。一致しないオブジェクトの削除や、完了したアップロードのロールバックは行いません。
TypeScript のサポート
Node.js はネイティブの型除去でこのファイルを実行します。セットアップでは "type": "module" を宣言し、corepack yarn node が Plug’n’Play プロジェクトを含め、Yarn の依存関係ローダーを提供します。tsx、ts-node、コンパイル手順は不要です。ネイティブ実行では型チェックを行いません。PutObjectCommandInput はエディターによるリクエストフィールドのチェックを支援し、実行時のチェックでは引数と保存結果を引き続き検証します。
まとめ
出力された JSON を、アップロードと検証が完了した結果として使用し、失敗の原因を調査できるよう stderr も参照できる状態にしてください。エクスポートが、より広いファイル処理ワークフローの一部であれば、当社のサービスをご覧ください。
ご自身での運用は避けたいですか?
Transloadit は、単一の API 呼び出し内の処理の一環として、S3、Azure、Google Cloud などにファイルをエクスポートします。
