Boto3 で Amazon S3 にファイルをアップロード
Boto3 の upload_file() を使い、既存の非公開 S3 バケットにローカルファイルを送信します。この手順では、送信先を明示的に指定し、アップロードの完了を待ち、ファイルや転送に問題があれば失敗ステータスで終了するコマンドを作成します。認証情報とバケットの権限は AWS の設定で管理します。
Boto3 のマネージドアップロードは、大きなファイルのマルチパート転送を処理します。ファイル名、バケット名、オブジェクトキーを指定するだけで、ファイルを自分で分割する必要はありません。
環境の準備
以下のコマンドは Linux 上で Bash と Python 3.12、venv、pip を使用します。この例で使用する Boto3 は 1.43.100 です。実行前に、以下を用意してください。
- 既存の非公開の汎用 S3 バケット、その AWS リージョン、および書き込み可能なプレフィックス(例:
incoming/)。S3 Block Public Access は有効のままにしてください。 - 認証済みの AWS プロファイル。ワークステーションでは、IAM Identity Center プロファイルなど、組織の一時認証情報を使用してください。先にその設定を完了してください。
uploadsという既存のプロファイルでは、AWS CLI v2 でaws sso login --profile uploadsを実行してセッションを更新します。スクリプトにアクセスキーを記述しないでください。 - 送信先オブジェクト(例:
arn:aws:s3:::your-bucket-name/incoming/*)に対してs3:PutObjectを実行する権限。失敗したマルチパートアップロードをクリーンアップできるよう、同じスコープでs3:AbortMultipartUploadも許可してください。AWS のマルチパート転送の権限を参照してください。このスクリプトはオブジェクトの一覧取得やダウンロードを行わないため、s3:ListBucketとs3:GetObjectは不要です。
新しいディレクトリと、分離された Python 環境を作成します。&& で連結したコマンドは、途中の処理が失敗すると停止します。boto3-upload がすでに存在する場合は、別のディレクトリ名を選んでから進めてください。
mkdir boto3-upload &&
cd boto3-upload &&
python3 -m venv .venv &&
.venv/bin/python -m pip install 'boto3==1.43.100'
インストールが成功したら、boto3-upload 内で作業を続けます。以下のコマンドはプロファイル uploads と
us-east-1 を前提としています。使用するプロファイルとバケットのリージョンに置き換えてください。Boto3 の認証情報チェーンでは、AWS 上でアタッチされた IAM ロールも使用できます。その環境では、ワークステーションの認証情報をサーバーにコピーせず、AWS_PROFILE を省略してください。環境変数の認証情報はプロファイルより優先される場合があります。Boto3 が意図しない ID を選択する場合は、シェルに残っている古い認証情報の上書き設定を削除してください。
アップロードコマンドの保存
以下のプログラム全体を、新しいディレクトリに upload.py として保存します。このプログラムは空のファイルを含む単一の通常ファイルを受け付けます。存在しないパスやディレクトリは、S3 クライアントを作成する前に拒否します。
import argparse
import sys
from pathlib import Path
import boto3
from boto3.exceptions import S3UploadFailedError
from botocore.exceptions import BotoCoreError, ClientError
def main():
parser = argparse.ArgumentParser(description="Upload one file to S3.")
parser.add_argument("file", type=Path, help="Local file to upload")
parser.add_argument("bucket", help="Existing S3 bucket name")
parser.add_argument("key", help="Full destination object key")
args = parser.parse_args()
if not args.bucket or not args.key:
parser.error("bucket and key must not be empty")
try:
if not args.file.is_file():
parser.error("file must be an existing regular file")
s3 = boto3.client("s3")
s3.upload_file(str(args.file), args.bucket, args.key)
except (S3UploadFailedError, BotoCoreError, ClientError, OSError) as error:
print(f"Upload failed ({type(error).__name__}).", file=sys.stderr)
return 1
print(f"Uploaded to s3://{args.bucket}/{args.key}")
return 0
if __name__ == "__main__":
sys.exit(main())
アップロードの実装は、成功時に
None を返し、失敗時に例外を送出します。戻り値の真偽で成功を判定しないでください。このプログラムは呼び出しの完了後にのみ成功を表示し、マネージド転送の失敗と、低レベルの SDK エラーやファイルシステムエラーの両方を捕捉します。サービスレスポンス全体を出力せず、例外の型を報告します。
クライアントはデフォルトで証明書検証付きの HTTPS を使用します。AWS ではこのデフォルトを維持し、ローカルテストで使った独自のエンドポイント設定が残っていれば削除してください。保存時の暗号化とアクセス権限は別の設定であり、後述します。
明示的なオブジェクトキーで実行
コマンドを実行する前に、ローカルファイルと送信先を選びます。ここでの ./report.pdf は、boto3-upload に配置する既存のファイルです。別のパスにも置き換えられます。your-bucket-name は、s3:// プレフィックスを付けずに、使用するバケット名に置き換えてください。
AWS_PROFILE=uploads AWS_DEFAULT_REGION=us-east-1 \
.venv/bin/python upload.py './report.pdf' 'your-bucket-name' 'incoming/report.pdf'
キーはバケット内での完全な名前です。S3 はローカルパスからキーを推測したり、incoming/ にファイル名を追加したりしません。空白を含むパスやキーは引用符で囲んでください。ハイフンで始まるローカルファイル名には、./ プレフィックスを付けてください。
上記の送信先では、成功時に以下が出力されます。
Uploaded to s3://your-bucket-name/incoming/report.pdf
このコマンドを再実行すると、確認なしで同じキーに再度書き込みます。バージョニングが無効のバケットでは、既存のオブジェクトを置き換えます。バージョニングが有効の場合、S3 は新しいバージョンを保存します。アップロードを個別に保持する必要がある場合は、別のキーを使用してください。AWS の上書きとバージョニングの動作を参照してください。
スケジューラーや別のスクリプトから使う場合は、プロセスの終了ステータスで判定します。0 はアップロード完了、1 は捕捉されたアップロード失敗、2 は引数の不正、または入力が存在しないかファイルではないことを示します。ローカルファイルはそのまま残ります。S3 がリクエストを受け付けた後にレスポンスが失われた場合、接続障害によってリモート側の結果が不明になることがあります。バージョンの重複が問題になる場合は、再試行前に送信先を確認してください。アップロード中は元のファイルを変更しないでください。
バケットの暗号化設定の使用
Amazon S3 は、新しいオブジェクトをすべて保存時に暗号化します。バケットの初期デフォルトは AES256 を使用する SSE-S3 で、暗号化の追加料金はありません。管理者は SSE-KMS など、別のデフォルトを選択できます。このプログラムは暗号化の上書き設定を送信しないため、S3 はバケットに設定されたデフォルトを使用します。
SSE-KMS では、アップロードを行う ID に、そのキーに対する
kms:GenerateDataKey 権限が必要です。マルチパートアップロードでは
kms:Decrypt も必要です。キーはバケットと同じリージョンに配置し、キーポリシーで意図した用途を許可する必要があります。これらの KMS の権限と要件は AWS のドキュメントに記載されています。明示的な暗号化ヘッダーを要求するバケットポリシーは、バケットのデフォルト暗号化が設定されていても、このスクリプトを拒否する場合があります。この例を使う前に、デフォルト設定によるアップロードが許可されているかバケット所有者に確認してください。アップロードを成功させるためにポリシーを緩めないでください。
バケット所有者によるアクセス制御の維持
ACL を省略しても、任意のバケットが非公開になるわけではありません。先ほど準備した非公開バケットと、権限範囲を限定した ID を使用してください。新しいバケットのデフォルトはバケット所有者強制設定で、ACL は無効になります。このようなバケットへのアップロードに ACL='private' を追加すると、AccessControlListNotSupported が発生する場合があります。AWS の S3 セキュリティガイダンスに従い、ポリシーでアクセスを管理し、Block Public Access を有効のままにしてください。
HTTPS 以外のリクエストを拒否する要件など、バケット全体のルールはバケット所有者に管理してもらってください。アップロード側で、ファイルを送信するたびに新しいバケットポリシーを設定するべきではありません。
アップロード失敗の診断
- 入力不正、ステータス
2: 現在のディレクトリを基準にパスを確認してください。ディレクトリはアップロード可能なファイルではありません。このコマンドは再帰的に処理しません。 NoCredentialsErrorまたはセッションの期限切れ: 意図したプロファイルを選び、ログインを更新してください。対話型シェルでしか動作しない場合は、スケジューラーやサービスに専用の ID が設定されているか確認してください。S3UploadFailedError: バケット名、正確なキープレフィックス、アップロード権限、バケットポリシーによる拒否の有無を所有者と確認してください。SSE-KMS ではキーの権限も確認してください。この例外は複数種類のサービスエラーをラップする場合があり、型だけではアクセス拒否と断定できません。EndpointConnectionErrorまたは別の接続エラー: ネットワーク、リージョン、プロキシ、エンドポイント設定を確認してください。TLS エラーを回避するために証明書検証を無効にしないでください。PermissionErrorまたは別のOSError: プロセスがファイルを読み取れることと、アップロード中にファイルが移動または削除されていないことを確認してください。
Transfer Acceleration、ライフサイクルルール、イベント通知は、それぞれ別のバケット管理上の判断事項です。特に、S3 の通知設定を書き込むと、既存の設定が置き換えられます。Lambda トリガーの追加は、既存の通知先を保持したうえで、レビューを経たインフラ変更として行う必要があります。スケジュール実行するジョブに組み込む前に、意図した ID とプレフィックスで単一ファイルのコマンドが動作することを確認してください。
