← Cloudflare R2 / r2 / api / s3

Presigned URLs

Presigned URLs jsou Koncept S3 ↗ pro udělení dočasného přístupu k objektům, aniž byste odhalili své přihlašovací údaje API. Presigned URL obsahuje parametry podpisu přímo v URL, čímž opravňuje kohokoli s touto URL k provedení konkrétní operace (například GetObject nebo PutObject) na konkrétním objektu, dokud adresa URL nevyprší.

Jsou ideální pro udělení dočasného přístupu ke konkrétním objektům, například když chcete uživatelům umožnit nahrávat soubory přímo do R2 nebo poskytnout časově omezené odkazy ke stažení.

Chcete-li vygenerovat předem podepsanou URL adresu, zadáte:

1. Identifikátor prostředku: ID účtu, název bucketu a cesta k objektu
2. Operace: Povolená operace S3 API (GET, PUT, HEAD nebo DELETE)
3. Platnost: Časový limit od 1 sekundy do 7 dnů (604 800 sekund)

Presigned URLs se generují na straně serveru bez jakékoli komunikace s R2. Stačí k tomu vaše přihlašovací údaje R2 API a implementace podpisového algoritmu AWS Signature Version 4.

R2 podporuje dva vzory časově omezeného přístupu. Částečně se překrývají, ale mají odlišné kompromisy:

• ID účtu (pro sestavení adresy URL koncového bodu S3)
• Token R2 API (Access Key ID a Secret Access Key)
• AWS SDK nebo kompatibilní klientská knihovna S3

import { S3Client, GetObjectCommand, PutObjectCommand } from "@aws-sdk/client-s3";
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";

const S3 = new S3Client({
	region: "auto", // Required by SDK but not used by R2
	// Provide your Cloudflare account ID
	endpoint: `https://<ACCOUNT_ID>.r2.cloudflarestorage.com`,
	// Retrieve your S3 API credentials for your R2 bucket via API tokens (see: https://developers.cloudflare.com/r2/api/tokens)
	credentials: {
		accessKeyId: '<ACCESS_KEY_ID>',
		secretAccessKey: '<SECRET_ACCESS_KEY>',
	},
});

// Generate presigned URL for reading (GET)
const getUrl = await getSignedUrl(
	S3,
	new GetObjectCommand({ Bucket: "my-bucket", Key: "image.png" }),
	{ expiresIn: 3600 }, // Valid for 1 hour
);
// https://my-bucket.<ACCOUNT_ID>.r2.cloudflarestorage.com/image.png?X-Amz-Algorithm=...

// Generate presigned URL for writing (PUT)
// Specify ContentType to restrict uploads to a specific file type
const putUrl = await getSignedUrl(
	S3,
	new PutObjectCommand({
		Bucket: "my-bucket",
		Key: "image.png",
		ContentType: "image/png",
	}),
	{ expiresIn: 3600 },
);

import boto3

s3 = boto3.client(
    service_name="s3",
    # Provide your Cloudflare account ID
    endpoint_url='https://<ACCOUNT_ID>.r2.cloudflarestorage.com',
    # Retrieve your S3 API credentials for your R2 bucket via API tokens (see: https://developers.cloudflare.com/r2/api/tokens)
    aws_access_key_id='<ACCESS_KEY_ID>',
    aws_secret_access_key='<SECRET_ACCESS_KEY>',
    region_name="auto", # Required by SDK but not used by R2
)

# Generate presigned URL for reading (GET)
get_url = s3.generate_presigned_url(
	'get_object',
	Params={'Bucket': 'my-bucket', 'Key': 'image.png'},
	ExpiresIn=3600  # Valid for 1 hour
)
# https://my-bucket.<ACCOUNT_ID>.r2.cloudflarestorage.com/image.png?X-Amz-Algorithm=...

# Generate presigned URL for writing (PUT)
# Specify ContentType to restrict uploads to a specific file type
put_url = s3.generate_presigned_url(
	'put_object',
	Params={
		'Bucket': 'my-bucket',
		'Key': 'image.png',
		'ContentType': 'image/png'
	},
	ExpiresIn=3600
)

# Generate presigned URL for reading (GET)
# The AWS CLI presign command defaults to GET operations
aws s3 presign --endpoint-url https://<ACCOUNT_ID>.r2.cloudflarestorage.com \
  s3://my-bucket/image.png \
  --expires-in 3600

# Output:
# https://<ACCOUNT_ID>.r2.cloudflarestorage.com/my-bucket/image.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...

# Note: The AWS CLI presign command only supports GET operations.
# For PUT operations, use one of the SDK examples above.

Úplné příklady a další operace naleznete v dokumentaci pro konkrétní SDK:

• AWS SDK for JavaScript
• AWS SDK for Python (Boto3)
• AWS CLI
• AWS SDK for Go
• AWS SDK for PHP

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

• Omezení Content-Type: Zadejte povolené Content-Type v parametrech vašeho SDK. Podpis bude tuto hlavičku zahrnovat, takže nahrávání selže s 403/SignatureDoesNotMatch chybu, pokud klient odešle jiný Content-Type pro požadavek na nahrání.
• Konfigurace CORS: Pokud se vaše presigned URL budou používat z prohlížeče, nastavte Pravidla CORS na vašem bucketu, abyste určili, které originy mohou odesílat požadavky.

Jakmile je vygenerována, používejte předem podepsanou URL adresu jako jakýkoli jiný koncový bod HTTP. Podpis je součástí URL adresy, takže nejsou potřeba žádné další autentizační hlavičky.

# Download using a GET presigned URL
curl "https://my-bucket.<ACCOUNT_ID>.r2.cloudflarestorage.com/image.png?X-Amz-Algorithm=..."

# Upload using a PUT presigned URL
curl -X PUT "https://my-bucket.<ACCOUNT_ID>.r2.cloudflarestorage.com/image.png?X-Amz-Algorithm=..." \
  --data-binary @image.png

Presigned URL můžete také použít přímo ve webových prohlížečích, mobilních aplikacích nebo v jakémkoli HTTP klientovi. Stejnou presigned URL lze opakovaně použít až do jejího vypršení.

Následuje příklad předem podepsané URL adresy vytvořené pomocí přihlašovacích údajů R2 API postupem podepisování AWS Signature Version 4:

https://my-bucket.123456789abcdef0123456789abcdef.r2.cloudflarestorage.com/photos/cat.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=CFEXAMPLEKEY12345%2F20251201%2Fauto%2Fs3%2Faws4_request&X-Amz-Date=20251201T180512Z&X-Amz-Expires=3600&X-Amz-Signature=8c3ac40fa6c83d64b4516e0c9e5fa94c998bb79131be9ddadf90cefc5ec31033&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject

V tomto příkladu tato presigned URL provádí GetObject na objektu photos/cat.png v rámci bucketu my-bucket v účtu s id 123456789abcdef0123456789abcdef. Klíčové parametry podpisu, které tvoří tuto presigned URL, jsou:

• X-Amz-Algorithm: Určuje algoritmus použitý k podepsání URL.
• X-Amz-Credential: Obsahuje informace o přihlašovacích údajích použitých k výpočtu podpisu.
• X-Amz-Date: Datum a čas (ve formátu ISO 8601), kdy byl podpis vytvořen.
• X-Amz-Expires: Doba platnosti presigned URL v sekundách počítaná od X-Amz-Date.
• X-Amz-Signature: Podpis dokazující, že URL byla podepsána pomocí tajného klíče.
• X-Amz-SignedHeaders: Uvádí HTTP hlavičky, které byly zahrnuty do výpočtu podpisu.

R2 podporuje předem podepsané URL adresy pro následující metody HTTP:

• GET: Načte objekt z bucketu
• HEAD: Načtěte metadata objektu z bucketu
• PUT: Nahrajte objekt do bucketu
• DELETE: Odstraní objekt z bucketu

POST (vícedílné nahrávání formulářů prostřednictvím formulářů HTML) v současnosti není podporováno.

Předem podpodepsané URL adresy považujte za bearer tokeny. Kdokoli, kdo má tuto URL adresu, může provést danou operaci, dokud nevyprší její platnost. Předem podepsané URL adresy sdílejte pouze se zamýšlenými příjemci a u citlivých operací zvažte použití krátké doby platnosti.

Presigned URLs fungují s doménou S3 API (<ACCOUNT_ID>.r2.cloudflarestorage.com) a nelze je použít s vlastními doménami.

Pokud potřebujete ověřování pro buckety R2 přístupné přes vlastní domény (veřejné buckety), použijte funkce ověřování HMAC pro WAF (vyžaduje plán Pro nebo vyšší).