← Cloudflare R2 / r2 / examples / aws

boto3

Musíte vygenerovat Access Key než začnete. Všechny příklady budou používat access_key_id a access_key_secret proměnné, které představují Access Key ID a Secret Access Key hodnoty, které jste vygenerovali.

Nakonfigurujte boto3 ↗ k použití vašeho koncového bodu 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",
)

Můžete vynechat aws_access_key_id a aws_secret_access_key pokud nastavíte AWS_ACCESS_KEY_ID a AWS_SECRET_ACCESS_KEY proměnné prostředí ↗.

Běžné operace pomocí klienta:

# 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")

Optimalizace výkonu nahrávání

U velkých objektů (soubory o velikosti několika GB, například trénovací data nebo video) upload_fileobj se může stát úzkým hrdlem propustnosti. Jeho interní fond vláken je omezen Pythonovým GIL ↗, a zvyšování max_concurrency prostřednictvím TransferConfig přináší klesající přínos nad ~10 vlákny.

Nízkoúrovňové vícedílné API použijte s ThreadPoolExecutor místo toho:

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

Další informace o vícedílném nahrávání, včetně limitů velikosti dílů a správy životního cyklu, najdete v Nahrávání objektů.

Generování presigned URL adres

Generujte presigned odkazy pro sdílení dočasného veřejného přístupu ke čtení nebo zápisu do bucketu.

# 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>

Nahrajte pomocí předem podepsané PUT URL. Při použití předem podepsané URL s ContentType, klient musí uvést odpovídající Content-Type hlavičku:

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

Omezení nahrávání pomocí CORS a Content-Type

Při generování předem podepsaných URL adres pro nahrávání můžete omezit zneužití těmito způsoby:

Omezení Content-Type: Zadejte povolený typ obsahu v parametrech presigned URL. Pokud klient odešle jiný Content-Type hlavička.
Konfigurace CORS: Nastavte Pravidla CORS na vašem bucketu, abyste určili, které originy mohou nahrávat soubory. CORS nakonfigurujte prostřednictvím Cloudflare dashboard ↗ přidáním JSON policy do nastavení vašeho bucketu:

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

Poté vygenerujte presigned URL s omezením na Content-Type:

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

Když klient použije tuto předem podepsanou URL adresu, musí:

Odešlete požadavek z povoleného zdroje (vynucováno pomocí CORS)
Zahrňte Content-Type: image/png hlavička (vynucená podpisem)