Événements et flux

Présentation

La hiérarchie des données dans Datastream est la suivante :

Un flux composé d'une source de données et d'une destination.
Un objet, qui correspond à une partie d'un flux, telle qu'une table provenant d'une base de données spécifique.
Un événement, qui correspond à une modification unique générée par un objet spécifique, tel qu'une insertion de base de données.

Les flux, les objets et les événements sont associés à des données et des métadonnées. Ces données et métadonnées peuvent servir à différentes fins.

À propos des événements

Chaque événement se compose de trois types de données :

Données d'événement:il s'agit de la modification apportée aux données elles-mêmes à partir de l'objet provenant de la source du flux. Chaque événement contient l'intégralité de la ligne qui a été modifiée.
Métadonnées génériques : ces métadonnées apparaissent pour chaque événement généré par Datastream utilisé pour des actions, telles que la suppression de données en double dans la destination.
Métadonnées spécifiques à la source:ces métadonnées apparaissent pour chaque événement généré par une source de flux spécifique. Ces métadonnées varient selon la source.

Données d'événement

Les données d'événement correspondent à la charge utile de chaque modification provenant d'un objet donné issu d'une source de flux.

Les événements sont au format Avro ou JSON. Compte tenu du format Avro, pour chaque colonne, l'événement contiendra l'index et la valeur de la colonne. Grâce à cet index, vous pouvez extraire le nom de la colonne et le type unifié à partir du schéma de l'en-tête Avro.

Lorsque vous utilisez le format JSON, l'événement contient le nom et la valeur de chaque colonne.

Les métadonnées d'événement peuvent servir à collecter des informations sur l'origine de l'événement, et à supprimer les données en double dans la destination et les événements de commande par le consommateur en aval.

Les tableaux suivants répertorient et décrivent les champs et les types de données des métadonnées d'événements génériques et spécifiques à la source.

Métadonnées génériques

Ces métadonnées sont cohérentes entre les flux de tous types.

Champ	Type Avro	Type JSON	Description
`stream_name`	chaîne	chaîne	Nom de flux unique, tel qu'il est défini au moment de la création.
`read_method`	chaîne	chaîne	Indique si les données ont été lues à partir de la source à l'aide d'une méthode de capture de données modifiées (CDC, Change Data Capture) dans le cadre d'un remplissage d'historique ou dans le cadre d'une tâche de complément créée lors d'un rollback d'une transaction pendant la réplication CDC. Les valeurs possibles sont les suivantes : `oracle-cdc-logminer` `oracle-backfill` `oracle-supplementation` `mysql-cdc-binlog` `mysql-backfill-incremental` `mysql-backfill-fulldump` `postgres-cdc-wal` `postgresql-backfill`
`object`	chaîne	chaîne	Nom utilisé pour regrouper différents types d'événements, généralement le nom de la table ou de l'objet dans la source.
`schema_key`	chaîne	chaîne	Identifiant unique du schéma unifié de l'événement.
`uuid`	chaîne	chaîne	Identifiant unique de l'événement généré par Datastream.
`read_timestamp`	timestamp-millis	chaîne	Horodatage (UTC) de la lecture de l'enregistrement par Datastream (horodatage de l'epoch en millisecondes).
`source_timestamp`	timestamp-millis	chaîne	Horodatage (UTC) de la modification de l'enregistrement dans la source (horodatage de l'epoch en millisecondes).
`sort_keys`	`{"type": "array", "items": ["string", "long"]}`	tableau	Tableau des valeurs pouvant être utilisées pour trier les événements dans l'ordre dans lequel ils se sont produits.

Métadonnées spécifiques à la source

Ces métadonnées sont associées aux événements de CDC et de remplissage à partir d'une base de données source. Pour afficher ces métadonnées, sélectionnez une source dans le menu déroulant ci-dessous.

Source	Champ	Type Avro	Type JSON	Description
MySQL	`log_file`	chaîne	chaîne	Fichier journal dont Datastream extrait les événements lors de la réplication CDC.
MySQL	`log_position`	long	long	Oosition du journal (décalage) dans le journal binaire MySQL
MySQL	`primary_keys`	tableau de chaînes	tableau de chaînes	Liste des noms de colonnes (un ou plusieurs) qui constituent les clés primaires des tableaux. Si la table ne comporte pas de clé primaire, ce champ est vide.
MySQL	`is_deleted`	boolean	boolean	Une valeur `true` indique que la ligne a été supprimée dans la source. Une valeur `false` signifie que la ligne n'a pas été supprimée.
MySQL	`database`	chaîne	chaîne	Base de données associée à l'événement.
MySQL	`table`	chaîne	chaîne	Tableau associé à l'événement.
MySQL	`change_type`	chaîne	chaîne	Type de modification (`INSERT`, `UPDATE-INSERT`, `UPDATE-DELETE` et `DELETE`) représenté par l'événement. Pour la réplication MySQL basée sur les lignes, chaque événement d'une ligne avec modification de clé primaire contient deux images: une image "avant" dont les colonnes sont mises en correspondance lors de la recherche de la ligne à mettre à jour et une image "après" contenant les modifications. Par exemple, pour la modification `UPDATE-DELETE`, `UPDATE-DELETE` correspond à l'image "avant" et `UPDATE-INSERT` à l'image "après". En savoir plus sur la réplication basée sur les lignes MySQL.
Oracle	`log_file`	chaîne	chaîne	Fichier journal dont Datastream extrait les événements lors de la réplication CDC.
Oracle	`scn`	long	long	Position dans le journal (décalage) dans le journal des transactions Oracle.
Oracle	`row_id`	chaîne	chaîne	row_id d'Oracle.
Oracle	`is_deleted`	boolean	boolean	Une valeur `true` indique que la ligne a été supprimée dans la source. Une valeur `false` signifie que la ligne n'a pas été supprimée.
Oracle	`database`	chaîne	chaîne	Base de données associée à l'événement.
Oracle	`schema`	chaîne	chaîne	Schéma associé à la table à partir de l'événement.
Oracle	`table`	chaîne	chaîne	Tableau associé à l'événement.
Oracle	`change_type`	chaîne	chaîne	Type de modification (`INSERT`, `UPDATE-INSERT`, `UPDATE-DELETE` et `DELETE`) représenté par l'événement. Pour la réplication basée sur des lignes dans Oracle, chaque événement d'une ligne avec modification de clé primaire contient deux images: une image "avant" dont les colonnes sont mises en correspondance lors de la recherche de la ligne à mettre à jour, et une image "après" contenant les modifications. Par exemple, pour la modification `UPDATE-DELETE`, `UPDATE-DELETE` correspond à l'image "avant" et `UPDATE-INSERT` à l'image "après". En savoir plus sur la réplication basée sur les lignes Oracle.
Oracle	`tx_id`	chaîne	chaîne	ID de la transaction à laquelle l'événement appartient.
Oracle	`rs_id`	chaîne	chaîne	ID du jeu d'enregistrements. Le couplage de `rs_id` et `ssn` identifie de manière unique une ligne dans `V$LOGMNR_CONTENTS`. `rs_id` identifie de manière unique l'enregistrement de rétablissement qui a généré la ligne.
Oracle	`ssn`	long	long	Numéro de séquence SQL. Ce numéro est utilisé avec `rs_id` et identifie une ligne de manière unique dans `V$LOGMNR_CONTENTS`.
PostgreSQL	`schema`	chaîne	chaîne	Schéma associé à la table à partir de l'événement.
PostgreSQL	`table`	chaîne	chaîne	Tableau associé à l'événement.
PostgreSQL	`is_deleted`	boolean	boolean	Une valeur `true` indique que la ligne a été supprimée dans la source. Une valeur `false` signifie que la ligne n'a pas été supprimée.
PostgreSQL	`change_type`	chaîne	chaîne	Type de modification (`INSERT`, `UPDATE`, `DELETE`) représenté par l'événement. Pour la réplication basée sur les lignes de PostgreSQL, chaque événement d'une ligne avec modification de clé primaire contient deux images: une image "avant" dont les colonnes sont mises en correspondance lors de la recherche de la ligne à mettre à jour, et une image "après" contenant les modifications. Par exemple, pour la modification `UPDATE-DELETE`, `UPDATE-DELETE` correspond à l'image "avant" et `UPDATE-INSERT` à l'image "après". En savoir plus sur la réplication basée sur les lignes de PostgreSQL
PostgreSQL	`tx_id`	chaîne	chaîne	ID de la transaction à laquelle l'événement appartient.
PostgreSQL	`lsn`	chaîne	chaîne	Numéro de séquence de journal pour l'entrée actuelle.
PostgreSQL	`primary_keys`	tableau de chaînes	tableau de chaînes	Liste des noms de colonnes (un ou plusieurs) qui constituent les clés primaires des tableaux. Si la table ne comporte pas de clé primaire, ce champ est vide.
SQL Server	`table`	chaîne	chaîne	Tableau associé à l'événement.
SQL Server	`database`	long	long	Base de données associée à l'événement.
SQL Server	`schema`	tableau de chaînes	tableau de chaînes	Schéma associé à la table à partir de l'événement.
SQL Server	`is_deleted`	boolean	boolean	Une valeur "true" indique que la ligne a été supprimée dans la source. Une valeur "false" signifie que la ligne n'a pas été supprimée.
SQL Server	`lsn`	chaîne	chaîne	Numéro de séquence dans le journal de l'événement.
SQL Server	`tx_id`	chaîne	chaîne	ID de la transaction à laquelle l'événement appartient.
SQL Server	`physical_location`	Tableau d'entiers	Tableau d'entiers	Emplacement physique de l'enregistrement de journal décrit par trois entiers: l'ID de fichier, l'ID de page et l'ID d'emplacement de l'enregistrement.
SQL Server	`replication_index`	Tableau de chaînes.	Tableau de chaînes.	Liste des noms de colonne d'un index pouvant identifier de manière unique une ligne de la table.
SQL Server	`change_type`	Chaîne	Chaîne	Type de modification (`INSERT`, UPDATE, `DELETE`) représenté par l'événement.

Exemple de flux d'événements

Ce flux illustre les événements générés par trois opérations consécutives : INSERT, UPDATE et DELETE, sur une seule ligne d'une table SAMPLE pour une base de données source.

HEURE	THIS_IS_MY_PK (int)	FIELD1 (nchar pouvant être nul)	FIELD2 (nchar non-null)>
0	1231535353	foo	TLV
1	1231535353	NULL	TLV

INSERT (T0)

La charge utile du message comprend l'intégralité de la nouvelle ligne.

{
  "stream_name": "projects/myProj/locations/myLoc/streams/Oracle-to-Source",
  "read_method": "oracle-cdc-logminer",
  "object": "SAMPLE.TBL",
  "uuid": "d7989206-380f-0e81-8056-240501101100",
  "read_timestamp": "2019-11-07T07:37:16.808Z",
  "source_timestamp": "2019-11-07T02:15:39",
  "source_metadata": {
    "log_file": ""
    "scn": 15869116216871,
    "row_id": "AAAPwRAALAAMzMBABD",
    "is_deleted": false,
    "database": "DB1",
    "schema": "ROOT",
    "table": "SAMPLE"
    "change_type": "INSERT",
    "tx_id":
    "rs_id": "0x0073c9.000a4e4c.01d0",
    "ssn": 67,
  },
  "payload": {
    "THIS_IS_MY_PK": "1231535353",
    "FIELD1": "foo",
    "FIELD2": "TLV",
  }
}

UPDATE (T1)

La charge utile du message comprend l'intégralité de la nouvelle ligne. Il n'inclut pas les valeurs précédentes.

{
  "stream_name": "projects/myProj/locations/myLoc/streams/Oracle-to-Source",
  "read_method": "oracle-cdc-logminer",
  "object": "SAMPLE.TBL",
  "uuid": "e6067366-1efc-0a10-a084-0d8701101101",
  "read_timestamp": "2019-11-07T07:37:18.808Z",
  "source_timestamp": "2019-11-07T02:17:39",
  "source_metadata": {
    "log_file":
    "scn": 15869150473224,
    "row_id": "AAAGYPAATAAPIC5AAB",
    "is_deleted": false,
    "database":
    "schema": "ROOT",
    "table": "SAMPLE"
    "change_type": "UPDATE",
    "tx_id":
    "rs_id": "0x006cf4.00056b26.0010",
    "ssn": 0,
  },
  "payload": {
    "THIS_IS_MY_PK": "1231535353",
    "FIELD1": null,
    "FIELD2": "TLV",
  }
}

DELETE (T2)

La charge utile du message comprend l'intégralité de la nouvelle ligne.

{
  "stream_name": "projects/myProj/locations/myLoc/streams/Oracle-to-Source",
  "read_method": "oracle-cdc-logminer",
  "object": "SAMPLE.TBL",
  "uuid": "c504f4bc-0ffc-4a1a-84df-6aba382fa651",
  "read_timestamp": "2019-11-07T07:37:20.808Z",
  "source_timestamp": "2019-11-07T02:19:39",
  "source_metadata": {
    "log_file":
    "scn": 158691504732555,
    "row_id": "AAAGYPAATAAPIC5AAC",
    "is_deleted": true,
    "database":
    "schema": "ROOT",
    "table": "SAMPLE"
    "change_type": "DELETE",
    "tx_id":
    "rs_id": "0x006cf4.00056b26.0011",
    "ssn": 0,
  },
  "payload": {
    "THIS_IS_MY_PK": "1231535353",
    "FIELD1": null,
    "FIELD2": "TLV",
  }
}

Mise en ordre et cohérence

Cette section explique comment Datastream gère la mise en ordre et la cohérence.

commandes

Datastream ne garantit pas l'ordre, mais chaque événement contient la ligne complète de données et l'horodatage du moment où les données ont été écrites dans la source. Dans BigQuery, les événements non ordonnés sont automatiquement fusionnés dans la bonne séquence. BigQuery utilise les métadonnées de l'événement et un numéro de séquence de modifications interne (CSN) pour appliquer les événements à la table dans le bon ordre. Dans Cloud Storage, les événements planifiés en même temps peuvent s'étendre sur plusieurs fichiers.

Les événements générés dans le désordre se produisent dès lors qu'ils sont remplis pour le remplissage initial des données créées au lancement du flux.

Il est possible de classer les données en fonction de chaque source.

Source	Description
MySQL	Les événements qui font partie du remplissage initial comportent le champ `read_method` commençant par `mysql-backfill`. L'ordre dans lequel les événements sont reçus dans le remplissage n'a aucune incidence, car ils peuvent être utilisés dans n'importe quel ordre. Le champ `read_method` des événements faisant partie de la réplication en cours est défini sur `mysql-cdc-binlog`. L'ordre peut être déduit de la combinaison du champ `log_file` et du champ `log_position` qui est un décalage par rapport au fichier journal. Cette combinaison fournit un nombre unique croissant de manière incrémentielle qui identifie l'ordre des opérations dans la base de données.
Oracle	Les événements qui font partie du remplissage initial comportent le champ `read_method` commençant par `oracle-backfill`. L'ordre dans lequel les événements sont reçus dans le remplissage n'a aucune incidence, car ils peuvent être utilisés dans n'importe quel ordre. Le champ `read_method` des événements faisant partie de la réplication en cours est défini sur `oracle-cdc-logminer`. L'ordre peut être déduit de la combinaison du champ `rs_id` (ID du jeu d'enregistrements) et du champ `ssn` (numéro de séquence SQL). Cette combinaison fournit un nombre unique croissant de manière incrémentielle qui identifie l'ordre des opérations dans la base de données.
PostgreSQL	Les événements qui font partie du remplissage initial comportent le champ `read_method` commençant par `postgresql-backfill`. L'ordre dans lequel les événements sont reçus dans le remplissage n'a aucune incidence, car ils peuvent être utilisés dans n'importe quel ordre. Le champ `read_method` des événements faisant partie de la réplication en cours est défini sur `postgres-cdc-wal`. L'ordre peut être déterminé par la combinaison des champs `source_timestamp` et `lsn` (numéro de séquence du journal). Cette combinaison fournit un nombre unique croissant de manière incrémentielle qui identifie l'ordre des opérations dans la base de données.
SQL Server	Les événements qui font partie du remplissage initial comportent le champ `read_method` commençant par `sqlserver-backfill`. L'ordre dans lequel les événements sont reçus dans le remplissage n'a aucune incidence, car ils peuvent être utilisés dans n'importe quel ordre. Le champ `read_method` des événements faisant partie de la réplication en cours est défini sur `sqlserver-cdc`. L'ordre peut être déterminé par la combinaison des champs `source_timestamp` et `lsn` (numéro de séquence du journal). Cette combinaison fournit un nombre unique croissant de manière incrémentielle qui identifie l'ordre des opérations dans la base de données.

Cohérence

Datastream garantit que les données de la base de données source seront livrées à la destination au moins une fois. Aucun événement ne sera manqué, mais il peut y avoir des événements en double dans le flux. La fenêtre des événements en double doit être de l'ordre de quelques minutes et l'identifiant unique universel (UUID) de l'événement dans les métadonnées d'événement peut être utilisé pour détecter les doublons.

Lorsque les fichiers journaux de base de données contiennent des transactions non validées, si des transactions sont annulées, la base de données le reflète dans les fichiers journaux en tant qu'opérations en langage de manipulation de données (LMD) "inverses". Par exemple, une opération INSERT annulée aura une opération DELETE correspondante. Datastream lit ces opérations à partir des fichiers journaux.

À propos des flux

Chaque flux contient des métadonnées qui décrivent à la fois le flux et la source dont il extrait les données. Ces métadonnées incluent des informations telles que le nom du flux, les profils de connexion source et de destination, etc.

Pour afficher la définition complète de l'objet "Flux", consultez la documentation de référence de l'API.

État d'un flux

Un flux peut avoir l'un des états suivants :

Not started
Starting
Running
Draining
Paused
Failed
Failed permanently

Vous pouvez utiliser les journaux pour trouver des informations d'état supplémentaires, telles que le remplissage des tables, le nombre de lignes traitées, etc. Vous pouvez également utiliser l'API FetchStreamErrors pour récupérer les erreurs.

Métadonnées d'objets disponibles en utilisant l'API Discovery

L'API Discover renvoie des objets représentant la structure des objets définis dans la source de données ou la destination représentées par le profil de connexion. Chaque objet possède des métadonnées sur l'objet lui-même, ainsi que pour chaque champ de données qu'il extrait. Ces métadonnées sont disponibles via l'API Discover.

Contrôles de simultanéité de flux

Créer un flux