Membuat langganan Cloud Storage

Dokumen ini menjelaskan cara membuat langganan Cloud Storage. Anda dapat menggunakan konsol Google Cloud, Google Cloud CLI, library klien, atau Pub/Sub API untuk membuat langganan Cloud Storage.

Sebelum memulai

Sebelum membaca dokumen ini, pastikan Anda memahami hal-hal berikut:

• Cara kerja langganan Cloud Storage.
• Cara kerja Cloud Storage dan cara membuat serta mengelola bucket Cloud Storage.
• Cara mengonfigurasi topik yang dihentikan pengirimannya untuk menangani kegagalan pesan.

Peran dan izin yang diperlukan

Berikut adalah daftar panduan terkait peran dan izin:

• Untuk membuat langganan, Anda harus mengonfigurasi kontrol akses di tingkat project.

• Anda juga memerlukan izin tingkat resource jika subscription dan topik Anda berada di project yang berbeda, seperti yang akan dibahas nanti di bagian ini.

• Untuk membuat langganan Cloud Storage, akun layanan Pub/Sub harus memiliki izin untuk menulis ke bucket Cloud Storage tertentu dan membaca metadata bucket. Untuk informasi selengkapnya tentang cara memberikan izin ini, lihat bagian berikut dalam dokumen ini.

Untuk mendapatkan izin yang diperlukan guna membuat langganan Cloud Storage, minta administrator untuk memberi Anda peran IAM Pub/Sub Editor (roles/pubsub.editor) di project. Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses ke project, folder, dan organisasi.

Peran yang telah ditentukan ini berisi izin yang diperlukan untuk membuat langganan Cloud Storage. Untuk melihat izin yang benar-benar diperlukan, luaskan bagian Izin yang diperlukan:

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

Jika Anda perlu membuat langganan Cloud Storage di satu project yang terkait dengan topik di project lain, minta administrator topik untuk juga memberi Anda peran IAM (roles/pubsub.editor) Editor Pub/Sub pada topik tersebut.

Menetapkan peran Cloud Storage ke akun layanan Pub/Sub

Beberapa layanan Google Cloud memiliki akun layanan yang dikelola Google Cloud yang memungkinkan layanan mengakses resource Anda. Akun layanan ini dikenal sebagai agen layanan. Pub/Sub membuat dan mengelola akun layanan untuk setiap project dalam format service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com.

Untuk membuat langganan Cloud Storage, akun layanan Pub/Sub harus memiliki izin untuk menulis ke bucket Cloud Storage tertentu dan membaca metadata bucket. Pilih salah satu prosedur berikut:

• Berikan izin di tingkat bucket. Di bucket Cloud Storage tertentu, berikan peran Storage Object Creator (roles/storage.objectCreator) dan peran Storage Legacy Bucket Reader (roles/storage.legacyBucketReader) ke akun layanan Pub/Sub.

• Jika harus memberikan peran di tingkat project, Anda dapat memberikan peran Storage Admin (roles/storage.admin) di project yang berisi bucket Cloud Storage. Berikan peran ini ke akun layanan Pub/Sub.

Untuk informasi selengkapnya tentang IAM Cloud Storage, lihat Cloud Storage Identity and Access Management.

Properti langganan Cloud Storage

Saat mengonfigurasi langganan Cloud Storage, Anda harus menentukan properti yang umum untuk semua jenis langganan dan beberapa properti khusus langganan Cloud Storage tambahan.

Properti langganan umum

Pelajari properti langganan umum yang dapat Anda tetapkan di semua langganan.

Nama bucket

Bucket Cloud Storage harus sudah ada sebelum Anda membuat langganan Cloud Storage.

Pesan dikirim sebagai batch dan disimpan di bucket Cloud Storage. Satu batch atau file disimpan sebagai objek di bucket.

Bucket Cloud Storage harus menonaktifkan Pemohon Membayar.

Untuk membuat bucket Cloud Storage, lihat artikel Membuat bucket.

Awalan, akhiran, dan tanggal waktu nama file

File Cloud Storage output yang dihasilkan oleh langganan Cloud Storage disimpan sebagai objek di bucket Cloud Storage. Nama objek yang disimpan di bucket Cloud Storage memiliki format berikut: <file-prefix><UTC-date-time>_<uuid><file-suffix>.

Daftar berikut menyertakan detail format file dan kolom yang dapat Anda sesuaikan:

• <file-prefix> adalah awalan nama file kustom. Kolom ini bersifat opsional.

• <UTC-date-time> adalah string yang dibuat otomatis dan dapat disesuaikan berdasarkan waktu pembuatan objek.

• <uuid> adalah string acak yang dibuat otomatis untuk objek.

• <file-suffix> adalah akhiran nama file kustom. Kolom ini bersifat opsional. Akhiran nama file tidak boleh diakhiri dengan "/".

• Anda dapat mengubah awalan dan akhiran nama file:

  • Misalnya, jika nilai awalan nama file adalah prod_ dan nilai akhiran nama file adalah _archive, contoh nama objek adalah prod_2023-09-25T04:10:00+00:00_uN1QuE_archive.

  • Jika Anda tidak menentukan awalan dan akhiran nama file, nama objek yang disimpan di bucket Cloud Storage akan memiliki format: <UTC-date-time>_<uuid>.

  • Persyaratan penamaan objek Cloud Storage juga berlaku untuk awalan dan akhiran nama file. Untuk mengetahui informasi selengkapnya, lihat Tentang objek Cloud Storage.

• Anda dapat mengubah cara tanggal dan waktu ditampilkan dalam nama file:

  • Pencocok tanggal/waktu wajib yang hanya dapat Anda gunakan sekali: tahun (YYYY atau YY), bulan (MM), hari (DD), jam (hh), menit (mm), detik (ss). Misalnya, YY-YYYY atau MMM tidak valid.

  • Pencocok opsional yang hanya dapat Anda gunakan sekali: pemisah tanggal dan waktu (T) serta offset zona waktu (Z atau +00:00).

  • Elemen opsional yang dapat Anda gunakan beberapa kali: tanda hubung (-), garis bawah (_), titik dua (:), dan garis miring (/).

  • Misalnya, jika nilai format tanggal waktu nama file adalah YYYY-MM-DD/hh_mm_ssZ, nama objek contohnya adalah prod_2023-09-25/04_10_00Z_uNiQuE_archive.

  • Jika format tanggal waktu nama file diakhiri dengan karakter yang bukan pencocok, karakter tersebut akan menggantikan pemisah antara <UTC-date-time> dan <uuid>. Misalnya, jika nilai format tanggal waktu nama file adalah YYYY-MM-DDThh_mm_ss-, nama objek contohnya adalah prod_2023-09-25T04_10_00-uNiQuE_archive.

Pengelompokan file

Langganan Cloud Storage memungkinkan Anda memutuskan kapan ingin membuat file output baru yang disimpan sebagai objek di bucket Cloud Storage. Pub/Sub menulis file output saat salah satu kondisi pengelompokan yang ditentukan terpenuhi. Berikut adalah kondisi pengelompokan Cloud Storage:

• Durasi maksimum batch penyimpanan. Setelan ini wajib diisi. Langganan Cloud Storage akan menulis file output baru jika nilai durasi maksimum yang ditentukan terlampaui. Jika Anda tidak menentukan nilai, nilai default 5 menit akan diterapkan. Berikut adalah nilai yang berlaku untuk durasi maksimum:

  • Nilai minimum = 1 menit
  • Nilai default = 5 menit
  • Nilai maksimum = 10 menit

• Byte maksimum batch penyimpanan. Ini adalah setelan opsional. Langganan Cloud Storage akan menulis file output baru jika nilai byte maksimum yang ditentukan terlampaui. Berikut adalah nilai yang berlaku untuk byte maksimum:

  • Nilai minimum = 1 KB
  • Nilai maksimum = 10 GiB

• Pesan maksimum batch penyimpanan. Ini adalah setelan opsional. Langganan Cloud Storage akan menulis file output baru jika jumlah pesan maksimum yang ditentukan terlampaui. Berikut adalah nilai yang berlaku untuk pesan maksimum:

  • Nilai minimum = 1.000

Misalnya, Anda dapat mengonfigurasi durasi maksimum sebagai 6 menit dan byte maksimum sebagai 2 GB. Jika pada menit ke-4, file output mencapai ukuran file 2 GB, Pub/Sub akan menyelesaikan file sebelumnya dan mulai menulis ke file baru.

Langganan Cloud Storage mungkin menulis ke beberapa file di bucket Cloud Storage secara bersamaan. Jika telah mengonfigurasi langganan untuk membuat file baru setiap menit ke-6, Anda mungkin mengamati beberapa file Cloud Storage yang dibuat setiap 6 menit.

Dalam beberapa situasi, Pub/Sub mungkin mulai menulis ke file baru lebih awal dari waktu yang dikonfigurasi oleh kondisi pengelompokan file. File juga dapat melebihi nilai Max bytes jika langganan menerima pesan yang lebih besar dari nilai Max bytes.

Format file

Saat membuat langganan Cloud Storage, Anda dapat menentukan format file output yang akan disimpan di bucket Cloud Storage sebagai Text atau Avro.

• Teks: Pesan disimpan sebagai teks biasa. Karakter baris baru memisahkan pesan dari pesan sebelumnya dalam file. Hanya payload pesan yang disimpan, bukan atribut atau metadata lainnya.

• Avro: Pesan disimpan dalam format biner Apache Avro. Saat memilih Avro, Anda dapat mengaktifkan properti tambahan berikut:

  • Tulis metadata: Opsi ini memungkinkan Anda menyimpan metadata pesan bersama dengan pesan. Metadata seperti kolom subscription_name, message_id, publish_time, dan attributes ditulis ke kolom tingkat atas dalam objek Avro output, sedangkan semua properti pesan lainnya selain data (misalnya, ordering_key, jika ada) ditambahkan sebagai entri dalam peta attributes.

    Jika metadata tulis dinonaktifkan, hanya payload pesan yang akan ditulis ke objek Avro output. Berikut adalah skema Avro untuk pesan output dengan metadata tulis dinonaktifkan:

    {
      "type": "record",
      "namespace": "com.google.pubsub",
      "name": "PubsubMessage",
      "fields": [
        { "name": "data", "type": "bytes" }
      ]
    }
    

    Berikut adalah skema Avro untuk pesan output dengan metadata tulis diaktifkan:

    {
      "type": "record",
      "namespace": "com.google.pubsub",
      "name": "PubsubMessageWithMetadata",
      "fields": [
        { "name": "subscription_name", "type": "string" },
        { "name": "message_id", "type": "string"  },
        { "name": "publish_time", "type": {
            "type": "long",
            "logicalType": "timestamp-micros"
          }
        },
        { "name": "attributes", "type": { "type": "map", "values": "string" } },
        { "name": "data", "type": "bytes" }
      ]
    }
    

  • Gunakan skema topik: Opsi ini memungkinkan Pub/Sub menggunakan skema topik Pub/Sub yang dipasangkan ke langganan saat menulis file Avro.

    Saat menggunakan opsi ini, jangan lupa untuk memeriksa persyaratan tambahan berikut:

    • Skema topik harus dalam format Apache Avro.

    • Jika gunakan skema topik dan tulis metadata diaktifkan, skema topik harus memiliki objek Record di root-nya. Pub/Sub akan memperluas daftar kolom Data untuk menyertakan kolom metadata. Akibatnya, Data tidak boleh berisi kolom apa pun dengan nama yang sama dengan kolom metadata (subscription_name, message_id, publish_time, atau attributes).

Membuat langganan Cloud Storage

namespace pubsub = ::google::cloud::pubsub;
namespace pubsub_admin = ::google::cloud::pubsub_admin;
[](pubsub_admin::SubscriptionAdminClient client,
   std::string const& project_id, std::string const& topic_id,
   std::string const& subscription_id, std::string const& bucket) {
  google::pubsub::v1::Subscription request;
  request.set_name(
      pubsub::Subscription(project_id, subscription_id).FullName());
  request.set_topic(pubsub::Topic(project_id, topic_id).FullName());
  request.mutable_cloud_storage_config()->set_bucket(bucket);
  auto sub = client.CreateSubscription(request);
  if (!sub) {
    if (sub.status().code() == google::cloud::StatusCode::kAlreadyExists) {
      std::cout << "The subscription already exists\n";
      return;
    }
    throw std::move(sub).status();
  }

  std::cout << "The subscription was successfully created: "
            << sub->DebugString() << "\n";
}

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

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

// createCloudStorageSubscription creates a Pub/Sub subscription that exports messages to Cloud Storage.
func createCloudStorageSubscription(w io.Writer, projectID, subID string, topic *pubsub.Topic, bucket string) error {
	// projectID := "my-project-id"
	// subID := "my-sub"
	// topic of type https://godoc.org/cloud.google.com/go/pubsub#Topic
	// note bucket should not have the gs:// prefix
	// bucket := "my-bucket"
	ctx := context.Background()
	client, err := pubsub.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("pubsub.NewClient: %w", err)
	}
	defer client.Close()

	sub, err := client.CreateSubscription(ctx, subID, pubsub.SubscriptionConfig{
		Topic: topic,
		CloudStorageConfig: pubsub.CloudStorageConfig{
			Bucket:         bucket,
			FilenamePrefix: "log_events_",
			FilenameSuffix: ".avro",
			OutputFormat:   &pubsub.CloudStorageOutputFormatAvroConfig{WriteMetadata: true},
			MaxDuration:    1 * time.Minute,
			MaxBytes:       1e8,
		},
	})
	if err != nil {
		return fmt.Errorf("client.CreateSubscription: %w", err)
	}
	fmt.Fprintf(w, "Created Cloud Storage subscription: %v\n", sub)

	return nil
}

import com.google.cloud.pubsub.v1.SubscriptionAdminClient;
import com.google.protobuf.Duration;
import com.google.pubsub.v1.CloudStorageConfig;
import com.google.pubsub.v1.ProjectSubscriptionName;
import com.google.pubsub.v1.ProjectTopicName;
import com.google.pubsub.v1.Subscription;
import java.io.IOException;

public class CreateCloudStorageSubscriptionExample {
  public static void main(String... args) throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String topicId = "your-topic-id";
    String subscriptionId = "your-subscription-id";
    String bucket = "your-bucket";
    String filenamePrefix = "log_events_";
    String filenameSuffix = ".text";
    Duration maxDuration = Duration.newBuilder().setSeconds(300).build();

    createCloudStorageSubscription(
        projectId, topicId, subscriptionId, bucket, filenamePrefix, filenameSuffix, maxDuration);
  }

  public static void createCloudStorageSubscription(
      String projectId,
      String topicId,
      String subscriptionId,
      String bucket,
      String filenamePrefix,
      String filenameSuffix,
      Duration maxDuration)
      throws IOException {
    try (SubscriptionAdminClient subscriptionAdminClient = SubscriptionAdminClient.create()) {

      ProjectTopicName topicName = ProjectTopicName.of(projectId, topicId);
      ProjectSubscriptionName subscriptionName =
          ProjectSubscriptionName.of(projectId, subscriptionId);

      CloudStorageConfig cloudStorageConfig =
          CloudStorageConfig.newBuilder()
              .setBucket(bucket)
              .setFilenamePrefix(filenamePrefix)
              .setFilenameSuffix(filenameSuffix)
              .setMaxDuration(maxDuration)
              .build();

      Subscription subscription =
          subscriptionAdminClient.createSubscription(
              Subscription.newBuilder()
                  .setName(subscriptionName.toString())
                  .setTopic(topicName.toString())
                  .setCloudStorageConfig(cloudStorageConfig)
                  .build());

      System.out.println("Created a CloudStorage subscription: " + subscription.getAllFields());
    }
  }
}

Memantau langganan Cloud Storage

Cloud Monitoring menyediakan sejumlah metrik untuk memantau langganan.

Untuk mengetahui daftar semua metrik yang tersedia terkait Pub/Sub dan deskripsinya, lihat Dokumentasi pemantauan untuk Pub/Sub.

Anda juga dapat memantau langganan dari dalam Pub/Sub.

Langkah selanjutnya

• Memecahkan masalah langganan Cloud Storage.

• Baca tentang Cloud Storage.

• Tinjau harga untuk Pub/Sub, termasuk langganan Cloud Storage.