העלאות מרובות חלקים ב-API ל-XML

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

סקירה כללית

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

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

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

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

העלאה מרובת חלקים באמצעות API בפורמט XML כוללת שלושה שלבים:

  1. התחלת ההעלאה באמצעות בקשת POST, הכוללת ציון של כל המטא-נתונים שצריכים להיות לאובייקט השלם. התשובה תחזיר UploadId שבו משתמשים בכל הבקשות הבאות הקשורות להעלאה.

  2. העלאת הנתונים באמצעות בקשת PUT אחת או יותר.

  3. השלמת ההעלאה באמצעות בקשת POST. הבקשה הזו מחליפה כל אובייקט קיים בקטגוריה שיש לו את אותו השם.

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

לתשומת ליבכם

המגבלות הבאות חלות על שימוש בהעלאות מרובות חלקים באמצעות API בפורמט XML:

  • יש מגבלות על הגודל המינימלי של חלק, על הגודל המקסימלי של חלק ועל מספר החלקים שמשמשים להרכבת ההעלאה המלאה.
  • הבקשות לא תומכות בתנאים מוקדמים.
  • לא קיימים גיבובים של MD5 בשביל אובייקטים שהועלו בשיטה הזו.
  • שיטת ההעלאה הזו לא אפשרית במסוף או ב-Google Cloud CLI. Google Cloud

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

איך ספריות לקוח משתמשות בהעלאות מרובות חלקים באמצעות API בפורמט XML

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

ספריות לקוח

Java

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

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

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

Node.js

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

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

אפשר לבצע העלאות מרובות חלקים באמצעות API בפורמט XML באמצעות ה-method‏ uploadFileInChunks. לדוגמה:

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The ID of your GCS bucket
// const bucketName = 'your-unique-bucket-name';

// The path of file to upload
// const filePath = 'path/to/your/file';

// The size of each chunk to be uploaded
// const chunkSize = 32 * 1024 * 1024;

// Imports the Google Cloud client library
const {Storage, TransferManager} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

// Creates a transfer manager client
const transferManager = new TransferManager(storage.bucket(bucketName));

async function uploadFileInChunksWithTransferManager() {
  // Uploads the files
  await transferManager.uploadFileInChunks(filePath, {
    chunkSizeBytes: chunkSize,
  });

  console.log(`${filePath} uploaded to ${bucketName}.`);
}

uploadFileInChunksWithTransferManager().catch(console.error);

Python

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

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

אפשר לבצע העלאות מרובות חלקים באמצעות API בפורמט XML באמצעות ה-method‏ upload_chunks_concurrently. לדוגמה:

def upload_chunks_concurrently(
    bucket_name,
    source_filename,
    destination_blob_name,
    chunk_size=32 * 1024 * 1024,
    workers=8,
):
    """Upload a single file, in chunks, concurrently in a process pool."""
    # The ID of your GCS bucket
    # bucket_name = "your-bucket-name"

    # The path to your file to upload
    # source_filename = "local/path/to/file"

    # The ID of your GCS object
    # destination_blob_name = "storage-object-name"

    # The size of each chunk. The performance impact of this value depends on
    # the use case. The remote service has a minimum of 5 MiB and a maximum of
    # 5 GiB.
    # chunk_size = 32 * 1024 * 1024 (32 MiB)

    # The maximum number of processes to use for the operation. The performance
    # impact of this value depends on the use case. Each additional process
    # occupies some CPU and memory resources until finished. Threads can be used
    # instead of processes by passing `worker_type=transfer_manager.THREAD`.
    # workers=8

    from google.cloud.storage import Client, transfer_manager

    storage_client = Client()
    bucket = storage_client.bucket(bucket_name)
    blob = bucket.blob(destination_blob_name)

    transfer_manager.upload_chunks_concurrently(
        source_filename, blob, chunk_size=chunk_size, max_workers=workers
    )

    print(f"File {source_filename} uploaded to {destination_blob_name}.")


if __name__ == "__main__":
    argparse = argparse.ArgumentParser(
        description="Upload a file to GCS in chunks concurrently."
    )
    argparse.add_argument(
        "--bucket_name", help="The name of the GCS bucket to upload to."
    )
    argparse.add_argument(
        "--source_filename", help="The local path to the file to upload."
    )
    argparse.add_argument(
        "--destination_blob_name", help="The name of the object in GCS."
    )
    argparse.add_argument(
        "--chunk_size",
        type=int,
        default=32 * 1024 * 1024,
        help="The size of each chunk in bytes (default: 32 MiB). The remote\
              service has a minimum of 5 MiB and a maximum of 5 GiB",
    )
    argparse.add_argument(
        "--workers",
        type=int,
        default=8,
        help="The number of worker processes to use (default: 8).",
    )
    args = argparse.parse_args()
    upload_chunks_concurrently(
        args.bucket_name,
        args.source_filename,
        args.destination_blob_name,
        args.chunk_size,
        args.workers,
    )

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