JSON ileti biçimi - olay akışını değiştirme

Uygulandığı yer: SQL Server 2025 (17.x) Azure SQL VeritabanıAzure SQL Yönetilen ÖrneğiMicrosoft Fabric'te SQL veritabanı

Bu makale, SQL Server 2025 (17.x), Azure SQL Veritabanı, Azure SQL Yönetilen Örneği içinde Change event Streaming (CES) özelliğini kullandığınızda Azure Event Hubs veya Fabric Eventstream'e akan CloudEvents mesaj formatını açıklarve Microsoft Fabric'te SQL veritabanı ile birlikte bulundu.

Uyarı

Change event streaming şu anda önizleme aşamasında ve ürünler arasında desteklenebilirlik farklılıkları var. Önizleme sırasında bu özellik değiştirilebilir.

Genel Bakış

Change event streaming CloudEvents spesifikasyonuna uygun etkinlikler yayıyor, böylece bunları olay odaklı sistemlerle kolayca entegre edebilirsiniz. Tüm CES CloudEvents 11 öznitelik (alan) içerir. CES'i, özniteliği dahil data tüm CloudEvent'i yerel JSON veya Avro ikili olarak serileştirmek için yapılandırabilirsiniz. Yerel JSON etkinliklerinde Avro ikili bölümleri bulunmaz. Her iki serileştirme formatında da niteliğin data bayt-dizi tipi vardır. Baytlar, seçilen serileştirme formatına göre JSON veya Avro ikili kodlamasını kullanır ve CES veri özniteliği Avro şemasını takip eder.

Important

15 Ağustos 2026 itibarıyla, AMQP protokolü değişiklik olay akışı (CES) için kullanımdan kaldırılmıştır. Platformlar arasında farklılıklar var. Göç adımları ve zaman çizelgeleri için AMQP protokolünün kullanımdan kaldırılmasına bakınız.

Uygun olduğunda, bu bölümdeki açıklamalar daha fazla detay içeren CloudEvent spesifikasyonundan alınmıştır.

Özellikler

  • specversion:

    • Veri türü: Dize
    • Gerekli CloudEvent özniteliği
    • Olayın kullandığı CloudEvents belirtiminin sürümü. Bu versiyon, bağlamın yorumlanmasını mümkün kılar.

  • type

    • Veri türü: Dize
    • Gerekli CloudEvent özniteliği
    • Kaynak oluşumla ilgili olay türünü açıklayan bir değer içerir. Bu değerin formatı üretici tarafından tanımlanır ve tipin versiyonu gibi bilgileri içerebilir. Daha fazla bilgi için CloudEvents'in Sürüm Seçimi bölümüne bakınız.
    • Change event streaming events için şu anda tür: com.microsoft.SQL.CES.DML.V{n}, burada {n} Microsoft change event streaming DML olay şemasının versiyonunu gösterir.
      • Mevcut en güncel şema sürümü 1.

  • source

    • Veri türü: Dize
    • Gerekli CloudEvent özniteliği
    • Bir olayın gerçekleştiği bağlamı tanımlar. Kaynak ve kimlik kombinasyonu her olay için benzersiz olmalıdır. Şu anda bu alan her zaman SQL'den yayınlanan olaylar gibi gönderilir \/ .

  • id

    • Veri türü: Dize
    • Gerekli CloudEvent özniteliği
    • Olayı tanımlar. Yapımcılar, kaynak ve kimlik kombinasyonunun her ayrı olay için benzersiz olmasını sağlamalıdır. Yinelenen bir olay yineleniyorsa (örneğin, bir ağ hatası nedeniyle) aynı kimlikte olabilir. Tüketiciler, özdeş kaynağa ve kimliğe sahip olayların yinelenen olduğunu varsayabilir.

  • logicalid

    • Veri türü: Dize
    • Uzantı özniteliği
    • Paylaşılan mantıksal kimlikler, bölünmüş mesajları tanımlar (Event Hubs mesaj boyutu kısıtlamaları nedeniyle).

  • time

    • Veri türü: Zaman damgası
    • İsteğe bağlı CloudEvent özniteliği
    • Bir SQL işleminde yapılan ve akışlı bir olayı tetikleyen bir işlem içinde commit gerçekleştiği zaman damgası.

  • datacontenttype

    • Veri türü: Dize
    • İsteğe bağlı CloudEvent özniteliği
    • Veri değerinin içerik türü. Bu öznitelik, verilerin herhangi bir içerik türünü taşımasına olanak tanır ve burada biçim ve kodlama seçilen olay biçiminden farklı olabilir. Örneğin, JSON zarf biçimi kullanılarak işlenen bir olay verilerde xml yükü taşıyabilir ve tüketiciye bu özniteliğin "application/xml" olarak ayarlandığı bildirilir. Veri içeriğinin farklı datacontenttype değerler için nasıl işlendiğine dair kurallar, olay formatı spesifikasyonlarında tanımlanmıştır.

  • operation

    • Veri türü: Dize
    • Uzantı özniteliği
    • Gerçekleşen SQL işleminin türünü temsil eder:
      • Eklemeler için INS
      • Güncellemeler için GÜNCELLEME
      • Silme işlemleri için DEL

  • segmentindex

    • Veri türü: Tamsayı
    • Uzantı özniteliği
    • Segment indeksi, mesajın mantıksal mesaj parçaları içindeki konumunu gösterir. Segment dizini, iletinin mantıksal ileti parçaları dizisinde nerede durduğu hakkında bilgi sağlar. Bu alan her zaman mevcut. logicalidBüyük SQL yük bölünmesini temsil eden gelen olayları yapılandırma değerine segmentindex göre sıralamak için , finalsegment, ve max_message_size_kb alanları kullanın.

  • finalsegment

    • Veri türü: Boole dili
    • Uzantı özniteliği
    • Bu segmentin dizinin son bölümü olup olmadığını gösterir. Bu alan her zaman mevcuttur ve bir SQL olayının yapılandırılmış max_message_size_kb değere göre alt olaylara bölünüp bölünmediğini belirlemeye yardımcı olur.

  • data

    • Veri türü: Bayt dizisi
    • İsteğe bağlı CloudEvent özniteliği
    • Değişikliği tanımlayan alana özgü olay verilerini içerir. Baytları seçilen serileştirme formatına göre JSON veya Avro ikili olarak serilikten çıkar. Serilerden arındırılmış veriler, CES veri özniteliği Avro şemasını takip eder. Alanları hakkında bilgi için bkz. Veri öznitelik formatı.

Uyarı

Mesaj bölme, sütun değeri kesintisinden ayrıdır. CES özniteliği data serileştirmeden önce, 1 MB'den büyük her akış sütun değerini 1 MB'a kısaltır. CES daha sonra oluşturulan olayı gerektiğinde mesaj parçalarına böler.max_message_size_kb

Örnekler

JSON ileti örneği - ekleme

{
  "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\\\"}\"}}"
}

JSON mesaj örneği - güncelleme

{
  "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\\\"}\"}}"
}

JSON ileti örneği - delete

{
  "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\":\"{}\"}}"
}

Veri özniteliği biçimi

Bu öznitelik data bayt dizisi olarak tanımlanır. Baytları seçilen serileştirme formatına göre JSON veya Avro ikili olarak serilikten çıkar. Her iki formatta da, ortaya çıkan Data kayıt CES veri özniteliği Avro şemasını takip eder ve iki öznitelik içerir:

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

Aşağıdaki bölümler, seri dışı özelliklerin daha ayrıntılı açıklandığını açıklar.

eventsource

Veritabanı ve olayın oluştuğu tablo hakkındaki meta verileri açıklar:

  • db

    • Veri türü: Dize
    • Açıklama: Tablonun bulunduğu veritabanının adı.
    • Örnek: EmployeesDb

  • schema

    • Veri türü: Dize
    • Açıklama: Tabloyu içeren veritabanı şeması.
    • Örnek: dbo

  • tbl

    • Veri türü: Dize
    • Açıklama: Olayın gerçekleştiği tablo.
    • Örnek: Employees

  • cols

    • Veri türü: Dizi
    • Açıklama: Tablodaki sütunların ayrıntılarını gösteren bir dizi.
      • name (ip): Sütunun adı.
      • type (dizgi): Sütunun SQL veri tipi, uzunluğu, hassasiyeti veya uygun olduğunda ölçeği dahil olmak üzere. Örnek olarak int, nvarchar(50)ve datetime2(7)verilebilir.
      • index (tam sayı): Tablodaki sütunun indeks veya konumu.

  • pkkey

    • Veri türü: Dizi
    • Açıklama: Birincil anahtar sütunlarını ve belirli bir satırı tanımlamak için bunların değerlerini temsil eder.
      • columnname (dize): Birincil anahtarda kullanılan sütunun adı.
      • value (diz): Birincil anahtarda kullanılan sütunun değeri. Bu değer, satırın benzersiz şekilde tanımlanmasına yardımcı olur.

  • transaction

    • Veri türü: Nesne
    • Açıklama: Veri işlemini içeren SQL işlemini tanımlar.
      • commitlsn (dize): İşlemin commit log dizisi numarası (LSN).
      • beginlsn (dize): İşlemin başlangıç LSN'si.
      • sequencenumber (tam sayı): İşlem içindeki veri işleminin ardışık sayı. Bu değeri bir işlem içindeki olayları sıralamak için kullanın.
      • finalevent (boolean): Kullanılmıyor. Bu alan her zaman değere sahiptir.false
      • committime (dizgi): İşlemin veritabanında gerçekleştiği tarih ve saat.

Uyarı

UTC dışı bir zaman dilimi ile yapılandırılmış SQL ürünlerinde, committime alan yanlış bir Z eki içerir, oysa bu alan yayınlama veritabanının yerel zamanını gösterir. Veritabanı UTC kullandığında, değer ve ekler aynı şekilde karşılık verir. Bu sorun biliniyor ve özelliğin gelecekteki bir sürümünde bir düzeltme bekleniyor.

eventrow

Satır düzeyi değişiklikleri açıklar ve kayıttaki alanların eski ve geçerli değerlerini karşılaştırır.

  • old (dizeye sarmalanan nesne): Olaydan önceki satırdaki değerleri temsil eder.
    • Her anahtar-değer çifti şunlardan oluşur:
      • <column_name>: (dize): Sütunun adı.
      • <column_value>: (string/int/etc.): Bu sütunun önceki değeri.
  • current (dizeye sarmalanan nesne): Olaydan sonraki satırdaki güncelleştirilmiş değerleri temsil eder.
    • Her anahtar-değer çifti şu şekilde yapılandırılmış eski nesneye benzer:
      • <column_name> (dize): Sütunun adı.
      • <column_value> (string/int/etc.): Bu sütunun yeni veya geçerli değeri.

CES CloudEvent Avro şeması

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

CES veri özniteliği Avro şeması

Yerel JSON ve Avro ikili CloudEvents'te bayt dizisini seri dışı data bırakırken aşağıdaki şemayı kullanın:

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

İlgili içerik

  • Last updated on