boto3

開始する前に、Access Key を生成する必要があります。以降の例では、生成した Access Key ID と Secret Access Key の値を表す access_key_id と access_key_secret 変数を使います。

boto3 ↗ を R2 エンドポイント向けに設定します。

import boto3

s3 = boto3.client(
    service_name="s3",
    endpoint_url="https://<ACCOUNT_ID>.r2.cloudflarestorage.com",
    aws_access_key_id="<ACCESS_KEY_ID>",
    aws_secret_access_key="<SECRET_ACCESS_KEY>",
    region_name="auto",
)

AWS_ACCESS_KEY_ID と AWS_SECRET_ACCESS_KEY の環境変数 ↗ を設定していれば、aws_access_key_id と aws_secret_access_key は省略できます。

クライアントでよく使う操作は次のとおりです。

# Get object metadata
s3.head_object(Bucket="my-bucket", Key="dog.png")

# Get object
response = s3.get_object(Bucket="my-bucket", Key="dog.png")

# Upload single file
with open("./dog.png", "rb") as f:
    s3.upload_fileobj(f, "my-bucket", "dog.png")

# Delete object
s3.delete_object(Bucket="my-bucket", Key="dog.png")

アップロード性能の最適化

大きいオブジェクト（学習データや動画のような数 GB のファイル）では、upload_fileobj がスループットのボトルネックになることがあります。内部のスレッドプールは Python の GIL ↗ に制約され、TransferConfig で max_concurrency を上げても、約 10 スレッドを超えると効果が小さくなります。

代わりに、低レベルのマルチパート API と ThreadPoolExecutor を使います。

import boto3
import math
import os
from concurrent.futures import ThreadPoolExecutor

s3 = boto3.client(
    service_name="s3",
    endpoint_url="https://<ACCOUNT_ID>.r2.cloudflarestorage.com",
    aws_access_key_id="<ACCESS_KEY_ID>",
    aws_secret_access_key="<SECRET_ACCESS_KEY>",
    region_name="auto",
)

bucket = "my-bucket"
key = "large-file.bin"
file_path = "./large-file.bin"
part_size = 16 * 1024 * 1024  # 16 MiB per part
max_workers = 10

# Step 1: Create the multipart upload
upload_id = None
mpu = s3.create_multipart_upload(Bucket=bucket, Key=key)
upload_id = mpu["UploadId"]

def upload_part(part_number, data):
    response = s3.upload_part(
        Bucket=bucket,
        Key=key,
        UploadId=upload_id,
        PartNumber=part_number,
        Body=data,
    )
    return {"PartNumber": part_number, "ETag": response["ETag"]}

try:
    file_size = os.path.getsize(file_path)
    part_count = math.ceil(file_size / part_size)

    # Step 2: Upload parts in parallel
    with ThreadPoolExecutor(max_workers=max_workers) as pool:
        futures = []
        with open(file_path, "rb") as f:
            for i in range(part_count):
                data = f.read(part_size)
                futures.append(pool.submit(upload_part, i + 1, data))

        parts = [future.result() for future in futures]

    # Step 3: Complete the upload
    s3.complete_multipart_upload(
        Bucket=bucket,
        Key=key,
        UploadId=upload_id,
        MultipartUpload={"Parts": parts},
    )
    print("Multipart upload complete.")
except Exception:
    if upload_id:
        try:
            s3.abort_multipart_upload(Bucket=bucket, Key=key, UploadId=upload_id)
        except Exception:
            pass
    raise

パートサイズの上限やライフサイクル管理を含むマルチパートアップロードの詳細は、オブジェクトをアップロードするを参照してください。

署名付き URL を生成する

バケットへの一時的な公開読み取りまたは書き込みアクセスを共有する、署名付きリンクを生成します。

# Generate presigned URL for reading (GET)
get_url = s3.generate_presigned_url(
    "get_object",
    Params={"Bucket": "my-bucket", "Key": "dog.png"},
    ExpiresIn=3600,  # Valid for 1 hour
)

# Generate presigned URL for writing (PUT)
put_url = s3.generate_presigned_url(
    "put_object",
    Params={
        "Bucket": "my-bucket",
        "Key": "dog.png",
        "ContentType": "image/png",
    },
    ExpiresIn=3600,
)

https://<ACCOUNT_ID>.r2.cloudflarestorage.com/my-bucket/dog.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...&X-Amz-Date=<timestamp>&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=<signature>
https://<ACCOUNT_ID>.r2.cloudflarestorage.com/my-bucket/dog.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...&X-Amz-Date=<timestamp>&X-Amz-Expires=3600&X-Amz-SignedHeaders=content-type%3Bhost&X-Amz-Signature=<signature>

署名付き PUT URL でアップロードします。ContentType 付きの署名付き URL を使う場合、クライアントは一致する Content-Type ヘッダーを含める必要があります。

curl -X PUT "https://<ACCOUNT_ID>.r2.cloudflarestorage.com/my-bucket/dog.png?X-Amz-Algorithm=..." \
  -H "Content-Type: image/png" \
  --data-binary @dog.png

CORS と Content-Type でアップロードを制限する

アップロード用の署名付き URL を生成するときは、次の方法で不正利用を抑えられます。

Content-Type を制限する: 署名付き URL のパラメータで許可するコンテンツタイプを指定します。クライアントが別の Content-Type ヘッダーを送ると、アップロードは失敗します。
CORS を設定する: バケットに CORS ルールを設定し、どのオリジンからファイルをアップロードできるかを制御します。Cloudflare ダッシュボード ↗ で、バケット設定に JSON ポリシーを追加して CORS を設定します。

[
	{
		"AllowedOrigins": ["https://example.com"],
		"AllowedMethods": ["PUT"],
		"AllowedHeaders": ["Content-Type"],
		"ExposeHeaders": ["ETag"],
		"MaxAgeSeconds": 3600
	}
]

続けて、Content-Type を制限した署名付き URL を生成します。

put_url = s3.generate_presigned_url(
    "put_object",
    Params={
        "Bucket": "my-bucket",
        "Key": "dog.png",
        "ContentType": "image/png",
    },
    ExpiresIn=3600,
)

クライアントがこの署名付き URL を使うときは、次の条件を満たす必要があります。

許可されたオリジンからリクエストする（CORS で強制）
Content-Type: image/png ヘッダーを含める（署名で強制）