תיעוד 252

S3

R2 מספק תמיכה ב-API תואם S3, כלומר אפשר להשתמש בכל SDK, ספרייה או כלי של S3 כדי לעבוד עם הדליים. אם יש קוד קיים שעובד עם S3, אפשר להשתמש בו עם R2 על ידי שינוי כתובת נקודת הקצה.

#1. יצירת דלי

דלי מאחסן את האובייקטים ב-R2. כדי ליצור דלי R2 חדש:

התחבר לחשבון Cloudflare:
```
npx wrangler login
```
צור דלי בשם my-bucket:
```
npx wrangler r2 bucket create my-bucket
```
אם מופיעה בקשה, בחר את החשבון שבו רוצים ליצור את הדלי.
ודא שהדלי נוצר:
```
npx wrangler r2 bucket list
```
בלוח הבקרה של Cloudflare, עבור אל R2 object storage. עבור אל Overview ↗
בחר Create bucket.
הזן שם לדלי.
בחר מיקום לדלי ו-מחלקת אחסון ברירת מחדל.
בחר Create bucket.

#2. יצירת פרטי גישה ל-API

כדי להשתמש ב-S3 API, צריך ליצור פרטי גישה ולקבל Access Key ID ו-Secret Access Key:

עבור אל לוח הבקרה של Cloudflare ↗.
בחר Storage & databases > R2 > Overview.
בחר Manage ב-API Tokens.
בחר Create Account API token או Create User API token
בחר הרשאת Object Read & Write ואת Apply to specific buckets only כדי לבחור את הדליים שאליהם רוצים גישה.
בחר Create API Token.
העתק את Access Key ID ואת Secret Access Key. אחסן אותם בצורה מאובטחת, כי אי אפשר להציג את הסוד שוב.

צריך גם את כתובת נקודת הקצה של S3 API. אפשר למצוא אותה בתחתית דף האישור של Create API Token אחרי יצירת האסימון, או בדף R2 Overview:

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

#3. שימוש ב-AWS SDK

הדוגמאות הבאות מראות איך להשתמש ב-SDK של Python ושל JavaScript. לשפות אחרות, ראה דוגמאות SDK תואמות S3 עבור Go, Java, PHP, Ruby ו-Rust.

התקן את boto3 ↗:
```
pip install boto3
```
צור קובץ בדיקה להעלאה:
```
echo 'Hello, R2!' > myfile.txt
```

השתמש בפרטי הגישה כדי ליצור לקוח S3 ולעבוד עם הדלי:

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']}")

שמור את זה כ-example.py והרץ:

python example.py

Uploaded myfile.txt
Downloaded to downloaded.txt
Object: myfile.txt

ראה דוגמאות boto3 לפעולות נוספות.

התקן את החבילה @aws-sdk/client-s3 ↗:
```
npm install @aws-sdk/client-s3
```

השתמש בפרטי הגישה כדי ליצור לקוח S3 ולעבוד עם הדלי:

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),
);

שמור את זה כ-example.mjs והרץ:

node example.mjs

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

ראה דוגמאות AWS SDK ל-JavaScript לפעולות נוספות.

#השלבים הבאים

#כתובות URL חתומות מראש

יצירת כתובות URL זמניות לגישה לאובייקט פרטי.

#דליים ציבוריים

הגשת קבצים ישירות דרך HTTP עם דלי ציבורי.

#CORS

הגדרת CORS להעלאות מהדפדפן.

#מחזורי חיים של אובייקטים

הגדרת כללי מחזור חיים למחיקה אוטומטית של אובייקטים ישנים.