Mehrteilige XML API-Uploads

Auf dieser Seite werden mehrteilige XML API-Uploads in Cloud Storage erläutert. Bei dieser Uploadmethode werden Dateien teilweise hochgeladen und dann mit einer abschließenden Anfrage in einem einzigen Objekt zusammengefasst. Mehrteilige XML API-Uploads sind mit mehrteiligen Amazon S3-Uploads kompatibel.

Übersicht

Mit einem mehrteiligen XML API-Upload können Sie Daten in mehreren Teilen hochladen und dann zu einem endgültigen Objekt zusammenstellen. Dieses Verhalten bietet mehrere Vorteile, insbesondere bei großen Dateien:

• Sie können Teile gleichzeitig hochladen, wodurch der Zeitraum für das Hochladen der Daten komplett verkürzt wird.

• Wenn einer der Uploadvorgänge fehlschlägt, müssen Sie nur einen Teil des gesamten Objekts noch einmal hochladen anstatt von vorn beginnen.

• Da die Gesamtgröße der Datei nicht im Voraus angegeben wird, können Sie mehrteilige XML API-Uploads für Streaming-Uploads oder zum Komprimieren von Daten während des Uploads verwenden.

Ein mehrteiliger XML API-Upload umfasst drei erforderliche Schritte:

1. Starten des Uploads mit einer POST-Anfrage, einschließlich der Angabe aller Metadaten, die das abgeschlossene Objekt haben sollte. Als Antwort wird eine UploadId zurückgegeben, die Sie in allen nachfolgenden Anfragen verwenden, die mit dem Upload verknüpft sind.

2. Hochladen der Daten mit einer oder mehreren PUT-Anfragen.

3. Schließen Sie den Upload mit einer POST-Anfrage ab. Diese Anfrage überschreibt jedes vorhandene Objekt im Bucket mit demselben Namen.

Es gibt keine Beschränkung dafür, wie lange ein mehrteiliger Upload und die hochgeladenen Teile in einem Bucket unvollständig oder inaktiv bleiben.

• Erfolgreich hochgeladene Teile werden auf Ihre monatliche Speichernutzung angerechnet.
• Wenn Sie aufgegebene mehrteilige Uploads vermeiden möchten, verwenden Sie die Verwaltung des Objektlebenszyklus. Damit werden mehrteilige Uploads automatisch entfernt, wenn sie ein bestimmtes Alter erreicht haben.

Hinweise

Die folgenden Einschränkungen gelten für die Verwendung von mehrteiligen XML API-Uploads:

• Es gibt Grenzwerte für die Mindest- und die maximale Größe eines Teils sowie für die Anzahl der Teile, die zum Zusammenstellen des vollständigen Uploads verwendet werden.
• Vorbedingungen werden in den Anfragen nicht unterstützt.
• Für Objekte, die mit dieser Methode hochgeladen wurden, gibt es keine MD5-Hashes.
• Diese Uploadmethode wird in der Google Cloud Console oder der Google Cloud CLI nicht unterstützt.

Beachten Sie bei der Arbeit mit mehrteiligen XML API-Uploads Folgendes:

• Für mehrteilige XML API-Uploads sind spezifische IAM-Berechtigungen erforderlich. Wenn Sie benutzerdefinierte IAM-Rollen verwenden, sollten Sie darauf achten, dass diese Rollen die erforderlichen Berechtigungen haben.

• Sie können zwar einen Upload starten und Teile des Uploads hochladen, die Anfrage zum Abschließen des Uploads schlägt jedoch fehl, wenn Sie ein Objekt mit einem Hold oder einer nicht erfüllten Aufbewahrungsdauer überschreiben.

• Sie können zwar laufende Uploads in einem Bucket auflisten, doch werden nur abgeschlossene Uploads in der normalen Liste der Objekte im Bucket angezeigt.

• Für einen hochgeladenen Teil können Gebühren für vorzeitiges Löschen anfallen, wenn er nie verwendet wird.

Mehrteilige XML API-Uploads in Clientbibliotheken

In diesem Abschnitt finden Sie Informationen zum Ausführen mehrteiliger XML API-Uploads mit Clientbibliotheken, die diese Funktion unterstützen.

/**
 * 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);

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}.")

Nächste Schritte

• Weitere Methoden zum Hochladen von Cloud Storage-Methoden
• Informationen zum abgeschnittenen exponentiellen Backoff und dazu, wann Anfragen wiederholt werden sollen