Partager via

Format de message JSON - Modifier le streaming d’événements

S’applique à : SQL Server 2025 (17.x) Azure SQL Database

Cet article décrit le format JSON d’un message CloudEvents diffusé de SQL Server vers Azure Event Hubs lors de l’utilisation de la fonction de changement de flux d’événements (CES) introduite dans SQL Server 2025 (17.x) et Azure SQL Database.

Remarque

La diffusion en continu d’événements change actuellement en préversion pour :

Pendant la préversion, cette fonctionnalité est susceptible de changer. Pour connaître la prise en charge actuelle, consultez Limitations.

Aperçu

Les événements émis par la diffusion en continu d’événements de modification suivent la spécification CloudEvents , ce qui facilite leur intégration avec les systèmes pilotés par les événements. Tous ces CloudEvents contiennent 11 attributs (champs). CES peut être configuré pour sérialiser CloudEvents en tant que JSON (natif) ou en tant que binaire Avro. Les sections suivantes de cet article décrivent le format de message en détail, y compris les attributs CES CloudEvent et la sérialisation.

Le cas échéant, les descriptions de cette section sont extraites de la spécification CloudEvent, qui inclut des détails supplémentaires.

Attributs

  • specversion :

    • Type de données : Chaîne
    • Attribut CloudEvent requis
    • Version de la spécification CloudEvents utilisée par l’événement. Cela permet l’interprétation du contexte.

  • type

    • Type de données : Chaîne
    • Attribut CloudEvent requis
    • Contient une valeur qui décrit le type d’événement lié à l’occurrence d’origine. Le format de celui-ci est défini par le producteur et peut inclure des informations telles que la version du type. Pour plus d’informations, passez en revue le contrôle de version de CloudEvents.
    • Pour les événements de diffusion d’événements de changement, le type est actuellement : com.microsoft.SQL.CES.DML.V{n}, où {n} indique la version du schéma d’événement DML de streaming d’événements de changement d’événement.
      • La dernière version actuelle du schéma est la 1.

  • source

    • Type de données : Chaîne
    • Attribut CloudEvent requis
    • Identifie le contexte dans lequel un événement s’est produit. Source + ID doit être unique pour chaque événement. Actuellement, ce champ est toujours envoyé comme \/ dans des événements diffusés depuis SQL.

  • id

    • Type de données : Chaîne
    • Attribut CloudEvent requis
    • Identifie l’événement. Les producteurs doivent s’assurer que la source + ID est unique pour chaque événement distinct. Si un événement en double est renvoyé (par exemple, en raison d’une erreur réseau), il peut avoir le même ID. Les consommateurs peuvent supposer que les événements avec une source et un ID identiques sont des doublons.

  • logicalid

    • Type de données : Chaîne
    • Attribut d’extension
    • Les messages fractionnés (en raison des restrictions de taille de msg Event Hubs) sont identifiés par des ID logiques partagés.

  • time

    • Type de données : Horodatage
    • Attribut CloudEvent facultatif
    • Horodatage UTC du moment où le commit a eu lieu dans une transaction SQL qui déclenche à l’origine un événement en streaming.

  • datacontenttype

    • Type de données : Chaîne
    • Attribut CloudEvent facultatif
    • Type de contenu de valeur de données. Cet attribut permet aux données de porter n’importe quel type de contenu, dans lequel le format et l’encodage peuvent différer de celui du format d’événement choisi. Par exemple, un événement rendu au format d’enveloppe JSON peut contenir une charge utile XML dans les données, et le consommateur est informé par cet attribut défini sur « application/xml ». Les règles pour la manière dont le contenu des données est rendu pour différentes datacontenttype valeurs sont définies dans les spécifications du format d’événement

  • operation

    • Type de données : Chaîne
    • Extension
    • Représente le type d’opération SQL qui a eu lieu :
      • INS pour les inserts
      • Mise à jour pour les mises à jour
      • DEL pour les suppressions

  • segmentindex

    • Type de données : Integer
    • Attribut d’extension
    • Index de segment, qui indique la position du message dans les blocs de message logiques. L’index de segment fournit des informations sur l’emplacement du message dans la séquence de fragments de message logique. Ce champ est toujours présent. Utilisez logicalid + segmentindex + finalsegment champs pour trier les événements entrants représentant une grande charge utile SQL divisée en plusieurs événements.

  • finalsegment

    • Type de données : booléen
    • Attribut d’extension
    • Indique si ce segment est le segment final de la séquence. Ce champ est toujours présent et aide à identifier si un événement SQL trop grand pour la taille maximale configurée du message a été divisé en sous-événements.

  • data

    • Type de données : Chaîne
    • Attribut CloudEvent facultatif
    • Données d’événement spécifiques au domaine. Pour CES, les données sont des chaînes qui peuvent être analysées en tant que JSON. Ce json décrit comment les données ont changé. Le format de l’attribut de données est au format d’attribut de données.

Exemples

Exemple de message JSON - Insérer

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

Exemple de message JSON – mis à jour

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

Exemple de message JSON - Supprimer

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

Format d’attribut de données

Les données sont un objet JSON encapsulé dans l’attribut de chaîne qui contient deux attributs :

  • eventSource
  • eventRow
"data": "{ "eventsource": {<eventSource>}, "eventdata": {<eventData>}}"

Les détails de ces deux attributs sont expliqués plus en détail dans les sections suivantes :

eventsource

Décrit les métadonnées relatives à la base de données et à la table où l’événement s’est produit :

  • db

    • Type de données : Chaîne
    • Description : nom de la base de données où se trouve la table.
    • Exemple : cessqldb001

  • schema

    • Type de données : Chaîne
    • Description : schéma de base de données qui contient la table.
    • Exemple : dbo

  • tbl

    • Type de données : Chaîne
    • Description : table dans laquelle l’événement s’est produit.
    • Exemple : Purchases

  • cols

    • Type de données : Tableau
    • Description : tableau détaillant les colonnes du tableau.
      • nom (chaîne) : nom de la colonne.
      • type (chaîne) : type de données de la colonne (VARCHAR ou INT).
      • index (entier) : index ou position de la colonne dans la table.

  • pkkey

    • Type de données : Tableau
    • Description : représente les colonnes clés primaires et leurs valeurs pour identifier la ligne spécifique.
      • columnname (chaîne) : nom de colonne utilisé dans la clé primaire.
      • valeur (chaîne/int/etc.) : la valeur de la colonne utilisée dans la clé primaire permet d’identifier de manière unique la ligne.

eventrow

Décrit les modifications au niveau des lignes et compare les valeurs anciennes et actuelles des champs de l’enregistrement.

  • old (objet encapsulé dans la chaîne) : représente les valeurs de la ligne avant l’événement.
    • Chaque paire clé-valeur se compose des éléments suivants :
      • <column_name>: (chaîne) : nom de la colonne.
      • <column_value>: (chaîne/int/etc.) : valeur précédente pour cette colonne.
  • current (objet encapsulé dans la chaîne) : représente les valeurs mises à jour dans la ligne après l’événement.
    • Similaire à l’ancien objet, avec chaque paire clé-valeur structurée comme suit :
      • <column_name> (chaîne) : nom de la colonne.
      • <column_value> (chaîne/int/etc.) : nouvelle ou valeur actuelle pour cette colonne.

Schéma JSON 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"
    }
  ]
}

Schéma JSON de l’attribut de données 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"
          }
        ]
      }
    }
  ]
}

Contenu connexe

  • Last updated on