Partilhar via

Formato de mensagem JSON - alterar o streaming de eventos

Aplica-se a: SQL Server 2025 (17.x) Azure SQL Database

Este artigo descreve o formato JSON de uma mensagem CloudEvents que é transmitida do SQL Server para os Hubs de Eventos Azure ao utilizar a funcionalidade de alterar streaming de eventos (CES) introduzida no SQL Server 2025 (17.x) e na Azure SQL Database.

Observação

O streaming de eventos de mudança está atualmente em pré-visualização para:

Durante a visualização, esse recurso está sujeito a alterações. Para saber mais sobre a capacidade de suporte atual, consulte Limitações.

Visão geral

Os eventos emitidos pelo streaming de eventos de alteração seguem a especificação CloudEvents , facilitando a integração com sistemas orientados a eventos. Todos os CES CloudEvents contêm 11 atributos (campos). O CES pode ser configurado para serializar CloudEvents como JSON (nativo) ou como binário Avro. As seções a seguir deste artigo descrevem o formato da mensagem em detalhes, incluindo atributos CES CloudEvent e serialização.

Quando aplicável, as descrições nesta seção são retiradas da especificação CloudEvent, que inclui detalhes adicionais.

Atributos

  • specversion:

    • Tipo de dados: Cadeia
    • Atributo CloudEvent necessário
    • A versão da especificação CloudEvents que o evento usa. Isso 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 é definido pelo produtor e pode incluir informações como a versão do tipo. Para obter mais informações, consulte 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 em que um evento aconteceu. Source + ID deve ser exclusivo 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 fonte + ID seja ú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
    • As mensagens divididas (devido a restrições de tamanho msg dos Hubs de Eventos) são identificadas por IDs lógicos compartilhados.

  • 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 de formato de eventos

  • operation

    • Tipo de dados: Cadeia
    • 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 de mensagem lógica. 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 + segmentindex + campos finalsegment para ordenar os eventos recebidos que representam uma grande carga útil SQL dividida em múltiplos eventos.

  • finalsegment

    • Tipo de dados: Boolean
    • Atributo de extensão
    • Informa se este segmento é o segmento final da sequência. Este campo está sempre presente e ajuda a identificar se um evento SQL demasiado grande para o tamanho máximo de mensagem configurado foi dividido em subeventos.

  • 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.

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>}, "eventdata": {<eventData>}}"

Os detalhes desses dois atributos são explicados com mais detalhes nas seguintes seções:

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.

Esquema JSON do 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 JSON 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"
          }
        ]
      }
    }
  ]
}

Conteúdo relacionado

  • Last updated on