Streaming-Downloads

Cloud Storage unterstützt das Streaming von Daten aus einem Bucket zu einem Prozess, ohne dass die Daten zuerst in einer Datei gespeichert werden müssen.

Prüfsummenvalidierung beim Streaming verwenden

Sie sollten keinen Streaming-Download verwenden, wenn Sie eine Validierung der Prüfsumme benötigen, bevor die Daten zugänglich sind. Dies liegt daran, dass Streaming-Downloads den Header Range verwenden und Cloud Storage keine Validierung der Prüfsumme für solche Anfragen durchführt.

Es wird empfohlen, immer die Validierung der Prüfsumme zu verwenden, und Sie können dies manuell tun, nachdem ein Streaming-Download abgeschlossen ist. Die Validierung nach Abschluss des Downloads 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.

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.

Download streamen

Die folgenden Beispiele zeigen, wie Sie einen Download von einem Cloud Storage-Objekt in einen Prozess durchführen:

Console

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

Befehlszeile

Führen Sie den Befehl gcloud storage cp mit einem Bindestrich für die Ziel-URL aus und senden Sie die Daten anschließend über eine Pipeline an den Prozess.
```
gcloud storage cp gs://BUCKET_NAME/OBJECT_NAME - | PROCESS_NAME
```
Wobei:
- BUCKET_NAME ist der Name des Buckets, der das Objekt enthält. Beispiel: my_app_bucket.
- OBJECT_NAME ist der Name des Objekts, das Sie zum Prozess streamen. Beispiel: data_measurements
- PROCESS_NAME ist der Name des Prozesses, an den Sie Daten senden. Beispiel: analyze_data.

Sie können auch Daten von einem Cloud Storage-Objekt an einen Standard-Linux-Befehl wie sort streamen:

gcloud storage cp gs://my_app_bucket/data_measurements - | sort

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;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& object_name) {
  gcs::ObjectReadStream stream = client.ReadObject(bucket_name, object_name);

  int count = 0;
  std::string line;
  while (std::getline(stream, line, '\n')) {
    ++count;
  }
  if (stream.bad()) throw google::cloud::Status(stream.status());

  std::cout << "The object has " << count << " lines\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 DownloadFileSample
{
    public void DownloadFile(
        string bucketName = "your-unique-bucket-name",
        string objectName = "my-file-name",
        string localPath = "my-local-path/my-file-name")
    {
        var storage = StorageClient.Create();
        using var outputFile = File.OpenWrite(localPath);
        storage.DownloadObject(bucketName, objectName, outputFile);
        Console.WriteLine($"Downloaded {objectName} to {localPath}.");
    }
}

Go

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


import (
	"context"
	"fmt"
	"io"
	"io/ioutil"
	"time"

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

// downloadFileIntoMemory downloads an object.
func downloadFileIntoMemory(w io.Writer, bucket, object string) ([]byte, error) {
	// bucket := "bucket-name"
	// object := "object-name"
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return nil, fmt.Errorf("storage.NewClient: %w", err)
	}
	defer client.Close()

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

	rc, err := client.Bucket(bucket).Object(object).NewReader(ctx)
	if err != nil {
		return nil, fmt.Errorf("Object(%q).NewReader: %w", object, err)
	}
	defer rc.Close()

	data, err := ioutil.ReadAll(rc)
	if err != nil {
		return nil, fmt.Errorf("ioutil.ReadAll: %w", err)
	}
	fmt.Fprintf(w, "Blob %v downloaded.\n", object)
	return data, nil
}

Java

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


import com.google.cloud.ReadChannel;
import com.google.cloud.storage.BlobId;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;
import com.google.common.io.ByteStreams;
import java.io.IOException;
import java.nio.channels.FileChannel;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.nio.file.StandardOpenOption;

public class StreamObjectDownload {

  public static void streamObjectDownload(
      String projectId, String bucketName, String objectName, String targetFile)
      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 path to the file to download the object to
    // String targetFile = "path/to/your/file";
    Path targetFilePath = Paths.get(targetFile);

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
    try (ReadChannel reader = storage.reader(BlobId.of(bucketName, objectName));
        FileChannel targetFileChannel =
            FileChannel.open(targetFilePath, StandardOpenOption.WRITE)) {

      ByteStreams.copy(reader, targetFileChannel);

      System.out.println(
          "Downloaded object "
              + objectName
              + " from bucket "
              + bucketName
              + " to "
              + targetFile
              + " using a ReadChannel.");
    }
  }
}

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 ID of your GCS file
// const fileName = 'your-file-name';

// The filename and file path where you want to download the file
// const destFileName = '/local/path/to/file.txt';

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

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

async function streamFileDownload() {
  // The example below demonstrates how we can reference a remote file, then
  // pipe its contents to a local file.
  // Once the stream is created, the data can be piped anywhere (process, sdout, etc)
  await storage
    .bucket(bucketName)
    .file(fileName)
    .createReadStream() //stream is created
    .pipe(fs.createWriteStream(destFileName))
    .on('finish', () => {
      // The file download is complete
    });

  console.log(
    `gs://${bucketName}/${fileName} downloaded to ${destFileName}.`
  );
}

streamFileDownload().catch(console.error);

PHP

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

use Google\Cloud\Storage\StorageClient;

/**
 * Download an object from Cloud Storage and save it as a local file.
 *
 * @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 $destination The local destination to save the object.
 *        (e.g. '/path/to/your/file')
 */
function download_object(string $bucketName, string $objectName, string $destination): void
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $object = $bucket->object($objectName);
    $object->downloadToFile($destination);
    printf(
        'Downloaded gs://%s/%s to %s' . PHP_EOL,
        $bucketName,
        $objectName,
        basename($destination)
    );
}

Python

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

from google.cloud import storage


def download_blob_to_stream(bucket_name, source_blob_name, file_obj):
    """Downloads a blob to a stream or other file-like object."""

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

    # The ID of your GCS object (blob)
    # source_blob_name = "storage-object-name"

    # The stream or file (file-like object) to which the blob will be written
    # import io
    # file_obj = io.BytesIO()

    storage_client = storage.Client()

    bucket = storage_client.bucket(bucket_name)

    # Construct a client-side representation of a blob.
    # Note `Bucket.blob` differs from `Bucket.get_blob` in that it doesn't
    # retrieve metadata from Google Cloud Storage. As we don't use metadata in
    # this example, using `Bucket.blob` is preferred here.
    blob = bucket.blob(source_blob_name)
    blob.download_to_file(file_obj)

    print(f"Downloaded blob {source_blob_name} to file-like object.")

    return file_obj
    # Before reading from file_obj, remember to rewind with file_obj.seek(0).

Ruby

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

# Downloads a blob to a stream or other file-like object.

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

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

# The stream or file (file-like object) to which the contents will be written
# local_file_obj = StringIO.new

require "google/cloud/storage"

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

file.download local_file_obj, verify: :none

# rewind the object before starting to read the downloaded contents
local_file_obj.rewind
puts "The full downloaded file contents are: #{local_file_obj.read.inspect}"

REST APIs

JSON API

Folgen Sie der Anleitung zum Herunterladen eines Objekts unter Berücksichtigung folgender Überlegungen, um einen Streaming-Download durchzuführen:

Bevor Sie mit dem Download beginnen, rufen Sie die Metadaten des Objekts ab und speichern Sie die Generierungsnummer des Objekts. Fügen Sie diese Generierungsnummer in jede Anfrage ein, damit keine Daten von zwei verschiedenen Generierungen heruntergeladen werden, wenn das Original überschrieben wird.
Verwenden Sie in Ihrer Anfrage den Header Range, um einen Teil des Gesamtobjekts abzurufen, den Sie an den gewünschten lokalen Prozess senden können.
Führen Sie weitere Anfragen für aufeinanderfolgende Teile des Objekts aus, bis das gesamte Objekt abgerufen wurde.

XML API

Folgen Sie der Anleitung zum Herunterladen eines Objekts unter Berücksichtigung folgender Überlegungen, um einen Streaming-Download durchzuführen:

Bevor Sie mit dem Download beginnen, rufen Sie die Metadaten des Objekts ab und speichern Sie die Generierungsnummer des Objekts. Fügen Sie diese Generierungsnummer in jede Anfrage ein, damit keine Daten von zwei verschiedenen Generierungen heruntergeladen werden, wenn das Original überschrieben wird.
Verwenden Sie in Ihrer Anfrage den Header Range, um einen Teil des Gesamtobjekts abzurufen, den Sie an den gewünschten lokalen Prozess senden können.
Führen Sie weitere Anfragen für aufeinanderfolgende Teile des Objekts aus, bis das gesamte Objekt abgerufen wurde.

Streaming-Downloads

Prüfsummenvalidierung beim Streaming verwenden

Vorbereitung

Console

Befehlszeile

Clientbibliotheken

REST APIs

JSON API

Download streamen

Console

Befehlszeile

Clientbibliotheken

C++

C#

Go

Java

Node.js

PHP

Python

Ruby

REST APIs

JSON API

XML API

Nächste Schritte