העלאות מורכבות במקביל

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

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

לתשומת ליבכם

האובייקט הסופי שהעלאה מורכבת מקבילה מאחסנת בקטגוריה הוא אובייקט מורכב, שיש לו רק גיבוב crc32c ולא גיבוב MD5. המשמעות היא שאם תורידו את האובייקט באמצעות אפליקציות של Python, תצטרכו להשתמש ב-crcmod כדי לבצע בדיקות תקינוּת. אפשר להשתמש בהעלאות מורכבות מקבילות רק כשהתנאים הבאים מתקיימים:

  • אם אתם לא צריכים שהאובייקטים שהעליתם יהיו עם גיבוב MD5.

  • אם google-crc32c או crcmod מותקנים אצל המשתמשים שצריכים להוריד את האובייקטים באמצעות Python, כולל משתמשי gsutil.

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

התפקידים הנדרשים

כדי לקבל את ההרשאות שנדרשות לביצוע העלאות מקבילות של אובייקטים מורכבים, צריך לבקש מהאדמין להקצות לכם את התפקיד Storage Object User (roles/storage.objectUser) ב-IAM בקטגוריה.

התפקיד "אדמין של אחסון" (roles/storage.admin) כולל את ההרשאות שנדרשות כדי להעלות, לקרוא ולמחוק מקטעי אובייקטים. הוא גם מכיל את ההרשאה הנדרשת ל-CLI של gcloud כדי לבצע בדיקת תאימות ברמת הקטגוריה עם העלאות מקבילות של קבצים מורכבים. אם אתם לא יכולים לקבל את התפקיד "אדמין של Storage" (roles/storage.admin), אתם עדיין יכולים לבצע העלאות משולבות במקביל באמצעות ה-CLI של gcloud. לשם כך, צריך לקבל את התפקיד "משתמש באובייקט Storage" (roles/storage.objectUser) ולהשבית את המאפיין storage/parallel_composite_upload_compatibility_check. מידע נוסף זמין בכרטיסייה Command line בקטע How tools and APIs use parallel composite uploads.

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

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

איך להשתמש בהעלאות מורכבות מקבילות בכלים שונים ובממשקי API

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

המסוף

אי אפשר לבצע העלאות מורכבות במקביל במסוף Google Cloud .

שורת הפקודה

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

  • ‫storage/parallel_composite_upload_enabled: זהו המאפיין להפעלת העלאות מורכבות מקבילות. אם הערך שלו מוגדר ל-False, ההעלאות המורכבות המקבילות מושבתות והבדיקות של התאימות ברמת הקטגוריה לא מתבצעות. אם הערך שלו מוגדר ל-True או ל-None, ההעלאות המורכבות המקבילות יופעלו לאובייקטים שעומדים בקריטריונים שמוגדרים במאפיינים האחרים, ובדיקות התאימות יופעלו. ערך ברירת המחדל הוא None.

  • ‫storage/parallel_composite_upload_compatibility_check: זהו המאפיין שמפעיל את הבדיקות ברמת הקטגוריה, כדי לוודא תאימות ובטיחות בהעלאות מורכבות מקבילות. אם הערך הוא True, ה-CLI של gcloud שולח בקשת GET למטא-נתונים של קטגוריית היעד לפני שהוא מנסה לבצע העלאה מורכבת מקבילה, ולכן לחשבון המשתמש צריכה להיות ההרשאה storage.buckets.get. ה-CLI של gcloud מבצע העלאות מורכבות מקבילות רק כשכל התנאים הבאים מתקיימים:

    ערך ברירת המחדל הוא True. אם הערך שלו הוא False, ה-CLI של gcloud לא יבצע את בדיקת התאימות.

    אם מגדירים את storage/parallel_composite_upload_compatibility_check ל-False, ההעלאות המורכבות המקבילות לא מושבתות. כאשר storage/parallel_composite_upload_compatibility_check מוגדר ל-False ו-storage/parallel_composite_upload_enabled הוא None או True, ה-CLI של gcloud מדלג על בדיקת הקטגוריה וממשיך ישירות להעלאה משולבת במקביל.

    כדי לדלג על הבדיקה הזו, משביתים את המאפיין storage/parallel_composite_upload_compatibility_check:

    gcloud config set storage/parallel_composite_upload_compatibility_check False

  • ‫storage/parallel_composite_upload_threshold: זהו סף המינימום לגודל הכולל של הקבצים לביצוע העלאה מורכבת מקבילה. הגדרת ברירת המחדל היא ‎150MiB.

  • ‫storage/parallel_composite_upload_component_size: הגודל המקסימלי של כל אובייקט זמני. אם הקובץ הכולל גדול כל כך עד שנדרשים יותר מ-32 מקטעים בגודל הזה, המערכת מתעלמת מהמאפיין הזה.

  • ‫storage/parallel_composite_upload_component_prefix: זוהי התחילית של שם האובייקט, שמשמשת למתן השמות לאובייקטים הזמניים. המאפיין הזה יכול להכיל נתיב מוחלט או נתיב יחסי לאובייקט הסופי. למידע נוסף, ראו תיאור של מאפיינים. ברירת המחדל לתחילית של השם היא הנתיב המוחלט /gcloud/tmp/parallel_composite_uploads/see_gcloud_storage_cp_help_for_details.

כדי לשנות את המאפיינים האלה אפשר ליצור תצורה בעלת שם ולהחיל אותה בכל פקודה באמצעות הדגל --configuration ברמת הפרויקט או בכל הפקודות ב-CLI של gcloud באמצעות הפקודה gcloud config set.

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

השמות של האובייקטים הזמניים נקבעים באופן הבא:

TEMPORARY_PREFIX/RANDOM_VALUE_HEX_DIGEST_COMPONENT_ID

כאשר:

  • ‫TEMPORARY_PREFIX נקבע על ידי המאפיין storage/parallel_composite_upload_component_prefix.
  • ‫RANDOM_VALUE הוא ערך מספרי אקראי.
  • ‫HEX_DIGEST הוא גיבוב (hash) שנגזר מהשם של משאב המקור.
  • ‫COMPONENT_ID הוא המספר הרציף של המקטע.

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

ספריות לקוח

Java

למידע נוסף, קראו את מאמרי העזרה של Cloud Storage Java API.

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

כדי לבצע העלאות מורכבות במקביל, מגדירים את AllowParallelCompositeUpload ל-true. לדוגמה:

import com.google.cloud.storage.transfermanager.ParallelUploadConfig;
import com.google.cloud.storage.transfermanager.TransferManager;
import com.google.cloud.storage.transfermanager.TransferManagerConfig;
import com.google.cloud.storage.transfermanager.UploadResult;
import java.io.IOException;
import java.nio.file.Path;
import java.util.List;

class AllowParallelCompositeUpload {

  public static void parallelCompositeUploadAllowed(String bucketName, List<Path> files)
      throws IOException {
    TransferManager transferManager =
        TransferManagerConfig.newBuilder()
            .setAllowParallelCompositeUpload(true)
            .build()
            .getService();
    ParallelUploadConfig parallelUploadConfig =
        ParallelUploadConfig.newBuilder().setBucketName(bucketName).build();
    List<UploadResult> results =
        transferManager.uploadFiles(files, parallelUploadConfig).getUploadResults();
    for (UploadResult result : results) {
      System.out.println(
          "Upload for "
              + result.getInput().getName()
              + " completed with status "
              + result.getStatus());
    }
  }
}

Node.js

למידע נוסף, קראו את מאמרי העזרה של Cloud Storage Node.js API.

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

ספריית הלקוח Node.js לא תומכת בהעלאות משולבות במקביל. במקום זאת, השתמשו בהעלאות מרובות חלקים ב-API בפורמט XML.

Python

למידע נוסף, קראו את מאמרי העזרה של Cloud Storage Python API.

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

ספריית הלקוח של Python לא תומכת בהעלאות משולבות במקביל. במקום זאת, השתמשו בהעלאות מרובות חלקים ב-API בפורמט XML.

ממשקי API בארכיטקטורת REST

‫API בפורמט JSON

‫API בפורמט JSON תומך בהעלאה מקבילה של מקטעי אובייקטים והרכבה שלהם לאובייקט אחד באמצעות הפעולה compose.

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

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

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

‫API בפורמט XML

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

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

  • הפעולה compose לא משפיעה על האובייקטים במקור.

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

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

פתרון בעיות

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

אי אפשר לבדוק אם קטגוריית היעד תואמת להעלאות מורכבות במקביל

הבעיה: כשמעלים קובץ בגודל 150MiB או יותר באמצעות gcloud storage cp או gcloud storage mv, הפקודה מתעדת את ההודעה הבאה פעם אחת, אבל ההעלאה מסתיימת בהצלחה עם קוד היציאה 0:

ERROR: Cannot check if the destination bucket is compatible for running
parallel composite uploads as the user does not permission to perform GET
operation on the bucket. The operation will be performed without parallel
composite upload feature and hence might perform relatively slower.

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

אם אתם רוצים להשתמש בהעלאות מורכבות במקביל, ודאו שלחשבון המשתמש יש את ההרשאות storage.buckets.get,‏ storage.objects.get ו-storage.objects.delete בקטגוריית היעד. אפשר לתת את ההרשאות האלה באמצעות התפקיד "אדמין באחסון" (roles/storage.admin). לחלופין, אם לחשבון המשתמש כבר יש את ההרשאות storage.objects.get ו-storage.objects.delete באמצעות תפקיד כמו Storage Object User‏ (roles/storage.objectUser), הוא יכול להגדיר את המאפיין storage/parallel_composite_upload_compatibility_check לערך False כדי להשבית את בדיקת התאימות.

‫403: אין גישה ל-storage.objects.get

הבעיה: העלאות של קבצים קטנים מ-150MiB מצליחות, אבל העלאות של קבצים בגודל 150MiB או יותר נכשלות עם קוד היציאה 1 ושגיאה שדומה לזו:

HTTPError 403: PRINCIPAL does not have storage.objects.get access to
the Google Cloud Storage object.

הפתרון: הערך של storage/parallel_composite_upload_compatibility_check מוגדר ל-False והערך של storage/parallel_composite_upload_enabled מוגדר ל-None או ל-True. בהגדרה הזו, ה-CLI של gcloud מדלג על בדיקת התאימות של הקטגוריה וממשיך ישירות להעלאה מקבילה של קובץ מורכב.

האובייקטים הזמניים מועלים בהצלחה כי לחשבון המשתמש יש את ההרשאה storage.objects.create. עם זאת, כדי ליצור את האובייקט הסופי מהאובייקטים הזמניים נדרשת הרשאת storage.objects.get, וכדי למחוק את האובייקטים הזמניים לאחר מכן נדרשת הרשאת storage.objects.delete.

כדי לפתור את הבעיה, אפשר לנסות את אחת מהאפשרויות הבאות:

  • אם אתם לא צריכים העלאות מורכבות מקבילות, השביתו אותן:

    gcloud config set storage/parallel_composite_upload_enabled False

    כל הקבצים מועלים כהעלאות רגילות, וחשבון המשתמש צריך רק את ההרשאות שכלולות בתפקיד Storage Object Creator‏ (roles/storage.objectCreator). אפשר להשאיר את הערך של storage/parallel_composite_upload_compatibility_check כמו שהוא.

  • אם אתם צריכים להשתמש בהעלאות מורכבות מקבילות, תנו לחשבון המשתמש את ההרשאות storage.objects.get ו-storage.objects.delete בקטגוריית היעד. אפשר לתת את ההרשאות האלה באמצעות התפקיד Storage Object User ‏ (roles/storage.objectUser).

אם ההעלאה נכשלה ונשארו אובייקטים זמניים בקטגוריה, מחקו אותם. כברירת מחדל, לאובייקטים זמניים יש את התחילית gcloud/tmp/parallel_composite_uploads/see_gcloud_storage_cp_help_for_details. כדי למחוק אובייקטים זמניים שנוצרו כתוצאה מהעלאה שנכשלה, נדרשת ההרשאה storage.objects.delete.

שימו לב שהפקודה gcloud storage rsync פועלת באופן שונה מ-gcloud storage cp ומ-gcloud storage mv. כשהיעד הוא שורש הקטגוריה, כמו gs://my-bucket, הכלי gcloud storage rsync תמיד דורש את ההרשאה storage.buckets.get כדי לסנכרן עם הקטגוריה, בלי קשר להגדרות של ההעלאה המקבילה של קובצי קומפוזיט. כשהיעד הוא ספריית משנה של קטגוריה, כמו gs://my-bucket/dir/, לא נדרשת ההרשאה storage.buckets.get ל-gcloud storage rsync, כל עוד בדיקת התאימות מושבתת בהגדרות של ההעלאה המורכבת המקבילה. בתרחיש הזה, צריך את ההרשאה storage.objects.get ב-gcloud storage rsync במקום storage.buckets.get.