הסבר על אובייקטים ב-Cloud Storage

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

אובייקטים

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

לאובייקטים יש שני רכיבים: נתוני אובייקט ומטא-נתונים של אובייקט. נתונים של אובייקט הם בדרך כלל קובץ שרוצים לאחסן ב-Cloud Storage, והוא אטום לחלוטין מבחינת Cloud Storage. מטא-נתונים של אובייקט הם אוסף של צמדי שם-ערך שמתארים תכונות שונות של האובייקט.

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

אפשר להשתמש ברשימות של בקרת גישה (ACL) כדי לשלוט בגישה לאובייקטים ספציפיים. אפשר גם להשתמש בניהול זהויות והרשאות גישה (IAM) כדי לשלוט בגישה לכל האובייקטים בקטגוריה או בתיקייה מנוהלת.

שיקולים לגבי שמות

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

דרישות כלליות

  • שמות אובייקט יכולים להכיל כל רצף של תווי Unicode תקפים.
  • שמות אובייקט לא יכולים להכיל תו של חזרה לתחילת השורה או תו של מעבר שורה.
    • שימו לב: לוכסנים הפוכים שנשלחים דרך ממשקים כמו ה-CLI של gcloud ומסוף, עוברים escape מאחורי הקלעים. Cloud de Confiance לדוגמה, \n הופך ל-\\n. ההגבלה על החזרת כרכרה והזנת שורה מתייחסת אך ורק לתווי בריחה של ANSI.
  • שמות של אובייקטים לא יכולים להתחיל ב-.well-known/acme-challenge/.
  • אי אפשר לתת לאובייקטים את השם . או ...

מגבלות גודל אובייקט ספציפיות למרחב שמות

הגודל המקסימלי של שם אובייקט משתנה בהתאם למרחב השמות של הקטגוריה:

  • גודל שם האובייקט בקטגוריה עם מרחב שמות שטוח: 1 עד 1,024 בייטים בקידוד UTF-8.

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

    • ‫Folder name: שם התיקייה שבה נמצא האובייקט. הגודל המקסימלי של שם התיקייה הוא 512 בייטים בקידוד UTF-8.
    • שם בסיס: שם האובייקט שנמצא בתיקייה. הגודל המקסימלי של שם הבסיס הוא 512 בייטים בקידוד UTF-8.

    לדוגמה, הנתיב my-folder/my-object.txt מייצג אובייקט עם שם בסיס my-object.txt שמאוחסן בתיקייה בשם my-folder/.

המלצות

מומלץ מאוד ששמות האובייקטים שלכם לא יכללו:

  • תווי בקרה שהם לא חוקיים ב-XML 1.0 ‏(‎#x7F–#x84 ו-‎ #x86–#x9F). התווים האלה גורמים לבעיות בהצגת רשימות באמצעות XML כשאתם מנסים להציג את רשימת האובייקטים.
  • התו #. פקודות Google Cloud CLI מפרשות שמות של אובייקטים שמסתיימים ב-#NUMERIC_STRING כמזהי גרסה, ולכן הוספה של # בשמות של אובייקטים יכולה לגרום לכך שיהיה קשה או בלתי אפשרי לבצע פעולות באובייקטים כאלה עם גרסאות באמצעות ה-CLI של gcloud.
  • התווים [,‏ ],‏ * או ?. פקודות Google Cloud CLI מפרשות את התווים האלה כתווים כלליים לחיפוש. לכן אם כוללים אותם בשמות של אובייקטים, קשה או בלתי אפשרי לבצע פעולות עם תווים כלליים לחיפוש. בנוסף, * ו-? אינם תווים תקינים לשמות קבצים ב-Windows.
  • התווים :, ", <, > או |. הם לא תווים תקינים לשמות קבצים ב-Windows. לכן אי אפשר להוריד אובייקט שהתווים האלה כלולים בשמו לקובץ Windows, אלא אם כן ה-method של ההורדה כוללת שינוי שם לקובץ Windows שנוצר. התו /, על אף שהוא גם לא תו תקין לשמות קבצים ב-Windows, מתאים בדרך כלל לשימוש בשמות אובייקטים כדי לחקות מבנה ספרייה. כלים כמו Google Cloud CLI ממירים את התו הזה אוטומטית ל-\ כאשר מורידים קובץ לסביבת Windows.
  • רצפי התווים ./ ו-../. רצפי התווים האלה יוצרים תיקיות מדומה באמצעות נקודה אחת או שתי נקודות בשם התיקייה, כמו folder/./object.txt או folder/../object.txt. עם זאת, כשמורידים תיקייה, ספריות הלקוח ו-CLI של gcloud מפרשים מקטעי נתיב שמכילים רק נקודות כנתיבי קבצים יחסיים. המשמעות של ההתנהגות הזו היא שאובייקטים עלולים להידרס או שההורדה שלהם עלולה להיכשל.
    • נקודה אחת בקטע הנתיב מתפרשת כספרייה הנוכחית. לדוגמה, נניח שהורדתם את האובייקטים my-object.txt ו-./my-object.txt לאותו יעד. האובייקט הראשון יורד אל /destination-directory/my-object.txt. ההפניה . באובייקט השני נפתרת והנתיב האפקטיבי משתנה מ-/destination-directory/./my-object.txt ל-/destination-directory/my-object.txt, וכך מחליף את האובייקט השני שכבר קיים באותו נתיב.
    • שתי נקודות ברצף בקטע הנתיב מתפרשות כספריית האב. אם הנתיב הסופי של אובייקט שהורד נמצא מחוץ לספריית היעד, האובייקט לא יורד. האובייקטים שלא ניתן להוריד מוחזרים בתגובה לבקשה של ספריית הורדות.
  • מידע רגיש או פרטים אישיים מזהים (PII). שמות של אובייקטים גלויים באופן נרחב יותר מאשר נתוני אובייקטים. לדוגמה, שמות של אובייקטים מופיעים בכתובות URL של האובייקט וברשימת האובייקטים בקטגוריה.

אי אפשר לשנות שמות של אובייקטים קיימים באופן ישיר, אבל אפשר לשנות שם של אובייקט באופן עקיף על ידי העתקה ומחיקה של האובייקט המקורי.

מרחב השמות של אובייקטים

אפשר לאחסן אובייקטים במרחבי השמות הבאים:

מרחב שמות שטוח

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

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

לדוגמה, אם יוצרים אובייקט בשם folder1/file.txt בקטגוריה your-bucket, הנתיב לאובייקט הוא your-bucket/folder1/file.txt, ולא מאוחסנת ב-Cloud Storage תיקייה בשם folder1. מנקודת המבט של Cloud Storage, המחרוזת folder1/ היא חלק משם האובייקט.

עם זאת, מכיוון שהאובייקט מכיל / בשם שלו, חלק מהכלים מיישמים את המראה של תיקיות. לדוגמה, כשמשתמשים במסוף Cloud de Confiance , אפשר לנווט לאובייקט folder1/file1.txt כאילו הוא אובייקט בשם file1.txt בתיקייה בשם folder1. באופן דומה, אפשר ליצור תיקייה מנוהלת בשם folder1, ואז file1.txt יהיה כפוף למדיניות הגישה שהוגדרה בתיקייה המנוהלת הזו.

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

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

תיקיות מדומות

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

המסוף

מסוף Cloud de Confiance יוצר מצג חזותי של תיקיות שדומה למנהל הקבצים והתיקיות המקומי.

במסוף Cloud de Confiance אפשר ליצור תיקייה ריקה בתוך קטגוריה, או להעלות תיקייה קיימת.

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

כדי ליצור תיקייה:

  1. במסוף Cloud de Confiance , נכנסים לדף Buckets של Cloud Storage.

    כניסה לדף Buckets

  2. עוברים לקטגוריה.

  3. לוחצים על Create folder כדי ליצור תיקייה חדשה ריקה, או על Upload folder כדי להעלות תיקייה קיימת.

שורת הפקודה

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

כדי ליצור אשליה של עץ קבצים היררכי, ה-CLI של gcloud מחיל את הכללים הבאים כדי לקבוע אם יש להתייחס לכתובת היעד בפקודה כשם אובייקט או כתיקייה:

  1. אם כתובת היעד מסתיימת בתו /, פקודות ה-CLI של gcloud יתייחסו לכתובת היעד כתיקייה. לדוגמה, שימוש בפקודה הבאה, שבה your-file הוא שם של קובץ:

    gcloud storage cp your-file gs://your-bucket/abc/

    כתוצאה מהפקודה הזו, Cloud Storage יוצר אובייקט בשם abc/your-file בקטגוריה your-bucket.

  2. אם מעתיקים כמה קובצי מקור לכתובת יעד, באמצעות הדגל --recursive או תו כללי כמו **, ה-CLI של gcloud מתייחס לכתובת היעד כתיקייה. לדוגמה, שימוש בפקודה הבאה, שבה top-dir היא תיקייה שמכילה קבצים כמו file1 ו-file2:

    gcloud storage cp top-dir gs://your-bucket/abc --recursive

    כתוצאה מהפקודה הזו, Cloud Storage יוצר את האובייקטים abc/top-dir/file1 ו-abc/top-dir/file2 בקטגוריה your-bucket.

  3. אם אף אחד מהכללים האלה לא רלוונטי, ה-CLI של gcloud בודק את האובייקטים שבקטגוריה כדי לקבוע אם כתובת היעד היא שם של אובייקט או תיקייה. לדוגמה, שימוש בפקודה הבאה שבה your-file הוא שם של קובץ:

    gcloud storage cp your-file gs://your-bucket/abc

    ה-CLI של gcloud שולח בקשה להצגת רשימה של אובייקטים בשביל your-bucket, באמצעות התו המפריד / וגם prefix=abc‎, כדי לקבוע אם יש אובייקטים ב-your-bucket שהנתיב שלהם מתחיל ב-abc/. אם כן, ה-CLI של gcloud מתייחס ל-abc/ כשם של תיקייה, והפקודה יוצרת את האובייקט abc/your-file בקטגוריה your-bucket. אחרת, ה-CLI של gcloud יוצר את האובייקט abc ב-your-bucket.

הגישה הזו, שמבוססת על כללים, שונה מאופן הפעולה של כלים רבים, שיוצרים אובייקטים בגודל 0 בייט כדי לסמן את הקיום של התיקיות. ה-CLI של gcloud מבין כמה מוסכמות שבהן משתמשים הכלים האלה, כמו המוסכמה של הוספת _$folder$ בסוף שם האובייקט בגודל 0 בייט, אבל הוא לא זקוק לאובייקטי סימון כאלה כדי לממש התנהגות של מתן שמות שתואמת לפקודות UNIX.

בנוסף לכללים האלה, האופן שבו ה-CLI של gcloud מטפל בקובצי מקור תלוי בשימוש בדגל --recursive. אם משתמשים בדגל, ה-CLI של gcloud בונה שמות של אובייקטים שמשקפים את מבנה ספריית המקור, החל מנקודת העיבוד הרקורסיבי. לדוגמה, שימוש בפקודה הבאה, שבה home/top-dir היא תיקייה שמכילה קבצים כמו file1 ו-sub-dir/file2:

gcloud storage cp home/top-dir gs://your-bucket --recursive

כתוצאה מהפקודה הזו, Cloud Storage יוצר את האובייקטים top-dir/file1 ו-top-dir/sub-dir/file2 בקטגוריה your-bucket.

לעומת זאת, אם מעתיקים בלי הדגל --recursive, גם אם מעתיקים כמה קבצים בגלל נוכחות של תו כללי לחיפוש כמו **, התוצאה היא אובייקטים ששמם הוא רכיב הנתיב הסופי של קובצי המקור. לדוגמה, אם נניח שוב ש-home/top-dir היא תיקייה שמכילה קבצים כמו file1 ו-sub-dir/file2, אז הפקודה:

gcloud storage cp home/top-dir/** gs://your-bucket

יוצרת אובייקט בשם file1 ואובייקט בשם file2 בקטגוריה your-bucket.

ניסיונות חוזרים ומתן שמות

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

לדוגמה, שימוש בפקודה הבאה, שבה יש תיקיות משנה ב-your-dir/, כמו dir1 ו-dir2, ובשתי תיקיות המשנה קיים הקובץ abc:

gcloud storage cp ./your-dir gs://your-bucket/new --recursive

אם הנתיב gs://your-bucket/new עדיין לא קיים, ה-CLI של gcloud ייצור את האובייקטים הבאים בניסיון המוצלח הראשון:

new/dir1/abc
new/dir2/abc

עם זאת, בניסיון הבא של אותה פקודה, ה-CLI של gcloud ייצור את האובייקטים הבאים:

new/your-dir/dir1/abc
new/your-dir/dir2/abc

כדי שה-CLI של gcloud יפעל באופן עקבי בכל ניסיון, מומלץ לבצע את הפעולות הבאות:

  1. הוספה של קו נטוי בסוף כתובת היעד כדי שה-CLI של gcloud תמיד יתייחס אליה כתיקייה.

  2. שימוש ב-gcloud storage rsync. מכיוון ש-rsync לא משתמש בכללי cp-defined של Unix למתן שמות לתיקיות, הוא עובד בעקביות גם אם תיקיית המשנה של היעד קיימת וגם אם לא.

הערות נוספות

  • אי אפשר ליצור אובייקט בגודל אפס-בייט כדי לחקות תיקייה ריקה באמצעות ה-CLI של gcloud.

  • כשמורידים למערכת קבצים מקומית, ה-CLI של gcloud מדלג על אובייקטים שהשם שלהם מסתיים בתו /, כי אי אפשר ליצור קובץ שמסתיים בתו / ב-Linux וב-macOS.

  • אם משתמשים בסקריפטים כדי לבנות נתיבי קבצים על ידי שילוב נתיבי משנה, שימו לב שבגלל ש-/ הוא רק תו שבמקרה מופיע בשם האובייקט, רכיבי ה-CLI מפרשים את gs://your-bucket/folder/ כאובייקט אחר מ-gs://your-bucket/folder.

‫API בארכיטקטורת REST

API ל-JSON

לא קיימות תיקיות ב-API בפורמט JSON. אפשר לצמצם את האובייקטים שמציגים ברשימה ולדמות תיקיות באמצעות הפרמטרים של שאילתה prefix ו-delimiter.

לדוגמה, כדי להציג רשימה של כל האובייקטים בקטגוריה my-bucket עם התוספת לשם המאפיין folder/subfolder/, שולחים בקשה להצגת רשימה של אובייקטים באמצעות כתובת ה-URL הבאה:

"https://storage.s3nsapis.fr/storage/v1/b/my-bucket/o?prefix=folder/subfolder/"

‫API בפורמט XML

לא קיימות תיקיות ב-API בפורמט XML, אבל אפשר לצמצם את האובייקטים שמציגים ברשימה ולדמות תיקיות באמצעות הפרמטרים של שאילתה prefix ו-delimiter.

לדוגמה, כדי להציג רשימה של כל האובייקטים בקטגוריה my-bucket עם התוספת לשם המאפיין folder/subfolder/, שולחים בקשה להצגת רשימה של אובייקטים באמצעות כתובת ה-URL הבאה:

"https://storage.s3nsapis.fr/my-bucket?prefix=folder/subfolder/"

הסרת תיקיות מדומה

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

עם זאת, אם השתמשתם בכלי שיוצר אובייקטים בגודל אפס בייט בתור placeholders של תיקיות, כמו מסוף Cloud de Confiance , אתם צריכים למחוק את האובייקט בגודל אפס בייט כדי להסיר את התיקייה.

מרחב שמות היררכי

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

אובייקטים שאינם ניתנים לשינוי

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

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

שימו לב שיש מגבלה של פעם בשנייה להחלפה מהירה של אותו אובייקט. החלפת אותו אובייקט בתדירות גבוהה יותר עלולה לגרום לשגיאות 429 Too Many Requests. מומלץ לתכנן את האפליקציה כך שנתונים של אובייקט מסוים לא יועלו יותר מפעם בשנייה, ולטפל בשגיאות 429 Too Many Requests אקראיות באמצעות אסטרטגיית ניסיון חוזר של השהיה מעריכית לפני ניסיון חוזר (exponential backoff).

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