Formato de mensagem JSON - alterar o streaming de eventos

Aplica-se a: SQL Server 2025 (17.x) Base de Dados SQL do AzureAzure SQL Managed InstanceSQL database in Microsoft Fabric

Este artigo descreve o formato de mensagem CloudEvents que transmite para o Hubs de Eventos do Azure ou Fabric Eventstream quando utiliza a funcionalidade de alterar o streaming de eventos (CES) no SQL Server 2025 (17.x), Base de Dados SQL do Azure, Azure SQL Managed Instance, e base de dados SQL no Microsoft Fabric.

Visão geral

O streaming de eventos de mudança emite eventos que seguem a especificação CloudEvents , para que possa integrá-los facilmente com sistemas orientados a eventos. Todos os CES CloudEvents contêm 11 atributos (campos). Pode configurar o CES para serializar todo o CloudEvent, incluindo o data atributo, como binário JSON nativo ou Avro. Os eventos JSON nativos não contêm secções binárias do Avro. Em ambos os formatos de serialização, o data atributo tem 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 secção provê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 utiliza. 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 deste valor é definido pelo produtor e pode incluir informações como a versão do tipo. Para mais informações, consulte Versionamento de 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 em que um evento aconteceu. A combinação de fonte e ID deve ser única para cada evento. Atualmente, este campo é sempre enviado como \/ em eventos transmitidos a partir de 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 é única para cada evento distinto. Se um evento duplicado for reenviado (por exemplo, devido a um erro de rede), ele poderá ter a mesma ID. Os consumidores podem presumir que eventos com origem e ID idênticos são duplicados.

• logicalid

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

• time

  • Tipo de dados: Timestamp
  • Atributo CloudEvent opcional
  • Carimbo temporal UTC de quando o commit ocorreu dentro de uma transação SQL que originalmente desencadeia um evento transmitido.

• datacontenttype

  • Tipo de dados: Cadeia
  • Atributo CloudEvent opcional
  • Tipo de conteúdo do valor dos dados. Este atributo permite que os dados carreguem qualquer tipo de conteúdo, em que o formato e a codificação podem diferir 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 sendo definido como "application/xml". As regras para 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 ocorreu:
    • INS para inserts
    • Atualização para atualizações
    • DEL para eliminações

• segmentindex

  • Tipo de dados: Integer
  • Atributo de extensão
  • Índice de segmento, que denota 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. Este campo está sempre presente. Use logicalid, , e segmentindex campos para ordenar eventos recebidos que representem uma grande divisão de carga útil SQL de acordo com o valor configurado finalsegmentmax_message_size_kb.

• finalsegment

  • Tipo de dados: Boolean
  • Atributo de extensão
  • Indica se este segmento é o segmento final da sequência. Este 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 dados: Array de bytes
  • Atributo CloudEvent opcional
  • Contém os dados de eventos específicos do domínio que descrevem a alteração. Desserialize os bytes como binário JSON ou Avro de acordo com o formato de serialização selecionado. Os dados deserializados seguem o esquema Avro do atributo CES. Para informações sobre os seus campos, consulte 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 do 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 registo resultante Data segue o esquema Avro do atributo de dados CES e contém dois atributos:

• eventsource
• eventrow

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

As secções seguintes explicam os atributos desserializados com mais detalhe.

Fonte de eventos

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

• db

  • Tipo de dados: Cadeia
  • Descrição: o nome do banco de dados onde 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: Array
  • Descrição: uma matriz que detalha as colunas na tabela.
    • name (fio): O nome da coluna.
    • type (string): O tipo de dado SQL da coluna, incluindo o 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: Array
  • 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. Este valor ajuda a identificar de forma única a linha.

• transaction

  • Tipo de dados: 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 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 este valor para ordenar eventos dentro de uma transação.
    • finalevent (booleano): Não está em uso. Este corpo tem sempre um valor de false.
    • committime (string): A data e hora em que a transação foi confirmada na base de dados.

EventRow

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

• old (objeto encapsulado em string): representa os valores na linha antes do evento.
  • Cada par chave-valor consiste em:
    • <column_name>: (string): O nome da coluna.
    • <column_value>: (string/int/etc.): O valor anterior para essa coluna.
• current (objeto encapsulado em string): Representa os valores atualizados na linha após o evento.
  • Semelhante ao objeto antigo, com cada par chave-valor estruturado como:
    • <column_name> (string): 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 mudança?
• Configurar o streaming de eventos de alteração
• Perguntas frequentes sobre a CES