Format pesan JSON - ubah streaming peristiwa

Berlaku untuk: SQL Server 2025 (17.x) Azure SQL Database

Artikel ini menjelaskan format JSON pesan CloudEvents yang dialirkan dari SQL Server ke Azure Event Hubs saat menggunakan fitur perubahan event streaming (CES) yang diperkenalkan di SQL Server 2025 (17.x) dan Azure SQL Database.

Nota

Streaming peristiwa perubahan saat ini dalam pratinjau untuk:

SQL Server 2025 (konfigurasi cakupan database fitur pratinjau diperlukan).
Azure SQL Database (pratinjau konfigurasi cakupan database fitur tidak diperlukan).

Selama pratinjau, fitur ini dapat berubah. Untuk dukungan saat ini, lihat Batasan.

Gambaran Umum

Peristiwa yang dipancarkan oleh streaming peristiwa perubahan mengikuti spesifikasi CloudEvents , membuatnya mudah diintegrasikan dengan sistem berbasis peristiwa. Semua CES CloudEvents berisi 11 atribut (bidang). CES dapat dikonfigurasi untuk menserialisasikan CloudEvents sebagai JSON (asli), atau sebagai biner Avro. Bagian berikut dari artikel ini menjelaskan format pesan secara rinci, termasuk atribut CES CloudEvent, dan serialisasi.

Jika berlaku, deskripsi di bagian ini diambil dari spesifikasi CloudEvent, yang mencakup detail tambahan.

Atributs

specversion:
- Jenis data: String
- Atribut CloudEvent yang diperlukan
- Versi spesifikasi CloudEvents yang digunakan peristiwa. Ini memungkinkan interpretasi konteks.
type
- Jenis data: String
- Atribut CloudEvent yang diperlukan
- Berisi nilai yang menjelaskan jenis peristiwa yang terkait dengan kemunculan asal. Format ini didefinisikan oleh produsen dan mungkin menyertakan informasi seperti versi jenisnya. Untuk informasi selengkapnya, tinjau Penerapan versi CloudEvents.
- Untuk peristiwa Ubah Streaming Peristiwa, jenisnya saat ini adalah: com.microsoft.SQL.CES.DML.V{n}, di mana {n} menunjukkan versi skema peristiwa DML Ubah Streaming Peristiwa Microsoft.
  - Versi skema terbaru saat ini adalah 1.
source
- Jenis data: String
- Atribut CloudEvent yang diperlukan
- Mengidentifikasi konteks di mana peristiwa terjadi. Sumber + 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 sumber + 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
- Pesan terpisah (karena pembatasan ukuran msg Azure Event Hubs) diidentifikasi oleh ID logis bersama.
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 dirender untuk nilai yang berbeda datacontenttype ditentukan dalam spesifikasi format peristiwa
operation
- Jenis data: String
- Ekstensi
- Mewakili jenis operasi SQL yang terjadi:
  - INS untuk sisipan
  - UPD untuk pembaruan
  - DEL untuk penghapusan
segmentindex
- Jenis data: Bilangan bulat
- Atribut ekstensi
- Indeks segmentasi, yang menunjukkan posisi pesan dalam gugus pesan logis. Indeks segmen menyediakan informasi tentang di mana pesan berada dalam urutan fragmen pesan logis. Bidang ini selalu ada. Gunakan bidang logicalid + segmentindex + finalsegment untuk mengurutkan peristiwa masuk yang mewakili payload SQL besar yang dibagi menjadi beberapa peristiwa.
finalsegment
- Jenis data: Boolean
- Atribut ekstensi
- Memberi tahu apakah segmen ini adalah segmen akhir dari urutan. Bidang ini selalu ada dan membantu mengidentifikasi apakah peristiwa SQL yang terlalu besar untuk ukuran pesan maksimum yang dikonfigurasi dibagi menjadi sub-peristiwa.
data
- Jenis data: String
- Atribut CloudEvent opsional
- Data peristiwa khusus domain. Untuk CES, data adalah string yang dapat diurai sebagai JSON. JSON ini menjelaskan bagaimana data berubah. Format atribut data berada pada format atribut Data.

Contoh

Contoh pesan JSON - sisipkan

{
  "specversion": "1.0",
  "type": "com.microsoft.SQL.CES.DML.V1",
  "source": "\/",
  "id": "d43f09a6-d13b-4902-86d4-17bdb5edb872",
  "logicalid": "9c8d4ad2-bf54-4f10-a96f-038af496997f:0000002C00000300017C:00000000000000000001",
  "time": "2025-03-14T16:45:20.650Z",
  "datacontenttype": "application\/json",
  "operation": "INS",
  "splitindex": 0,
  "splittotalcnt": 0,
  "data": "{\n  \"eventsource\": {\n    \"db\": \"db1\",\n    \"schema\": \"dbo\",\n    \"tbl\": \"Purchases\",\n    \"cols\": [\n      {\n        \"name\": \"purchase_id\",\n        \"type\": \"int\",\n        \"index\": 0\n      },\n      {\n        \"name\": \"customer_name\",\n        \"type\": \"varchar(100)\",\n        \"index\": 1\n      },\n      {\n        \"name\": \"product_id\",\n        \"type\": \"int\",\n        \"index\": 2\n      },\n      {\n        \"name\": \"product_name\",\n        \"type\": \"varchar(100)\",\n        \"index\": 3\n      },\n      {\n        \"name\": \"price_per_item\",\n        \"type\": \"int\",\n        \"index\": 4\n      },\n      {\n        \"name\": \"quantity\",\n        \"type\": \"int\",\n        \"index\": 5\n      },\n      {\n        \"name\": \"purchase_date\",\n        \"type\": \"datetime\",\n        \"index\": 6\n      },\n      {\n        \"name\": \"payment_method\",\n        \"type\": \"varchar(50)\",\n        \"index\": 7\n      }\n    ],\n    \"pkkey\": [\n      {\n        \"columnname\": \"purchase_id\",\n        \"value\": \"105\"\n      }\n    ]\n  },\n  \"eventrow\": {\n    \"old\": \"{}\",\n    \"current\": \"{\\\"purchase_id\\\": \\\"105\\\", \\\"customer_name\\\": \\\"Anna Doe\\\", \\\"product_id\\\": \\\"101\\\", \\\"product_name\\\": \\\"Game 2077\\\", \\\"price_per_item\\\": \\\"60\\\", \\\"quantity\\\": \\\"1\\\", \\\"purchase_date\\\": \\\"2025-03-14 16:45:01.000\\\", \\\"payment_method\\\": \\\"Credit Card\\\"}\"\n  }\n}"
}

Contoh pesan JSON – diperbarui

{
  "specversion": "1.0",
  "type": "com.microsoft.SQL.CES.DML.V1",
  "source": "\/",
  "id": "c425575f-00bb-45cf-acec-c55fdc7d08cd",
  "logicalid": "9c8d4ad2-bf54-4f10-a96f-038af496997f:0000002C000003500004:00000000000000000001",
  "time": "2025-03-14T16:49:59.567Z",
  "datacontenttype": "application\/json",
  "operation": "UPD",
  "splitindex": 0,
  "splittotalcnt": 0,
  "data": "{\n  \"eventsource\": {\n    \"db\": \"db1\",\n    \"schema\": \"dbo\",\n    \"tbl\": \"Purchases\",\n    \"cols\": [\n      {\n        \"name\": \"purchase_id\",\n        \"type\": \"int\",\n        \"index\": 0\n      },\n      {\n        \"name\": \"customer_name\",\n        \"type\": \"varchar(100)\",\n        \"index\": 1\n      },\n      {\n        \"name\": \"product_id\",\n        \"type\": \"int\",\n        \"index\": 2\n      },\n      {\n        \"name\": \"product_name\",\n        \"type\": \"varchar(100)\",\n        \"index\": 3\n      },\n      {\n        \"name\": \"price_per_item\",\n        \"type\": \"int\",\n        \"index\": 4\n      },\n      {\n        \"name\": \"quantity\",\n        \"type\": \"int\",\n        \"index\": 5\n      },\n      {\n        \"name\": \"purchase_date\",\n        \"type\": \"datetime\",\n        \"index\": 6\n      },\n      {\n        \"name\": \"payment_method\",\n        \"type\": \"varchar(50)\",\n        \"index\": 7\n      }\n    ],\n    \"pkkey\": [\n      {\n        \"columnname\": \"purchase_id\",\n        \"value\": \"105\"\n      }\n    ]\n  },\n  \"eventrow\": {\n    \"old\": \"{}\",\n    \"current\": \"{\\\"purchase_id\\\": \\\"105\\\", \\\"customer_name\\\": \\\"Anna Doe\\\", \\\"product_id\\\": \\\"100\\\", \\\"product_name\\\": \\\"Game 2066\\\", \\\"price_per_item\\\": \\\"50\\\", \\\"quantity\\\": \\\"2\\\", \\\"purchase_date\\\": \\\"2025-03-14 16:45:01.000\\\", \\\"payment_method\\\": \\\"Credit Card\\\"}\"\n  }\n}"
}

Contoh pesan JSON - hapus

{
  "specversion": "1.0",
  "type": "com.microsoft.SQL.CES.DML.V1",
  "source": "\/",
  "id": "24fa0c2c-c45d-4abf-9a8d-fba04c29fc86",
  "logicalid": "9c8d4ad2-bf54-4f10-a96f-038af496997f:0000002C000003600019:00000000000000000001",
  "time": "2025-03-14T16:51:39.613Z",
  "datacontenttype": "application\/json",
  "operation": "DEL",
  "splitindex": 0,
  "splittotalcnt": 0,
  "data": "{\n  \"eventsource\": {\n    \"db\": \"db1\",\n    \"schema\": \"dbo\",\n    \"tbl\": \"Purchases\",\n    \"cols\": [\n      {\n        \"name\": \"purchase_id\",\n        \"type\": \"int\",\n        \"index\": 0\n      },\n      {\n        \"name\": \"customer_name\",\n        \"type\": \"varchar(100)\",\n        \"index\": 1\n      },\n      {\n        \"name\": \"product_id\",\n        \"type\": \"int\",\n        \"index\": 2\n      },\n      {\n        \"name\": \"product_name\",\n        \"type\": \"varchar(100)\",\n        \"index\": 3\n      },\n      {\n        \"name\": \"price_per_item\",\n        \"type\": \"int\",\n        \"index\": 4\n      },\n      {\n        \"name\": \"quantity\",\n        \"type\": \"int\",\n        \"index\": 5\n      },\n      {\n        \"name\": \"purchase_date\",\n        \"type\": \"datetime\",\n        \"index\": 6\n      },\n      {\n        \"name\": \"payment_method\",\n        \"type\": \"varchar(50)\",\n        \"index\": 7\n      }\n    ],\n    \"pkkey\": [\n      {\n        \"columnname\": \"purchase_id\",\n        \"value\": \"105\"\n      }\n    ]\n  },\n  \"eventrow\": {\n    \"old\": \"{\\\"purchase_id\\\": \\\"105\\\", \\\"customer_name\\\": \\\"Anna Doe\\\", \\\"product_id\\\": \\\"100\\\", \\\"product_name\\\": \\\"Game 2066\\\", \\\"price_per_item\\\": \\\"50\\\", \\\"quantity\\\": \\\"2\\\", \\\"purchase_date\\\": \\\"2025-03-14 16:45:01.000\\\", \\\"payment_method\\\": \\\"Credit Card\\\"}\",\n    \"current\": \"{}\"\n  }\n}"
}

Format atribut data

Data adalah objek JSON yang dibungkus dalam atribut string yang berisi dua atribut:

eventSource
eventRow

"data": "{ "eventsource": {<eventSource>}, "eventdata": {<eventData>}}"

Detail kedua atribut ini dijelaskan secara lebih rinci di bagian berikut:

sumber peristiwa

Menjelaskan metadata tentang database dan tabel tempat peristiwa terjadi:

db
- Jenis data: String
- Deskripsi: Nama database tempat tabel berada.
- Contoh: cessqldb001
schema
- Jenis data: String
- Deskripsi: Skema database yang berisi tabel.
- Contoh: dbo
tbl
- Jenis data: String
- Deskripsi: Tabel tempat peristiwa terjadi.
- Contoh: Purchases
cols
- Jenis data: Array
- Deskripsi: Array yang merinci kolom dalam tabel.
  - nama (string): Nama kolom.
  - type (string): Jenis data kolom (VARCHAR atau INT).
  - indeks (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 dalam kunci primer.
  - value (string/int/etc.): Nilai untuk kolom yang digunakan dalam kunci primer, membantu mengidentifikasi baris secara unik.

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 JSON 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"
    }
  ]
}

Skema JSON atribut data CES

{
  "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": "committime",
                  "type": "string"
                }
              ]
            }
          }
        ]
      }
    },
    {
      "name": "eventrow",
      "type": {
        "name": "EventRow",
        "type": "record",
        "fields": [
          {
            "name": "old",
            "type": "string"
          },
          {
            "name": "current",
            "type": "string"
          }
        ]
      }
    }
  ]
}

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-11-18