Streaming-Uploads

Cloud Storage unterstützt das Streaming von Daten in einen Bucket, ohne dass die Daten zuerst in einer Datei gespeichert werden müssen. Dies ist hilfreich, wenn Sie Daten hochladen möchten, aber die endgültige Größe zu Beginn des Uploads nicht kennen, z. B. wenn Sie die Upload-Daten aus einem Prozess heraus generieren oder wenn Sie ein Objekt direkt komprimieren.

Prüfsummenvalidierung beim Streaming verwenden

Da eine Prüfsumme nur in der ersten Anfrage eines Uploads bereitgestellt werden kann, ist es häufig nicht möglich, die Prüfsummenvalidierung von Cloud Storage beim Streaming zu verwenden. Es wird empfohlen, immer die Validierung der Prüfsumme zu verwenden, und Sie können dies manuell tun, nachdem ein Streaming-Upload abgeschlossen ist. Die Validierung nach Abschluss der Übertragung bedeutet jedoch, dass beschädigte Daten während der Zeit, die für die Bestätigung der Beschädigung und deren Beseitigung benötigt wird, zugänglich sind.

Wenn Sie eine Validierung der Prüfsumme benötigen, bevor der Upload abgeschlossen ist und die Daten zugänglich sind, sollten Sie keinen Streaming-Upload verwenden. Sie sollten eine andere Uploadoption verwenden, die vor dem Abschluss des Objekts eine Validierung der Prüfsumme durchführt.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen eine der folgenden Rollen zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Streamen von Uploads benötigen:

Bitten Sie bei Uploads mit einer Objektaufbewahrungssperre Ihren Administrator, Ihnen die IAM-Rolle Storage-Objekt-Administrator (roles/storage.objectAdmin) für den Bucket zuzuweisen.
In allen anderen Fällen bitten Sie Ihren Administrator, Ihnen die IAM-Rolle Storage-Objekt-Nutzer (roles/storage.objectUser) für den Bucket zuzuweisen.

Diese vordefinierten Rollen enthalten die Berechtigungen, die zum Streamen von Uploads in Cloud Storage erforderlich sind. Erweitern Sie den Abschnitt Erforderliche Berechtigungen, um die erforderlichen Berechtigungen anzuzeigen:

Erforderliche Berechtigungen

storage.objects.create
storage.objects.delete

Diese Berechtigung ist nur für Uploads erforderlich, die ein vorhandenes Objekt überschreiben.

storage.objects.get
storage.objects.list

Diese Berechtigung ist nur erforderlich, um mit der Google Cloud CLI die Anleitungen auf dieser Seite auszuführen.

storage.objects.setRetention
- Diese Berechtigung ist nur für Uploads erforderlich, die eine Objektaufbewahrungssperre enthalten.

Sie können diese Berechtigungen auch mit anderen vordefinierten Rollen oder benutzerdefinierten Rollen erhalten.

Informationen zum Zuweisen von Rollen für Buckets finden Sie unter IAM mit Buckets verwenden.

Upload streamen

Die folgenden Beispiele zeigen, wie ein Streaming-Upload von einem Prozess zu einem Cloud Storage-Objekt durchgeführt wird:

Console

Die Google Cloud Console unterstützt keine Streaming-Uploads. Verwenden Sie stattdessen die gcloud CLI.

Befehlszeile

Senden Sie die Daten über eine Pipeline an den Befehl gcloud storage cp und verwenden Sie bei der Quell-URL einen Bindestrich.
```
PROCESS_NAME | gcloud storage cp - gs://BUCKET_NAME/OBJECT_NAME
```
Dabei gilt:
- PROCESS_NAME ist der Name des Prozesses, von dem Sie Daten erheben. Beispiel: collect_measurements
- BUCKET_NAME ist der Name des Buckets, der das Objekt enthält. Beispiel: my_app_bucket.
- OBJECT_NAME ist der Name des Objekts, das aus den Daten erstellt wird. Beispiel: data_measurements

Clientbibliotheken

C++

Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage C++ 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.

namespace gcs = ::google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& object_name, int desired_line_count) {
  std::string const text = "Lorem ipsum dolor sit amet";
  gcs::ObjectWriteStream stream =
      client.WriteObject(bucket_name, object_name);

  for (int lineno = 0; lineno != desired_line_count; ++lineno) {
    // Add 1 to the counter, because it is conventional to number lines
    // starting at 1.
    stream << (lineno + 1) << ": " << text << "\n";
  }

  stream.Close();

  StatusOr<gcs::ObjectMetadata> metadata = std::move(stream).metadata();
  if (!metadata) throw std::move(metadata).status();
  std::cout << "Successfully wrote to object " << metadata->name()
            << " its size is: " << metadata->size()
            << "\nFull metadata: " << *metadata << "\n";
}

C#

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


using Google.Cloud.Storage.V1;
using System;
using System.IO;

public class UploadFileSample
{
    public void UploadFile(
        string bucketName = "your-unique-bucket-name",
        string localPath = "my-local-path/my-file-name",
        string objectName = "my-file-name")
    {
        var storage = StorageClient.Create();
        using var fileStream = File.OpenRead(localPath);
        storage.UploadObject(bucketName, objectName, null, fileStream);
        Console.WriteLine($"Uploaded {objectName}.");
    }
}

Go

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

import (
	"bytes"
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/storage"
)

// streamFileUpload uploads an object via a stream.
func streamFileUpload(w io.Writer, bucket, object string) error {
	// bucket := "bucket-name"
	// object := "object-name"
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %w", err)
	}
	defer client.Close()

	b := []byte("Hello world.")
	buf := bytes.NewBuffer(b)

	ctx, cancel := context.WithTimeout(ctx, time.Second*50)
	defer cancel()

	// Upload an object with storage.Writer.
	wc := client.Bucket(bucket).Object(object).NewWriter(ctx)
	wc.ChunkSize = 0 // note retries are not supported for chunk size 0.

	if _, err = io.Copy(wc, buf); err != nil {
		return fmt.Errorf("io.Copy: %w", err)
	}
	// Data can continue to be added to the file until the writer is closed.
	if err := wc.Close(); err != nil {
		return fmt.Errorf("Writer.Close: %w", err)
	}
	fmt.Fprintf(w, "%v uploaded to %v.\n", object, bucket)

	return nil
}

Java

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


import com.google.cloud.WriteChannel;
import com.google.cloud.storage.BlobId;
import com.google.cloud.storage.BlobInfo;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;
import java.io.IOException;
import java.nio.ByteBuffer;
import java.nio.charset.StandardCharsets;

public class StreamObjectUpload {

  public static void streamObjectUpload(
      String projectId, String bucketName, String objectName, String contents) throws IOException {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The ID of your GCS bucket
    // String bucketName = "your-unique-bucket-name";

    // The ID of your GCS object
    // String objectName = "your-object-name";

    // The string of contents you wish to upload
    // String contents = "Hello world!";

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
    BlobId blobId = BlobId.of(bucketName, objectName);
    BlobInfo blobInfo = BlobInfo.newBuilder(blobId).build();
    byte[] content = contents.getBytes(StandardCharsets.UTF_8);
    try (WriteChannel writer = storage.writer(blobInfo)) {
      writer.write(ByteBuffer.wrap(content));
      System.out.println(
          "Wrote to " + objectName + " in bucket " + bucketName + " using a WriteChannel.");
    }
  }
}

Node.js

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

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

// The new ID for your GCS file
// const destFileName = 'your-new-file-name';

// The content to be uploaded in the GCS file
// const contents = 'your file content';

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

// Import Node.js stream
const stream = require('stream');

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

// Get a reference to the bucket
const myBucket = storage.bucket(bucketName);

// Create a reference to a file object
const file = myBucket.file(destFileName);

// Create a pass through stream from a string
const passthroughStream = new stream.PassThrough();
passthroughStream.write(contents);
passthroughStream.end();

async function streamFileUpload() {
  passthroughStream.pipe(file.createWriteStream()).on('finish', () => {
    // The file upload is complete
  });

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

streamFileUpload().catch(console.error);

PHP

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

use Google\Cloud\Storage\StorageClient;
use Google\Cloud\Storage\WriteStream;

/**
 * Upload a chunked file stream.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 * @param string $objectName The name of your Cloud Storage object.
 *        (e.g. 'my-object')
 * @param string $contents The contents to upload via stream chunks.
 *        (e.g. 'these are my contents')
 */
function upload_object_stream(string $bucketName, string $objectName, string $contents): void
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $writeStream = new WriteStream(null, [
        'chunkSize' => 1024 * 256, // 256KB
    ]);
    $uploader = $bucket->getStreamableUploader($writeStream, [
        'name' => $objectName,
    ]);
    $writeStream->setUploader($uploader);
    $stream = fopen('data://text/plain,' . $contents, 'r');
    while (($line = stream_get_line($stream, 1024 * 256)) !== false) {
        $writeStream->write($line);
    }
    $writeStream->close();

    printf('Uploaded %s to gs://%s/%s' . PHP_EOL, $contents, $bucketName, $objectName);
}

Python

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

from google.cloud import storage


def upload_blob_from_stream(bucket_name, file_obj, destination_blob_name):
    """Uploads bytes from a stream or other file-like object to a blob."""
    # The ID of your GCS bucket
    # bucket_name = "your-bucket-name"

    # The stream or file (file-like object) from which to read
    # import io
    # file_obj = io.BytesIO()
    # file_obj.write(b"This is test data.")

    # The desired name of the uploaded GCS object (blob)
    # destination_blob_name = "storage-object-name"

    # Construct a client-side representation of the blob.
    storage_client = storage.Client()
    bucket = storage_client.bucket(bucket_name)
    blob = bucket.blob(destination_blob_name)

    # Rewind the stream to the beginning. This step can be omitted if the input
    # stream will always be at a correct position.
    file_obj.seek(0)

    # Upload data from the stream to your bucket.
    blob.upload_from_file(file_obj)

    print(
        f"Stream data uploaded to {destination_blob_name} in bucket {bucket_name}."
    )

Ruby

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


# The ID of your GCS bucket
# bucket_name = "your-unique-bucket-name"

# The stream or file (file-like object) from which to read
# local_file_obj = StringIO.new "This is test data."

# Name of a file in the Storage bucket
# file_name   = "some_file.txt"

require "google/cloud/storage"

storage = Google::Cloud::Storage.new
bucket  = storage.bucket bucket_name

local_file_obj.rewind
bucket.create_file local_file_obj, file_name

puts "Stream data uploaded to #{file_name} in bucket #{bucket_name}"

REST APIs

JSON API

Verwenden Sie eine der folgenden Methoden, um einen Streaming-Upload durchzuführen:

Ein fortsetzbarer Upload mit den folgenden Anpassungen:
- Verwenden Sie mehrere Blockuploads, wenn Sie die Dateidaten hochladen.
- Da Sie die Gesamtgröße der Dateien erst kennen, wenn Sie beim letzten Block angekommen sind, verwenden Sie im Content-Range-Header der Zwischenblöcke ein * für die Gesamtgröße der Datei.
  
  Wenn beispielsweise der erste Block, den Sie hochladen, eine Größe von 512 KiB hat, hat der Header Content-Range für den Block den Wert bytes 0-524287/*. Wenn bei Ihrem Upload nach dem Hochladen des ersten Blocks noch 64.000 Byte verbleiben, senden Sie danach einen letzten Block, der die verbleibenden Byte enthält und einen Content-Range-Header mit dem Wert bytes 524288-588287/588288 hat.
Ein Einzelanfrage-Upload mit den folgenden Anpassungen:
- Fügen Sie eine Transfer-Encoding: chunked-Überschrift ein und schließen Sie die Content-Length-Überschrift aus.
- Erstellen Sie die Anfrage gemäß der Spezifikation und senden Sie die Objektdaten in Blöcken, sobald sie verfügbar sind.

XML API