Pular para o conteúdo

S3

Atualizado em Ver como Markdown

R2 provides support for a S3-compatible API, which means you can use any S3 SDK, library, or tool to interact with your buckets. If you have existing code that works with S3, you can use it with R2 by changing the endpoint URL.

1. Create a bucket

A bucket stores your objects in R2. To create a new R2 bucket:

  1. Log in to your Cloudflare account:

    npx wrangler login

  2. Create a bucket named my-bucket:

    npx wrangler r2 bucket create my-bucket

    If prompted, select the account you want to create the bucket in.

  3. Verify the bucket was created:

    npx wrangler r2 bucket list

  1. In the Cloudflare Dashboard, go to R2 object storage.

    Go to Overview ↗

  2. Select Create bucket.

  3. Enter a name for your bucket.

  4. Select a location for your bucket and a default storage class.

  5. Select Create bucket.

2. Generate API credentials

To use the S3 API, you need to generate credentials and get an Access Key ID and Secret Access Key:

  1. Go to the Cloudflare Dashboard ↗.
  2. Select Storage & databases > R2 > Overview.
  3. Select Manage in API Tokens.
  4. Select Create Account API token or Create User API token
  5. Choose Object Read & Write permission and Apply to specific buckets only to select the buckets you want to access.
  6. Select Create API Token.
  7. Copy the Access Key ID and Secret Access Key. Store these securely as you cannot view the secret again.

You also need your S3 API endpoint URL which you can find at the bottom of the Create API Token confirmation page once you have created your token, or on the R2 Overview page:

https://<ACCOUNT_ID>.r2.cloudflarestorage.com

3. Use an AWS SDK

The following examples show how to use Python and JavaScript SDKs. For other languages, refer to S3-compatible SDK examples for Go, Java, PHP, Ruby, and Rust.

  1. Install boto3 ↗:

    pip install boto3

  2. Create a test file to upload:

    echo 'Hello, R2!' > myfile.txt

  3. Use your credentials to create an S3 client and interact with your bucket:

    import boto3

s3 = boto3.client(
    service_name='s3',
    # Provide your R2 endpoint: https://<ACCOUNT_ID>.r2.cloudflarestorage.com
    endpoint_url='https://<ACCOUNT_ID>.r2.cloudflarestorage.com',
    # Provide your R2 Access Key ID and Secret Access Key
    aws_access_key_id='<ACCESS_KEY_ID>',
    aws_secret_access_key='<SECRET_ACCESS_KEY>',
    region_name='auto',  # Required by boto3, not used by R2
)

# Upload a file
s3.upload_file('myfile.txt', 'my-bucket', 'myfile.txt')
print('Uploaded myfile.txt')

# Download a file
s3.download_file('my-bucket', 'myfile.txt', 'downloaded.txt')
print('Downloaded to downloaded.txt')

# List objects
response = s3.list_objects_v2(Bucket='my-bucket')
for obj in response.get('Contents', []):
    print(f"Object: {obj['Key']}")

  4. Save this as example.py and run it:

    python example.py
    Uploaded myfile.txt
Downloaded to downloaded.txt
Object: myfile.txt

Refer to boto3 examples for more operations.

  1. Install the @aws-sdk/client-s3 ↗ package:

    npm install @aws-sdk/client-s3

  2. Use your credentials to create an S3 client and interact with your bucket:

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

const s3 = new S3Client({
	region: "auto", // Required by AWS SDK, not used by R2
	// Provide your R2 endpoint: https://<ACCOUNT_ID>.r2.cloudflarestorage.com
	endpoint: "https://<ACCOUNT_ID>.r2.cloudflarestorage.com",
	credentials: {
		// Provide your R2 Access Key ID and Secret Access Key
		accessKeyId: "<ACCESS_KEY_ID>",
		secretAccessKey: "<SECRET_ACCESS_KEY>",
	},
});

// Upload a file
await s3.send(
	new PutObjectCommand({
		Bucket: "my-bucket",
		Key: "myfile.txt",
		Body: "Hello, R2!",
	}),
);
console.log("Uploaded myfile.txt");

// Download a file
const response = await s3.send(
	new GetObjectCommand({
		Bucket: "my-bucket",
		Key: "myfile.txt",
	}),
);
const content = await response.Body.transformToString();
console.log("Downloaded:", content);

// List objects
const list = await s3.send(
	new ListObjectsV2Command({
		Bucket: "my-bucket",
	}),
);
console.log(
	"Objects:",
	list.Contents.map((obj) => obj.Key),
);

  3. Save this as example.mjs and run it:

    node example.mjs
    Uploaded myfile.txt
Downloaded: Hello, R2!
Objects: [ 'myfile.txt' ]

Refer to AWS SDK for JavaScript examples for more operations.

Next steps

CORS

Configure CORS for browser-based uploads.