שיתוף משאבים בין מקורות (CORS)

הגדרה דוגמאות להגדרות

שיתוף משאבים בין מקורות (CORS) מאפשר לאפליקציות אינטרנט בצד הלקוח לגשת למשאבים ממקורות שונים. ‫Cloud Storage תומך במפרט CORS, ומאפשר להגדיר את הקטגוריות כך שישתפו משאבים בצורה מאובטחת עם סקריפטים ממקורות אחרים. לדוגמה, אפשר להשתמש ב-CORS כדי לאפשר לאפליקציית האינטרנט https://example-app.appspot.com לגשת למשאב במקור https://example-data.storage.googleapis.com.

למידע נוסף על רכיבי ההגדרות של CORS, ראו הגדרת CORS של קטגוריה.

איך CORS עובד

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

אישור גישה בין דומיינים

כברירת מחדל, דפדפני אינטרנט אוכפים אמצעי אבטחה שנקרא מדיניות המקור הזהה. מדיניות המקור הזהה מונעת מסקריפט באתר אחד ליצור אינטראקציה עם משאבים בדומיין אחר. ההגדרה הזו מגנה על המשתמשים מפני אתרים זדוניים, אבל היא גם חוסמת בקשות לגיטימיות. לדוגמה, אם אפליקציית האינטרנט https://example-app.appspot.com מנסה לגשת למשאב במקור https://example-data.storage.googleapis.com, הדפדפן יחסום את הבקשה כברירת מחדל כי הדומיינים לא תואמים.

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

ב-Cloud Storage אפשר להגדיר את הגדרות ה-CORS בקטגוריה. כשמגדירים את Cloud Storage, הוא שולח כותרות HTTP ספציפיות בחזרה לדפדפן (למשל Access-Control-Allow-Origin), שמאשרות לדפדפן לשתף את המשאבים של הקטגוריה עם אפליקציית האינטרנט.

סוגי בקשות

בקשות CORS פועלות בשתי דרכים: פשוטות וקדם-הפעלה. בקשה פשוטה מועברת ישירות, ואילו בקשת קדם-הפעלה שולחת קודם בקשה מקדימה כדי לקבל הרשאה.

בקשות פשוטות

התהליך הבא מתרחש כשהדפדפן שולח בקשה פשוטה ל-Cloud Storage:

הדפדפן מוסיף את הכותרת Origin לבקשה. הכותרת Origin מכילה את מקור המשאב שמעוניין לשתף את המשאבים של הקטגוריה של Cloud Storage, לדוגמה Origin:https://www.example-app.appspot.com.
‫Cloud Storage משווה את ה-method של ה-HTTP בבקשה ואת הערך של הכותרת Origin למידע על ה-Methods והמקורות בהגדרות ה-CORS של קטגוריית היעד כדי לבדוק אם יש התאמות. אם יש, Cloud Storage יכלול את הכותרת Access-Control-Allow-Origin בתגובה. הכותרת Access-Control-Allow-Origin מכילה את הערך של הכותרת Origin מהבקשה הראשונית.
הדפדפן מקבל את התשובה ובודק אם הערך Access-Control-Allow-Origin תואם לדומיין שצוין בבקשה המקורית. אם הם תואמים, הבקשה תצליח. אם הם לא תואמים או אם הכותרת Access-Control-Allow-Origin לא מופיעה בתשובה, הבקשה תיכשל.

בקשות עם בדיקה מקדימה

בקשה תעבור קדם-הפעלה כשמתקיים אחד מהמצבים הבאים:

היא משתמשת ב-methods שאינן GET, HEAD או POST.
היא משתמשת ב-method POST עם Content-Type שאינו text/plain, application/x-www-form-urlencoded או multipart/form-data.
היא מגדירה כותרות בהתאמה אישית. לדוגמה, X-PINGOTHER.

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

הדפדפן שולח בקשת OPTIONS המכילה את ה-Requested Method ואת ה-Requested Headers של הבקשה הראשית.
‫Cloud Storage משיב עם הערכים של ה-methods והכותרות של HTTP שאפשר להשתמש בהן במשאב היעד. אם ערכי ה-method או הכותרות בבקשה של קדם-ההפעלה לא נמצאים בקבוצת ה-methods והכותרות שמשאב היעד מאפשר, הבקשה תיכשל והבקשה הראשית לא תישלח.

תיאור מקיף יותר של בקשות CORS מופיע במפרט של אחזור.

תמיכה ב-CORS ב-Cloud Storage

ב-Cloud Storage אפשר להגדיר את ה-CORS ברמת הקטגוריה. נקודות הקצה (endpoints) של API בפורמט JSON ו-API בפורמט XML מטפלות בבקשות CORS ומחזירות כותרות תגובה באופן שונה. כדי להגדיר את הדליים בצורה יעילה, חשוב להבין את ההתנהגויות הבאות:

נקודות הקצה (endpoints) של API בפורמט JSON תמיד מאפשרות בקשות CORS ומחזירות ערכי ברירת מחדל בכותרות התגובות של CORS, בלי קשר להגדרות האישיות של הקטגוריה.
נקודות הקצה (endpoints) של API בפורמט XML מאפשרות רק בקשות CORS שמבוססות על ההגדרות האישיות של הקטגוריה, ומחזירות ערכים ספציפיים של כותרות CORS בתגובה להגדרות האישיות האלו.
נקודת הקצה (endpoint) המאומתת storage.cloud.google.com להורדה באמצעות הדפדפן לא מאפשרת בקשות CORS. שימו לב: מסוף Google Cloud Google Cloud מספק את נקודת הקצה (endpoint) הזו בשביל הקישור הציבורי לכתובת ה-URL של כל אובייקט.

אפשר להשתמש באחת מכתובות ה-URL הבאות של בקשות API בפורמט XML כדי לקבל תשובה מ-Cloud Storage המכילה כותרות CORS:

storage.googleapis.com/BUCKET_NAME

BUCKET_NAME.storage.googleapis.com

למידע נוסף על כתובות URL של בקשות API בפורמט XML, ראו בקשה של נקודות קצה (endpoints).

רכיבי הגדרות CORS

כשמשתמשים ב-API בפורמט XML, הערכים בהגדרות CORS של הקטגוריה קובעים את כותרות ה-CORS שיוחזרו בתגובת HTTP של Cloud Storage. כשמשתמשים ב-API בפורמט JSON, לא מתבצעת ב-Cloud Storage הערכה של ההגדרות האישיות של הקטגוריה, אלא מוחזרים ערכי ברירת מחדל של הכותרת.

בטבלה הבאה מתוארים השדות בהגדרות CORS וההתנהגות של התגובות בממשקי ה-API בפורמט XML ובפורמט JSON. כדי להבין איך משתמשים בשדות האלו, ראו דוגמאות להגדרות CORS.

שדה¹	תיאור	התנהגות התגובה מה-API בפורמט XML	התנהגות התגובה מה-API בפורמט JSON
`origin`	מציינים את המקורות שרוצים לאפשר בשביל שיתוף של משאבים בין מקורות עם הקטגוריה הזו של Cloud Storage. לדוגמה, `https://origin1.example.com`.	אם המקור בבקשה של הדפדפן תואם למקור בהגדרות האישיות של CORS, אז Cloud Storage יחזיר את `Access-Control-Allow-Origin` לדפדפן. אם אין התאמה, Cloud Storage לא יכלול את `Access-Control-Allow-Origin` בתגובה. אפשר לספק ערך של תו כללי לחיפוש שמעניק גישה לכל המקורות: `<Origin>*</Origin>`.	Cloud Storage מחזיר את הכותרת `Access-Control-Allow-Origin` המוגדרת למקור הבקשה.
`method`	מציינים methods של HTTP שרוצים לאפשר בשביל שיתוף של משאבים בין מקורות עם הקטגוריה הזו של Cloud Storage. הערך מוחזר בכותרת של `Access-Control-Allow-Methods` בתגובה לבקשות קדם-הפעלה שהצליחו. ֶ`OPTIONS` היא method סטנדרטית שדפדפנים משתמשים בה כדי ליזום בקשות קדם-הפעלה, ולכן לא מציינים את `OPTIONS` בהגדרות האישיות של CORS.	Cloud Storage תומך ב-methods: `DELETE`, `GET`, `HEAD`, `POST` ו-`PUT`. Cloud Storage בודק את ה-methods שנשלחו מהדפדפן בכותרת `Access-Control-Request-Methods` מול הגדרות ה-CORS של הקטגוריה. אם לא נמצאה התאמה, Cloud Storage מחזיר קוד תגובה `200` ללא כותרות תגובה של CORS.	Cloud Storage מחזיר את הכותרת `Access-Control-Allow-Methods` המוגדרת ל-methods: `DELETE`, `GET`, `HEAD`, `PATCH`, `POST`, `PUT`.
`responseHeader`	מציינים אילו כותרות לאפשר בשביל שיתוף משאבים בין מקורות עם הקטגוריה הזו של Cloud Storage. הערך מוחזר בכותרת `Access-Control-Allow-Headers` בתגובה לבקשות קדם-הפעלה שהצליחו.	בשביל בקשות קדם-הפעלה, Cloud Storage בודק את הכותרות שנשלחו מהדפדפן בכותרת של `Access-Control-Request-Headers` מול הגדרות ה-CORS של הקטגוריה. אם אין התאמה, Cloud Storage לא מחזיר כותרות תגובה של CORS.	Cloud Storage מחזיר את הכותרת `Access-Control-Allow-Headers` המוגדרת לערכים שצוינו על ידי הכותרת `Access-Control-Request-Headers`.
ֶ`maxAgeSeconds` (אופציונלי)	מציינים את מספר השניות שבהן הדפדפן יכול לשלוח בקשות לפני שהוא צריך לחזור על בקשת הקדם-ההפעלה. זה נקרא גם 'מועד התפוגה של המטמון'. הערך הזה מוחזר בכותרת `Access-Control-Max-Age` בתגובות לבקשות קדם-הפעלה. לדוגמה, `3600` מגדיר את מועד התפוגה של המטמון לשעה אחת.	Cloud Storage מחזיר את הכותרת `Access-Control-Max-Age` עם מועד התפוגה של המטמון שצוין. אם לא משמיטים את השדה הזה, Cloud Storage מחזיר את ערך ברירת המחדל של `3600`.	Cloud Storage מחזיר את הכותרת `Access-Control-Max-Age` עם ערך ברירת המחדל של `3600`.

¹ השמות המתועדים בעמודה Field הם ספציפיים ל-API בפורמט JSON. כשמשתמשים ב-API בפורמט XML כדי להגדיר CORS, משתמשים בפורמט ספציפי ל-XML.

ציון של כמה מקורות, methods או כותרות

כדי להגדיר כמה מקורות, methods או כותרות בהגדרות CORS, אפשר לעיין ברשימה הבאה:

כשמשתמשים ב-API בפורמט JSON, אפשר לציין כמה מקורות, methods או כותרות באמצעות מערך שמופרד בפסיקים. לדוגמה, "method": ["GET", "PUT"].

שימו לב: כשמגדירים CORS באמצעות API בפורמט JSON, בקשות מכל המקורות מתקבלות בלי קשר לערך השדה origin בהגדרות ה-CORS.
כשמשתמשים ב-API בפורמט XML, אפשר לציין כמה מקורות, methods או כותרות באמצעות רכיבים נפרדים. לדוגמה:
```
<Methods>
  <Method>PUT</Method>
  <Method>GET</Method>
</Methods>
```
כדי לאפשר שליחת בקשות מכל מקור, מגדירים את המקור לתו כללי *. לדוגמה, "origin": ["*"] ב-API בפורמט JSON או <Origin>*</Origin> ב-API בפורמט XML. המקור הזה שימושי לבדיקת הגדרות, אבל ברוב המקרים כדאי להגביל את מקורות הבקשות כדי למנוע שימוש לא רצוי במשאבים.

שיקולים נוספים

בטבלה הבאה מפורטים השיקולים שיש להתחשב בהם כששולחים בקשות באמצעות פרטי כניסה או כותרות של בקרת גישה:

מאפיין או כותרת תיאור התנהגות התגובה מה-API בפורמט XML התנהגות התגובה מה-API בפורמט JSON

פרטי כניסה

קובצי cookie, כותרות הרשאות או אישורי לקוח של TLS.

מאפיין או כותרת	תיאור	התנהגות התגובה מה-API בפורמט XML	התנהגות התגובה מה-API בפורמט JSON
פרטי כניסה	קובצי cookie, כותרות הרשאות או אישורי לקוח של TLS.	ֶCloud Storage אף פעם לא מחזיר את הכותרת `Access-Control-Allow-Credentials`. פרטי הכניסה של CORS לא נתמכים על ידי API בפורמט XML.	בבקשות פשוטות, אם בקשת ה-CORS מאושרת, הכותרת `Access-Control-Allow-Credentials` מוגדרת כ-TRUE. בבקשות קדם-הפעלה, אם `Access-Control-Request-Method` ריקה, Cloud Storage מגדיר את `Access-Control-Allow-Credentials` כ-TRUE ודוחה את הבקשה עם `404 - Not Found`.
כותרות חשופות	בבקשות קדם-הפעלה, כותרת הבקשה `Access-Control-Request-Headers` מציינת אילו כותרות בקשת CORS עתידית עשויה לכלול. כותרת התגובה `Access-Control-Expose-Headers` כלולה בתגובת השרת ומציינת ללקוח אילו כותרות יכולות להיות חשופות.	בבקשות פשוטות, ב-`Access-Control-Expose-Headers` מופיעים הערכים של כותרות התגובה בהגדרות ה-CORS.	בבקשות פשוטות, `Access-Control-Expose-Headers` מחזירה את הערכים שצוינו ב-`Access-Control-Request-Headers` אם הם חלק מרשימה של כותרות HTTP נפוצות.

ֶCloud Storage אף פעם לא מחזיר את הכותרת Access-Control-Allow-Credentials. פרטי הכניסה של CORS לא נתמכים על ידי API בפורמט XML.

בבקשות פשוטות, אם בקשת ה-CORS מאושרת, הכותרת Access-Control-Allow-Credentials מוגדרת כ-TRUE.

בבקשות קדם-הפעלה, אם Access-Control-Request-Method ריקה, Cloud Storage מגדיר את Access-Control-Allow-Credentials כ-TRUE ודוחה את הבקשה עם 404 - Not Found.

כותרות חשופות בבקשות קדם-הפעלה, כותרת הבקשה Access-Control-Request-Headers מציינת אילו כותרות בקשת CORS עתידית עשויה לכלול. כותרת התגובה Access-Control-Expose-Headers כלולה בתגובת השרת ומציינת ללקוח אילו כותרות יכולות להיות חשופות. בבקשות פשוטות, ב-Access-Control-Expose-Headers מופיעים הערכים של כותרות התגובה בהגדרות ה-CORS. בבקשות פשוטות, Access-Control-Expose-Headers מחזירה את הערכים שצוינו ב-Access-Control-Request-Headers אם הם חלק מרשימה של כותרות HTTP נפוצות.

מתן הרשאה לקטגוריות לגשת למשאבים חיצוניים

לפעמים רוצים לאפשר לסקריפטים המתארחים ב-Cloud Storage לגשת למשאבים סטטיים המתארחים באתר שמחוץ ל-Cloud Storage. בתרחיש הזה, האתר מציג כותרות CORS כדי לאפשר גישה לתוכן ב-storage.googleapis.com.

השיטה המומלצת היא להקצות קטגוריה ספציפית בשביל הגישה הזו לנתונים. הגישה הזו מונעת מהאתר לחשוף בטעות משאבים סטטיים לכל storage.googleapis.com. לדוגמה, אם רוצים להקצות קטגוריה ייעודית בשם mybucket בשביל גישה לנתונים, צריך שהאתר יגיש את כותרת ה-CORS Access-Control-Allow-Origin: https://mybucket.storage.googleapis.com במקום את Access-Control-Allow-Origin: https://storage.googleapis.com.

תמיכה ב-CORS בצד הלקוח

רוב הדפדפנים משתמשים באובייקט XMLHttpRequest כדי לשלוח בקשה במספר דומיינים. הוספת הכותרות הנכונות והטיפול באינטראקציה של CORS עם השרת מבוצעת על ידי XMLHttpRequest. לא צריך להוסיף קוד חדש כדי להשתמש בתמיכה ב-CORS בקטגוריות של Cloud Storage.

המאמרים הבאים

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