Formato de mensagem JSON – alterar o streaming de eventos

Aplica-se a: SQL Server 2025 (17.x) Banco de Dados SQL do AzureInstância Gerenciada de SQL do Azurebanco de dados SQL no Microsoft Fabric

Este artigo descreve o formato de mensagem CloudEvents que transmite para Hubs de Eventos do Azure ou Fabric Eventstream quando você usa o recurso de alterar streaming de eventos (CES) no SQL Server 2025 (17.x), Banco de Dados SQL do Azure, Instância Gerenciada de SQL do Azure, e banco de dados SQL no Microsoft Fabric.

Visão geral

O streaming de eventos de mudança emite eventos que seguem a especificação CloudEvents , então você pode facilmente integrá-los com sistemas orientados a eventos. Todos os CES CloudEvents contêm 11 atributos (campos). Você pode configurar o CES para serializar todo o CloudEvent, incluindo o data atributo, como JSON nativo ou binário Avro. Eventos JSON nativos não contêm seções binárias do Avro. Em ambos os formatos de serialização, o data atributo possui um tipo de array de bytes. Os bytes utilizam codificação binária JSON ou Avro de acordo com o formato de serialização selecionado e seguem o esquema Avro do atributo de dados CES.

Especificações e recursos relacionados

Quando aplicável, as descrições nesta seção vêm da especificação CloudEvent, que inclui mais detalhes.

Atributos

• specversion:

  • Tipo de dados: Cadeia
  • Atributo CloudEvent necessário
  • A versão da especificação CloudEvents que o evento usa. Esta versão permite a interpretação do contexto.

• type

  • Tipo de dados: Cadeia
  • Atributo CloudEvent necessário
  • Contém um valor que descreve o tipo de evento relacionado à ocorrência de origem. O formato desse valor é definido pelo produtor e pode incluir informações como a versão do tipo. Para mais informações, veja Versionamento do CloudEvents.
  • Para eventos de streaming de eventos de alteração, o tipo atualmente é: com.microsoft.SQL.CES.DML.V{n}, onde {n} indica a versão do esquema de eventos DML de streaming de eventos de mudança da Microsoft.
    • A versão mais recente do esquema é 1.

• source

  • Tipo de dados: Cadeia
  • Atributo CloudEvent necessário
  • Identifica o contexto no qual ocorreu um evento. A combinação de fonte e ID deve ser única para cada evento. Atualmente, esse campo é sempre enviado como \/ em eventos transmitidos pelo SQL.

• id

  • Tipo de dados: Cadeia
  • Atributo CloudEvent necessário
  • Identifica o evento. Os produtores devem garantir que a combinação de origem e ID seja única para cada evento distinto. Se um evento duplicado for ressentido (por exemplo, devido a um erro de rede), ele poderá ter a mesma ID. Os consumidores podem assumir que eventos com origem e ID idênticas são duplicados.

• logicalid

  • Tipo de dados: Cadeia
  • Atributo de extensão
  • IDs lógicos compartilhados identificam mensagens divididas (devido às restrições de tamanho das mensagens dos Event Hubs).

• time

  • Tipo de dados: Carimbo de data/hora
  • Atributo CloudEvent opcional
  • Carimbo de tempo UTC de quando o commit ocorreu dentro de uma transação SQL que originalmente dispara um evento transmitido.

• datacontenttype

  • Tipo de dados: Cadeia
  • Atributo CloudEvent opcional
  • Tipo de conteúdo de valor de dados. Esse atributo permite que os dados carreguem qualquer tipo de conteúdo, pelo qual o formato e a codificação podem ser diferentes do formato de evento escolhido. Por exemplo, um evento renderizado usando o formato de envelope JSON pode carregar uma carga XML nos dados e o consumidor é informado por esse atributo que está sendo definido como "application/xml". As regras de como o conteúdo dos dados é renderizado para diferentes datacontenttype valores são definidas nas especificações do formato do evento.

• operation

  • Tipo de dados: Cadeia
  • Atributo de extensão
  • Representa o tipo de operação SQL que aconteceu:
    • INS para inserts
    • Atualização para atualizações
    • DEL para deleções

• segmentindex

  • Tipo de dados: Inteiro
  • Atributo de extensão
  • Índice de segmento, que indica a posição da mensagem dentro dos blocos lógicos da mensagem. O índice de segmento fornece informações sobre onde a mensagem está na sequência de fragmentos de mensagem lógica. Esse campo está sempre presente. Use logicalid, , e segmentindex campos para ordenar eventos recebidos que representam uma grande divisão de carga útil SQL de acordo com o valor configurado finalsegmentmax_message_size_kb.

• finalsegment

  • Tipo de dados: Booleano
  • Atributo de extensão
  • Indica se este segmento é o segmento final da sequência. Esse campo está sempre presente e ajuda a identificar se um evento SQL foi dividido em subeventos de acordo com o valor configurado max_message_size_kb .

• data

  • Tipo de dado: Array de bytes
  • Atributo CloudEvent opcional
  • Contém os dados específicos do evento do domínio que descrevem a mudança. Desserialize os bytes como binário JSON ou Avro de acordo com o formato de serialização selecionado. Os dados desserializados seguem o esquema Avro do atributo CES. Para informações sobre seus campos, veja Formato do atributo Data.

Exemplos

Exemplo de mensagem JSON – inserir

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

Exemplo de mensagem JSON - atualização

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

Exemplo de mensagem JSON – excluir

{
  "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 dados

O data atributo é um array de bytes. Desserialize os bytes como binário JSON ou Avro de acordo com o formato de serialização selecionado. Em ambos os formatos, o registro resultante Data segue o esquema Avro do atributo CES e contém dois atributos:

• eventsource
• eventrow

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

As seções seguintes explicam os atributos desserializados com mais detalhes.

eventsource

Descreve os metadados sobre o banco de dados e a tabela em que o evento ocorreu:

• db

  • Tipo de dados: Cadeia
  • Descrição: o nome do banco de dados em que a tabela está localizada.
  • Exemplo: EmployeesDb

• schema

  • Tipo de dados: Cadeia
  • Descrição: o esquema de banco de dados que contém a tabela.
  • Exemplo: dbo

• tbl

  • Tipo de dados: Cadeia
  • Descrição: a tabela na qual o evento ocorreu.
  • Exemplo: Employees

• cols

  • Tipo de dados: Matriz
  • Descrição: uma matriz que detalha as colunas na tabela.
    • name (string): O nome da coluna.
    • type (string): O tipo de dado SQL da coluna, incluindo seu comprimento, precisão ou escala quando aplicável. Exemplos incluem int, nvarchar(50)e datetime2(7).
    • index (inteiro): O índice ou posição da coluna na tabela.

• pkkey

  • Tipo de dados: Matriz
  • Descrição: representa as colunas de chave primária e seus valores para identificar a linha específica.
    • columnname (string): O nome da coluna usada na tonalidade primária.
    • value (string): O valor da coluna usada na chave primária. Esse valor ajuda a identificar de forma única a linha.

• transaction

  • Tipo de dado: Objeto
  • Descrição: Descreve a transação SQL que contém a operação de dados.
    • commitlsn (string): O número de sequência log de commit (LSN) da transação.
    • beginlsn (string): O LSN inicial da transação.
    • sequencenumber (inteiro): O número sequencial da operação de dados dentro da transação. Use esse valor para ordenar eventos dentro de uma transação.
    • finalevent (booleano): Não está em uso. Esse corpo sempre tem um valor de false.
    • committime (string): A data e hora em que a transação foi comprometida no banco de dados.

eventrow

Descreve as alterações no nível de linha e compara os valores antigos e atuais dos campos no registro.

• old (objeto encapsulado em cadeia de caracteres): representa os valores na linha antes do evento.
  • Cada par chave-valor consiste em:
    • <column_name>: (cadeia de caracteres): o nome da coluna.
    • <column_value>: (string/int/etc.): o valor anterior para essa coluna.
• current (objeto encapsulado em cadeia de caracteres): representa os valores atualizados na linha após o evento.
  • Semelhante ao objeto antigo, com cada par chave-valor estruturado como:
    • <column_name> (cadeia de caracteres): o nome da coluna.
    • <column_value> (string/int/etc.): o valor novo ou atual para essa coluna.

CES CloudEvent esquema Avro

{
  "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 do atributo de dados CES

Use o seguinte esquema ao desserializar o data array de bytes em JSON nativo e no CloudEvents binário Avro:

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

Conteúdo relacionado

• O que é o streaming de eventos de alteração (versão prévia)?
• Configurar o streaming de eventos de mudança (prévia) para o Hubs de Eventos do Azure
• Perguntas frequentes sobre CES