Tous les produits
Search
Centre de documentation

Realtime Compute for Apache Flink:Kafka YAML connector

Dernière mise à jour :Oct 10, 2026

Le connecteur Kafka peut être utilisé en tant que source ou destination dans les tâches d'ingestion de données Flink CDC. Cette rubrique décrit la syntaxe, les paramètres et des exemples d'utilisation du connecteur Kafka YAML.

Prérequis

Connectez-vous à votre cluster en utilisant l'une des méthodes suivantes :

  • Connexion à un cluster ApsaraMQ for Kafka

    • La version du cluster Kafka est 0,11 ou ultérieure.

    • ApsaraMQ for Kafka Le cluster est créé. Pour plus d'informations, consultez la section Créer des ressources.

    • L'espace de travail Flink et le cluster Kafka résident dans le même VPC, et ApsaraMQ for Kafka a ajouté Flink à sa liste d'autorisation. Pour plus d'informations, consultez la section Configurer une liste d'autorisation.

    Important

    Limites liées à l'écriture dans ApsaraMQ for Kafka :

    • ApsaraMQ for Kafka ne prend pas en charge l'écriture de données au format de compression zstd.

    • ApsaraMQ for Kafka ne prend pas en charge les écritures idempotentes ni les écritures transactionnelles ; par conséquent, la sémantique exactly-once fournie par les tables de destination Kafka n'est pas disponible. À partir de la version VVR 8.0.0, le client Kafka open source utilisé par le connecteur Kafka est mis à niveau vers la version 3.x, dans laquelle la propriété properties.enable.idempotence est définie sur true par défaut, ce qui active explicitement les écritures idempotentes. Par conséquent, lorsque vous écrivez dans ApsaraMQ for Kafka avec VVR 8.0.0 ou une version ultérieure, vous devez ajouter explicitement properties.enable.idempotence=false à la table de destination pour désactiver les écritures idempotentes et éviter les échecs d'écriture. Pour comparer les moteurs de stockage et connaître les limites fonctionnelles d'ApsaraMQ for Kafka, consultez la section Comparaison des moteurs de stockage.

  • Connexion à un cluster Apache Kafka autogéré

    • La version du cluster Apache Kafka autogéré est 0,11 ou ultérieure.

    • La connectivité réseau entre Flink et le cluster Apache Kafka autogéré est établie. Pour vous connecter à un cluster autogéré via Internet, consultez la section Connexions réseau.

    • Seuls les éléments de configuration client d'Apache Kafka 2.8 sont pris en charge. Pour plus d'informations, consultez la documentation de configuration des consommateurs et des producteurs d'Apache Kafka.

Limites

  • Il est recommandé d'utiliser Kafka comme source de données pour l'ingestion de données Flink CDC avec VVR 11.1 ou une version ultérieure.

  • Seuls les formats JSON, Debezium JSON et Canal JSON sont pris en charge. Les autres formats de données ne sont pas pris en charge.

  • Pour les sources, les données d'une même table distribuées sur plusieurs partitions ne sont prises en charge qu'à partir de VVR 8.0.11.

Remarques d'utilisation

Actuellement, les écritures transactionnelles ne sont pas recommandées en raison des limitations de conception au sein des communautés Flink et Kafka. Lorsque vous définissez sink.delivery-guarantee = exactly-once, le connecteur Kafka active les écritures transactionnelles. Les trois problèmes suivants sont connus :

  • Chaque point de contrôle (Checkpoint) génère un ID de transaction. Si l'intervalle entre les points de contrôle est trop court, un nombre excessif d'ID de transaction est généré. Le coordinateur du cluster Kafka peut alors manquer de mémoire, ce qui compromet la stabilité du cluster Kafka.

  • Chaque transaction crée une instance de producteur. Si trop de transactions sont validées simultanément, le TaskManager peut manquer de mémoire, ce qui compromet la stabilité de la tâche Flink.

  • Si plusieurs tâches Flink utilisent le même préfixe sink.transactional-id-prefix, les ID de transaction qu'elles génèrent peuvent entrer en conflit. Lorsqu'une tâche échoue à écrire des données, le LSO (Log Start Offset) de la partition Kafka est bloqué, ce qui affecte tous les consommateurs lisant les données depuis cette partition.

Si vous avez besoin d'une sémantique exactly-once, utilisez le connecteur Upsert Kafka pour écrire des données dans une table avec clé primaire et reposez-vous sur la clé primaire pour garantir l'idempotence. Si vous devez absolument utiliser des écritures transactionnelles, consultez la section Sémantique exactly-once.

Syntaxe

source:
  type: kafka
  name: Kafka source
  properties.bootstrap.servers: localhost:9092
  topic: ${kafka.topic}
sink:
  type: kafka
  name: Kafka Sink
  properties.bootstrap.servers: localhost:9092

Éléments de configuration

  • Général

    Paramètre

    Description

    Obligatoire

    Type de données

    Valeur par défaut

    Remarques

    type

    Le type de la source ou du puits.

    Oui

    String

    Aucune

    La valeur doit être kafka.

    name

    Le nom de la source ou du puits.

    Non

    String

    Aucune

    Aucune

    properties.bootstrap.servers

    L'adresse du courtier Kafka.

    Oui

    String

    Aucune

    Le format est host:port,host:port,host:port. Utilisez des virgules (,) pour séparer plusieurs adresses.

    properties.*

    Les configurations transmises directement au client Kafka.

    Non

    String

    Aucune

    Le suffixe doit correspondre à un élément de configuration de producteur ou de consommateur défini dans la documentation officielle d'Apache Kafka.

    Flink supprime le préfixe properties. et transmet la configuration restante au client Kafka. Par exemple, vous pouvez utiliser 'properties.allow.auto.create.topics' = 'false' pour désactiver la création automatique de topics.

    Dans la valeur de properties.sasl.jaas.config, vous pouvez définir le nom d'utilisateur et le mot de passe sur secret://kms.<secret-name>.<key> afin de référencer un identifiant géré par KMS au lieu d'utiliser du texte en clair. Cette fonctionnalité est prise en charge à partir de la version VVR 11.9 du moteur Realtime Compute. Pour la procédure de configuration, consultez Intégration de la gestion des identifiants KMS.

    key.format

    Le format utilisé pour lire ou écrire la partie clé des messages Kafka.

    Non

    String

    Aucune

    • Pour les sources, seul json est pris en charge.

    • Pour les puits, valeurs valides :

      • csv

      • json

    Remarque

    Ce paramètre est pris en charge uniquement à partir de la version VVR 11.0.0.

    value.format

    Le format utilisé pour lire ou écrire la partie valeur des messages Kafka.

    Non

    String

    debezium-json

    • Pour les sources, valeurs valides :

      • debezium-json

      • canal-json

      • json

    • Pour les puits, valeurs valides :

      • debezium-json

      • canal-json

      • canal-protobuf

    Remarque
    • Les formats debezium-json et canal-json sont pris en charge uniquement à partir de la version VVR 8.0.10.

    • Le format json est pris en charge uniquement à partir de la version VVR 11.0.0.

  • Source

    Paramètre

    Description

    Obligatoire

    Type de données

    Valeur par défaut

    Remarques

    topic

    Le nom du topic à lire.

    Non

    String

    Aucune

    Séparez plusieurs noms de topics par des points-virgules (;), par exemple topic-1 et topic-2.

    Remarque

    Vous ne pouvez spécifier qu'un seul paramètre entre topic et topic-pattern.

    topic-pattern

    L'expression régulière utilisée pour faire correspondre les noms des topics à lire. Tous les topics correspondant à l'expression régulière sont lus lors de l'exécution de la tâche.

    Non

    String

    Aucune

    Exemples :

    • user_event_.* : correspond à tous les topics dont le nom commence par user_event_

    • prod\.logs\..* : correspond aux topics dont le nom a le préfixe prod.logs. (le caractère . doit être échappé)

    Remarque

    Vous ne pouvez spécifier qu'un seul paramètre entre topic et topic-pattern.

    properties.group.id

    L'ID du groupe de consommateurs.

    Non

    String

    Aucune

    Si l'ID de groupe spécifié est utilisé pour la première fois, vous devez définir properties.auto.offset.reset sur earliest ou latest pour spécifier le décalage de démarrage initial.

    scan.startup.mode

    Le décalage de démarrage à partir duquel Kafka lit les données.

    Non

    String

    group-offsets

    Valeurs valides :

    • earliest-offset : lit les données à partir du décalage le plus ancien de la partition Kafka.

    • latest-offset : lit les données à partir du décalage le plus récent de la partition Kafka.

    • group-offsets (par défaut) : lit les données à partir du décalage validé du groupe de consommateurs spécifié par properties.group.id.

    • timestamp : lit les données à partir de l'horodatage spécifié par scan.startup.timestamp-millis.

    • specific-offsets : lit les données à partir du décalage spécifié par scan.startup.specific-offsets.

    Remarque

    Ce paramètre prend effet uniquement lorsque la tâche démarre sans état. Lorsque la tâche redémarre à partir d'un point de contrôle (Checkpoint) ou récupère à partir d'un état, la lecture reprend à partir de la progression enregistrée dans l'état.

    scan.startup.specific-offsets

    Le décalage de démarrage de chaque partition lorsque le mode de démarrage est specific-offsets.

    Non

    String

    Aucune

    Exemple : partition:0,offset:42;partition:1,offset:300

    scan.startup.timestamp-millis

    L'horodatage de démarrage lorsque le mode de démarrage est timestamp.

    Non

    Long

    Aucune

    Unité : millisecondes.

    scan.topic-partition-discovery.interval

    L'intervalle de détection dynamique des topics et partitions Kafka.

    Non

    Duration

    5 minutes

    L'intervalle de découverte des partitions par défaut est de 5 minutes. Pour désactiver cette fonctionnalité, définissez explicitement l'intervalle de découverte des partitions sur une valeur non positive. Lorsque la découverte dynamique des partitions est activée, la source Kafka détecte automatiquement les nouvelles partitions et lit les données qui s'y trouvent. En mode topic-pattern, la source lit les données des nouvelles partitions des topics existants ainsi que de toutes les partitions des nouveaux topics correspondant à l'expression régulière.

    scan.check.duplicated.group.id

    Indique s'il faut vérifier si le groupe de consommateurs spécifié par properties.group.id est dupliqué.

    Non

    Boolean

    false

    Valeurs valides :

    • true : vérifie les conflits de groupes de consommateurs avant le démarrage de la tâche. Si un conflit existe, la tâche signale une erreur. Cela permet d'éviter les conflits avec les groupes de consommateurs existants.

    • false : démarre la tâche directement sans vérifier les conflits de groupes de consommateurs.

    schema.inference.strategy

    La politique d'analyse du schéma.

    Non

    String

    continuous

    Valeurs valides :

    • continuous : analyse le schéma de chaque enregistrement. Lorsque deux schémas consécutifs sont incompatibles, un schéma plus large est analysé et un événement de modification de schéma est généré.

    • static : analyse le schéma une seule fois au démarrage de la tâche. Les données sont ensuite analysées sur la base du schéma initial et aucun événement de modification de schéma n'est généré.

    Remarque

    scan.max.pre.fetch.records

    Le nombre maximal de messages à consommer et à analyser à partir de chaque partition lors de l'analyse initiale du schéma.

    Non

    Int

    50

    Avant que la tâche ne lise et ne traite les données, le nombre spécifié de derniers messages est consommé à l'avance à partir de chaque partition pour initialiser les informations de schéma.

    key.fields-prefix

    Le préfixe personnalisé ajouté aux noms de champs analysés à partir de la clé du message. Cela permet d'éviter les conflits de nommage après l'analyse de la clé du message Kafka.

    Non

    String

    Aucune

    Par exemple, si ce paramètre est défini sur key_ et que la clé contient un champ nommé a, le champ sera nommé key_a après l'analyse de la clé.

    Remarque

    La valeur de key.fields-prefix ne peut pas être un préfixe de value.fields-prefix.

    value.fields-prefix

    Le préfixe personnalisé ajouté aux noms de champs analysés à partir de la valeur du message. Cela permet d'éviter les conflits de nommage après l'analyse de la valeur du message Kafka.

    Non

    String

    Aucune

    Par exemple, si ce paramètre est défini sur value_ et que la valeur contient un champ nommé b, le champ sera nommé value_b après l'analyse de la valeur.

    Remarque

    La valeur de value.fields-prefix ne peut pas être un préfixe de key.fields-prefix.

    metadata.list

    Les colonnes de métadonnées à transmettre en aval.

    Non

    String

    Aucune

    Les colonnes de métadonnées disponibles sont topic, partition, offset, timestamp, timestamp-type, headers, leader-epoch, __raw_key__ et __raw_value__. Séparez plusieurs colonnes par des virgules (,).

    Remarque

    Les colonnes de métadonnées __raw_key__ et __raw_value__ sont disponibles uniquement à partir de la version VVR 11.6.

    scan.value.initial-schemas.ddls

    Le schéma initial de tables spécifiques, spécifié à l'aide d'instructions DDL.

    Non

    String

    Aucune

    Séparez plusieurs instructions DDL par ;. Par exemple, utilisez CREATE TABLE db1.t1 (id BIGINT, name VARCHAR(10)); CREATE TABLE db1.t2 (id BIGINT); pour spécifier les schémas initiaux des tables db1.t1 et db1.t2.

    Le schéma de table dans l'instruction DDL doit être cohérent avec la table de destination et respecter les règles de syntaxe Flink SQL.

    Remarque

    Ce paramètre est pris en charge uniquement à partir de la version VVR 11.5.

    ingestion.ignore-errors

    Indique s'il faut ignorer les erreurs lors de l'analyse des données.

    Non

    Boolean

    false

    Remarque

    Ce paramètre est pris en charge uniquement à partir de la version VVR 11.5.

    ingestion.error-tolerance.max-count

    Le nombre cumulé d'erreurs d'analyse après lequel la tâche échoue lorsque les erreurs d'analyse des données sont ignorées.

    Non

    Integer

    -1

    Ce paramètre prend effet uniquement lorsque ingestion.ignore-errors est activé. La valeur par défaut -1 indique que les exceptions d'analyse ne provoquent pas l'échec de la tâche.

    Remarque

    Ce paramètre est pris en charge uniquement à partir de la version VVR 11.5.

    scan.duplicate-field.strategy

    Spécifie comment gérer les noms de champs en double analysés à partir des parties clé et valeur.

    Non

    String

    EXCEPTION

    Valeurs valides :

    • EXCEPTION : lève une exception lorsque des champs en double existent dans la clé et la valeur. Il s'agit du comportement par défaut dans les versions VVR 11.6 et antérieures.

    • PREFER_KEY : privilégie la valeur du champ clé en cas de duplication des champs.

    • PREFER_VALUE : privilégie la valeur du champ valeur en cas de duplication des champs.

    Remarque

    Ce paramètre est pris en charge uniquement à partir de la version VVR 11.7.

    • Table source au format Debezium JSON

      Paramètre

      Obligatoire

      Type de données

      Valeur par défaut

      Description

      debezium-json.distributed-tables

      Non

      Boolean

      false

      Activez cette option si les données d'une seule table au format Debezium JSON apparaissent dans plusieurs partitions.

      Remarque

      Ce paramètre est pris en charge uniquement à partir de la version VVR 8.0.11.

      Important

      Après avoir modifié ce paramètre, vous devez démarrer la tâche sans état.

      debezium-json.schema-include

      Non

      Boolean

      false

      Lorsque vous configurez Debezium Kafka Connect, vous pouvez activer la valeur de configuration Kafka value.converter.schemas.enable pour inclure le schéma dans les messages. Cette option indique si les messages Debezium JSON contiennent le schéma.

      Valeurs valides :

      • true : les messages Debezium JSON contiennent le schéma.

      • false : les messages Debezium JSON ne contiennent pas le schéma.

      debezium-json.ignore-parse-errors

      Non

      Boolean

      false

      Valeurs valides :

      • true : ignore la ligne actuelle lorsqu'une exception d'analyse se produit.

      • false (par défaut) : signale une erreur et la tâche ne parvient pas à démarrer.

      debezium-json.infer-schema.primitive-as-string

      Non

      Boolean

      false

      Indique s'il faut analyser tous les types comme String lors de l'analyse du schéma de la table.

      Valeurs valides :

      • true : analyse tous les types primitifs comme String.

      • false (par défaut) : analyse les données selon les règles de base.

      debezium-json.infer-schema.string-type-inference

      Non

      Boolean

      true

      Indique s'il faut tenter de déduire les champs de chaîne comme étant de type TIME, DATE ou TIMESTAMP. Si ce paramètre est défini sur false, l'inférence est ignorée et les champs restent de type STRING.

      Remarque

      Ce paramètre est pris en charge uniquement à partir de la version VVR 11.8.

    • Table source au format Canal JSON

      Paramètre

      Obligatoire

      Type de données

      Valeur par défaut

      Description

      canal-json.distributed-tables

      Non

      Booléen

      false

      Activez cette option si les données d'une seule table dans le format Canal JSON apparaissent dans plusieurs partitions.

      Remarque

      Ce paramètre est pris en charge uniquement à partir de la version VVR 8.0.11.

      Important

      Après avoir modifié ce paramètre, vous devez démarrer la tâche sans état.

      canal-json.database.include

      Non

      Chaîne

      Aucune

      Expression régulière facultative correspondant au champ de métadonnées de la base de données dans les enregistrements Canal, afin de lire uniquement les journaux des modifications (changelog) de la base de données spécifiée. La chaîne d'expression régulière est compatible avec l'objet Java Pattern.

      canal-json.table.include

      Non

      Chaîne

      Aucune

      Expression régulière facultative correspondant au champ de métadonnées de la table dans les enregistrements Canal, afin de lire uniquement les journaux des modifications (changelog) de la table spécifiée. La chaîne d'expression régulière est compatible avec l'objet Java Pattern.

      canal-json.ignore-parse-errors

      Non

      Booléen

      false

      Valeurs possibles :

      • true : ignore la ligne actuelle en cas d'exception d'analyse.

      • false (par défaut) : signale une erreur et empêche le démarrage de la tâche.

      canal-json.infer-schema.primitive-as-string

      Non

      Booléen

      false

      Indique s'il faut analyser tous les types sous forme de String lors de l'analyse du schéma de la table.

      Valeurs possibles :

      • true : analyse tous les types primitifs sous forme de String.

      • false (par défaut) : analyse les données selon les règles de base.

      canal-json.infer-schema.strategy

      Non

      Chaîne

      AUTO

      Politique d'analyse utilisée lors de l'analyse du schéma de la table.

      Valeurs possibles :

      • AUTO (par défaut) : analyse automatiquement les types en analysant les données JSON. Si les données ne contiennent pas le champ sqlType, nous vous recommandons d'utiliser AUTO pour éviter les échecs d'analyse.

      • SQL_TYPE : analyse les types en se basant sur le tableau sqlType dans les données Canal JSON. Si les données contiennent le champ sqlType, nous vous recommandons de définir canal-json.infer-schema.strategy sur SQL_TYPE pour obtenir des types plus précis.

      • MYSQL_TYPE : analyse les types en se basant sur le tableau mysqlType dans les données Canal JSON.

      Lorsque les données Canal JSON dans Kafka contiennent le champ sqlType et que vous avez besoin d'un mappage de types plus précis, nous vous recommandons de définir canal-json.infer-schema.strategy sur SQL_TYPE.

      Pour connaître les règles de mappage des types sqlType, consultez la section Analyse du schéma Canal JSON.

      Remarque
      • Ce paramètre est pris en charge uniquement à partir de la version VVR 11.1.

      • MYSQL_TYPE est pris en charge uniquement à partir de la version VVR 11.3.

      canal-json.mysql.treat-mysql-timestamp-as-datetime-enabled

      Non

      Booléen

      true

      Indique s'il faut mapper le type timestamp MySQL au type timestamp CDC :

      • true (par défaut) : mappe le type timestamp MySQL au type timestamp CDC.

      • false : mappe le type timestamp MySQL au type timestamp_ltz CDC.

      canal-json.mysql.treat-tinyint1-as-boolean.enabled

      Non

      Booléen

      true

      Indique s'il faut mapper le type MySQL tinyint(1) au type boolean CDC lors de l'utilisation de l'analyse MYSQL_TYPE :

      • true (par défaut) : mappe le type MySQL tinyint(1) au type boolean CDC.

      • false : mappe le type MySQL tinyint(1) au type tinyint(1) CDC.

      Ce paramètre prend effet uniquement lorsque canal-json.infer-schema.strategy est défini sur MYSQL_TYPE.

      canal-json.infer-schema.string-type-inference

      Non

      Booléen

      true

      Indique s'il faut tenter de déduire les champs de type string comme étant de type TIME, DATE ou TIMESTAMP. Si ce paramètre est défini sur false, l'inférence est ignorée et les champs restent de type STRING.

      Remarque

      Ce paramètre est pris en charge uniquement à partir de la version VVR 11.8.

    • Table source au format JSON

      Paramètre

      Obligatoire

      Type de données

      Valeur par défaut

      Description

      json.timestamp-format.standard

      Non

      Chaîne

      SQL

      Format d'horodatage en entrée et en sortie. Valeurs possibles :

      • SQL : analyse les horodatages d'entrée au format yyyy-MM-dd HH:mm:ss.s{précision}, par exemple 2020-12-30 12:13:14.123.

      • ISO-8601 : analyse les horodatages d'entrée au format yyyy-MM-ddTHH:mm:ss.s{précision}, par exemple 2020-12-30T12:13:14.123.

      json.ignore-parse-errors

      Non

      Booléen

      false

      Valeurs possibles :

      • true : ignore la ligne actuelle en cas d'exception d'analyse.

      • false (par défaut) : signale une erreur et empêche le démarrage de la tâche.

      json.infer-schema.primitive-as-string

      Non

      Booléen

      false

      Indique s'il faut analyser tous les types sous forme de String lors de l'analyse du schéma de la table.

      Valeurs possibles :

      • true : analyse tous les types primitifs sous forme de String.

      • false (par défaut) : analyse les données selon les règles de base.

      json.infer-schema.flatten-nested-columns.enable

      Non

      Booléen

      false

      Indique s'il faut développer récursivement les colonnes imbriquées dans les données JSON lors de l'analyse. Valeurs possibles :

      • true : développe récursivement les colonnes imbriquées.

      • false (par défaut) : traite les colonnes imbriquées comme des String.

      json.decode.parser-table-id.fields

      Non

      Chaîne

      Aucune

      Indique s'il faut utiliser les valeurs de champs JSON spécifiques pour générer le tableId lors de l'analyse des données JSON. Séparez plusieurs champs par ,. Par exemple, si les données JSON sont {"col0":"a", "col1","b", "col2","c"}, le résultat généré est le suivant :

      Configuration

      tableId

      col0

      a

      col0,col1

      a.b

      col0,col1,col2

      a.b.c

      json.infer-schema.fixed-types

      Non

      Chaîne

      Aucune

      Types spécifiques de certains champs lors de l'analyse des données JSON. Séparez plusieurs champs par ,. Par exemple, id BIGINT, name VARCHAR(10) spécifie le type du champ id dans les données JSON comme BIGINT et le type du champ name comme VARCHAR(10).

      Remarque
      • Ce paramètre est pris en charge uniquement à partir de la version VVR 11.5.

      • Lorsque vous utilisez ce paramètre dans VVR 11.5, vous devez également ajouter scan.max.pre.fetch.records: 0.

      json.decode.converter-class

      Non

      Chaîne

      Aucune

      Nom complet qualifié de la classe d'implémentation. Le convertisseur peut modifier le tableau d'octets JSON byte[] avant l'analyse des données JSON.

      Remarque

      Ce paramètre est pris en charge uniquement à partir de la version VVR 11.6.

      json.decode.empty-value-as-delete.enabled

      Non

      Booléen

      false

      Indique s'il faut analyser les messages tombstone (avec une valeur vide) dans les topics compactés de Kafka comme des événements DELETE. Cela s'applique aux scénarios où une valeur vide indique une suppression, tels que la mise en miroir de topics compactés et les signaux de suppression CDC.

      Remarque

      Ce paramètre est pris en charge uniquement à partir de la version VVR 11.7.

      json.infer-schema.string-type-inference

      Non

      Booléen

      true

      Indique s'il faut tenter de déduire les champs de type string comme étant de type TIME, DATE ou TIMESTAMP. Si ce paramètre est défini sur false, l'inférence est ignorée et les champs restent de type STRING.

      Remarque

      Ce paramètre est pris en charge uniquement à partir de la version VVR 11.8.

  • Destination (Sink)

    Paramètre

    Description

    Obligatoire

    Type de données

    Valeur par défaut

    Notes

    type

    Type de la destination.

    Oui

    Chaîne

    Aucune

    La valeur doit être kafka.

    name

    Nom de la destination.

    Non

    Chaîne

    Aucune

    Aucune

    topic

    Nom du topic Kafka.

    Non

    Chaîne

    Aucune

    Si cette option est activée, toutes les données sont écrites dans ce topic.

    Remarque

    Si cette option est désactivée, chaque enregistrement est écrit dans le topic nommé d'après sa chaîne TableID (générée en joignant avec .), par exemple databaseName.tableName.

    partition.strategy

    Politique utilisée pour écrire les données dans les partitions Kafka.

    Non

    Chaîne

    all-to-zero

    Valeurs possibles :

    • all-to-zero (par défaut) : écrit toutes les données dans la partition 0.

    • hash-by-key : écrit les données dans plusieurs partitions en fonction de la valeur de hachage de la clé primaire. Cela garantit que les données ayant la même clé primaire sont écrites dans la même partition dans l'ordre.

    sink.tableId-to-topic.mapping

    Mappage entre les noms des tables source et les noms des topics Kafka de destination.

    Non

    Chaîne

    Aucune

    Séparez chaque mappage par ;. Séparez le nom de la table source et le nom du topic Kafka de destination par :. Les noms de table peuvent être des expressions régulières. Plusieurs tables mappées vers le même topic peuvent être jointes par ,. Par exemple : mydb.mytable1:topic1;mydb.mytable2:topic2.

    Remarque

    Ce paramètre vous permet de modifier le topic mappé tout en conservant les informations du nom de table d'origine.

    • Table de destination au format Canal JSON

      Paramètre

      Obligatoire

      Type de données

      Valeur par défaut

      Description

      canal-json.serialize.update.keep-changed-fields-only

      Non

      Booléen

      false

      Indique si la partie « ancienne » d'un message UPDATE au format canal-json contient uniquement les valeurs précédentes des champs qui ont changé.

      Remarque

      Ce paramètre est pris en charge uniquement à partir de la version VVR 11.8.

    • Table de destination au format Debezium JSON

      Paramètre

      Obligatoire

      Type de données

      Valeur par défaut

      Description

      debezium-json.include-schema.enabled

      Non

      Booléen

      false

      Indique si les données Debezium JSON contiennent des informations de schéma.

      debezium-json.emit.full-table-id.enabled

      Non

      Booléen

      false

      Indique s'il faut écrire l'identifiant complet de table en trois parties dans les champs de métadonnées Debezium JSON.

      Mappage lorsque ce paramètre est activé :

      Partie de l'identifiant de table CDC

      Clé Debezium JSON

      Namespace

      db

      Schema

      schema

      Table

      table

      Mappage lorsque ce paramètre est désactivé :

      Partie de l'identifiant de table CDC

      Clé Debezium JSON

      Namespace

      Aucune

      Schema

      db

      Table

      table

      Remarque

      Ce paramètre est pris en charge uniquement à partir de la version VVR 11.6.

Réutiliser un catalogue existant

À partir de la version VVR 11.5, vous pouvez référencer directement le catalogue Kafka intégré créé sur la page Catalogs dans une tâche d'ingestion de données Flink CDC. Cela réduit la nécessité de saisir manuellement les propriétés de connexion.

source:
  type: kafka
  using.built-in-catalog: kafka_catalog

Actuellement, les tâches d'ingestion de données prennent en charge la réutilisation automatique des paramètres de catalogue Kafka suivants :

  • properties.bootstrap.servers

  • format

  • key.fields-prefix

  • value.fields-prefix

  • timestamp-format.standard

  • infer-schema.flatten-nested-columns.enable

  • infer-schema.primitive-as-string

  • max.fetch.records

Pour remplacer les paramètres réutilisés automatiquement, spécifiez explicitement les paramètres YAML correspondants, qui ont une priorité plus élevée.

Exemples de configuration

  • Utilisez Kafka comme source d'une tâche d'ingestion de données :

    source:
      type: kafka
      name: Kafka source
      properties.bootstrap.servers: ${kafka.bootstraps.server}
      topic: ${kafka.topic}
      value.format: ${value.format}
      scan.startup.mode: ${scan.startup.mode}
     
    sink:
      type: hologres
      name: Hologres sink
      endpoint: <yourEndpoint>
      dbname: <yourDbname>
      username: ${secret_values.ak_id}
      password: ${secret_values.ak_secret}
      sink.type-normalize-strategy: BROADEN
  • Utilisez Kafka comme destination d'une tâche d'ingestion de données :

    source:
      type: mysql
      name: MySQL Source
      hostname: ${secret_values.mysql.hostname}
      port: ${mysql.port}
      username: ${secret_values.mysql.username}
      password: ${secret_values.mysql.password}
      tables: ${mysql.source.table}
      server-id: 8601-8604
    
    sink:
      type: kafka
      name: Kafka Sink
      properties.bootstrap.servers: ${kafka.bootstraps.server}
    
    route:
      - source-table: ${mysql.source.table}
        sink-table: ${kafka.topic}

    Dans cet exemple, le module route est utilisé pour définir le nom du topic Kafka dans lequel la table source est écrite.

Remarque

ApsaraMQ for Kafka n'active pas la création automatique de topics par défaut. Pour plus d'informations, consultez la section FAQ sur la création automatique de topics. Avant d'écrire des données dans ApsaraMQ for Kafka, vous devez créer les topics correspondants. Pour plus d'informations, consultez la section Étape 3 : Créer des ressources.

Exemples

Les exemples suivants présentent les configurations pour des scénarios typiques.

Lire un seul topic

L'exemple suivant lit le topic customers et écrit les données dans Data Lake Formation :

source:
  type: kafka
  topic: customers
  properties.bootstrap.servers: localhost:9092
  properties.group.id: ${kafka.group.id}
  value.format: json
  # (可选)动态识别每条数据Schema,并比对生成Schema变更
  schema.inference.strategy: continuous

sink:
  type: paimon
  name: Paimon Sink
  catalog.properties.metastore: rest
  catalog.properties.uri: dlf_uri
  catalog.properties.warehouse: your_warehouse
  catalog.properties.token.provider: dlf
  #(可选)提交用户名,建议为不同作业设置不同的提交用户以避免冲突
  commit.user: your_job_name
  #(可选)开启删除向量,提升读取性能
  table.properties.deletion-vectors.enabled: true

Dans cet exemple, le nom de la table généré pour le format JSON est identique au nom du topic par défaut.

Lire plusieurs topics

L'exemple suivant lit plusieurs topics correspondant à une expression régulière et écrit les données dans le connecteur StarRocks connector :

source:
  type: kafka
  topic-pattern: user_event_.*
  properties.bootstrap.servers: localhost:9092
  properties.group.id: ${kafka.group.id}
  value.format: json
  # (可选)动态识别每条数据Schema,并比对生成Schema变更
  schema.inference.strategy: continuous

sink:
  type: starrocks
  jdbc-url: jdbc:mysql://<yourFeHostname>:9030
  load-url: <yourFeHostname>:8030
  username: <yourUsername>
  password: ${secret_values.starrocks_password}
 
  # (可选)数据量不大的作业建议调低 flush 间隔,避免数据长时间不落盘(默认 300000,即 5 分钟)
  sink.buffer-flush.interval-ms: 5000
  # (可选)上游为 utf8mb4 字符集时建议设为 4,避免文本截断(默认 3)
  unicode-char.max-bytes: 4
  # (可选)自动建表的分桶数;StarRocks 2.5.7 以下必须显式配置,更高版本可自动推断
  table.create.num-buckets: 8
  # (可选)自动建表的副本数,按集群情况配置
  table.create.properties.replication_num: 3
  # (可选)StarRocks 3.2 及以上建议开启,加速表结构变更
  table.create.properties.fast_schema_evolution: true
  # 注意:通过 transform 变更主键时,必须同时设置 sink.ignore.update-before: false,
  # 否则旧主键对应的行会残留在下游

Dans cet exemple, le nom de la table généré pour le format JSON est identique au nom du topic par défaut.

Lire les clés et éviter les conflits de champs

Pour éviter les erreurs dues aux conflits de champs entre la clé et la valeur, utilisez l'une des solutions suivantes :

  1. Ajoutez un préfixe aux champs pour éviter les conflits :

source:
  type: kafka
  topic: ${kafka.topic}
  properties.bootstrap.servers: localhost:9092
  properties.group.id: ${kafka.group.id}
  key.format: json
  value.format: json
  # key部分的字段名添加key_前缀
  key.fields-prefix: key_
  # value部分的字段名添加value_前缀
  value.fields-prefix: value_
  # (可选)动态识别每条数据Schema,并比对生成Schema变更
  schema.inference.strategy: continuous

sink:
  type: paimon
  name: Paimon Sink
  catalog.properties.metastore: rest
  catalog.properties.uri: dlf_uri
  catalog.properties.warehouse: your_warehouse
  catalog.properties.token.provider: dlf
  #(可选)提交用户名,建议为不同作业设置不同的提交用户以避免冲突
  commit.user: your_job_name
  #(可选)开启删除向量,提升读取性能
  table.properties.deletion-vectors.enabled: true
  1. Configurez une politique de résolution des conflits. Pour plus d'informations, consultez la section scan.duplicate-field.strategy. Dans la configuration suivante, les champs de la clé sont prioritaires et les champs portant le même nom dans la valeur sont ignorés en cas de doublons.

source:
  type: kafka
  topic: ${kafka.topic}
  properties.bootstrap.servers: localhost:9092
  properties.group.id: ${kafka.group.id}
  key.format: json
  value.format: json
  # 优先使用key的字段,忽略同名的value中字段
  scan.duplicate-field.strategy: PREFER_KEY
  # (可选)动态识别每条数据Schema,并比对生成Schema变更
  schema.inference.strategy: continuous

sink:
  type: paimon
  name: Paimon Sink
  catalog.properties.metastore: rest
  catalog.properties.uri: dlf_uri
  catalog.properties.warehouse: your_warehouse
  catalog.properties.token.provider: dlf
  #(可选)提交用户名,建议为不同作业设置不同的提交用户以避免冲突
  commit.user: your_job_name
  #(可选)开启删除向量,提升读取性能
  table.properties.deletion-vectors.enabled: true

Ajouter des colonnes de métadonnées

L'exemple suivant lit le topic customers et ajoute les colonnes de métadonnées topic et partition aux champs :

source:
  type: kafka
  topic: customers
  properties.bootstrap.servers: localhost:9092
  properties.group.id: ${kafka.group.id}
  value.format: json
  # (可选)动态识别每条数据Schema,并比对生成Schema变更
  schema.inference.strategy: continuous
  metadata.list: topic,partition

sink:
  type: paimon
  name: Paimon Sink
  catalog.properties.metastore: rest
  catalog.properties.uri: dlf_uri
  catalog.properties.warehouse: your_warehouse
  catalog.properties.token.provider: dlf
  #(可选)提交用户名,建议为不同作业设置不同的提交用户以避免冲突
  commit.user: your_job_name
  #(可选)开启删除向量,提升读取性能
  table.properties.deletion-vectors.enabled: true

Gérer les erreurs d'analyse

Les erreurs d'analyse des données entraînent l'échec des jobs. Vous pouvez configurer un job pour qu'il tolère les erreurs d'analyse, ce qui est couramment utilisé conjointement avec la collecte de données incorrectes.

L'exemple suivant ignore complètement les erreurs d'analyse :

source:
  type: kafka
  topic: customers
  properties.bootstrap.servers: localhost:9092
  properties.group.id: ${kafka.group.id}
  value.format: json
  # (可选)动态识别每条数据Schema,并比对生成Schema变更
  schema.inference.strategy: continuous
  # 开启忽略解析报错,默认忽略全部解析报错
  ingestion.ignore-errors: true

sink:
  type: paimon
  name: Paimon Sink
  catalog.properties.metastore: rest
  catalog.properties.uri: dlf_uri
  catalog.properties.warehouse: your_warehouse
  catalog.properties.token.provider: dlf
  #(可选)提交用户名,建议为不同作业设置不同的提交用户以避免冲突
  commit.user: your_job_name
  #(可选)开启删除向量,提升读取性能
  table.properties.deletion-vectors.enabled: true
  
# 开启脏数据收集器,打印解析失败数据
pipeline:
  dirty-data.collector:
    name: Logger Dirty Data Collector
    type: logger

L'exemple suivant provoque l'échec du job après 30 échecs d'analyse cumulés :

source:
  type: kafka
  topic: customers
  properties.bootstrap.servers: localhost:9092
  properties.group.id: ${kafka.group.id}
  value.format: json
  # (可选)动态识别每条数据Schema,并比对生成Schema变更
  schema.inference.strategy: continuous
  # 开启忽略解析报错
  ingestion.ignore-errors: true
  # 解析报错发生30次后触发作业失败
  ingestion.error-tolerance.max-count: 30
  
sink:
  type: paimon
  name: Paimon Sink
  catalog.properties.metastore: rest
  catalog.properties.uri: dlf_uri
  catalog.properties.warehouse: your_warehouse
  catalog.properties.token.provider: dlf
  #(可选)提交用户名,建议为不同作业设置不同的提交用户以避免冲突
  commit.user: your_job_name
  #(可选)开启删除向量,提升读取性能
  table.properties.deletion-vectors.enabled: true
  
# 开启脏数据收集器,打印解析失败数据
pipeline:
  dirty-data.collector:
    name: Logger Dirty Data Collector
    type: logger

Lire des données JSON

Les sections suivantes décrivent les méthodes courantes pour lire des données au format JSON.

Spécifier l'ID de table pour l'analyse

Par défaut, l'ID de table des données JSON correspond au nom du topic. Vous pouvez spécifier les valeurs des champs des données comme ID de table. Dans l'exemple suivant, les champs db et tbl sont spécifiés comme ID de table.

source:
  type: kafka
  topic: customers
  properties.bootstrap.servers: localhost:9092
  properties.group.id: ${kafka.group.id}
  value.format: json
  # (可选)动态识别每条数据Schema,并比对生成Schema变更
  schema.inference.strategy: continuous
  # 指定字段 db 和 table 作为 table id
  value.json.decode.parser-table-id.fields: db,tbl

sink:
  type: paimon
  name: Paimon Sink
  catalog.properties.metastore: rest
  catalog.properties.uri: dlf_uri
  catalog.properties.warehouse: your_warehouse
  catalog.properties.token.provider: dlf
  #(可选)提交用户名,建议为不同作业设置不同的提交用户以避免冲突
  commit.user: your_job_name
  #(可选)开启删除向量,提升读取性能
  table.properties.deletion-vectors.enabled: true
  
# 开启脏数据收集器,打印解析失败数据
pipeline:
  dirty-data.collector:
    name: Logger Dirty Data Collector
    type: logger

Spécifier les types de champs

Les types de champs sont déduits à partir des valeurs des champs. Certains types inférés peuvent ne pas correspondre à vos attentes. Vous pouvez spécifier des types fixes pour certains champs et ignorer l'inférence et l'évolution ultérieures de ces types de champs.

La configuration suivante fixe les types de quatre champs :

source:
  type: kafka
  topic: customers
  properties.bootstrap.servers: localhost:9092
  properties.group.id: ${kafka.group.id}
  value.format: json
  # 指定字段 db 和 tbl 作为 table id
  value.json.decode.parser-table-id.fields: db,tbl
  # 固定指定部分字段类型
  value.json.infer-schema.fixed-types: 'db STRING, tbl STRING, id BIGINT, amount DECIMAL(18, 2)'
  # 允许未声明字段继续动态推断
  schema.inference.strategy: continuous

sink:
  type: paimon
  name: Paimon Sink
  catalog.properties.metastore: rest
  catalog.properties.uri: dlf_uri
  catalog.properties.warehouse: your_warehouse
  catalog.properties.token.provider: dlf
  #(可选)提交用户名,建议为不同作业设置不同的提交用户以避免冲突
  commit.user: your_job_name
  #(可选)开启删除向量,提升读取性能
  table.properties.deletion-vectors.enabled: true
  
# 开启脏数据收集器,打印解析失败数据
pipeline:
  dirty-data.collector:
    name: Logger Dirty Data Collector
    type: logger

Lire des données Canal JSON

Les sections suivantes décrivent les méthodes courantes pour lire des données au format Canal JSON.

Politiques d'inférence de type

Par défaut, lors de la lecture des données Canal JSON, les valeurs des données sont utilisées pour inférer les types de schéma.

source:
  type: kafka
  topic: customers
  properties.bootstrap.servers: localhost:9092
  properties.group.id: ${kafka.group.id}
  value.format: canal-json
  # (可选)动态识别每条数据Schema,并比对生成Schema变更
  schema.inference.strategy: continuous

sink:
  type: paimon
  name: Paimon Sink
  catalog.properties.metastore: rest
  catalog.properties.uri: dlf_uri
  catalog.properties.warehouse: your_warehouse
  catalog.properties.token.provider: dlf
  #(可选)提交用户名,建议为不同作业设置不同的提交用户以避免冲突
  commit.user: your_job_name
  #(可选)开启删除向量,提升读取性能
  table.properties.deletion-vectors.enabled: true
  
# 开启脏数据收集器,打印解析失败数据
pipeline:
  dirty-data.collector:
    name: Logger Dirty Data Collector
    type: logger

Vous pouvez également déduire les types à partir des informations de schéma (type SQL ou type MySQL) enregistrées dans les données Canal JSON. L'exemple suivant utilise le type MySQL pour déduire le schéma.

source:
  type: kafka
  topic: customers
  properties.bootstrap.servers: localhost:9092
  properties.group.id: ${kafka.group.id}
  value.format: canal-json
  # (可选)动态识别每条数据Schema,并比对生成Schema变更
  schema.inference.strategy: continuous
  # 使用 mysql type 信息推导 Schema,也可以配置为 SQL_TYPE 通过 sql type 推导
  value.canal-json.infer-schema.strategy: MYSQL_TYPE

sink:
  type: paimon
  name: Paimon Sink
  catalog.properties.metastore: rest
  catalog.properties.uri: dlf_uri
  catalog.properties.warehouse: your_warehouse
  catalog.properties.token.provider: dlf
  #(可选)提交用户名,建议为不同作业设置不同的提交用户以避免冲突
  commit.user: your_job_name
  #(可选)开启删除向量,提升读取性能
  table.properties.deletion-vectors.enabled: true
  
# 开启脏数据收集器,打印解析失败数据
pipeline:
  dirty-data.collector:
    name: Logger Dirty Data Collector
    type: logger

Lire des données Debezium JSON

L'exemple suivant lit le topic customers et écrit les données dans Data Lake Formation :

source:
  type: kafka
  topic: customers
  properties.bootstrap.servers: localhost:9092
  properties.group.id: ${kafka.group.id}
  value.format: debezium-json
  # (可选)动态识别每条数据Schema,并比对生成Schema变更
  schema.inference.strategy: continuous

sink:
  type: paimon
  name: Paimon Sink
  catalog.properties.metastore: rest
  catalog.properties.uri: dlf_uri
  catalog.properties.warehouse: your_warehouse
  catalog.properties.token.provider: dlf
  #(可选)提交用户名,建议为不同作业设置不同的提交用户以避免冲突
  commit.user: your_job_name
  #(可选)开启删除向量,提升读取性能
  table.properties.deletion-vectors.enabled: true

Synchroniser les journaux binaires MySQL bruts vers Kafka

L'ingestion de données Flink CDC prend en charge la synchronisation du contenu brut des journaux binaires MySQL vers Canal JSON. Le job suivant synchronise les journaux binaires de plusieurs tables vers le topic order_dw_tables.

source:
  type: mysql
  hostname: #{hostname}
  port: 3306
  username: #{username}
  password: #{password}
  tables: order_dw.\.*
  server-id: 28601-28604
  #(可选)同步增量阶段新创建的表的数据
  scan.binlog.newly-added-table.enabled: true
  #(可选)同步表注释和字段注释
  include-comments.enabled: true
  #(可选)优先分发无界的分片以避免可能出现的TaskManager OutOfMemory问题
  scan.incremental.snapshot.unbounded-chunk-first.enabled: true
  #(可选)开启解析过滤,加速读取
  scan.only.deserialize.captured.tables.changelog.enabled: true
  # 在 Canal JSON 中补充 mysqlType、sqlType、sql、isDdl 等信息
  include-binlog-meta.enable: true
  
sink:
  type: kafka
  properties.bootstrap.servers: localhost:9092
  topic: order_dw_tables
  # Kafka value 使用 Canal JSON changelog 格式
  value.format: canal-json
  # 指定序列化日期类型数据时使用的格式
  value.canal-json.timestamp-format.standard: SQL
  # 数据统一写入分区0,保证binlog顺序
  partition.strategy: all-to-zero

Fonctionnalités avancées

Politiques d'analyse du schéma et de synchronisation des modifications

Le connecteur Kafka conserve les schémas de toutes les tables actuellement connues.

Initialisation des informations de schéma de table

Les informations de schéma de table comprennent les champs et leurs types de données, les informations sur la base de données et la table, ainsi que les clés primaires. Ces trois catégories d'informations sont initialisées comme suit :

  • Informations sur les champs et les types de données

Une tâche d'ingestion de données peut déduire automatiquement les champs et les types de données d'une table à partir des données. Toutefois, dans certains scénarios, vous pouvez souhaiter spécifier explicitement les champs et les types de certaines tables. Selon le niveau de granularité auquel vous définissez les types de champs, l'initialisation du schéma de table peut s'effectuer selon l'une des trois politiques suivantes :

  1. Déduction entièrement automatique par le programme

Avant la lecture des données Kafka, le connecteur tente de consommer par anticipation jusqu'au nombre de messages indiqué par le paramètre scan.max.pre.fetch.records pour chaque partition. Il analyse ensuite le schéma de chaque enregistrement et fusionne ces schémas afin d'initialiser les informations de schéma de table. Avant la consommation effective des données, les événements de création de table correspondants sont générés sur la base du schéma initialisé.

Remarque

Pour les formats Debezium JSON et Canal JSON, les informations de table figurent dans des messages individuels. Les messages scan.max.pre.fetch.records consommés par anticipation peuvent contenir des données provenant de plusieurs tables ; il est donc impossible de déterminer un nombre précis d'enregistrements anticipés par table. La pré-consommation et l'initialisation du schéma de table n'ont lieu qu'une seule fois, avant la consommation et le traitement effectifs des messages de chaque partition. Si des données relatives à une nouvelle table arrivent ultérieurement, le schéma extrait du premier enregistrement de cette table sert de schéma initial, sans nouvelle phase de pré-consommation ni d'initialisation pour cette table.

Important

La prise en charge des données d'une même table réparties sur plusieurs partitions n'est disponible qu'à partir de VVR 8.0.11. Dans ce cas, vous devez définir debezium-json.distributed-tables ou canal-json.distributed-tables sur true.

  1. Spécification du schéma de table initial

Dans certains scénarios, vous pouvez souhaiter définir vous-même le schéma de table initial, par exemple lorsque vous écrivez des données Kafka dans une table aval déjà créée. Ajoutez alors le paramètre scan.value.initial-schemas.ddls pour indiquer le schéma initial. Voici un exemple de configuration :

source:
  type: kafka
  name: Kafka Source
  properties.bootstrap.servers: host:9092
  topic: test-topic
  value.format: json
  scan.startup.mode: earliest-offset
  # 使用数据中的 db、table 字段作为 Table ID
  json.decode.parser-table-id.fields: db,table
  # 设置初始表结构
  scan.value.initial-schemas.ddls: CREATE TABLE db1.t1 (id BIGINT, name VARCHAR(10)); CREATE TABLE db1.t2 (id BIGINT);

L'instruction CREATE TABLE doit être cohérente avec le schéma de la table de destination. Dans cet exemple, le type initial du champ id de la table db1.t1 est défini sur BIGINT, celui du champ name sur VARCHAR(10), et le type initial du champ id de la table db1.t2 sur BIGINT.

L'instruction CREATE TABLE utilise la syntaxe Flink SQL.

  1. Fixation des types pour certains champs

Il peut être nécessaire de figer le type de données de champs spécifiques. Par exemple, vous pouvez vouloir que certains champs, qui seraient autrement inférés comme TIMESTAMP, soient transmis sous forme de chaînes. Ajoutez alors le paramètre json.infer-schema.fixed-types pour définir le schéma de table initial. Cette option n'est effective que lorsque le format de message est json. Voici un exemple de configuration :

source:
  type: kafka
  name: Kafka Source
  properties.bootstrap.servers: host:9092
  topic: test-topic
  value.format: json
  scan.startup.mode: earliest-offset
  # 设置特定字段始终为固定类型
  json.infer-schema.fixed-types: id BIGINT, name VARCHAR(10)
  scan.max.pre.fetch.records: 0

Dans cet exemple, tous les champs id sont fixés au type BIGINT et tous les champs name au type VARCHAR(10).

Les types utilisés correspondent aux types de données Flink SQL.

  • Informations sur la base de données et la table

    • Pour les formats Canal JSON et Debezium JSON, les informations de table sont extraites de chaque message et incluent le nom de la base de données ainsi que le nom de la table.

    • Pour le format JSON, les informations de table ne contiennent par défaut que le nom de la table, qui correspond au nom du topic où résident les données. Si vos données incluent des informations sur la base de données et la table, utilisez le paramètre json.infer-schema.fixed-types pour indiquer les champs contenant ces informations. Ces champs sont mappés respectivement au nom de la base de données et au nom de la table. Voici un exemple de configuration :

      source:
        type: kafka
        name: Kafka Source
        properties.bootstrap.servers: host:9092
        topic: test-topic
        value.format: json
        scan.startup.mode: earliest-offset
        # 使用 col1 字段中的值作为库名,使用 col2 字段中的值作为表名
        json.decode.parser-table-id.fields: col1,col2

      Dans cet exemple, chaque enregistrement est acheminé vers la table dont le nom de base de données correspond à la valeur du champ col1 et dont le nom de table correspond à la valeur du champ col2.

  • Informations sur la clé primaire

    • Pour le format Canal JSON, la clé primaire d'une table est définie à partir du champ pkNames présent dans le JSON.

    • Pour les formats Debezium JSON et JSON, le JSON ne contient pas d'informations sur la clé primaire. Vous pouvez ajouter manuellement des clés primaires à une table à l'aide de règles de transformation :

      transform:
        - source-table: \.*.\.*
          projection: \*
          primary-keys: key1, key2

Analyse du schéma et modifications de schéma

Une fois le schéma de table initialisé, si le paramètre schema.inference.strategy est défini sur static, le connecteur Kafka analyse la valeur de chaque message selon le schéma initial et ne génère aucun événement de modification de schéma. Si schema.inference.strategy est défini sur continuous, le connecteur analyse la valeur de chaque message Kafka, identifie les colonnes physiques du message et les compare au schéma actuellement maintenu. En cas d'écart entre le schéma analysé et le schéma actuel, le connecteur tente de fusionner les schémas et génère les événements de modification de schéma de table correspondants. Les règles de fusion sont les suivantes :

  • Si les colonnes physiques analysées contiennent des champs absents du schéma actuel, ces champs sont ajoutés au schéma et un événement add-nullable-column est généré.

  • Si les colonnes physiques analysées ne contiennent pas un champ déjà présent dans le schéma actuel, ce champ est conservé et ses données sont renseignées avec NULL. Aucun événement drop-column n'est généré.

  • Si les deux schémas contiennent des colonnes portant le même nom, le traitement est le suivant :

    • Lorsque les types sont identiques mais que les précisions diffèrent, le type offrant la précision la plus élevée est retenu et un événement column-type-change est généré.

    • Lorsque les types diffèrent, le nœud parent commun le plus bas dans l'arborescence suivante est utilisé comme type de colonne, et un événement column-type-change est généré.

      image

  • Les politiques de modification de schéma suivantes sont actuellement prises en charge :

    • Ajout d'une colonne : la colonne correspondante est ajoutée à la fin du schéma actuel, les données de la nouvelle colonne sont synchronisées et la colonne est définie comme nullable.

    • Suppression d'une colonne : aucun événement drop-column n'est généré. Les données de la colonne sont automatiquement renseignées avec des valeurs NULL.

    • Renommage d'une colonne : cette opération est traitée comme l'ajout d'une colonne et la suppression d'une autre. La colonne renommée est ajoutée à la fin du schéma actuel et les données de la colonne avant le renommage sont renseignées avec des valeurs NULL.

    • Modification du type d'une colonne :

      • Pour les systèmes aval qui prennent en charge les modifications de type de colonne, les tâches d'ingestion de données acceptent les changements de type des colonnes standard une fois que le connecteur de sortie (sink) aval gère ces modifications. Par exemple, une colonne peut passer du type INT au type BIGINT. Ces évolutions dépendent des règles de modification de type de colonne prises en charge par le sink aval. Chaque table de sortie possède ses propres règles. Reportez-vous à la documentation de la table de sortie pour connaître les règles applicables.

      • Pour les systèmes aval qui ne prennent pas en charge les modifications de type de colonne, tels que Hologres, vous pouvez utiliser Élargissement de type. Dans ce cas, une table aux types élargis est créée dans le système aval au démarrage de la tâche. Lorsqu'une modification de type de colonne survient, la tâche vérifie si le sink aval peut accepter le changement, ce qui permet une prise en charge tolérante des modifications de type de colonne.

  • Les modifications de schéma suivantes ne sont pas prises en charge :

    • Modifications des contraintes, telles que les clés primaires ou les index.

    • Passage de NOT NULL à NULLABLE.

  • Analyse du schéma Canal JSON

    Les données Canal JSON peuvent inclure un champ sqlType facultatif qui enregistre les informations de type précises des colonnes de données. Pour obtenir un schéma plus exact, définissez canal-json.infer-schema.strategy sur SQL_TYPE afin d'utiliser les types indiqués dans sqlType. Les correspondances de types sont les suivantes :

    Type JDBC

    Code de type

    Type CDC

    BIT

    -7

    BOOLEAN

    BOOLEAN

    16

    TINYINT

    -6

    TINYINT

    SMALLINT

    -5

    SMALLINT

    INTEGER

    4

    INT

    BIGINT

    -5

    BIGINT

    DECIMAL

    3

    DECIMAL(38,18)

    NUMERIC

    2

    REAL

    7

    FLOAT

    FLOAT

    6

    DOUBLE

    8

    DOUBLE

    BINARY

    -2

    BYTES

    VARBINARY

    -3

    LONGVARBINARY

    -4

    BLOB

    2004

    DATE

    91

    DATE

    TIME

    92

    TIME

    TIMESTAMP

    93

    TIMESTAMP

    CHAR

    1

    STRING

    VARCHAR

    12

    LONGVARCHAR

    -1

    Autres types

Tolérance et collecte des données erronées

Il arrive que votre source de données Kafka contienne des données malformées (données erronées). Pour éviter que la tâche de synchronisation n'échoue et ne redémarre fréquemment à cause de ces anomalies, vous pouvez configurer la tâche afin qu'elle ignore ces données. Voici un exemple de configuration :

source:
  type: kafka
  name: Kafka Source
  properties.bootstrap.servers: host:9092
  topic: test-topic
  value.format: json
  scan.startup.mode: earliest-offset
  # 开启脏数据容忍功能
  ingestion.ignore-errors: true
  # 容忍 1000 条脏数据
  ingestion.error-tolerance.max-count: 1000

Cette configuration ignore jusqu'à 1 000 enregistrements erronés, permettant à la tâche de s'exécuter normalement en présence d'un faible volume de données incorrectes. Lorsque le nombre d'enregistrements erronés dépasse ce seuil, la tâche échoue, ce qui vous invite à valider les données.

Si vous souhaitez éviter tout échec de la tâche dû aux données erronées, utilisez la configuration suivante :

source:
  type: kafka
  name: Kafka Source
  properties.bootstrap.servers: host:9092
  topic: test-topic
  value.format: json
  scan.startup.mode: earliest-offset
  # 开启脏数据容忍功能
  ingestion.ignore-errors: true
  # 容忍所有的脏数据
  ingestion.error-tolerance.max-count: -1

La politique de tolérance aux données erronées empêche les échecs répétés de la tâche causés par des données anormales. Vous pouvez également souhaiter examiner ces données pour ajuster le comportement du producteur de données Kafka. En suivant la procédure décrite dans Collecte des données erronées, vous pouvez consulter les données erronées de la tâche dans les journaux TaskManager. Voici un exemple de configuration :

source:
  type: kafka
  name: Kafka Source
  properties.bootstrap.servers: host:9092
  topic: test-topic
  value.format: json
  scan.startup.mode: earliest-offset
  # 开启脏数据容忍功能
  ingestion.ignore-errors: true
  # 容忍所有的脏数据
  ingestion.error-tolerance.max-count: -1

pipeline:
  dirty-data.collector:
    # 将脏数据写入 TaskManager 的日志文件中
    type: logger

Politiques de mappage entre les noms de table et les topics

Lorsque Kafka sert de destination (sink) à une tâche d'ingestion de données, le format des messages Kafka (debezium-json ou canal-json) contient également des informations sur le nom de la table. Lors de la consommation ultérieure des messages Kafka, le nom de table présent dans les données est généralement utilisé comme nom de table réel, plutôt que le nom du topic. Il est donc essentiel de configurer avec soin la politique de mappage entre les noms de table et les topics.

Supposons que les deux tables mydb.mytable1 et mydb.mytable2 de MySQL doivent être synchronisées. Les politiques de configuration suivantes sont disponibles :

1. Aucune politique de mappage configurée

En l'absence de politique de mappage, chaque table est écrite dans le topic correspondant, nommé selon le format nom_de_base_de_données.nom_de_table. Ainsi, les données de mydb.mytable1 sont écrites dans le topic nommé mydb.mytable1, et celles de mydb.mytable2 dans le topic nommé mydb.mytable2. Voici un exemple de configuration :

source:
  type: mysql
  name: MySQL Source
  hostname: ${secret_values.mysql.hostname}
  port: ${mysql.port}
  username: ${secret_values.mysql.username}
  password: ${secret_values.mysql.password}
  tables: mydb.mytable1,mydb.mytable2
  server-id: 8601-8604

sink:
  type: kafka
  name: Kafka Sink
  properties.bootstrap.servers: ${kafka.bootstraps.server}

2. Configuration de règles de routage pour le mappage (non recommandé)

Dans de nombreux scénarios, vous ne souhaitez pas que le topic de destination suive le format nom_de_base_de_données.nom_de_table et préférez écrire les données dans un topic spécifique. Configurez alors des règles de routage pour le mappage. Voici un exemple de configuration :

source:
  type: mysql
  name: MySQL Source
  hostname: ${secret_values.mysql.hostname}
  port: ${mysql.port}
  username: ${secret_values.mysql.username}
  password: ${secret_values.mysql.password}
  tables: mydb.mytable1,mydb.mytable2
  server-id: 8601-8604

sink:
  type: kafka
  name: Kafka Sink
  properties.bootstrap.servers: ${kafka.bootstraps.server}
  
 route:
  - source-table: mydb.mytable1,mydb.mytable2
    sink-table: mytable1

Dans ce cas, toutes les données issues de mydb.mytable1 et mydb.mytable2 sont écrites dans le seul topic mytable1.

Toutefois, lorsque des règles de routage modifient le nom du topic de destination, les informations sur le nom de table contenues dans les messages Kafka (au format debezium-json ou canal-json) sont également modifiées. Tous les noms de table dans les messages Kafka deviennent alors mytable1, ce qui peut entraîner des résultats inattendus lors de la consommation des messages de ce topic par d'autres systèmes.

3. Configuration du paramètre sink.tableId-to-topic.mapping pour le mappage (recommandé)

Pour définir des règles de mappage entre les noms de table et les topics tout en préservant les informations sur le nom de table source, utilisez le paramètre sink.tableId-to-topic.mapping. Voici un exemple de configuration :

source:
  type: mysql
  name: MySQL Source
  hostname: ${secret_values.mysql.hostname}
  port: ${mysql.port}
  username: ${secret_values.mysql.username}
  password: ${secret_values.mysql.password}
  tables: mydb.mytable1,mydb.mytable2
  server-id: 8601-8604

sink:
  type: kafka
  name: Kafka Sink
  properties.bootstrap.servers: ${kafka.bootstraps.server}
  sink.tableId-to-topic.mapping: mydb.mytable1,mydb.mytable2:mytable

Ou

source:
  type: mysql
  name: MySQL Source
  hostname: ${secret_values.mysql.hostname}
  port: ${mysql.port}
  username: ${secret_values.mysql.username}
  password: ${secret_values.mysql.password}
  tables: mydb.mytable1,mydb.mytable2
  server-id: 8601-8604

sink:
  type: kafka
  name: Kafka Sink
  properties.bootstrap.servers: ${kafka.bootstraps.server}
  sink.tableId-to-topic.mapping: mydb.mytable1:mytable;mydb.mytable2:mytable

Dans ce cas, toutes les données issues de mydb.mytable1 et mydb.mytable2 sont écrites dans le seul topic mytable1, tandis que les informations sur le nom de table contenues dans les messages Kafka (au format debezium-json ou canal-json) restent mydb.mytable1 ou mydb.mytable2. Lors de la consommation des messages de ce topic par d'autres systèmes, ces derniers peuvent correctement récupérer les informations sur le nom de table source.

Implémentation du convertisseur JSON

Le format des données JSON n'est pas toujours parfaitement homogène, et certaines exigences de traitement ne peuvent pas être satisfaites par le module Transform. Par exemple, vous pouvez avoir besoin de fusionner deux colonnes en une nouvelle, de supprimer les deux colonnes d'origine, tout en garantissant la synchronisation des modifications de schéma. Pour traiter les données JSON avec plus de flexibilité, implémentez l'interface KafkaPayloadConverter afin de modifier les données JSON avant leur traitement par le framework. Pour utiliser cette fonctionnalité, ajoutez la configuration json.decode.converter-class et définissez-la sur le nom qualifié complet de la classe d'implémentation.

Le processus d'implémentation et d'utilisation d'un convertisseur JSON est le suivant :

  1. Implémentez l'interface KafkaPayloadConverter et empaquetez-la. Le dépôt de démonstration open source propose déjà plusieurs exemples d'implémentation.

  2. Ajoutez le fichier empaqueté aux dépendances supplémentaires de la tâche d'ingestion de données.

  3. Dans le module Source, indiquez la configuration json.decode.converter-class. L'exemple suivant utilise la classe ArrayElementExtractorConverter issue du projet open source :

    source:                                                                                                                                                                                                                                                                                                            
      type: kafka                                                                                                                                                                                                                                                                                          
      properties.bootstrap.servers: localhost:9092                                                                                                                                                                                                                                                                     
      topic: my_cdc_topic                                                                                                                                                                                                                                                                                              
      properties.group.id: flink-cdc-group                                                                                                                                                                                                                                                                             
      scan.startup.mode: earliest-offset  
      value.format: json                                                                                                                                                                                                                                                                              
      # 对 Kafka 消息 value 的 JSON 数据应用自定义转换器
      value.json.decode.converter-class: org.apache.flink.cdc.connectors.kafka.ArrayElementExtractorConverter
  4. Déployez et exécutez la tâche.

Format de clé et format de valeur

Dans VVR 11.5 et versions antérieures, il est impossible de distinguer les configurations du format de clé et du format de valeur. Lorsque le même format est utilisé, la configuration s'applique à la fois au format de clé et au format de valeur.

À partir de VVR 11.6, ce comportement est optimisé. Prenons l'exemple du format json : les éléments de configuration de format sont transmis comme suit :

  • Préfixe de format (par exemple json.infer-schema.primitive-as-string) : pour maintenir la compatibilité des versions, les configurations comportant le préfixe de format s'appliquent par défaut à la fois au format de clé et au format de valeur.

  • Préfixe key suivi du préfixe de format (par exemple key.json.infer-schema.primitive-as-string) : les configurations comportant le préfixe key suivi du préfixe de format s'appliquent uniquement au format de clé et ont une priorité supérieure à celles utilisant seulement le préfixe de format.

  • Préfixe value suivi du préfixe de format (par exemple value.json.infer-schema.primitive-as-string) : les configurations comportant le préfixe value suivi du préfixe de format s'appliquent uniquement au format de valeur et ont une priorité supérieure à celles utilisant seulement le préfixe de format.

Dans la configuration source Kafka suivante, des convertisseurs JSON distincts sont configurés pour le format de clé et le format de valeur.

source:                                                                                                                                                                                                                                                                                                            
  type: kafka                                                                                                                                                                                                                                                                                          
  properties.bootstrap.servers: localhost:9092                                                                                                                                                                                                                                                                     
  topic: my_cdc_topic                                                                                                                                                                                                                                                                                              
  properties.group.id: flink-cdc-group                                                                                                                                                                                                                                                                             
  scan.startup.mode: earliest-offset 
  key.format: json  
  value.format: json                                                                                                                                                                                                                                                                            
  # 对 Kafka 消息 key 的 JSON 数据应用自定义转换器
  key.json.decode.converter-class: com.example.KeyExampleConverter                                                                                                                                                                                                                                                                            
  # 对 Kafka 消息 value 的 JSON 数据应用自定义转换器
  value.json.decode.converter-class: com.example.ValueExampleConverter