Meng-commit revisi skema

Dokumen ini menunjukkan cara meng-commit revisi skema untuk topik Pub/Sub.

Sebelum memulai

Peran dan izin yang diperlukan

Untuk mendapatkan izin yang diperlukan guna meng-commit revisi skema dan mengelola skema, 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 meng-commit revisi skema dan mengelola skema. Untuk melihat izin yang benar-benar diperlukan, perluas bagian Izin yang diperlukan:

Izin yang diperlukan

Izin berikut diperlukan untuk meng-commit revisi skema dan mengelola skema:

  • Membuat skema: pubsub.schemas.create
  • Melampirkan skema ke topik: pubsub.schemas.attach
  • Meng-commit revisi skema: pubsub.schemas.commit
  • Menghapus skema atau revisi skema: pubsub.schemas.delete
  • Mendapatkan skema atau revisi skema: pubsub.schemas.get
  • Mencantumkan skema: pubsub.schemas.list
  • Mencantumkan revisi skema: pubsub.schemas.listRevisions
  • Melakukan rollback skema: pubsub.schemas.rollback
  • Memvalidasi pesan: pubsub.schemas.validate
  • Mendapatkan kebijakan IAM untuk skema: pubsub.schemas.getIamPolicy
  • Mengonfigurasi kebijakan IAM untuk skema: pubsub.schemas.setIamPolicy

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

Anda dapat memberikan peran dan izin kepada principal seperti pengguna, grup, domain, atau akun layanan. Anda dapat membuat skema di satu project dan melampirkannya ke topik yang berada di project lain. Pastikan Anda memiliki izin yang diperlukan untuk setiap project.

Merevisi skema

Anda dapat meng-commit revisi skema menggunakan Google Cloud konsol, gcloud CLI, Pub/Sub API, atau Cloud Client Libraries.

Berikut beberapa panduan untuk meng-commit revisi skema:

  • Anda dapat merevisi skema dalam batasan tertentu:

    • Untuk skema Protocol Buffer, Anda dapat menambahkan atau menghapus kolom opsional. Anda tidak dapat menambahkan atau menghapus kolom lain. Anda juga tidak dapat mengedit kolom yang ada.

    • Untuk skema Avro, lihat dokumentasi Avro untuk mengetahui aturan tentang resolusi skema. Revisi baru harus mengikuti aturan seolah-olah merupakan skema pembaca dan skema penulis.

    • Skema dapat memiliki maksimum 20 revisi sekaligus. Jika Anda melebihi batas, hapus revisi skema sebelum membuat revisi lain.

  • Setiap revisi memiliki ID revisi unik yang terkait dengannya. ID revisi adalah UUID delapan karakter yang dibuat otomatis.

  • Saat Anda memperbarui rentang revisi atau revisi skema yang digunakan untuk validasi topik, perubahan mungkin memerlukan waktu beberapa menit agar diterapkan.

Konsol

Untuk membuat revisi skema, ikuti langkah-langkah berikut:

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

    Buka Skema

  2. Klik Schema ID skema yang ada.

    Halaman Schema details untuk skema akan terbuka.

  3. Klik Create revision.

    Halaman Create schema revision akan terbuka.

  4. Lakukan perubahan sesuai kebutuhan.

    Misalnya, untuk skema contoh di Avro yang Anda buat di Membuat skema, Anda dapat menambahkan kolom opsional tambahan yang disebut Price sebagai berikut:

     {
   "type": "record",
   "name": "Avro",
   "fields": [
     {
       "name": "ProductName",
       "type": "string",
       "default": ""
     },
     {
       "name": "SKU",
       "type": "int",
       "default": 0
     },
     {
       "name": "InStock",
       "type": "boolean",
       "default": false
     },
     {
       "name": "Price",
       "type": "double",
       "default": "0.0"
     }
   ]
 }

  5. Klik Validate definition untuk memeriksa apakah definisi skema sudah benar.

  6. Anda juga dapat memvalidasi pesan untuk skema.

    1. Klik Test message untuk menguji pesan contoh.

    2. Di jendela Test message, pilih jenis Message encoding.

    3. Di isi pesan, masukkan pesan pengujian.

      Misalnya, berikut adalah contoh pesan untuk skema pengujian. Dalam contoh ini, pilih Message encoding sebagai JSON.

      {"ProductName":"GreenOnions", "SKU":34543, "Price":12, "InStock":true}

    4. Klik Test.

  7. Klik Commit untuk menyimpan skema.

gcloud

gcloud pubsub schemas commit SCHEMA_ID \
        --type=SCHEMA_TYPE \
        --definition=SCHEMA_DEFINITION

Dengan:

  • SCHEMA_TYPE adalah avro atau protocol-buffer.
  • SCHEMA_DEFINITION adalah string yang berisi definisi skema, yang diformat sesuai dengan jenis skema yang dipilih.

Anda juga dapat menentukan definisi skema dalam file:

gcloud pubsub schemas commit SCHEMA_ID \
        --type=SCHEMA_TYPE \
        --definition-file=SCHEMA_DEFINITION_FILE

Dengan:

  • SCHEMA_TYPE adalah avro atau protocol-buffer.
  • SCHEMA_DEFINITION_FILE adalah string yang berisi jalur ke file dengan definisi skema, yang diformat sesuai dengan jenis skema yang dipilih.

REST

Untuk meng-commit revisi skema, kirim permintaan POST seperti berikut:

POST https://pubsub.googleapis.com/v1/projects/PROJECT_ID/schemas/SCHEMA_ID:commit
Authorization: Bearer $(gcloud auth application-default print-access-token)
Content-Type: application/json --data @response-body.json

Tentukan kolom berikut dalam isi permintaan:

{
  "definition": SCHEMA_DEFINITION
  "type": SCHEMA_TYPE
  "name": SCHEMA_NAME
}

Dengan:

  • SCHEMA_TYPE adalah AVRO atau PROTOCOL_BUFFER.
  • SCHEMA_DEFINITION adalah string yang berisi definisi skema, yang diformat sesuai dengan jenis skema yang dipilih.
  • SCHEMA_NAME adalah nama skema yang ada.

Isi respons harus berisi representasi JSON dari resource skema . Contoh:

{
  "name": SCHEMA_NAME,
  "type": SCHEMA_TYPE,
  "definition": SCHEMA_DEFINITION
  "revisionId": REVISION_ID
  "revisionCreateTime": REVISION_CREATE_TIME
}

Dengan:

  • REVISION_ID adalah ID yang dibuat server untuk revisi.
  • REVISION_CREATE_TIME adalah stempel waktu ISO 8601 saat revisi dibuat.

Go

Contoh berikut menggunakan versi utama library klien Pub/Sub Go (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 API Pub/Sub Go.

Avro

import (
	"context"
	"fmt"
	"io"
	"os"

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

// commitAvroSchema commits a new Avro schema revision to an existing schema.
func commitAvroSchema(w io.Writer, projectID, schemaID, avscFile string) error {
	// projectID := "my-project-id"
	// schemaID := "my-schema-id"
	// avscFile = "path/to/an/avro/schema/file(.avsc)/formatted/in/json"
	ctx := context.Background()
	client, err := pubsub.NewSchemaClient(ctx)
	if err != nil {
		return fmt.Errorf("pubsub.NewSchemaClient: %w", err)
	}
	defer client.Close()

	// Read an Avro schema file formatted in JSON as a byte slice.
	avscSource, err := os.ReadFile(avscFile)
	if err != nil {
		return fmt.Errorf("error reading from file: %s", avscFile)
	}

	schema := &pubsubpb.Schema{
		Name:       fmt.Sprintf("projects/%s/schemas/%s", projectID, schemaID),
		Type