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

S'applique à : SQL Server 2025 (17.x) Azure SQL Database Azure SQL Managed Instance Base de données SQL dans Microsoft Fabric

Cet article décrit le format de message CloudEvents qui diffuse vers Azure Event Hubs ou Fabric Eventstream lorsque vous utilisez la fonction de changement de flux d’événements (CES) dans SQL Server 2025 (17.x), Azure SQL Database, Azure SQL Managed Instanceet la base de données SQL dans Microsoft Fabric.

Remarque

Le streaming des événements de changement est actuellement en aperçu, et présente des différences de supportabilité selon les produits. Pendant la préversion, cette fonctionnalité est susceptible de changer.

Aperçu

Le changement d’événements en streaming émet des événements qui suivent la spécification CloudEvents , ce qui vous permet de les intégrer facilement avec des systèmes pilotés par des événements. Tous ces CloudEvents contiennent 11 attributs (champs). Vous pouvez configurer CES pour sérialiser l’ensemble de CloudEvent, y compris l’attribut data , en binaire JSON natif ou Avro. Les événements JSON natifs ne contiennent pas de sections binaires Avro. Dans les deux formats de sérialisation, l’attribut data a un type de tableau d’octets. Les octets utilisent un codage binaire JSON ou Avro selon le format de sérialisation sélectionné et suivent le schéma Avro attribut CES.

Important

Depuis le 15 août 2026, le protocole AMQP est obsolété pour le flux d’événements de changement (CES). Il y a des différences entre les plateformes. Pour les étapes de migration et les délais de migration, voir dépréciation du protocole AMQP.

Lorsque cela est applicable, les descriptions de cette section proviennent de la spécification CloudEvent, qui inclut plus de détails.

Attributs

specversion :
- Type de données : Chaîne
- Attribut CloudEvent requis
- Version de la spécification CloudEvents utilisée par l’événement. Cette version permet d’interpréter le 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 cette valeur est défini par le producteur et peut inclure des informations telles que la version du type. Pour plus d’informations, voir Versioning of CloudEvents.
- Pour modifier les événements de streaming d’événements, le type est actuellement : com.microsoft.SQL.CES.DML.V{n}, où {n} indique la version du schéma d’événements DML de changement d’événements de streaming d’événements Microsoft.
  - 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. La combinaison de la source et de l’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 combinaison de la source et de l’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 identifiants logiques partagés identifient les messages divisés (en raison des restrictions de taille des messages des Event Hubs).
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 concernant la manière dont le contenu des données est affiché pour différentes datacontenttype valeurs sont définies dans les spécifications du format d’événement.
operation
- Type de données : Chaîne
- Attribut d’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 au sein des blocs logiques du message. 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, , et segmentindex les champs pour trier les événements entrants qui représentent une grande répartition de la charge utile SQL selon la valeur configurée finalsegmentmax_message_size_kb.
finalsegment
- Type de données : booléen
- Attribut d’extension
- Indique si ce segment est le dernier segment de la séquence. Ce champ est toujours présent et aide à identifier si un événement SQL a été divisé en sous-événements selon la valeur configurée max_message_size_kb .
data
- Type de données : tableau d’octets
- Attribut CloudEvent facultatif
- Contient les données d’événement spécifiques au domaine qui décrivent le changement. Désérialisez les octets en binaire JSON ou Avro selon le format de sérialisation sélectionné. Les données désérialisées suivent le schéma Avro de l’attribut CES. Pour plus d’informations sur ses champs, voir Data attribute format.

Remarque

La division des messages est distincte de la troncature par valeurs de colonne. Avant que CES ne sérialise l’attribut data , il tronque chaque valeur de colonne en flux supérieure à 1 Mo à 1 Mo. CES divise ensuite l’événement formé en blocs de message selon les besoins selon max_message_size_kb.

Exemples

Exemple de message JSON - Insérer

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

Exemple de message JSON - mise à jour

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

Exemple de message JSON - Supprimer

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

Format d’attribut de données

L’attribut data est un tableau d’octets. Désérialisez les octets en binaire JSON ou Avro selon le format de sérialisation sélectionné. Dans les deux formats, l’enregistrement résultant Data suit le schéma Avro attribut CES et contient deux attributs :

eventsource
eventrow

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

Les sections suivantes expliquent les attributs désérialisés plus en détail.

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 : EmployeesDb
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 : Employees
cols
- Type de données : Tableau
- Description : tableau détaillant les colonnes du tableau.
  - name (ficelle) : Le nom de la colonne.
  - type (chaîne) : Le type de données SQL de la colonne, incluant sa longueur, sa précision ou son échelle lorsque cela est applicable. Exemples : , intnvarchar(50)et datetime2(7).
  - index (entier) : L’index ou la position de la colonne dans le tableau.
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) : Le nom de la colonne utilisée dans la clé primaire.
  - value (chaîne) : La valeur de la colonne utilisée dans la clé primaire. Cette valeur aide à identifier de manière unique la ligne.
transaction
- Type de données : Objet
- Description : Décrit la transaction SQL contenant l’opération de données.
  - commitlsn (chaîne) : Le numéro de séquence de log de validation (LSN) de la transaction.
  - beginlsn (string) : Le LSN de début de la transaction.
  - sequencenumber (entier) : Le nombre séquentiel de l’opération de données dans la transaction. Utilisez cette valeur pour trier les événements au sein d’une transaction.
  - finalevent (booléen) : Pas utilisé. Ce corps a toujours une valeur de false.
  - committime (chaîne) : La date et l’heure de la transaction dans la base de données.

Remarque

Sur les produits SQL configurés avec un fuseau horaire non UTC, le committime champ inclut incorrectement un suffixe Z , même si ce champ affiche l’heure locale de la base de données publiante. Lorsque la base de données utilise UTC, la valeur et le suffixe concordent. Ce problème est connu, et une correction est en attente dans une future version de la fonctionnalité.

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 Avro 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 Avro attribut des données CES

Utilisez le schéma suivant lors de la désérialisation du tableau d’octets data dans les CloudEvents binaires natifs JSON et 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"
          }
        ]
      }
    }
  ]
}

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2026-08-14

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

Aperçu

Spécifications et ressources associées

Attributs

Exemples

Exemple de message JSON - Insérer

Exemple de message JSON - mise à jour

Exemple de message JSON - Supprimer

Format d’attribut de données

eventsource

eventrow

Schéma Avro CES CloudEvent

Schéma Avro attribut des données CES

Contenu connexe

Commentaires

Ressources supplémentaires