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 Beschränkungen für die Mindestgröße eines Teils, die maximale Größe eines Teils und die Anzahl der Teile, die zum Zusammenstellen des abgeschlossenen 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:

So verwenden Clientbibliotheken mehrteilige XML API-Uploads

Dieser Abschnitt enthält Informationen zum Ausführen mehrteiliger XML API-Uploads mit Clientbibliotheken, die diese unterstützen.

Clientbibliotheken

Java

Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage Java API.

Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Cloud Storage zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.

Die Java-Clientbibliothek unterstützt keine mehrteiligen XML API-Uploads. Verwenden Sie stattdessen parallele zusammengesetzte Uploads.

Node.js

Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage Node.js API.

Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Cloud Storage zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.

Sie können mehrteilige XML API-Uploads mithilfe der Methode uploadFileInChunks ausführen. Beispiel:

/**
 * 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 fileName = '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

Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage Python API.

Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Cloud Storage zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.

Sie können mehrteilige XML API-Uploads mithilfe der Methode upload_chunks_concurrently ausführen. Beispiel:

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