JSON-meddelandeformat – ändra händelseströmning

Gäller för: SQL Server 2025 (17.x) Azure SQL DatabaseAzure SQL Managed InstanceSQL-databas i Microsoft Fabric

Denna artikel beskriver CloudEvents-meddelandeformatet som strömmar till Azure Event Hubs eller Fabric Eventstream när du använder change event streaming (CES)-funktionen i SQL Server 2025 (17.x), Azure SQL Database, Azure SQL Managed Instance, och SQL-databas i Microsoft Fabric.

Översikt

Förändringsströmning av händelser sänder händelser som följer CloudEvents-specifikationen , så att du enkelt kan integrera dem med händelsedrivna system. Alla CES CloudEvents innehåller 11 attribut (fält). Du kan konfigurera CES för att serialisera hela CloudEvent, inklusive attributet data , som en inbyggd JSON- eller Avro-binär. Inbyggda JSON-händelser innehåller inte Avro-binära sektioner. I båda serialiseringsformaten har attributet data en byte-array-typ. Bytena använder JSON- eller Avro-binärkodning enligt det valda serialiseringsformatet och följer CES-dataattributet Avro-schemat.

Relaterade specifikationer och resurser

När det är tillämpligt kommer beskrivningarna i detta avsnitt från CloudEvent-specifikationen, som innehåller fler detaljer.

Egenskaper

• specversion:

  • Datatyp: Sträng
  • Obligatoriskt CloudEvent-attribut
  • Den version av CloudEvents-specifikationen som händelsen använder. Denna version möjliggör tolkning av kontexten.

• type

  • Datatyp: Sträng
  • Obligatoriskt CloudEvent-attribut
  • Innehåller ett värde som beskriver vilken typ av händelse som är relaterad till den ursprungliga förekomsten. Formatet för detta värde definieras av producenten och kan inkludera information såsom typen version. För mer information, se Versionshantering av CloudEvents.
  • För att ändra händelseströmningshändelser är typen för närvarande: com.microsoft.SQL.CES.DML.V{n}, där {n} indikerar versionen av Microsoft ändrade händelseströmning DML-händelseschemat.
    • Den nuvarande senaste schemaversionen är 1.

• source

  • Datatyp: Sträng
  • Obligatoriskt CloudEvent-attribut
  • Identifierar kontexten där en händelse inträffade. Kombinationen av källa och ID måste vara unik för varje händelse. För närvarande skickas detta fält alltid som \/ händelser strömmade från SQL.

• id

  • Datatyp: Sträng
  • Obligatoriskt CloudEvent-attribut
  • Identifierar händelsen. Producenter måste säkerställa att kombinationen av källa och ID är unik för varje specifik händelse. Om en duplicerad händelse inte används igen (till exempel på grund av ett nätverksfel) kan den ha samma ID. Konsumenterna kan anta att händelser med identisk källa och ID är dubbletter.

• logicalid

  • Datatyp: Sträng
  • Tilläggsattribut
  • Delade logiska ID:n identifierar delade meddelanden (på grund av Event Hubs meddelandestorleksbegränsningar).

• time

  • Datatyp: Tidsstämpel
  • Valfritt CloudEvent-attribut
  • UTC-tidsstämpel för när commit skedde inom en SQL-transaktion som ursprungligen utlöser en strömmad händelse.

• datacontenttype

  • Datatyp: Sträng
  • Valfritt CloudEvent-attribut
  • Innehållstyp för datavärde. Det här attributet gör det möjligt för data att bära alla typer av innehåll, vilket innebär att format och kodning kan skilja sig från det valda händelseformatet. En händelse som återges med hjälp av JSON-kuvertformatet kan till exempel ha en XML-nyttolast i data, och konsumenten informeras om att det här attributet är inställt på "application/xml". Reglerna för hur datainnehåll renderas för olika datacontenttype värden definieras i händelseformatspecifikationerna.

• operation

  • Datatyp: Sträng
  • Tilläggsattribut
  • Representerar typen av SQL-operation som inträffade:
    • INS för insatser
    • UPD för uppdateringar
    • DEL för borttagningar

• segmentindex

  • Datatyp: Heltal
  • Tilläggsattribut
  • Segmentindex, som anger meddelandets position inom de logiska meddelandebitarna. Segmentindexet innehåller information om var meddelandet står i sekvensen med logiska meddelandefragment. Detta fält finns alltid närvarande. Använd logicalid, , och segmentindex fält för att sortera inkommande händelser som representerar en stor SQL-payload uppdelad enligt det konfigurerade finalsegment värdetmax_message_size_kb.

• finalsegment

  • Datatyp: Boolesk
  • Tilläggsattribut
  • Indikerar om detta segment är det sista segmentet i sekvensen. Detta fält finns alltid och hjälper till att identifiera om en SQL-händelse delades upp i delhändelser enligt det konfigurerade max_message_size_kb värdet.

• data

  • Datatyp: Bytearray
  • Valfritt CloudEvent-attribut
  • Innehåller domänspecifika händelsedata som beskriver ändringen. Deserialisera bytena som JSON- eller Avro-binär enligt det valda serialiseringsformatet. De deserialiserade uppgifterna följer CES-dataattributet Avro-schemat. För information om dess fält, se Dataattributformat.

Exempel

JSON-meddelandeexempel – infoga

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

Exempel på JSON-meddelande – uppdatering

{
  "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-meddelandeexempel – ta bort

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

Dataattributformat

Attributet data är en bytearray. Deserialisera bytena som JSON- eller Avro-binär enligt det valda serialiseringsformatet. I båda formaten följer den resulterande Data posten CES-dataattributet Avro-schemat och innehåller två attribut:

• eventsource
• eventrow

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

Följande avsnitt förklarar de deserialiserade attributen mer i detalj.

eventsource

Beskriver metadata om databasen och tabellen där händelsen inträffade:

• db

  • Datatyp: Sträng
  • Beskrivning: Namnet på databasen där tabellen finns.
  • Exempel: EmployeesDb

• schema

  • Datatyp: Sträng
  • Beskrivning: Databasschemat som innehåller tabellen.
  • Exempel: dbo

• tbl

  • Datatyp: Sträng
  • Beskrivning: Tabellen där händelsen inträffade.
  • Exempel: Employees

• cols

  • Datatyp: Matris
  • Beskrivning: En matris som beskriver kolumnerna i tabellen.
    • name (sträng): Namnet på kolumnen.
    • type (sträng): Kolumnens SQL-datatyp, inklusive dess längd, precision eller skala när det är tillämpligt. Exempel är int, nvarchar(50)och datetime2(7).
    • index (heltal): Indexet eller positionen för kolumnen i tabellen.

• pkkey

  • Datatyp: Matris
  • Beskrivning: Representerar primärnyckelkolumnerna och deras värden för att identifiera den specifika raden.
    • columnname (sträng): Namnet på kolumnen som används i primärnyckeln.
    • value (sträng): Värdet för kolumnen som används i primärnyckeln. Detta värde hjälper till att unikt identifiera raden.

• transaction

  • Datatyp: Objekt
  • Beskrivning: Beskriver SQL-transaktionen som innehåller dataoperationen.
    • commitlsn (sträng): Commitloggens sekvensnummer (LSN) för transaktionen.
    • beginlsn (sträng): Början av transaktionens LSN.
    • sequencenumber (heltal): Det sekventiella numret för dataoperationen inom transaktionen. Använd detta värde för att sortera händelser inom en transaktion.
    • finalevent (boolean): Ej i bruk. Detta fält har alltid värdet .false
    • committime (sträng): Datum och tid då transaktionen genomfördes i databasen.

eventrow

Beskriver ändringar på radnivå och jämför de gamla och aktuella värdena för fälten i posten.

• old (object wrapped in string): Representerar värdena på raden före händelsen.
  • Varje nyckel/värde-par består av:
    • <column_name>: (sträng): Namnet på kolumnen.
    • <column_value>: (string/int/etc.): Föregående värde för kolumnen.
• current (object wrapped in string): Representerar de uppdaterade värdena på raden efter händelsen.
  • Liknar det gamla objektet med varje nyckel/värde-par strukturerat som:
    • <column_name> (sträng): Namnet på kolumnen.
    • <column_value> (string/int/etc.): Det nya eller aktuella värdet för den kolumnen.

CES CloudEvent Avro-schema

{
  "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 dataattribut Avro schema

Använd följande schema när du deserialiserar bytearrayen data i native JSON och Avro binary CloudEvents:

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

Relaterat innehåll

• Vad är ändringshändelseströmning (förhandsversion)?
• Configure change event streaming (preview) to Azure Event Hubs
• Vanliga frågor och svar om CES