נקודות קצה למיקום

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

הערה: כדי להריץ עומסי עבודה בתאימות לתקנות International Traffic in Arms Regulations ‏ (ITAR), צריך להשתמש בנקודות קצה אזוריות. מידע על מגבלות השימוש ב-Cloud Storage באופן שעומד בדרישות התאימות ל-ITAR מופיע במאמר הגבלות ומגבלות של תאימות ל-ITAR.

סקירה כללית

נקודות קצה מבוססות-מיקום הן נקודות קצה של בקשות, שמאפשרות לשלוח בקשה רק אם המשאב המושפע נמצא במיקום שצוין בנקודת הקצה. לדוגמה, בקשת מחיקה של קטגוריה בנקודת הקצה https://us-central1-storage.googleapis.com תתבצע רק אם הקטגוריה ממוקמת ב-US-CENTRAL1.

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

הערה: ב-Cloud Load Balancing, ניתוב הבקשות לקטגוריות של Cloud Storage. מתבצע באמצעות נקודות קצה גלובליות של בקשות. לא ניתן להגדיר את Cloud Load Balancing לשימוש בנקודות קצה מבוססות-מיקום.

השימוש בנקודות קצה מבוססות-מיקום מבטיח:

• שהנתונים שמאוחסנים ב-Cloud Storage לא יוצאים מהמיקום שצוין.

• במעבר מהאחסון המקומי אל Google Cloud, פרוטוקול TLS עוצר את הנתונים באזור שנקבע על ידי נקודת הקצה.

כשמשתמשים בנקודות קצה מבוססות-מיקום:

• אתם צריכים לוודא שבקשות שנשלחות לנקודת קצה מבוססות-מיקום יגיעו מהמיקום שנקבע בנקודת הקצה הזו, כדי להבטיח את מיקום הנתונים. לדוגמה, אם אתם משתמשים במכונה וירטואלית של Compute Engine כדי לבצע בקשה לקטגוריה שנמצאת ב-US-CENTRAL1 דרך נקודת הקצה us-central1-storage.googleapis.com, גם המכונה הווירטואלית צריכה להיות ב-US-CENTRAL1.

• אפשר להשתמש בנקודות קצה מבוססות-מיקום רק לביצוע פעולות נתמכות. ביצוע פעולות שלא נתמכות יגרום לשגיאה.

נקודות קצה מבוססות-מיקום תומכות בתעבורה בין אחסון מקומי ל- Google Cloud באמצעות חיבור רשתות או VPN, ובתעבורה בין שירותי Google Cloud (למשל, מ-BigQuery אל Cloud Storage). אין תמיכה בתעבורת נתונים באינטרנט.

פעולות נתמכות

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

אם תנסו לבצע באמצעות נקודת קצה מבוססת-מיקום פעולה שלא נתמכת, Cloud Storage יחזיר קוד שגיאת HTTP 400 עם ההודעה: ‎"This endpoint does not implement this operation. Please use the global endpoint."‎

פעולה	שינוי נתוני האובייקט	תמיכה בשימוש עם נקודות קצה מבוססות-מיקום
כתיבת אובייקטים	כן	כן^1
מחיקת אובייקטים	לא	כן^1
אחזור אובייקטים	כן	כן^1
הכנסת אובייקטים	כן	כן^1
הצגת רשימה של אובייקטים	לא	כן^1
תיקון אובייקטים	לא	כן^1
העתקת אובייקטים	כן	כן^4
כתיבה מחדש של אובייקטים	כן	כן^4
הכנסת קטגוריות	לא	כן^2
מחיקת קטגוריות	לא	כן^3
אחזור קטגוריות	לא	כן^2
תיקון קטגוריות	לא	כן^2
עדכון קטגוריות	לא	כן^2
‏getIamPolicy של קטגוריות	לא	כן^2
‏setIamPolicy של קטגוריות	לא	כן^2
‏testIamPermissions של קטגוריות	לא	כן^2
‏lockRetentionPolicy של קטגוריות	לא	כן^2
‏BucketAccessControls של קטגוריות	לא	כן^2
‏DefaultObjectAccessControls של קטגוריות	לא	כן^2
‏ObjectAccessControls של קטגוריות	לא	כן^2
פעולות של מפתח HMAC	לא	לא
פעולות של חשבון שירות	לא	לא
פעולות של התראות Pub/Sub	משתנה בהתאם לפעולה	לא
פעולות התראה על שינוי אובייקט	משתנה בהתאם לפעולה	לא
פעולות באצווה	משתנה בהתאם לפעולה	לא

^‫1 כדי לבצע את הפעולה הזו באמצעות נקודות קצה מבוססות-מיקום, הקטגוריה שמכילה את האובייקט המושפע צריכה להיות במיקום שצוין בנקודת הקצה. לדוגמה: בקשה למחיקת אובייקט שנשלחת אל us-central1-storage.googleapis.com יכולה לשמש רק כדי למחוק אובייקטים בקטגוריות שממוקמות באזור US-CENTRAL1. אם תנסו למחוק אובייקט במיקום שהוא לא US-CENTRAL1, הפעולה תחזיר את השגיאה NOT_FOUND.

^‫2 כדי לבצע את הפעולה הזו באמצעות נקודות קצה מבוססות-מיקום, הקטגוריה חייבת להיות במיקום שצוין בנקודת הקצה. לדוגמה: בקשה ליצירת קטגוריה שנשלחת אל us-central1-storage.googleapis.com יכולה לשמש רק כדי ליצור קטגוריה באזור US-CENTRAL1. אם תנסו ליצור את הקטגוריה במיקום שהוא לא US-CENTRAL1, הפעולה תחזיר את השגיאה INVALID_ARGUMENT.

^‫3 כדי לבצע את הפעולה הזו באמצעות נקודות קצה מבוססות-מיקום, הקטגוריה חייבת להיות במיקום שצוין בנקודת הקצה. לדוגמה: בקשה למחיקת קטגוריה שנשלחת אל us-central1-storage.googleapis.com יכולה לשמש רק כדי למחוק קטגוריה באזור US-CENTRAL1. אם תנסו למחוק קטגוריה במיקום שהוא לא US-CENTRAL1, הפעולה תחזיר את השגיאה NOT_FOUND.

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

אזורים נתמכים

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

יצירת בקשות

המסוף

במאמר הגבלות ומגבלות של תאימות ל-ITAR מוסבר איך לבצע פעולות באמצעות מסוף Google Cloud באופן שעומד בדרישות התאימות ל-ITAR.

שורת הפקודה

כדי להגדיר את Google Cloud CLI לשימוש בנקודות קצה מבוססות-מיקום:

1. מגדירים את המאפיין api_endpoint_overrides/storage לנקודת הקצה מבוססת-המיקום שבה רוצים להשתמש:

   gcloud config set api_endpoint_overrides/storage https://LOCATION-storage.googleapis.com/

אחרי שמגדירים את המאפיין הזה, אפשר להשתמש בפקודות של ה-CLI של gcloud כרגיל.

אפשר גם להשתמש בנקודות קצה מבוססות-מיקום לפקודות בודדות על ידי הגדרת משתנה הסביבה CLOUDSDK_API_ENDPOINT_OVERRIDES_STORAGE בכל פקודה. לדוגמה:

CLOUDSDK_API_ENDPOINT_OVERRIDES_STORAGE=https://LOCATION-storage.googleapis.com/ gcloud ls gs://my-bucket

ספריות לקוח

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

ממשקי API ל-REST

‏API בפורמט JSON

ביצירת בקשות לנקודות קצה מבוססות-מיקום, משתמשים במזהי ה-URI הבאים:

• בבקשות כלליות של API בפורמט JSON, לא כולל העלאות של אובייקטים, משתמשים בנקודת הקצה הבאה:

  https://LOCATION-storage.googleapis.com

  מחליפים את LOCATION במיקום קטגוריה נתמך. לדוגמה, us-central1.

• כדי להעלות אובייקטים ב-API בפורמט JSON, משתמשים בנקודת הקצה הבאה:

  https://LOCATION-storage.googleapis.com/upload/storage/v1/b/BUCKET_NAME/o

  מחליפים את:

  • ‫LOCATION במיקום קטגוריה נתמך. לדוגמה, us-central1.

  • ‫BUCKET_NAME בשם הקטגוריה שאליה רוצים להעלות אובייקט. לדוגמה, my-example-bucket.

• להורדת אובייקטים ב-API בפורמט JSON משתמשים בנקודת הקצה הבאה:

  https://LOCATION-storage.googleapis.com/download/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME?alt=media

  מחליפים את:

  • ‫LOCATION במיקום קטגוריה נתמך. לדוגמה, us-central1.

  • ‫BUCKET_NAME בשם הקטגוריה שמכילה את האובייקט שרוצים להוריד. לדוגמה, my-example-bucket.

  • ‫OBJECT_NAME בשם האובייקט שרוצים להוריד. לדוגמה, waterfall.png.

הערה: נקודות הקצה ל-API בפורמט JSON תומכות רק בבקשות HTTPS.

‫API בפורמט XML

כשמשתמשים ב-API בפורמט XML כדי לשלוח בקשות לנקודות קצה מבוססות-מיקום, אפשר להשתמש בנקודת קצה בפורמט של מארח וירטואלי או בפורמט של נתיב:

• נקודת קצה בפורמט של מארח וירטואלי:

  https://BUCKET_NAME.LOCATION-storage.googleapis.com

• נקודת קצה בפורמט של נתיב:

  https://LOCATION-storage.googleapis.com/BUCKET_NAME

בשני סוגי נקודות הקצה, צריך להחליף את:

• ‫LOCATION במיקום קטגוריה נתמך. לדוגמה, us-central1.

• ‫BUCKET_NAME בשם קטגוריה תקין. לדוגמה, my-example-bucket.

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

נקודות קצה ל-API בפורמט XML תומכות בהצפנה של שכבת שקע מאובטחת (SSL), ולכן אפשר להשתמש ב-HTTP או ב-HTTPS. מומלץ להשתמש ב-HTTPS, במיוחד אם אתם משתמשים ב-OAuth 2.0 כדי לאמת ב-Cloud Storage.

פורמט תקין של בקשות

כדי לוודא שהבקשות שלכם עומדות בדרישות של כל הכלים ב-Cloud Storage:

• אתם צריכים לוודא שאתם מקודדים בצורה נכונה את התווים המיוחדים שמופיעים בשם האובייקט או במחרוזת השאילתה ב-URI של הבקשה.

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

מגבלות ידועות

נקודות קצה של mTLS לא נתמכות.

הגבלת השימוש בנקודת קצה גלובלית של API

כדי לאכוף את השימוש בנקודות קצה מבוססות-מיקום, אפשר להשתמש באילוץ מדיניות הארגון constraints/gcp.restrictEndpointUsage כדי לחסום בקשות לנקודת קצה גלובלית ל-API. מידע נוסף זמין במאמר הגבלת השימוש בנקודות קצה.