S3 基礎(put/get/delete/list)

Lambda+S3はAWSサーバレスで頻繁に利用される。
文字列・CSV・JSON・バイナリ・設定ファイル...S3に配置して処理する。

ただし、boto3のS3APIは”つまずきポイント”多数あり、理解していないとデータ破損、ファイル取得ミス、prefix違いの事故が起きます。

1.ファイルアップロード（put_object）

➤サンプル

s3 = boto3.client("s3")

def put_text(bucket: str, key: str, text: str):
    s3.put_object(
        Bucket=bucket,
        Key=key,
        Body=text.encode("utf-8"),
        ContentType="text/plain",
    )

ポイント

Bodyはstrではなくbytes
文字コードは必ずUTF-8指定（事故防止）
ContentTypeを指定しないとブラウザがご解釈することも
→ PythonはstrをそのままS3に送れない。暗黙的に変換して送るため、想定外の挙動のならないため明示的に送ってあげる必要がある。またS3はバイナリストレージのため人が見てわかるようContentTypeを設定してあげる。

アンチパターン：文字列をそのまま入れる

s3.put_object(Bucket=b, Key=k, Body="hello")

python内部で勝手にencodeing　→　AWS側の仕様変更で壊れる可能性が潜む

2.テキストファイル読み込み（get_object）

➤サンプル

def get_text(bucket, key) -> str:
    resp = s3.get_object(Bucket=bucket, Key=key)
    return resp["Body"].read().decode("utf-8")

==============================================
import gzip

def get_text(bucket, key) -> str:
    resp = s3.get_object(Bucket=bucket, Key=key)
    raw = resp["Body"].read()

    if resp.get("ContentEncoding") == "gzip":
        raw = gzip.decompress(raw)

    return raw.decode("utf-8")

ポイント

BodyはStreamingBodyという型でファイルの中身を持っているわけではなく、データを少しずつ読みだせ、一気にメモリに載せない。取り出すにはread()で取り出す
decodeしないとStreamingBody.read() の結果は必ず bytes
レスポンスがgzip圧縮されてる場合にはdecodeの前に解凍が必要

アンチパターン：Bodyをそのまま返す

content = resp["Body"]

この場合、この処理時点ではエラーも出ず、テキスト、Jsonなど期待した結果は入っておらず
StreamingBodyのオブジェクトが入っているだけで取り出したファイルを処理する際エラーとなる。

3.JSON読み書き

JSON 保存

import json

def put_json(bucket, key, obj):
    s3.put_object(
        Bucket=bucket,
        Key=key,
        Body=json.dumps(obj).encode("utf-8"),
        ContentType="application/json",
    )

JSON 読み込み

def get_json(bucket, key):
    resp = s3.get_object(Bucket=bucket, Key=key)
    text = resp["Body"].read().decode("utf-8")
    return json.loads(text)

アンチパターン：json.loads()にbytesを直接渡す

data = json.loads(resp["Body"].read())

pythonはbytes → JSONパースできない

json.loadsって
JSON形式の文字列（str）を、Pythonの辞書・リストに変換する関数。
例：'{"a": 1}' → {"a": 1}

S3 の「なんちゃってフォルダ構造」

S3はフォルダがないオブジェクトストレージ
見た目は階層的だが、中身はただのキー名

その結果実装で様々な事故に...

prefixが曖昧で関係ないファイルまでヒット
listが最大1000件までしか返さない
フォルダのつもりで末尾 / の扱いをミスる

1.基本 list_objets_v2（最大1000件まで）

resp = s3.list_objects_v2(Bucket=bucket, Prefix=prefix)
contents = resp.get("Contents", [])

ポイント

Contentsが0件の時S3はキー自体を返さないためKeyErrorになる
→ 対策： .get("Contents", []) は実務必須の安全策。
S3 の LIST API は最大 1000 件までしか返さない
→ 対策： 1000 件超は NextContinuationToken を使って繰り返し取得

2. 1000件を超える場合（必須：ContinuationToken）

def list_all(bucket, prefix):
    token = None
    keys = []

    while True:
        params = {"Bucket": bucket, "Prefix": prefix}
        if token:
            params["ContinuationToken"] = token

        resp = s3.list_objects_v2(**params)

        for obj in resp.get("Contents", []):
            keys.append(obj["Key"])

        if resp.get("IsTruncated"):  # まだ続きがある
            token = resp.get("NextContinuationToken")
        else:
            break

    return keys

やってることざっくり

paramsの初期化
S3に渡すパラメータを作る。
s3.list_objects_v2(**params)
prefixに一致する最大1000件のリストが返る。
.get("Contents", [])
prefixに一致するオブジェクトが0件の時Contensキーを返さない
if resp.get("IsTruncated")
IsTruncatedはbool型（True / False）で返ってくる
Trueで1000件以上あり、レスポンスが途中まで、False＝これで全部

prefixはフォルダっぽい検索だけど、S3はあくまで文字列の一致

アンチパターン：# Prefixのファイル全部取りたい！！

resp = s3.list_objects_v2(Bucket=b, Prefix=p)
keys = [c["Key"] for c in resp["Contents"]]

1000件以上あると永遠に残りが取れない

Prefixの罠

何度も書いているが、S3のフォルダは実態ではなく「ただのキー名の一部」

dir1/file1.txt
dir1/file2.txt
dir10/file3.txt
こんな感じの時prefixを"dir1"で検索するとdir10までヒットしてしまう。

1.末尾スラッシュ（"/"）これ絶対

正しい例

prefix = "dir1/"

まずい例：

prefix = "dir1"

こうすることでdir1に絞りdir10,dir100がヒットしない。

2.「/」位置ずれ

S3内のキー：data/2025/...というのがあるとして

date = "2025/"
prefix = f"data/{date} # NG
prefix = f"data/{date}/ # OK

この場合NGパターンは一切ヒットしない。
OKパターンのようにすることで必ずフォルダ風の prefix になる

S3はホントに「キー文字列一致」の世界で
1文字ズレただけで見つからない or 取りすぎの事故発生

3.S3でフォルダを作る方法

AWSのコンソールでフォルダ作成から「my-dir」を作成してみる

ん？フォルダの概念はないのでは
実態は、ただのキー（文字列）であったフォルダではない。
フォルダを表現するための0バイトオブジェクト

なぜ知っておく必要があるか
狙った操作が正確に行えず事故の原因となってしまう可能性があるので知識として