Formát zprávy JSON – změna streamování událostí

Platí pro: SQL Server 2025 (17.x) Azure SQL DatabaseSpravovaná instance Azure SQLSQL databáze v Microsoft Fabric

Tento článek popisuje formát zpráv CloudEvents, který se streamuje do Azure Event Hubs nebo Fabric Eventstream, když používáte funkci change event streaming (CES) v SQL Server 2025 (17.x), Azure SQL Database, Azure SQL Managed Instance, a SQL databázi v Microsoft Fabric.

Poznámka:

Streamování událostí změny je momentálně ve verzi preview a liší se v podpoře mezi produkty. Ve verzi Preview se tato funkce může změnit.

Přehled

Stream změn událostí vysílá události, které odpovídají specifikaci CloudEvents , takže je můžete snadno integrovat se systémy řízenými událostmi. Všechny ces CloudEvents obsahují 11 atributů (pole). Můžete nakonfigurovat CES tak, aby serializoval celý CloudEvent, včetně atributu data , jako nativní JSON nebo Avro binární soubor. Nativní JSON události neobsahují binární sekce v Avro. V obou formátech serializace má atribut data typ bajtového pole. Bajty používají binární kódování JSON nebo Avro podle zvoleného serializačního formátu a následují schéma datového atributu Avro s datovým atributem CES.

Important

Od 15. srpna 2026 je protokol AMQP pro change event streaming (CES) již zastaralý. Existují rozdíly mezi platformami. Pro kroky a časové harmonogramy migrace viz AMQP protokol deprecation.

Pokud je to relevantní, popisy v této sekci pocházejí ze specifikace CloudEvent, která obsahuje více podrobností.

Atributy

  • specversion:

    • Datový typ: Řetězec
    • Požadovaný atribut CloudEvent
    • Verze specifikace CloudEvents, kterou událost používá. Tato verze umožňuje interpretaci kontextu.

  • type

    • Datový typ: Řetězec
    • Požadovaný atribut CloudEvent
    • Obsahuje hodnotu, která popisuje typ události související s původní výskyt. Formát této hodnoty je definován producentem a může zahrnovat informace jako verze typu. Pro více informací viz Verze CloudEvents.
    • Pro události streamování změn je aktuálně com.microsoft.SQL.CES.DML.V{n}typ: , kde {n} označuje verzi schématu událostí Microsoft Change Event Streaming DML.
      • Aktuální nejnovější verze schématu je 1.

  • source

    • Datový typ: Řetězec
    • Požadovaný atribut CloudEvent
    • Identifikuje kontext, ve kterém došlo k události. Kombinace zdroje a ID musí být pro každou událost jedinečná. V současnosti je toto pole vždy posíláno jako \/ události streamované ze SQL.

  • id

    • Datový typ: Řetězec
    • Požadovaný atribut CloudEvent
    • Identifikuje událost. Producenti musí zajistit, aby kombinace zdroje a ID byla jedinečná pro každou konkrétní událost. Pokud se duplicitní událost znovu odešle (například kvůli chybě sítě), může mít stejné ID. Uživatelé můžou předpokládat, že události se stejným zdrojem a ID jsou duplicitní.

  • logicalid

    • Datový typ: Řetězec
    • Atribut rozšíření
    • Sdílené logické ID identifikují rozdělené zprávy (kvůli omezením velikosti zpráv v Event Hubu).

  • time

    • Datový typ: Časové razítko
    • Volitelný atribut CloudEvent
    • UTC časové razítko, kdy commit proběhl v rámci SQL transakce, která původně spustí streamovanou událost.

  • datacontenttype

    • Datový typ: Řetězec
    • Volitelný atribut CloudEvent
    • Typ obsahu datové hodnoty Tento atribut umožňuje datům přenášet libovolný typ obsahu, přičemž formát a kódování se můžou lišit od formátu zvolené události. Například událost vykreslená pomocí formátu obálky JSON může obsahovat datovou část XML a příjemce je informován tímto atributem nastaveným na "application/xml". Pravidla pro vykreslování datového obsahu pro různé datacontenttype hodnoty jsou definována ve specifikacích formátu události.

  • operation

    • Datový typ: Řetězec
    • Atribut rozšíření
    • Představuje typ SQL operace, která proběhla:
      • INS pro inserty
      • UPD pro aktualizace
      • DEL pro mazání

  • segmentindex

    • Datový typ: Celé číslo
    • Atribut rozšíření
    • Indexu segmentu, který označuje pozici zprávy v logických blokech zpráv. Index segmentu poskytuje informace o tom, kde zpráva stojí v posloupnosti logických fragmentů zpráv. Toto pole je vždy přítomné. Použijte logicalid, , a segmentindex pole k třídění příchozích událostí, které představují velký SQL payload rozdělený podle nastavené hodnoty finalsegmentmax_message_size_kb.

  • finalsegment

    • Datový typ: Logická hodnota
    • Atribut rozšíření
    • Označuje, zda je tento segment posledním segmentem sekvence. Toto pole je vždy přítomné a pomáhá určit, zda byla SQL událost rozdělena na podudálosti podle nakonfigurované max_message_size_kb hodnoty.

  • data

    • Typ dat: Pole bajtů
    • Volitelný atribut CloudEvent
    • Obsahuje data o událostech specifická pro danou doménu, která popisují změnu. Deserializujte bajty jako binární soubory JSON nebo Avro podle zvoleného formátu serializace. Deserializovaná data následují schéma atributu Avro s atributem CES. Pro informace o jejích polích viz formát atributu Data.

Poznámka:

Dělení zpráv je oddělené od okrácení sloupcových hodnot. Než CES serializuje data atribut, zkracuje každou hodnotu streamovaného sloupce větší než 1 MB na 1 MB. CES pak rozdělí vytvořenou událost na části zpráv podle potřeby podle .max_message_size_kb

Příklady

Příklad zprávy JSON – vložení

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

Příklad zprávy JSON - aktualizace

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

Příklad zprávy JSON – odstranění

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

Formát atributu dat

Atributem data je bajtové pole. Deserializujte bajty jako binární soubory JSON nebo Avro podle zvoleného formátu serializace. V obou formátech výsledný Data záznam následuje schéma atributu Avro s datovým atributem CES a obsahuje dva atributy:

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

Následující sekce podrobněji vysvětlují deserializované atributy.

zdroj událostí

Popisuje metadata o databázi a tabulce, ve které došlo k události:

  • db

    • Datový typ: Řetězec
    • Popis: Název databáze, ve které se nachází tabulka.
    • Příklad: EmployeesDb

  • schema

    • Datový typ: Řetězec
    • Popis: Schéma databáze, které obsahuje tabulku.
    • Příklad: dbo

  • tbl

    • Datový typ: Řetězec
    • Popis: Tabulka, ve které došlo k události.
    • Příklad: Employees

  • cols

    • Datový typ: Pole
    • Popis: Pole s podrobnostmi o sloupcích v tabulce.
      • name (string): Název sloupku.
      • type (string): SQL datový typ sloupce, včetně jeho délky, přesnosti nebo měřítka, pokud je to relevantní. Mezi příklady patří int, nvarchar(50)a datetime2(7).
      • index (celé číslo): Index nebo pozice sloupce v tabulce.

  • pkkey

    • Datový typ: Pole
    • Popis: Představuje sloupce primárního klíče a jejich hodnoty pro identifikaci konkrétního řádku.
      • columnname (string): Název sloupce použitý v primárním klíči.
      • value (string): Hodnota sloupce použitého v primárním klíči. Tato hodnota pomáhá jednoznačně identifikovat řádek.

  • transaction

    • Typ dat: Objekt
    • Popis: Popisuje SQL transakci, která obsahuje datovou operaci.
      • commitlsn (string): Sekvenční číslo záznamu commitu (LSN) transakce.
      • beginlsn (string): Počáteční LSN transakce.
      • sequencenumber (celé číslo): Sekvenční číslo datové operace v rámci transakce. Použijte tuto hodnotu k třídění událostí v rámci transakce.
      • finalevent (boolean): Není v provozu. Toto pole má vždy hodnotu false.
      • committime (string): Datum a čas, kdy byla transakce provedena v databázi.

Poznámka:

Na SQL produktech nakonfigurovaných s časovým pásmem mimo UTC pole committime nesprávně obsahuje příponu Z , i když toto pole ukazuje místní čas publikující databáze. Když databáze používá UTC, hodnota a přípona se shodují. Tento problém je známý a oprava je připravena v budoucím vydání této funkce.

eventrow

Popisuje změny na úrovni řádků a porovnává staré a aktuální hodnoty polí v záznamu.

  • starý (objekt zabalený v řetězci): Představuje hodnoty v řádku před událostí.
    • Každý pár klíč-hodnota se skládá z:
      • <column_name>: (řetězec): Název sloupce.
      • <column_value>: (string/int/etc.): Předchozí hodnota pro daný sloupec.
  • current (objekt zabalený v řetězci): Představuje aktualizované hodnoty v řádku za událostí.
    • Podobně jako u starého objektu se každou dvojicí klíč-hodnota strukturovaná takto:
      • <column_name> (řetězec): Název sloupce.
      • <column_value> (string/int/etc.): Nová nebo aktuální hodnota pro daný sloupec.

CES CloudEvent Avro schéma

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

Schéma atributu Avro v CES datovém atributu

Při deserializaci data bajtového pole v nativním JSON a Avro binárním CloudEvents použijte následující schéma:

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

Související obsah

  • Last updated on