📘 תיעוד 217

גישה מאובטחת והעלאת נכסים עם Cloudflare R2

המדריך הזה מסביר איך ליצור פרויקט Cloudflare Workers מבוסס TypeScript שיכול לגשת לקבצים מתוך דלי Cloudflare R2 ולהעלות אליו קבצים בצורה מאובטחת. Cloudflare R2 מאפשר למפתחים לאחסן כמויות גדולות של נתונים לא מובנים בלי דמי רוחב הפס של יציאה (egress) היקרים שמשויכים לשירותי אחסון ענן טיפוסיים.

#דרישות מקדימות

כדי להמשיך:

1. הירשמו לחשבון Cloudflare ↗︎ אם עדיין לא עשיתם זאת.

2. התקינו את npm ↗︎.

3. התקינו את Node.js ↗︎.

   השתמשו בVite+ (vp env) ↗︎ כדי להתקין ולנהל גרסאות של Node.js.

   לגרסאות Node.js הנתמכות, עיינו בדרישות המערכת של Wrangler.

#יצירת יישום Worker

תחילה, השתמשו בCLI של create-cloudflare ↗︎ כדי ליצור Worker חדש. כדי לעשות זאת, פתחו חלון מסוף והריצו את הפקודה הבאה:

npm

npm create cloudflare@latest -- upload-r2-assets

yarn

yarn create cloudflare upload-r2-assets

pnpm

pnpm create cloudflare@latest upload-r2-assets

להגדרה, בחרו את האפשרויות הבאות:

• עבור What would you like to start with?, בחרו Hello World example.
• עבור Which template would you like to use?, בחרו Worker only.
• עבור Which language do you want to use?, בחרו TypeScript.
• עבור Do you want to use git for version control?, בחרו Yes.
• עבור Do you want to add an AGENTS.md file to help AI coding tools understand Cloudflare APIs?, בחרו Yes.
• עבור Do you want to deploy your application?, בחרו No (אנחנו נבצע כמה שינויים לפני הפריסה).

עברו לספרייה החדשה שיצרתם:

cd upload-r2-assets

#יצירת דלי R2

לפני שתשלבו גישה לדלי R2 ביישום ה-Worker, צריך ליצור דלי R2:

npx wrangler r2 bucket create <YOUR_BUCKET_NAME>

החליפו את <YOUR_BUCKET_NAME> בשם שאתם רוצים להקצות לדלי. הציגו את רשימת דליי ה-R2 של החשבון כדי לוודא שדלי חדש נוסף:

npx wrangler r2 bucket list

#הגדרת גישה לדלי R2

אחרי שדלי ה-R2 החדש מוכן, השתמשו בו בתוך יישום ה-Worker.

השתמשו בדלי ה-R2 בתוך פרויקט ה-Worker על ידי שינוי קובץ התצורה של Wrangler כך שיכלול binding של דלי R2. הוסיפו את ה-binding הבא של דלי R2 לקובץ Wrangler:

jsonc

{
	"r2_buckets": [
		{
			"binding": "MY_BUCKET",
			"bucket_name": "<YOUR_BUCKET_NAME>"
		}
	]
}

toml

[[r2_buckets]]
binding = "MY_BUCKET"
bucket_name = "<YOUR_BUCKET_NAME>"

תנו שם ל-binding של דלי ה-R2. החליפו את <YOUR_BUCKET_NAME> בשם של דלי ה-R2 שיצרתם קודם.

יישום ה-Worker יכול עכשיו לגשת לדלי ה-R2 באמצעות המשתנה MY_BUCKET. עכשיו אפשר לבצע פעולות CRUD (Create, Read, Update, Delete) על תוכן הדלי.

#שליפה מדלי R2

אחרי הגדרת binding של דלי R2, תממשו את הפונקציונליות של ה-Worker לאינטראקציה עם דלי ה-R2, כגון שליפת קבצים מהדלי והעלאת קבצים לדלי.

כדי לשלוף קבצים מדלי ה-R2, השתמשו בפונקציה BINDING.get. בדוגמה למטה, ה-binding של דלי ה-R2 נקרא MY_BUCKET. באמצעות .get(key) אפשר לאחזר נכס לפי נתיב ה-URL כמפתח. בדוגמה הזו, נתיב ה-URL הוא /image.png, ומפתח הנכס הוא image.png.

interface Env {
	MY_BUCKET: R2Bucket;
}
export default {
	async fetch(request, env): Promise<Response> {
		// For example, the request URL my-worker.account.workers.dev/image.png
		const url = new URL(request.url);
		const key = url.pathname.slice(1);
		// Retrieve the key "image.png"
		const object = await env.MY_BUCKET.get(key);

		if (object === null) {
			return new Response("Object Not Found", { status: 404 });
		}

		const headers = new Headers();
		object.writeHttpMetadata(headers);
		headers.set("etag", object.httpEtag);

		return new Response(object.body, {
			headers,
		});
	},
} satisfies ExportedHandler<Env>;

הקוד שנכתב למעלה שולף ומחזיר נתונים מדלי ה-R2 כאשר מתבצעת בקשת GET ליישום ה-Worker באמצעות נתיב URL מסוים.

#העלאה מאובטחת לדלי R2

בהמשך, תוסיפו את היכולת להעלות לדלי ה-R2 באמצעות אימות. כדי לאמת בצורה מאובטחת את בקשות ההעלאה, השתמשו ביכולת הסודות של Wrangler. Wrangler הותקן כשהרצתם את הפקודה create cloudflare@latest.

צרו ערך סודי לבחירתכם, לדוגמה מחרוזת אקראית או סיסמה. באמצעות ה-CLI של Wrangler, הוסיפו את הסוד לפרויקט בתור AUTH_SECRET:

npx wrangler secret put AUTH_SECRET

עכשיו, הוסיפו נתיב קוד חדש שמטפל בבקשת HTTP מסוג PUT. הקוד החדש יבדוק שהסוד שהועלה קודם משמש נכון לאימות, ואז יעלה ל-R2 באמצעות MY_BUCKET.put(key, data):

interface Env {
	MY_BUCKET: R2Bucket;
	AUTH_SECRET: string;
}
export default {
	async fetch(request, env): Promise<Response> {
		if (request.method === "PUT") {
			// Note that you could require authentication for all requests
			// by moving this code to the top of the fetch function.
			const auth = request.headers.get("Authorization");
			const expectedAuth = `Bearer ${env.AUTH_SECRET}`;

			if (!auth || auth !== expectedAuth) {
				return new Response("Unauthorized", { status: 401 });
			}

			const url = new URL(request.url);
			const key = url.pathname.slice(1);
			await env.MY_BUCKET.put(key, request.body);
			return new Response(`Object ${key} uploaded successfully!`);
		}

		// include the previous code here...
	},
} satisfies ExportedHandler<Env>;

הגישה הזו מבטיחה שרק לקוחות שמספקים אסימון bearer תקף, דרך כותרת Authorization ששווה לערך AUTH_SECRET, יורשו להעלות לדלי ה-R2. אם השתמשתם בשם binding שונה מ-AUTH_SECRET, החליפו אותו בקוד למעלה.

#פריסת יישום ה-Worker

אחרי השלמת פרויקט ה-Cloudflare Worker, פרסו אותו ל-Cloudflare. ודאו שאתם בתוך ספריית יישום ה-Worker שיצרתם עבור המדריך הזה, ואז הריצו:

npx wrangler deploy

היישום שלכם עכשיו פעיל ונגיש בכתובת <YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev.

יצרתם בהצלחה Cloudflare Worker שמאפשר לכם לתקשר עם דלי R2 כדי לבצע משימות כגון העלאה והורדה של קבצים. עכשיו אפשר להשתמש בזה כנקודת התחלה לפרויקטים שלכם.

#הצעדים הבאים

כדי לבנות עוד עם R2 ו-Workers, עיינו במדריכים ובתיעוד של R2.

אם יש לכם שאלות, אתם זקוקים לעזרה, או שתרצו לשתף את הפרויקט, הצטרפו לקהילת המפתחים של Cloudflare בDiscord ↗︎ כדי להתחבר למפתחים אחרים ולצוות Cloudflare.