Formato de mensagem JSON - alterar o streaming de eventos

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

Este artigo descreve o formato JSON de uma mensagem CloudEvents que transmite para Hubs de Eventos do Azure ou Fabric Eventstream ao utilizar a funcionalidade de alterar 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.

Observação

O streaming de eventos de mudança está atualmente em pré-visualização e apresenta diferenças de suporte entre produtos. Durante a visualização, esse recurso está sujeito a alterações.

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). Podes configurar o CES para serializar CloudEvents como JSON (nativo) ou como binário Avro. As secções seguintes deste artigo descrevem em detalhe o formato da mensagem, incluindo atributos CES CloudEvent e serialização.

Importante

A partir de 15 de agosto de 2026, o protocolo AMQP está obsoleto para transmissão de eventos de alteração (CES). Todos os grupos de stream recém-criados devem usar AzureEventHubs como o destination_type to stream com o protocolo Apache Kafka. Para passos e prazos de migração, veja a descontinuação do protocolo AMQP.

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: Cadeia
- Atributo CloudEvent opcional
- Dados de eventos específicos do domínio. Para CES, os dados são cadeias de caracteres que podem ser analisadas como JSON. Este JSON descreve como os dados foram alterados. O formato do atributo de dados está em Data attribute format.

Observação

A divisão de mensagens é separada da truncação de valores de coluna. Antes de o CES serializar o data atributo, ele trunca cada valor da coluna transmitida maior do que 1 MB para 1 MB. O CES divide então o evento formado em blocos de mensagem conforme necessário, de acordo com max_message_size_kb.

Exemplos

Exemplo de mensagem JSON - inserir

{
  "specversion": "1.0",
  "type": "com.microsoft.SQL.CES.DML.V1",
  "source": "\/",
  "id": "d43f09a6-d13b-4902-86d4-17bdb5edb872",
  "logicalid": "9c8d4ad2-bf54-4f10-a96f-038af496997f:0000002C00000300017C:00000000000000000001",
  "time": "2025-03-14T16:45:20.650Z",
  "datacontenttype": "application\/json",
  "operation": "INS",
  "splitindex": 0,
  "splittotalcnt": 0,
  "data": "{\n  \"eventsource\": {\n    \"db\": \"db1\",\n    \"schema\": \"dbo\",\n    \"tbl\": \"Purchases\",\n    \"cols\": [\n      {\n        \"name\": \"purchase_id\",\n        \"type\": \"int\",\n        \"index\": 0\n      },\n      {\n        \"name\": \"customer_name\",\n        \"type\": \"varchar(100)\",\n        \"index\": 1\n      },\n      {\n        \"name\": \"product_id\",\n        \"type\": \"int\",\n        \"index\": 2\n      },\n      {\n        \"name\": \"product_name\",\n        \"type\": \"varchar(100)\",\n        \"index\": 3\n      },\n      {\n        \"name\": \"price_per_item\",\n        \"type\": \"int\",\n        \"index\": 4\n      },\n      {\n        \"name\": \"quantity\",\n        \"type\": \"int\",\n        \"index\": 5\n      },\n      {\n        \"name\": \"purchase_date\",\n        \"type\": \"datetime\",\n        \"index\": 6\n      },\n      {\n        \"name\": \"payment_method\",\n        \"type\": \"varchar(50)\",\n        \"index\": 7\n      }\n    ],\n    \"pkkey\": [\n      {\n        \"columnname\": \"purchase_id\",\n        \"value\": \"105\"\n      }\n    ]\n  },\n  \"eventrow\": {\n    \"old\": \"{}\",\n    \"current\": \"{\\\"purchase_id\\\": \\\"105\\\", \\\"customer_name\\\": \\\"Anna Doe\\\", \\\"product_id\\\": \\\"101\\\", \\\"product_name\\\": \\\"Game 2077\\\", \\\"price_per_item\\\": \\\"60\\\", \\\"quantity\\\": \\\"1\\\", \\\"purchase_date\\\": \\\"2025-03-14 16:45:01.000\\\", \\\"payment_method\\\": \\\"Credit Card\\\"}\"\n  }\n}"
}

Exemplo de mensagem JSON - atualizado

{
  "specversion": "1.0",
  "type": "com.microsoft.SQL.CES.DML.V1",
  "source": "\/",
  "id": "c425575f-00bb-45cf-acec-c55fdc7d08cd",
  "logicalid": "9c8d4ad2-bf54-4f10-a96f-038af496997f:0000002C000003500004:00000000000000000001",
  "time": "2025-03-14T16:49:59.567Z",
  "datacontenttype": "application\/json",
  "operation": "UPD",
  "splitindex": 0,
  "splittotalcnt": 0,
  "data": "{\n  \"eventsource\": {\n    \"db\": \"db1\",\n    \"schema\": \"dbo\",\n    \"tbl\": \"Purchases\",\n    \"cols\": [\n      {\n        \"name\": \"purchase_id\",\n        \"type\": \"int\",\n        \"index\": 0\n      },\n      {\n        \"name\": \"customer_name\",\n        \"type\": \"varchar(100)\",\n        \"index\": 1\n      },\n      {\n        \"name\": \"product_id\",\n        \"type\": \"int\",\n        \"index\": 2\n      },\n      {\n        \"name\": \"product_name\",\n        \"type\": \"varchar(100)\",\n        \"index\": 3\n      },\n      {\n        \"name\": \"price_per_item\",\n        \"type\": \"int\",\n        \"index\": 4\n      },\n      {\n        \"name\": \"quantity\",\n        \"type\": \"int\",\n        \"index\": 5\n      },\n      {\n        \"name\": \"purchase_date\",\n        \"type\": \"datetime\",\n        \"index\": 6\n      },\n      {\n        \"name\": \"payment_method\",\n        \"type\": \"varchar(50)\",\n        \"index\": 7\n      }\n    ],\n    \"pkkey\": [\n      {\n        \"columnname\": \"purchase_id\",\n        \"value\": \"105\"\n      }\n    ]\n  },\n  \"eventrow\": {\n    \"old\": \"{}\",\n    \"current\": \"{\\\"purchase_id\\\": \\\"105\\\", \\\"customer_name\\\": \\\"Anna Doe\\\", \\\"product_id\\\": \\\"100\\\", \\\"product_name\\\": \\\"Game 2066\\\", \\\"price_per_item\\\": \\\"50\\\", \\\"quantity\\\": \\\"2\\\", \\\"purchase_date\\\": \\\"2025-03-14 16:45:01.000\\\", \\\"payment_method\\\": \\\"Credit Card\\\"}\"\n  }\n}"
}

Exemplo de mensagem JSON - excluir

{
  "specversion": "1.0",
  "type": "com.microsoft.SQL.CES.DML.V1",
  "source": "\/",
  "id": "24fa0c2c-c45d-4abf-9a8d-fba04c29fc86",
  "logicalid": "9c8d4ad2-bf54-4f10-a96f-038af496997f:0000002C000003600019:00000000000000000001",
  "time": "2025-03-14T16:51:39.613Z",
  "datacontenttype": "application\/json",
  "operation": "DEL",
  "splitindex": 0,
  "splittotalcnt": 0,
  "data": "{\n  \"eventsource\": {\n    \"db\": \"db1\",\n    \"schema\": \"dbo\",\n    \"tbl\": \"Purchases\",\n    \"cols\": [\n      {\n        \"name\": \"purchase_id\",\n        \"type\": \"int\",\n        \"index\": 0\n      },\n      {\n        \"name\": \"customer_name\",\n        \"type\": \"varchar(100)\",\n        \"index\": 1\n      },\n      {\n        \"name\": \"product_id\",\n        \"type\": \"int\",\n        \"index\": 2\n      },\n      {\n        \"name\": \"product_name\",\n        \"type\": \"varchar(100)\",\n        \"index\": 3\n      },\n      {\n        \"name\": \"price_per_item\",\n        \"type\": \"int\",\n        \"index\": 4\n      },\n      {\n        \"name\": \"quantity\",\n        \"type\": \"int\",\n        \"index\": 5\n      },\n      {\n        \"name\": \"purchase_date\",\n        \"type\": \"datetime\",\n        \"index\": 6\n      },\n      {\n        \"name\": \"payment_method\",\n        \"type\": \"varchar(50)\",\n        \"index\": 7\n      }\n    ],\n    \"pkkey\": [\n      {\n        \"columnname\": \"purchase_id\",\n        \"value\": \"105\"\n      }\n    ]\n  },\n  \"eventrow\": {\n    \"old\": \"{\\\"purchase_id\\\": \\\"105\\\", \\\"customer_name\\\": \\\"Anna Doe\\\", \\\"product_id\\\": \\\"100\\\", \\\"product_name\\\": \\\"Game 2066\\\", \\\"price_per_item\\\": \\\"50\\\", \\\"quantity\\\": \\\"2\\\", \\\"purchase_date\\\": \\\"2025-03-14 16:45:01.000\\\", \\\"payment_method\\\": \\\"Credit Card\\\"}\",\n    \"current\": \"{}\"\n  }\n}"
}

Formato do atributo de dados

Dados são um objeto JSON encapsulado em atributo string que contém dois atributos:

eventSource
eventRow

"data": "{ "eventsource": {<eventSource>}, "eventrow": {<eventRow>}}"

As secções seguintes explicam estes dois atributos 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: cessqldb001
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: Purchases
cols
- Tipo de dados: Array
- Descrição: uma matriz que detalha as colunas na tabela.
  - name (string): O nome da coluna.
  - type (string): O tipo de dados da coluna (VARCHAR ou INT).
  - índice (inteiro): O índice ou a 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 chave primária.
  - value (string/int/etc.): O valor da coluna usada na chave primária ajuda a identificar exclusivamente a linha.

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

{
  "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": "committime",
                  "type": "string"
                }
              ]
            }
          }
        ]
      }
    },
    {
      "name": "eventrow",
      "type": {
        "name": "EventRow",
        "type": "record",
        "fields": [
          {
            "name": "old",
            "type": "string"
          },
          {
            "name": "current",
            "type": "string"
          }
        ]
      }
    }
  ]
}

Comentários

Esta página foi útil?

Last updated on 2026-07-31