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.

Vorbereitung

Die Voraussetzungen können je nach verwendetem Tool variieren:

Console

Sie benötigen die entsprechenden IAM-Berechtigungen, um diesen Leitfaden mit der Google Cloud Console abzuschließen. Wenn Sie den Bucket, den Sie zum Streaming aufrufen wollen, in ein Projekt hochladen möchten, das nicht Sie erstellt haben, muss Ihnen der Projektinhaber möglicherweise erst eine Rolle zuweisen, die die erforderlichen Berechtigungen enthält.

Eine Liste der erforderlichen Berechtigungen für bestimmte Aktionen finden Sie unter IAM-Berechtigungen für die Google Cloud Console.

Eine Liste der relevanten Rollen finden Sie unter Cloud Storage-Rollen. Alternativ können Sie eine benutzerdefinierte Rolle erstellen, die spezifische, eingeschränkte Berechtigungen hat.

Befehlszeile

Damit Sie diese Anleitung mit einem Befehlszeilendienstprogramm ausführen können, benötigen Sie die entsprechenden IAM-Berechtigungen. Wenn sich der Bucket, auf den Sie zum Streaming zugreifen möchten, in einem Projekt befindet, das Sie nicht erstellt haben, muss Ihnen der Projektinhaber möglicherweise erst eine Rolle zuweisen, die die erforderlichen Berechtigungen enthält.

Eine Liste der erforderlichen Berechtigungen für bestimmte Aktionen finden Sie unter IAM-Berechtigungen für gcloud storage-Befehle.

Eine Liste der relevanten Rollen finden Sie unter Cloud Storage-Rollen. Alternativ können Sie eine benutzerdefinierte Rolle erstellen, die spezifische, eingeschränkte Berechtigungen hat.

Clientbibliotheken

Sie benötigen die entsprechenden IAM-Berechtigungen, um diesen Leitfaden mit den Cloud Storage-Clientbibliotheken abzuschließen. Wenn Sie den Bucket, den Sie zum Streaming aufrufen wollen, in ein Projekt hochladen möchten, das nicht Sie erstellt haben, muss Ihnen der Projektinhaber möglicherweise erst eine Rolle zuweisen, die die erforderlichen Berechtigungen enthält.

Sofern nicht anders angegeben, werden Clientbibliotheksanfragen über die JSON API gestellt und benötigen die unter IAM-Berechtigungen für JSON-Methoden aufgeführten Berechtigungen. Um zu erfahren, welche JSON API-Methoden aufgerufen werden, wenn Sie Anfragen über eine Clientbibliothek stellen, können Sie die Rohanfragen protokollieren.

Eine Liste der relevanten IAM-Rollen finden Sie unter Cloud Storage-Rollen. Alternativ können Sie eine benutzerdefinierte Rolle erstellen, die spezifische, eingeschränkte Berechtigungen hat.

REST APIs

JSON API

Sie benötigen die entsprechenden IAM-Berechtigungen, um diese Anleitung mit der JSON API abzuschließen. Wenn Sie den Bucket, den Sie zum Streaming aufrufen wollen, in ein Projekt hochladen möchten, das nicht Sie erstellt haben, muss Ihnen der Projektinhaber möglicherweise erst eine Rolle zuweisen, die die erforderlichen Berechtigungen enthält.

Eine Liste der für bestimmte Aktionen erforderlichen Berechtigungen finden Sie unter IAM-Berechtigungen für JSON-Methoden.

Eine Liste der relevanten Rollen finden Sie unter Cloud Storage-Rollen. Alternativ können Sie eine benutzerdefinierte Rolle erstellen, die spezifische, eingeschränkte Berechtigungen hat.

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
```
Wobei:
- 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

Folgen Sie der Anleitung zum Durchführen eines fortsetzbaren Uploads, um einen Streaming-Upload durchzuführen, und beachten Sie dabei die folgenden Punkte:

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 KB 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.

XML API

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

Ein mehrteiliger XML API-Upload
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.

Streaming-Uploads

Prüfsummenvalidierung beim Streaming verwenden

Vorbereitung

Console

Befehlszeile

Clientbibliotheken

REST APIs

JSON API

Upload streamen

Console

Befehlszeile

Clientbibliotheken

C++

C#

Go

Java

Node.js

PHP

Python

Ruby

REST APIs

JSON API

XML API

Nächste Schritte