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.

Prasyarat

Prasyarat dapat bervariasi berdasarkan alat yang digunakan:

Konsol

Untuk menyelesaikan panduan ini menggunakan konsol Google Cloud, Anda harus memiliki izin IAM yang tepat. Jika bucket yang ingin Anda akses untuk streaming ada di project yang tidak Anda buat, pemilik project harus memberi Anda peran yang berisi izin yang diperlukan.

Untuk mengetahui daftar izin yang diperlukan untuk tindakan tertentu, lihat Izin IAM untuk konsol Google Cloud.

Untuk daftar peran yang relevan, lihat peran Cloud Storage. Atau, Anda dapat membuat peran khusus yang memiliki izin tertentu dan terbatas.

Command line

Untuk menyelesaikan panduan ini menggunakan utilitas command line, Anda harus memiliki izin IAM yang tepat. Jika bucket yang ingin Anda akses untuk streaming ada di project yang tidak Anda buat, pemilik project harus memberi Anda peran yang berisi izin yang diperlukan.

Untuk mengetahui daftar izin yang diperlukan untuk tindakan tertentu, lihat Izin IAM untuk perintah gcloud storage.

Untuk daftar peran yang relevan, lihat peran Cloud Storage. Atau, Anda dapat membuat peran khusus yang memiliki izin tertentu dan terbatas.

Library klien

Untuk menyelesaikan panduan ini menggunakan library klien Cloud Storage, Anda harus memiliki izin IAM yang tepat. Jika bucket yang ingin Anda akses untuk streaming ada di project yang tidak Anda buat, pemilik project harus memberi Anda peran yang berisi izin yang diperlukan.

Kecuali jika dinyatakan lain, permintaan library klien dibuat melalui JSON API dan memerlukan izin seperti yang tercantum dalam izin IAM untuk metode JSON. Untuk melihat metode JSON API mana yang dipanggil saat Anda membuat permintaan menggunakan library klien, buat log permintaan mentah.

Untuk daftar peran IAM yang relevan, lihat peran Cloud Storage. Atau, Anda dapat membuat peran khusus yang memiliki izin tertentu dan terbatas.

REST API

JSON API

Untuk menyelesaikan panduan ini menggunakan JSON API, Anda harus memiliki izin IAM yang tepat. Jika bucket yang ingin Anda akses untuk streaming ada di project yang tidak Anda buat, pemilik project harus memberi Anda peran yang berisi izin yang diperlukan.

Untuk mengetahui daftar izin yang diperlukan untuk tindakan tertentu, lihat Izin IAM untuk metode JSON.

Untuk daftar peran yang relevan, lihat peran Cloud Storage. Sebagai alternatif, Anda dapat membuat peran khusus yang memiliki izin tertentu dan terbatas.

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 mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal. 

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 mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal. 


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 mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal. 

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 mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal. 


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 mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal. 

/**
 * 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 mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal. 

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 mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal. 

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 mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal. 


# 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, ikuti petunjuk cara melakukan upload yang dapat dilanjutkan dengan pertimbangan 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.

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.

Langkah selanjutnya