📘 תיעוד 272

הגדרת CORS

שיתוף משאבים בין מקורות (CORS) הוא שיטה תקנית שמונעת מדומיין X לגשת למשאבים של דומיין Y. היא עושה זאת באמצעות כותרות מיוחדות בתגובות HTTP מדומיין Y, שמאפשרות לדפדפן לוודא שדומיין Y מתיר לדומיין X לגשת למשאבים האלה.

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

CORS משמש כשאתם מקיימים אינטראקציה עם דלי מדפדפן אינטרנט, ויש לכם שתי אפשרויות:

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

כתובות URL חתומות מראש: מאפשרת לכל מי שיש לו גישה לכתובת ה-URL הייחודית לבצע פעולות מסוימות על הדלי.

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

לפני שאתם מגדירים CORS, חייבים להיות לכם:

• דלי R2 עם לפחות אובייקט אחד. אם אתם צריכים ליצור דלי, עיינו ביצירת דלי ציבורי.
• דומיין שאפשר להשתמש בו כדי לגשת לאובייקט. זה יכול להיות גם localhost.
• (אופציונלי) מפתחות גישה. מפתח גישה נדרש רק בעת יצירת כתובת URL חתומה מראש.

#שימוש ב-CORS עם דלי ציבורי

כדי להשתמש ב-CORS עם דלי ציבורי, ודאו שהדלי מוגדר לאפשר גישה ציבורית.

לאחר מכן, הוסיפו מדיניות CORS לדלי כדי לאפשר שיתוף של הקובץ.

#שימוש ב-CORS עם כתובת URL חתומה מראש

כתובות URL חתומות מראש מאפשרות גישה זמנית לביצוע פעולות מסוימות על הדלי בלי לחשוף את פרטי הגישה שלכם. למרות שכתובות URL חתומות מראש מטפלות באימות, עדיין צריך להגדיר CORS כשמבצעים בקשות מדפדפן.

כשדפדפן שולח בקשה לכתובת URL חתומה מראש במקור אחר, הדפדפן אוכף CORS. בלי מדיניות CORS, העלאות והורדות מבוססות דפדפן באמצעות כתובות URL חתומות מראש ייכשלו, גם אם כתובת ה-URL החתומה מראש עצמה תקינה.

כתובות URL חתומות מראש שפג תוקפן מחזירות תגובת 403 ExpiredRequest. R2 לא כולל כותרות תגובת CORS בתגובות של כתובות URL חתומות מראש שפג תוקפן, ולכן JavaScript בדפדפן לא יכול לקרוא את גוף השגיאה. רעננו כתובות URL חתומות מראש לפני שתוקפן פג, או ניתבו בקשות דרך שרת היישום אם הדפדפן צריך לטפל בשגיאות תפוגה ישירות.

כדי לאפשר גישה מבוססת דפדפן עם כתובות URL חתומות מראש:

1. הוסיפו מדיניות CORS לדלי שמאפשרת בקשות מהמקור של היישום שלכם.
2. הגדירו את AllowedMethods כך שיתאים לפעולות שכתובות ה-URL החתומות מראש מבצעות, השתמשו ב-GET, PUT, HEAD ו/או DELETE.
3. הגדירו את AllowedHeaders כך שיכלול כל כותרת שהלקוח ישלח בעת שימוש בכתובת ה-URL החתומה מראש, למשל כותרות לסוג תוכן, סכומי ביקורת, שמירה במטמון או מטא-נתונים מותאמים אישית.
4. (אופציונלי) הגדירו את ExposeHeaders כדי לאפשר ל-JavaScript שלכם לקרוא כותרות תגובה כמו ETag, שמכיל את הגיבוב של האובייקט ושימושי לאימות העלאות.
5. (אופציונלי) הגדירו את MaxAgeSeconds כדי לשמור במטמון את תגובת הבקשה המקדימה ולהפחית את מספר בקשות הבקשה המקדימה שהדפדפן מבצע.

הדוגמה הבאה מאפשרת העלאות מבוססות דפדפן מ-https://example.com עם כותרת Content-Type:

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

#שימוש ב-CORS עם דומיין מותאם אישית

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

בקשות בין מקורות חייבות לכלול כותרת בקשה Origin תקינה, לדוגמה Origin: https://example.com. אם אתם בודקים ישירות או משתמשים בכלי שורת פקודה כמו curl, לא תראו כותרות תגובה Access-Control-* של CORS אלא אם כותרת הבקשה Origin כלולה בבקשה.

שמירה במטמון וכותרות CORS

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

#הוספת מדיניות CORS מלוח הבקרה

1. בלוח הבקרה של Cloudflare, עברו לעמוד R2 object storage. מעבר אל Overview
2. אתרו ובחרו את הדלי שלכם מהרשימה.
3. בחרו Settings.
4. תחת CORS Policy, בחרו Add CORS policy.
5. מהלשונית JSON, הזינו ידנית או העתיקו והדביקו את המדיניות שלכם לתיבת הטקסט.
6. כשסיימתם, בחרו Save.

המדיניות שלכם מוצגת בעמוד Settings של הדלי.

#הוספת מדיניות CORS באמצעות Wrangler CLI

אפשר להגדיר כללי CORS באמצעות Wrangler CLI.

1. צרו קובץ JSON עם הגדרת ה-CORS שלכם:

cors.json

{
  "rules": [
    {
      "allowed": {
        "origins": ["https://example.com"],
        "methods": ["GET"]
      }
    }
  ]
}

2. החילו את מדיניות ה-CORS על הדלי:

npx wrangler r2 bucket cors set <BUCKET_NAME> --file cors.json

3. אמתו שמדיניות ה-CORS הוחלה:

npx wrangler r2 bucket cors list <BUCKET_NAME>

#כותרות תגובה

השדות הבאים במדיניות CORS של R2 ממופים לכותרות תגובת HTTP. כותרות התגובה האלה מוחזרות רק כשבקשת ה-HTTP הנכנסת היא בקשת CORS תקינה.

#דוגמה

דוגמה זו מציגה מדיניות CORS שנוספה לדלי שמכיל את האובייקט Roboto-Light.ttf, שהוא קובץ גופן.

AllowedOrigins מציין את שרת האינטרנט שבשימוש, ו-localhost:3000 הוא שם המארח שבו שרת האינטרנט פועל. AllowedMethods מציין שרק בקשות GET מותרות ויכולות לקרוא אובייקטים בדלי שלכם.

[
	{
		"AllowedOrigins": ["http://localhost:3000"],
		"AllowedMethods": ["GET"]
	}
]

באופן כללי, אסטרטגיה טובה לוודא שהגדרתם את כללי ה-CORS הנכונים היא להסתכל על בקשת הרשת שהדפדפן חוסם.

• ודאו ש-AllowedOrigins של הכלל כולל את המקור שממנו הבקשה נשלחת. (כמו http://localhost:3000 או https://yourdomain.com)
• ודאו ש-AllowedMethods של הכלל כולל את השיטה של הבקשה החסומה.
• ודאו ש-AllowedHeaders של הכלל כולל את הכותרות של הבקשה החסומה.

שימו לב גם שהפצת כללי CORS יכולה, במקרים נדירים, להימשך עד 30 שניות.

#בעיות נפוצות

• רק בקשה בין מקורות כוללת כותרות תגובת CORS. R2 מזהה בקשות אלה לפי כותרת בקשת HTTP בשם Origin. ערך הכותרת חייב להתאים למקור בשדה AllowedOrigins של המדיניות שלכם. בקשות בלי כותרת Origin לא מחזירות כותרות תגובת CORS.
• הערכים של AllowedOrigins במדיניות ה-CORS שלכם חייבים להיות * או תבנית תקינה שמבוססת על ערך כותרת HTTP Origin. כותרת Origin תקינה לא כוללת רכיב נתיב, והיא חייבת להכיל רק scheme://host[:port] (כאשר הפורט אופציונלי).
  • השתמשו ב-* כדי לאפשר בקשות מכל מקור.
  • תבנית מקור יכולה להכיל לכל היותר תו כללי * אחד. התו הכללי יכול לחצות נקודות. לדוגמה, https://*.example.com תואם גם ל-https://api.example.com וגם ל-https://a.b.example.com, אבל לא ל-https://example.com.
  • ערכי מקור בלי תו כללי חייבים להתאים בדיוק לכותרת Origin של הבקשה.
  • פורטים לא יכולים להכיל תווים כלליים. כדי לאפשר כמה פורטים של localhost, ציינו כל מקור בנפרד, למשל http://localhost:3000 ו-http://localhost:5173.
  • ערך AllowedOrigins תקין: https://static.example.com. כולל את הסכמה ואת המארח. פורט הוא אופציונלי ומשתמע מהסכמה.
  • ערך AllowedOrigins לא תקין: https://static.example.com/ או https://static.example.com/fonts/Calibri.woff2. כולל בטעות את רכיב הנתיב.
• אם אתם צריכים לגשת לערכי כותרות מסוימים באמצעות JavaScript בעמוד המקור, למשל כשמשתמשים בנגן וידאו, ודאו שהגדרתם את Access-Control-Expose-Headers נכון וכללו את הכותרות ש-JavaScript שלכם צריך לגשת אליהן, כמו Content-Length.