Upload streaming

Cloud Storage mendukung streaming data ke bucket tanpa mengharuskan data disimpan terlebih dahulu ke file. Fungsi ini berguna jika Anda ingin mengupload data, tetapi tidak mengetahui ukuran akhir pada saat upload dimulai, seperti ketika menghasilkan data upload dari proses tertentu, atau ketika mengompresi objek dengan cepat.

Menggunakan validasi checksum saat melakukan streaming

Karena checksum hanya dapat disediakan dalam permintaan awal upload, biasanya menjadi tidak mungkin untuk menggunakan validasi checksum Cloud Storage saat melakukan streaming. Sebaiknya selalu gunakan validasi checksum, dan Anda dapat melakukannya secara manual setelah upload streaming selesai; tetapi perlu diingat bahwa dengan melakukan validasi setelah transfer selesai, data yang rusak dapat diakses selama waktu yang diperlukan untuk mengonfirmasi kerusakan dan menghapusnya.

Jika memerlukan validasi checksum sebelum upload selesai dan data dapat diakses, sebaiknya Anda tidak menggunakan upload streaming. Sebaiknya gunakan opsi upload lain dengan validasi checksum yang dijalankan sebelum penyelesaian objek.

Peran yang diperlukan

Untuk mendapatkan izin yang diperlukan guna melakukan streaming upload, minta administrator untuk memberi Anda salah satu peran berikut:

• Untuk upload yang menyertakan Object Retention Lock, minta administrator untuk memberi Anda peran IAM Storage Object Admin (roles/storage.objectAdmin) untuk bucket.

• Untuk semua kasus lainnya, minta administrator untuk memberi Anda peran IAM Storage Object User (roles/storage.objectUser) untuk bucket.

Peran yang telah ditetapkan ini berisi izin yang diperlukan untuk melakukan streaming upload ke Cloud Storage. Untuk melihat izin yang benar-benar diperlukan, luaskan bagian Izin yang diperlukan:

Izin yang diperlukan

• storage.objects.create
• storage.objects.delete
• Izin ini hanya diperlukan untuk upload yang menimpa objek yang ada.
• storage.objects.list
• Izin ini hanya diperlukan untuk menggunakan Google Cloud CLI untuk menjalankan petunjuk di halaman ini.
• storage.objects.setRetention
  • Izin ini hanya diperlukan untuk upload yang menyertakan Kunci Retensi Objek.

Anda juga bisa mendapatkan izin ini dengan peran standar atau peran khusus lainnya.

Untuk informasi tentang cara memberikan peran pada bucket, lihat Menggunakan IAM dengan bucket.

Melakukan streaming upload

Contoh berikut menunjukkan cara melakukan upload streaming dari proses tertentu ke objek Cloud Storage:

Konsol

Konsol Google Cloud tidak mendukung upload streaming. Untuk itu, gunakan gcloud CLI.

Command line

1. Masukkan data ke perintah gcloud storage cp dan gunakan tanda hubung untuk URL sumber:

   PROCESS_NAME | gcloud storage cp - gs://BUCKET_NAME/OBJECT_NAME

   Dengan keterangan:

   • PROCESS_NAME adalah nama proses tempat Anda mengumpulkan data. Contohnya, collect_measurements.
   • BUCKET_NAME adalah nama bucket tempat objek berada. Contoh, my_app_bucket.
   • OBJECT_NAME adalah nama objek yang dibuat dari data. Contoh, data_measurements.

Library klien

C++

Untuk mengetahui informasi selengkapnya, lihatDokumentasi referensi Cloud Storage C++ API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

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#

Untuk mengetahui informasi selengkapnya, lihatDokumentasi referensi Cloud Storage C# API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

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

Untuk mengetahui informasi selengkapnya, lihatDokumentasi referensi Cloud Storage Go API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

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

Untuk mengetahui informasi selengkapnya, lihatDokumentasi referensi Cloud Storage Java API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

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

Untuk mengetahui informasi selengkapnya, lihatDokumentasi referensi Cloud Storage Node.js API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

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

Untuk mengetahui informasi selengkapnya, lihatDokumentasi referensi Cloud Storage PHP API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

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

Untuk mengetahui informasi selengkapnya, lihatDokumentasi referensi Cloud Storage Python API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

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

Untuk mengetahui informasi selengkapnya, lihatDokumentasi referensi Cloud Storage Ruby API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

# 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 API

JSON API

Untuk melakukan upload streaming, gunakan salah satu metode berikut:

• Upload yang dapat dilanjutkan, dengan penyesuaian berikut:

  • Saat mengupload data file, lakukan upload dalam beberapa potongan.

  • Karena total ukuran file baru dapat diketahui saat sampai ke potongan terakhir, gunakan * untuk total ukuran file di header Content-Range potongan menengah.

    Misalnya, jika potongan pertama yang Anda upload berukuran 512 KiB, header Content-Range untuk potongan tersebut adalah bytes 0-524287/*. Jika upload tersisa 64.000 byte setelah potongan pertama, lanjutkan dengan mengirimkan potongan terakhir berisi byte yang tersisa dan memiliki header Content-Range dengan nilai bytes 524288-588287/588288.

• Upload satu permintaan, dengan penyesuaian berikut:

  • Sertakan header Transfer-Encoding: chunked, dan kecualikan header Content-Length.

  • Buat permintaan sesuai dengan spesifikasi, yang mengirimkan data objek dalam potongan saat tersedia.

XML API

Untuk melakukan upload streaming, gunakan salah satu metode berikut:

• Upload multibagian XML API

• Upload yang dapat dilanjutkan, dengan penyesuaian berikut:

  • Saat mengupload data file, lakukan upload dalam beberapa potongan.

  • Karena total ukuran file baru dapat diketahui saat sampai ke potongan terakhir, gunakan * untuk total ukuran file di header Content-Range potongan menengah.

    Misalnya, jika potongan pertama yang Anda upload berukuran 512 KiB, header Content-Range untuk potongan tersebut adalah bytes 0-524287/*. Jika upload tersisa 64.000 byte setelah potongan pertama, lanjutkan dengan mengirimkan potongan terakhir berisi byte yang tersisa dan memiliki header Content-Range dengan nilai bytes 524288-588287/588288.

• Upload satu permintaan, dengan penyesuaian berikut:

  • Sertakan header Transfer-Encoding: chunked, dan kecualikan header Content-Length.

  • Buat permintaan sesuai dengan spesifikasi, yang mengirimkan data objek dalam potongan saat tersedia.

  • Perhatikan bahwa Anda tidak dapat melakukan upload streaming menggunakan metode ini jika permintaan menggunakan tanda tangan di header Authorization-nya.

Langkah selanjutnya

• Streaming download.
• Pelajari lebih lanjut tentang transcoding dekompresi.
• Pelajari lebih lanjut tentang upload dan download.