Formato de mensaje JSON: cambio del streaming de eventos

Se aplica a: SQL Server 2025 (17.x) Azure SQL DatabaseAzure SQL Managed InstanceBase de datos SQL en Microsoft Fabric

Este artículo describe el formato de mensaje CloudEvents que se transmite a Azure Event Hubs o Fabric Eventstream cuando usas la función de cambiar streaming de eventos (CES) en SQL Server 2025 (17.x), Azure SQL Database, Azure SQL Managed Instancey la base de datos SQL en Microsoft Fabric.

Nota:

La transmisión de eventos de cambio está actualmente en vista previa y presenta diferencias en la compatibilidad entre productos. Durante la versión preliminar, esta característica está sujeta a cambios.

Información general

El streaming de eventos por cambios emite eventos que siguen la especificación CloudEvents , por lo que puedes integrarlos fácilmente con sistemas orientados a eventos. Todos los eventos en la nube ces contienen 11 atributos (campos). Puedes configurar CES para serializar todo el CloudEvent, incluido el data atributo, como binario JSON nativo o Avro. Los eventos JSON nativos no contienen secciones binarias de Avro. En ambos formatos de serialización, el data atributo tiene un tipo de array de bytes. Los bytes utilizan codificación binaria JSON o Avro según el formato de serialización seleccionado y siguen el esquema Avro del atributo de datos CES.

Importante

Desde el 15 de agosto de 2026, el protocolo AMQP está obsoleto para la transmisión de eventos de cambio (CES). Hay diferencias entre plataformas. Para los pasos y plazos de migración, véase la deprecación del protocolo AMQP.

Cuando corresponde, las descripciones de esta sección provienen de la especificación CloudEvent, que incluye más detalles.

Atributos

  • specversion:

    • Tipo de datos: String
    • Atributo CloudEvent requerido
    • Versión de la especificación CloudEvents que usa el evento. Esta versión permite la interpretación del contexto.

  • type

    • Tipo de datos: String
    • Atributo CloudEvent requerido
    • Contiene un valor que describe el tipo de evento relacionado con la aparición de origen. El formato de este valor lo define el productor y puede incluir información como la versión del tipo. Para más información, véase Versionado de CloudEvents.
    • Para eventos de streaming de eventos de cambio, el tipo es actualmente: com.microsoft.SQL.CES.DML.V{n}, donde {n} indica la versión del esquema de eventos DML de streaming de eventos de cambio de Microsoft.
      • La última versión actual del esquema es la 1.

  • source

    • Tipo de datos: String
    • Atributo CloudEvent requerido
    • Identifica el contexto en el que se produjo un evento. La combinación de fuente e ID debe ser única para cada evento. Actualmente, este campo siempre se envía como \/ en eventos transmitidos desde SQL.

  • id

    • Tipo de datos: String
    • Atributo CloudEvent requerido
    • Identifica el evento. Los productores deben asegurarse de que la combinación de origen e ID sea única para cada evento distinto. Si se vuelve a enviar un evento duplicado (por ejemplo, debido a un error de red), podría tener el mismo identificador. Los consumidores pueden suponer que los eventos con un origen y un identificador idénticos son duplicados.

  • logicalid

    • Tipo de datos: String
    • Atributo de extensión
    • Los IDs lógicos compartidos identifican los mensajes divididos (debido a las restricciones de tamaño de los mensajes de los Event Hubs).

  • time

    • Tipo de datos: marca de tiempo
    • Atributo CloudEvent opcional
    • Marca de tiempo UTC de cuándo ocurrió el commit dentro de una transacción SQL que originalmente desencadena un evento transmitido.

  • datacontenttype

    • Tipo de datos: String
    • Atributo CloudEvent opcional
    • Tipo de contenido de valor de datos. Este atributo permite que los datos lleven cualquier tipo de contenido, en el que el formato y la codificación pueden diferir del del formato de evento elegido. Por ejemplo, un evento representado con el formato de sobre JSON podría llevar una carga XML en los datos y este atributo se informa al consumidor en "application/xml". Las reglas sobre cómo se renderiza el contenido de los datos para diferentes datacontenttype valores están definidas en las especificaciones del formato de evento.

  • operation

    • Tipo de datos: String
    • Atributo de extensión
    • Representa el tipo de operación SQL que ocurrió:
      • INS para insertos
      • Actualización para actualizaciones
      • DEL para eliminaciones

  • segmentindex

    • Tipo de datos: entero
    • Atributo de extensión
    • Índice de segmentos, que denota la posición del mensaje dentro de los bloques lógicos del mensaje. El índice de segmento proporciona información sobre dónde se encuentra el mensaje en la secuencia de fragmentos de mensaje lógicos. Este campo siempre está presente. Utiliza logicalid, , y segmentindex campos para ordenar los eventos entrantes que representan una gran distribución de la carga útil SQL según el valor configurado finalsegmentmax_message_size_kb.

  • finalsegment

    • Tipo de datos: booleano
    • Atributo de extensión
    • Indica si este segmento es el último de la secuencia. Este campo está siempre presente y ayuda a identificar si un evento SQL se dividió en subeventos según el valor configurado max_message_size_kb .

  • data

    • Tipo de datos: Array de bytes
    • Atributo CloudEvent opcional
    • Contiene los datos específicos del evento de dominio que describen el cambio. Deserializa los bytes como binario JSON o Avro según el formato de serialización seleccionado. Los datos deserializados siguen el esquema Avro del atributo CES. Para información sobre sus campos, véase Data attribute format.

Nota:

La división de mensajes es independiente de la truncación de valores de columna. Antes de que CES serialize el data atributo, trunca cada valor de columna transmitido mayor que 1 MB a 1 MB. CES luego divide el evento formado en fragmentos de mensaje según sea necesario según max_message_size_kb.

Ejemplos

Ejemplo de mensaje JSON: inserción

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

Ejemplo de mensaje JSON - actualización

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

Ejemplo de mensaje JSON: eliminació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\":\"{}\"}}"
}

Formato de atributo de datos

El data atributo es un array de bytes. Deserializa los bytes como binario JSON o Avro según el formato de serialización seleccionado. En ambos formatos, el registro resultante Data sigue el esquema Avro de atributos CES y contiene dos atributos:

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

Las siguientes secciones explican los atributos deserializados con mayor detalle.

eventsource

Describe los metadatos sobre la base de datos y la tabla donde se produjo el evento:

  • db

    • Tipo de datos: String
    • Descripción: nombre de la base de datos donde se encuentra la tabla.
    • Ejemplo: EmployeesDb

  • schema

    • Tipo de datos: String
    • Descripción: esquema de base de datos que contiene la tabla.
    • Ejemplo: dbo

  • tbl

    • Tipo de datos: String
    • Descripción: tabla en la que se produjo el evento.
    • Ejemplo: Employees

  • cols

    • Tipo de datos: Matriz
    • Descripción: matriz que detalla las columnas de la tabla.
      • name (cadena): El nombre de la columna.
      • type (cadena): El tipo de dato SQL de la columna, incluyendo su longitud, precisión o escala cuando corresponda. Algunos ejemplos son int, nvarchar(50)y datetime2(7).
      • index (entero): El índice o posición de la columna en la tabla.

  • pkkey

    • Tipo de datos: Matriz
    • Descripción: representa las columnas de clave principal y sus valores para identificar la fila específica.
      • columnname (cadena): El nombre de la columna usada en la tonalidad primaria.
      • value (cadena): El valor de la columna usada en la clave primaria. Este valor ayuda a identificar de forma única la fila.

  • transaction

    • Tipo de dato: Objeto
    • Descripción: Describe la transacción SQL que contiene la operación de datos.
      • commitlsn (cadena): El número de secuencia de log de commit (LSN) de la transacción.
      • beginlsn (cadena): El LSN inicial de la transacción.
      • sequencenumber (entero): El número secuencial de la operación de datos dentro de la transacción. Utiliza este valor para ordenar eventos dentro de una transacción.
      • finalevent (booleano): No se usa. Este campo siempre tiene un valor de false.
      • committime (cadena): La fecha y hora en que se confirmó la transacción en la base de datos.

Nota:

En productos SQL configurados con una zona horaria no UTC, el committime campo incluye incorrectamente un sufijo Z , aunque este campo muestre la hora local de la base de datos que publicó. Cuando la base de datos usa UTC, el valor y el sufijo coinciden. Este problema es conocido y una solución está pendiente en una futura versión de la función.

eventrow

Describe los cambios de nivel de fila y compara los valores antiguos y actuales de los campos del registro.

  • old (objeto encapsulado en cadena): representa los valores de la fila antes del evento.
    • Cada par clave-valor consta de:
      • <column_name>: (cadena): nombre de la columna.
      • <column_value>: (string/int/etc.): valor anterior de esa columna.
  • current (objeto ajustado en cadena): representa los valores actualizados de la fila después del evento.
    • De forma similar al objeto anterior, con cada par clave-valor estructurado como:
      • <column_name> (cadena): nombre de la columna.
      • <column_value> (string/int/etc.): el valor nuevo o actual de esa columna.

Esquema Avro de 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"
    }
  ]
}

Esquema Avro del atributo de datos CES

Utiliza el siguiente esquema al deserializar el data array de bytes en JSON nativo y en el binario de Avro 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"
          }
        ]
      }
    }
  ]
}

Contenido relacionado

  • Last updated on