Format pesan JSON - ubah streaming peristiwa

Berlaku untuk: SQL Server 2025 (17.x) Azure SQL DatabaseAzure SQL Managed InstanceDatabase SQL di Microsoft Fabric

Artikel ini menjelaskan format pesan CloudEvents yang di-stream ke Azure Event Hubs atau Fabric Eventstream saat Anda menggunakan fitur change event streaming (CES) di SQL Server 2025 (17.x), Azure SQL Database, Azure SQL Managed Instance, dan database SQL di Microsoft Fabric.

Nota

Streaming event perubahan saat ini sedang dalam preview, dan memiliki perbedaan dalam dukungan antar produk. Selama pratinjau, fitur ini dapat berubah.

Gambaran Umum

Streaming perubahan event menghasilkan event yang mengikuti spesifikasi CloudEvents , sehingga Anda dapat dengan mudah mengintegrasikannya ke sistem berbasis event. Semua CES CloudEvents berisi 11 atribut (bidang). Anda dapat mengonfigurasi CES untuk menserialisasi seluruh CloudEvent, termasuk atributnya data , sebagai biner JSON atau Avro asli. Event JSON native tidak mengandung bagian biner Avro. Dalam kedua format serialisasi, data atribut memiliki tipe byte-array. Byte menggunakan pengkodean biner JSON atau Avro sesuai format serialisasi yang dipilih dan mengikuti skema atribut data CES Avro.

Important

Per 15 Agustus 2026, protokol AMQP sudah tidak digunakan untuk change event streaming (CES). Ada perbedaan di berbagai platform. Untuk langkah migrasi dan garis waktu, lihat deprecation protokol AMQP.

Jika berlaku, deskripsi dalam bagian ini berasal dari spesifikasi CloudEvent, yang mencakup detail lebih lanjut.

Atributs

  • specversion:

    • Jenis data: String
    • Atribut CloudEvent yang diperlukan
    • Versi spesifikasi CloudEvents yang digunakan peristiwa tersebut. Versi ini memungkinkan interpretasi konteks.

  • type

    • Jenis data: String
    • Atribut CloudEvent yang diperlukan
    • Berisi nilai yang menjelaskan jenis peristiwa yang terkait dengan kemunculan asal. Format nilai ini ditentukan oleh produsen dan mungkin mencakup informasi seperti versi tipe. Untuk informasi lebih lanjut, lihat Versi CloudEvents.
    • Untuk event streaming event change, tipe saat ini adalah: com.microsoft.SQL.CES.DML.V{n}, di mana {n} menunjukkan versi skema event DML Microsoft change event streaming.
      • Versi skema terbaru saat ini adalah 1.

  • source

    • Jenis data: String
    • Atribut CloudEvent yang diperlukan
    • Mengidentifikasi konteks di mana peristiwa terjadi. Kombinasi sumber dan ID harus unik untuk setiap peristiwa. Saat ini, bidang ini selalu dikirim seperti \/ dalam peristiwa yang dialirkan dari SQL.

  • id

    • Jenis data: String
    • Atribut CloudEvent yang diperlukan
    • Mengidentifikasi peristiwa. Produsen harus memastikan bahwa kombinasi sumber dan ID unik untuk setiap peristiwa yang berbeda. Jika peristiwa duplikat ditolak (misalnya, karena kesalahan jaringan) peristiwa tersebut dapat memiliki ID yang sama. Konsumen mungkin berasumsi bahwa peristiwa dengan sumber dan ID yang identik adalah duplikat.

  • logicalid

    • Jenis data: String
    • Atribut ekstensi
    • ID logis bersama mengidentifikasi pesan yang dibagi (karena pembatasan ukuran pesan Event Hubs).

  • time

    • Jenis data: Tanda waktu
    • Atribut CloudEvent opsional
    • Stempel waktu UTC saat penerapan terjadi dalam transaksi SQL yang awalnya memicu peristiwa yang dialirkan.

  • datacontenttype

    • Jenis data: String
    • Atribut CloudEvent opsional
    • Jenis konten nilai data. Atribut ini memungkinkan data untuk membawa semua jenis konten, di mana format dan pengodean mungkin berbeda dari format peristiwa yang dipilih. Misalnya, peristiwa yang dirender menggunakan format amplop JSON mungkin membawa payload XML dalam data, dan konsumen diberi tahu oleh atribut ini yang diatur ke "aplikasi/xml". Aturan tentang bagaimana konten data ditampilkan untuk nilai yang berbeda datacontenttype didefinisikan dalam spesifikasi format event.

  • operation

    • Jenis data: String
    • Atribut ekstensi
    • Mewakili jenis operasi SQL yang terjadi:
      • INS untuk sisipan
      • UPD untuk pembaruan
      • DEL untuk penghapusan

  • segmentindex

    • Jenis data: Bilangan bulat
    • Atribut ekstensi
    • Indeks segmen, yang menunjukkan posisi pesan dalam potongan pesan logis. Indeks segmen menyediakan informasi tentang di mana pesan berada dalam urutan fragmen pesan logis. Bidang ini selalu ada. Gunakan logicalidfield , segmentindex, dan finalsegment untuk mengurutkan event masuk yang mewakili payload SQL besar yang dibagi berdasarkan nilai yang dikonfigurasi max_message_size_kb .

  • finalsegment

    • Jenis data: Boolean
    • Atribut ekstensi
    • Menunjukkan apakah segmen ini adalah segmen terakhir dari urutan. Kolom ini selalu ada dan membantu mengidentifikasi apakah sebuah event SQL dibagi menjadi subevent sesuai dengan nilai yang dikonfigurasi max_message_size_kb .

  • data

    • Jenis data: Array byte
    • Atribut CloudEvent opsional
    • Berisi data event khusus domain yang menjelaskan perubahan. Deserialisasi byte sebagai biner JSON atau Avro sesuai dengan format serialisasi yang dipilih. Data yang telah dideserialisasi mengikuti skema atribut data CES Avro. Untuk informasi tentang bidangnya, lihat Format atribut Data.

Nota

Pemisahan pesan terpisah dari pemotongan nilai kolom. Sebelum CES menserialisasi data atribut, ia memotong setiap nilai kolom yang di-stream lebih besar dari 1 MB menjadi 1 MB. CES kemudian membagi peristiwa yang telah dibentuk menjadi potongan pesan sesuai kebutuhan menurut max_message_size_kb.

Contoh

Contoh pesan JSON - sisipkan

{
  "specversion": "1.0",
  "type": "com.microsoft.SQL.CES.DML.V1",
  "source": "\/",
  "id": "56cb8ff3-5c55-4f3b-a7f7-b044d1933ef6",
  "logicalid": "1bf2756a-c15f-4d2e-a2d5-7d3f9dbf85b0:000000B1000008A80007:00000000000000000001",
  "time": "2026-08-07T16:25:00.890Z",
  "datacontenttype": "application\/json",
  "operation": "INS",
  "segmentindex": 0,
  "finalsegment": true,
  "data": "{\"eventsource\":{\"db\":\"EmployeesDb\",\"schema\":\"dbo\",\"tbl\":\"Employees\",\"cols\":[{\"name\":\"Id\",\"type\":\"int\",\"index\":0},{\"name\":\"FirstName\",\"type\":\"nvarchar(50)\",\"index\":1},{\"name\":\"LastName\",\"type\":\"nvarchar(50)\",\"index\":2},{\"name\":\"SignupDate\",\"type\":\"datetime2(7)\",\"index\":3}],\"pkkey\":[{\"columnname\":\"Id\",\"value\":\"8\"}],\"transaction\":{\"commitlsn\":\"000000B1:000008A8:0007\",\"beginlsn\":\"000000B1:000008A8:0003\",\"sequencenumber\":1,\"finalevent\":false,\"committime\":\"2026-08-07T16:25:00.890Z\"}},\"eventrow\":{\"old\":\"{}\",\"current\":\"{\\\"Id\\\":\\\"8\\\",\\\"FirstName\\\":\\\"Nikola\\\",\\\"LastName\\\":\\\"Nikolic\\\",\\\"SignupDate\\\":\\\"2026-08-07 16:25:00.8833333\\\"}\"}}"
}

Contoh pesan JSON - pembaruan

{
  "specversion": "1.0",
  "type": "com.microsoft.SQL.CES.DML.V1",
  "source": "\/",
  "id": "19221db1-a1b5-4ec7-8937-3fdf9d762abb",
  "logicalid": "1bf2756a-c15f-4d2e-a2d5-7d3f9dbf85b0:000000B1000009300009:00000000000000000001",
  "time": "2026-08-07T16:30:10.123Z",
  "datacontenttype": "application\/json",
  "operation": "UPD",
  "segmentindex": 0,
  "finalsegment": true,
  "data": "{\"eventsource\":{\"db\":\"EmployeesDb\",\"schema\":\"dbo\",\"tbl\":\"Employees\",\"cols\":[{\"name\":\"Id\",\"type\":\"int\",\"index\":0},{\"name\":\"FirstName\",\"type\":\"nvarchar(50)\",\"index\":1},{\"name\":\"LastName\",\"type\":\"nvarchar(50)\",\"index\":2},{\"name\":\"SignupDate\",\"type\":\"datetime2(7)\",\"index\":3}],\"pkkey\":[{\"columnname\":\"Id\",\"value\":\"8\"}],\"transaction\":{\"commitlsn\":\"000000B1:00000930:0009\",\"beginlsn\":\"000000B1:00000930:0002\",\"sequencenumber\":1,\"finalevent\":false,\"committime\":\"2026-08-07T16:30:10.123Z\"}},\"eventrow\":{\"old\":\"{\\\"Id\\\":\\\"8\\\",\\\"FirstName\\\":\\\"Nikola\\\",\\\"LastName\\\":\\\"Nikolic\\\",\\\"SignupDate\\\":\\\"2026-08-07 16:25:00.8833333\\\"}\",\"current\":\"{\\\"Id\\\":\\\"8\\\",\\\"FirstName\\\":\\\"Nikola\\\",\\\"LastName\\\":\\\"Nikolic-Smith\\\",\\\"SignupDate\\\":\\\"2026-08-07 16:25:00.8833333\\\"}\"}}"
}

Contoh pesan JSON - hapus

{
  "specversion": "1.0",
  "type": "com.microsoft.SQL.CES.DML.V1",
  "source": "\/",
  "id": "520f9a65-43d7-47f2-94f5-7ea14df635ed",
  "logicalid": "1bf2756a-c15f-4d2e-a2d5-7d3f9dbf85b0:000000B1000009700008:00000000000000000001",
  "time": "2026-08-07T16:35:42.450Z",
  "datacontenttype": "application\/json",
  "operation": "DEL",
  "segmentindex": 0,
  "finalsegment": true,
  "data": "{\"eventsource\":{\"db\":\"EmployeesDb\",\"schema\":\"dbo\",\"tbl\":\"Employees\",\"cols\":[{\"name\":\"Id\",\"type\":\"int\",\"index\":0},{\"name\":\"FirstName\",\"type\":\"nvarchar(50)\",\"index\":1},{\"name\":\"LastName\",\"type\":\"nvarchar(50)\",\"index\":2},{\"name\":\"SignupDate\",\"type\":\"datetime2(7)\",\"index\":3}],\"pkkey\":[{\"columnname\":\"Id\",\"value\":\"8\"}],\"transaction\":{\"commitlsn\":\"000000B1:00000970:0008\",\"beginlsn\":\"000000B1:00000970:0003\",\"sequencenumber\":1,\"finalevent\":false,\"committime\":\"2026-08-07T16:35:42.450Z\"}},\"eventrow\":{\"old\":\"{\\\"Id\\\":\\\"8\\\",\\\"FirstName\\\":\\\"Nikola\\\",\\\"LastName\\\":\\\"Nikolic-Smith\\\",\\\"SignupDate\\\":\\\"2026-08-07 16:25:00.8833333\\\"}\",\"current\":\"{}\"}}"
}

Format atribut data

Atributnya data adalah array byte. Deserialisasi byte sebagai biner JSON atau Avro sesuai dengan format serialisasi yang dipilih. Dalam kedua format, catatan yang dihasilkan Data mengikuti skema atribut data CES Avro dan berisi dua atribut:

  • eventsource
  • eventrow
{
  "data": "{\"eventsource\": {}, \"eventrow\": {\"old\": \"{}\", \"current\": \"{}\"}}"
}

Bagian berikut menjelaskan atribut yang telah dideserialisasi dengan lebih rinci.

sumber peristiwa

Menjelaskan metadata tentang database dan tabel tempat peristiwa terjadi:

  • db

    • Jenis data: String
    • Deskripsi: Nama database tempat tabel berada.
    • Contoh: EmployeesDb

  • schema

    • Jenis data: String
    • Deskripsi: Skema database yang berisi tabel.
    • Contoh: dbo

  • tbl

    • Jenis data: String
    • Deskripsi: Tabel tempat peristiwa terjadi.
    • Contoh: Employees

  • cols

    • Jenis data: Array
    • Deskripsi: Array yang merinci kolom dalam tabel.
      • name (string): Nama kolom.
      • type (string): Tipe data SQL dari kolom, termasuk panjang, presisi, atau skalanya jika berlaku. Contohnya termasuk int, nvarchar(50), dan datetime2(7).
      • index (bilangan bulat): Indeks atau posisi kolom dalam tabel.

  • pkkey

    • Jenis data: Array
    • Deskripsi: Mewakili kolom kunci utama dan nilainya untuk mengidentifikasi baris tertentu.
      • columnname (string): Nama kolom yang digunakan pada kunci primer.
      • value (string): Nilai untuk kolom yang digunakan pada kunci primer. Nilai ini membantu mengidentifikasi baris secara unik.

  • transaction

    • Jenis data: Objek
    • Deskripsi: Menjelaskan transaksi SQL yang berisi operasi data.
      • commitlsn (string): Nomor urutan log commit (LSN) dari transaksi.
      • beginlsn (string): LSN awal transaksi.
      • sequencenumber (bilangan bulat): Nomor berurutan dari operasi data dalam transaksi. Gunakan nilai ini untuk mengurutkan peristiwa dalam sebuah transaksi.
      • finalevent (boolean): Tidak digunakan. Medan ini selalu memiliki nilai .false
      • committime (string): Tanggal dan waktu ketika transaksi dikomitmenkan di database.

Nota

Pada produk SQL yang dikonfigurasi dengan zona waktu non-UTC, kolom tersebut committime secara keliru menyertakan akhiran Z , meskipun kolom ini menunjukkan waktu lokal database publikasi. Ketika database menggunakan UTC, nilai dan akhiran sesuai. Masalah ini sudah diketahui, dan perbaikan sedang menunggu dalam rilis fitur ini di masa depan.

eventrow

Menjelaskan perubahan tingkat baris dan membandingkan nilai bidang lama dan saat ini dalam rekaman.

  • lama (objek dibungkus dalam string): Mewakili nilai dalam baris sebelum peristiwa.
    • Setiap pasangan kunci-nilai terdiri dari:
      • <column_name>: (string): Nama kolom.
      • <column_value>: (string/int/etc.): Nilai sebelumnya untuk kolom tersebut.
  • saat ini (objek dibungkus dalam string): Mewakili nilai yang diperbarui dalam baris setelah peristiwa.
    • Mirip dengan objek lama, dengan setiap pasangan kunci-nilai disusun sebagai:
      • <column_name> (string): Nama kolom.
      • <column_value> (string/int/etc.): Nilai baru atau saat ini untuk kolom tersebut.

Skema Avro CES CloudEvent

{
  "type": "record",
  "name": "ChangeEvent",
  "fields": [
    {
      "name": "specversion",
      "type": "string"
    },
    {
      "name": "type",
      "type": "string"
    },
    {
      "name": "source",
      "type": "string"
    },
    {
      "name": "id",
      "type": "string"
    },
    {
      "name": "logicalid",
      "type": "string"
    },
    {
      "name": "time",
      "type": "string"
    },
    {
      "name": "datacontenttype",
      "type": "string"
    },
    {
      "name": "operation",
      "type": "string"
    },
    {
      "name": "segmentindex",
      "type": "int"
    },
    {
      "name": "finalsegment",
      "type": "boolean"
    },
    {
      "name": "data",
      "type": "bytes"
    }
  ]
}

Atribut data CES Skema Avro

Gunakan skema berikut saat mendeserialisasi data array byte di CloudEvents biner JSON dan Avro asli:

{
  "name": "Data",
  "type": "record",
  "fields": [
    {
      "name": "eventsource",
      "type": {
        "name": "EventSource",
        "type": "record",
        "fields": [
          {
            "name": "db",
            "type": "string"
          },
          {
            "name": "schema",
            "type": "string"
          },
          {
            "name": "tbl",
            "type": "string"
          },
          {
            "name": "cols",
            "type": {
              "type": "array",
              "items": {
                "name": "Column",
                "type": "record",
                "fields": [
                  {
                    "name": "name",
                    "type": "string"
                  },
                  {
                    "name": "type",
                    "type": "string"
                  },
                  {
                    "name": "index",
                    "type": "int"
                  }
                ]
              }
            }
          },
          {
            "name": "pkkey",
            "type": {
              "type": "array",
              "items": {
                "name": "PkKey",
                "type": "record",
                "fields": [
                  {
                    "name": "columnname",
                    "type": "string"
                  },
                  {
                    "name": "value",
                    "type": "string"
                  }
                ]
              }
            }
          },
          {
            "name": "transaction",
            "type": {
              "name": "Transaction",
              "type": "record",
              "fields": [
                {
                  "name": "commitlsn",
                  "type": "string"
                },
                {
                  "name": "beginlsn",
                  "type": "string"
                },
                {
                  "name": "sequencenumber",
                  "type": "int"
                },
                {
                  "name": "finalevent",
                  "type": "boolean"
                },
                {
                  "name": "committime",
                  "type": "string"
                }
              ]
            }
          }
        ]
      }
    },
    {
      "name": "eventrow",
      "type": {
        "name": "EventRow",
        "type": "record",
        "fields": [
          {
            "name": "old",
            "type": "string"
          },
          {
            "name": "current",
            "type": "string"
          }
        ]
      }
    }
  ]
}

Konten terkait

  • Last updated on