Membuat langganan dengan SMT

Dokumen ini menjelaskan cara membuat langganan Pub/Sub dengan Single Message Transforms (SMTs).

SMT langganan memungkinkan modifikasi ringan pada data dan atribut pesan secara langsung dalam Pub/Sub. Fitur ini memungkinkan pembersihan, pemfilteran, atau konversi format data sebelum pesan dikirimkan ke klien pelanggan.

Untuk membuat langganan dengan SMT, Anda dapat menggunakan Google Cloud konsol, Google Cloud CLI, library klien, atau Pub/Sub API.

Sebelum memulai

• Pelajari tentang layanan Pub/Sub dan terminologinya.

• Pelajari tentang SMT.

Peran dan izin yang diperlukan

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

Peran bawaan ini berisi izin yang diperlukan untuk membuat langganan dengan SMT. Untuk melihat izin yang benar-benar diperlukan, perluas bagian Izin yang diperlukan:

Izin yang diperlukan

Izin berikut diperlukan untuk membuat langganan dengan SMT:

• Berikan izin untuk membuat langganan di project: pubsub.subscriptions.create

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

Bergantung pada jenis langganan, Anda mungkin memerlukan izin tambahan. Untuk mengetahui daftar izin yang tepat, lihat dokumen yang membahas pembuatan langganan tertentu. Misalnya, jika Anda membuat langganan BigQuery dengan SMT, lihat Membuat langganan BigQuery.

Jika Anda membuat langganan di project yang berbeda dengan topik, Anda harus memberikan peran roles/pubsub.subscriber kepada principal project yang berisi langganan di project yang berisi topik.

Anda dapat mengonfigurasi kontrol akses di tingkat project dan di tingkat resource individual.

Membuat langganan dengan SMT

Sebelum membuat langganan dengan SMT, tinjau dokumentasi untuk Properti langganan.

Catatan: Sangat direkomendasikan untuk mengonfigurasi topik yang dihentikan pengirimannya untuk langganan dengan SMT. Pesan yang diteruskan ke topik yang dihentikan pengirimannya karena kegagalan SMT berisi atribut CloudPubSubDeadLetterSourceSMTErrorMessage yang memiliki alasan SMT gagal.

Untuk membuat langganan Pub/Sub dengan satu atau beberapa SMT, lakukan langkah-langkah berikut. Anda dapat mengaktifkan hingga 5 SMT per langganan.

Konsol

1. Di Google Cloud konsol, buka halaman Subscriptions Pub/Sub.

   Buka Langganan

2. Klik Create subscription.

3. Di kolom Subscription ID, masukkan ID untuk langganan Anda. Untuk mengetahui informasi selengkapnya tentang penamaan langganan, lihat panduan penamaan.

4. Di bagian Transforms, klik Add a transform.

5. Pilih Transform type. Untuk mengetahui informasi selengkapnya tentang jenis SMT yang didukung, lihat Jenis SMT.

6. Tetapkan properti konfigurasi untuk SMT. Kumpulan properti bergantung pada jenis SMT. Untuk mengetahui informasi selengkapnya, lihat dokumentasi untuk jenis SMT tersebut.

7. Opsional. Untuk memvalidasi SMT, klik Validate. Jika SMT valid, pesan "Validation passed" akan ditampilkan. Jika tidak, pesan error akan ditampilkan.

8. Untuk menambahkan transformasi lain, klik Add a transform dan ulangi langkah-langkah sebelumnya.

   Untuk mengatur SMT dalam urutan tertentu, klik Move up atau Move down. Untuk menghapus an SMT, klik Delete.

9. Opsional. Untuk menguji SMT pada pesan contoh, lakukan langkah-langkah berikut:

   1. Klik Test transforms.

   2. Di jendela Test transform, pilih fungsi yang ingin Anda uji.

   3. Di jendela Input message, masukkan pesan contoh.

   4. Untuk menambahkan atribut ke pesan, klik Add an attribute dan masukkan kunci serta nilai atribut. Anda dapat menambahkan beberapa atribut.

   5. Klik Test. Hasil penerapan SMT pada pesan ditampilkan di bagian Output message.

   6. Untuk menutup jendela Test transforms, klik Close.

   Jika membuat lebih dari satu SMT, Anda dapat menguji seluruh urutan transformasi sebagai berikut:

   1. Uji SMT pertama dalam urutan, seperti yang dijelaskan dalam langkah-langkah sebelumnya.
   2. Pilih SMT berikutnya. Pesan input telah diisi sebelumnya dengan pesan output dari pengujian sebelumnya.
   3. Lanjutkan pengujian SMT secara berurutan, untuk memastikan seluruh urutan berfungsi seperti yang diharapkan.

10. Klik Create untuk membuat langganan.

gcloud

1. Di konsol, aktifkan Cloud Shell. Google Cloud

   Aktifkan Cloud Shell

   Di bagian bawah konsol Google Cloud , sesi Cloud Shell akan dimulai dan menampilkan prompt command line. Cloud Shell adalah lingkungan shell dengan Google Cloud CLI yang sudah terinstal, dan dengan nilai yang sudah ditetapkan untuk project Anda saat ini. Diperlukan waktu beberapa detik untuk melakukan inisialisasi pada sesi.

2. Buat file YAML atau JSON yang menentukan satu atau beberapa SMT. Definisi YAML atau JSON bergantung pada jenis SMT. Untuk mengetahui informasi selengkapnya, lihat Jenis SMT.

   Jika file menyertakan lebih dari satu SMT, Pub/Sub akan mengeksekusinya dalam urutan yang tercantum.

3. Opsional. Untuk memvalidasi SMT, jalankan gcloud pubsub message-transforms validate perintah:

   gcloud pubsub message-transforms validate \
     --message-transform-file=TRANSFORM_FILE
   

   Ganti kode berikut:

   • TRANSFORM_FILE: Jalur ke file YAML atau JSON yang menentukan satu SMT. Jika membuat beberapa SMT, Anda harus memvalidasinya satu per satu.

4. Opsional. Untuk menguji satu atau beberapa SMT pada pesan Pub/Sub contoh, jalankan perintah gcloud pubsub message-transforms test:

   gcloud pubsub message-transforms test \
     --message-transforms-file=TRANSFORMS_FILE \
     --message=MESSAGE \
     --attribute=ATTRIBUTES
   

   Ganti kode berikut:

   • TRANSFORMS_FILE: Jalur ke file YAML atau JSON yang menentukan satu atau beberapa SMT.
   • MESSAGE: Isi pesan contoh.
   • ATTRIBUTES: Opsional. Daftar atribut pesan yang dipisahkan koma. Setiap atribut adalah pasangan nilai kunci yang diformat sebagai KEY="VALUE".

   Perintah ini mengeksekusi SMT secara berurutan, menggunakan output dari setiap SMT sebagai input ke SMT berikutnya. Perintah ini menampilkan hasil setiap langkah.

5. Untuk membuat langganan, jalankan gcloud pubsub subscriptions create perintah:

   gcloud pubsub subscriptions create SUBSCRIPTION_ID \
       --topic=projects/PROJECT_ID/topics/TOPIC_ID \
       --message-transforms-file=TRANSFORMS_FILE
   

   Ganti kode berikut:

   • SUBSCRIPTION_ID: ID atau nama langganan yang ingin Anda buat. Untuk mengetahui panduan tentang cara memberi nama a langganan, lihat Nama resource. Nama langganan tidak dapat diubah.

   • PROJECT_ID: ID project yang berisi topik.

   • TOPIC_ID: ID topik yang akan dilanggan.

   • TRANSFORMS_FILE: Jalur ke file YAML atau JSON yang menentukan satu atau beberapa SMT.

Java

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Java di Panduan Memulai: Menggunakan Library Klien. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi Pub/Sub Java API.

import com.google.cloud.pubsub.v1.SubscriptionAdminClient;
import com.google.pubsub.v1.JavaScriptUDF;
import com.google.pubsub.v1.MessageTransform;
import com.google.pubsub.v1.ProjectSubscriptionName;
import com.google.pubsub.v1.ProjectTopicName;
import com.google.pubsub.v1.Subscription;
import java.io.IOException;

public class CreateSubscriptionWithSmtExample {
  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";

    createSubscriptionWithSmtExample(projectId, topicId, subscriptionId);
  }

  public static void createSubscriptionWithSmtExample(
      String projectId, String topicId, String subscriptionId) throws IOException {

    // UDF that removes the 'ssn' field, if present
    String code =
        "function redactSSN(message, metadata) {"
            + "  const data = JSON.parse(message.data);"
            + "  delete data['ssn'];"
            + "  message.data = JSON.stringify(data);"
            + "  return message;"
            + "}";
    String functionName = "redactSSN";

    JavaScriptUDF udf =
        JavaScriptUDF.newBuilder().setCode(code).setFunctionName(functionName).build();
    MessageTransform transform = MessageTransform.newBuilder().setJavascriptUdf(udf).build();

    try (SubscriptionAdminClient subscriptionAdminClient = SubscriptionAdminClient.create()) {

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

      Subscription subscription =
          subscriptionAdminClient.createSubscription(
              Subscription.newBuilder()
                  .setName(subscriptionName.toString())
                  .setTopic(topicName.toString())
                  // Add the UDF message transform
                  .addMessageTransforms(transform)
                  .build());

      System.out.println("Created subscription with SMT: " + subscription.getAllFields());
    }
  }
}

Python

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Python di Panduan Memulai: Menggunakan Library Klien. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi Pub/Sub Python API.

from google.cloud import pubsub_v1
from google.pubsub_v1.types import JavaScriptUDF, MessageTransform

# TODO(developer): Choose an existing topic.
# project_id = "your-project-id"
# topic_id = "your-topic-id"
# subscription_id = "your-subscription-id"

publisher = pubsub_v1.PublisherClient()
subscriber = pubsub_v1.SubscriberClient()
topic_path = publisher.topic_path(project_id, topic_id)
subscription_path = subscriber.subscription_path(project_id, subscription_id)

code = """function redactSSN(message, metadata) {
            const data = JSON.parse(message.data);
            delete data['ssn'];
            message.data = JSON.stringify(data);
            return message;
            }"""
udf = JavaScriptUDF(code=code, function_name="redactSSN")
transforms = [MessageTransform(javascript_udf=udf)]

with subscriber:
    subscription = subscriber.create_subscription(
        request={
            "name": subscription_path,
            "topic": topic_path,
            "message_transforms": transforms,
        }
    )
    print(f"Created subscription with SMT: {subscription}")

Go

Contoh berikut menggunakan library klien Pub/Sub Go versi utama (v2). Jika Anda masih menggunakan library v1, lihat panduan migrasi ke v2. Untuk melihat daftar contoh kode v1, lihat contoh kode yang tidak digunakan lagi.

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Go di Panduan Memulai: Menggunakan Library Klien. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi Pub/Sub Go API.

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/pubsub/v2"
	"cloud.google.com/go/pubsub/v2/apiv1/pubsubpb"
)

// createSubscriptionWithSMT creates a subscription with a single message transform function applied.
func createSubscriptionWithSMT(w io.Writer, projectID, topicID, subID string) error {
	// projectID := "my-project-id"
	// topicID := "my-topic"
	// subID := "my-sub"
	ctx := context.Background()
	client, err := pubsub.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("pubsub.NewClient: %w", err)
	}
	defer client.Close()

	code := `function redactSSN(message, metadata) {
			const data = JSON.parse(message.data);
			delete data['ssn'];
			message.data = JSON.stringify(data);
			return message;
		}`

	transform := &pubsubpb.MessageTransform{
		Transform: &pubsubpb.MessageTransform_JavascriptUdf{
			JavascriptUdf: &pubsubpb.JavaScriptUDF{
				FunctionName: "redactSSN",
				Code:         code,
			},
		},
	}

	sub := &pubsubpb.Subscription{
		Name:              fmt.Sprintf("projects/%s/subscriptions/%s", projectID, subID),
		Topic:             fmt.Sprintf("projects/%s/topics/%s", projectID, topicID),
		MessageTransforms: []*pubsubpb.MessageTransform{transform},
	}
	sub, err = client.SubscriptionAdminClient.CreateSubscription(ctx, sub)
	if err != nil {
		return fmt.Errorf("CreateSubscription: %w", err)
	}
	fmt.Fprintf(w, "Created subscription with message transform: %v\n", sub)
	return nil
}

Cara SMT berinteraksi dengan fitur langganan lainnya

Pertimbangkan poin-poin berikut saat menggunakan SMT langganan.

Pemfilteran

Jika langganan Anda menggunakan SMT dan filter bawaan Pub/Sub , filter akan diterapkan sebelum SMT. Hal ini memiliki implikasi sebagai berikut:

• Jika SMT Anda mengubah atribut pesan, filter Pub/Sub tidak akan diterapkan ke kumpulan atribut baru.
• SMT Anda tidak diterapkan ke pesan yang difilter oleh filter Pub/Sub.
• Jika SMT Anda memfilter pesan, perhatikan dampaknya terhadap pemantauan backlog langganan Anda.
• Jika Anda menghubungkan langganan ke pipeline Dataflow, jangan gunakan SMT langganan untuk memfilter pesan, karena hal ini akan mengganggu penskalaan otomatis Dataflow.

Pengurutan pesan

Jika Anda menentukan SMT pada langganan yang mengaktifkan pengurutan, dan menjalankan SMT akan menampilkan error, pesan berikutnya untuk kunci pengurutan yang sama tidak akan dikirimkan ke pelanggan. Untuk menghindari masalah ini, siapkan a topik yang dihentikan pengirimannya pada langganan untuk menghapus pesan yang belum diproses dari backlog pesan.

Langkah berikutnya

• Memecahkan masalah SMT langganan

• Memperbarui SMT langganan

• Menghapus SMT langganan