Red Hat Summit 红帽全球峰会支持控制台（Console）开发人员开始试用联系人

7.12. 在 Debezium 事件记录中转换时区值

当 Debezium 发出事件记录时，记录中时间戳字段的时区值可能会有所不同，具体取决于数据源的类型和配置。要在数据处理管道和应用程序内保持数据一致性和精度，您可以使用 Timezone Converter SMT 来确保事件记录使用一致的时区来代表时间戳数据。

SMT 使用 converted.timezone 配置选项将指定字段的值转换为目标时区。您可以将目标时区指定为地理时区，如 America/New_York 或 UTC 偏移，如 +02:00。假设记录的字段为 UTC。除了指定的时区，SMT 还提供配置选项，以使用 include.list 和 exclude.list 配置选项从时区转换中包含或排除特定字段。

SMT 支持所有 Debezium 和 Kafka Connect temporal 和 non-temporal 类型。

以下主题提供详情：

注意

要遵守夏时节省时间，您必须在 converted.timezone 配置选项中指定地理时区。如果您指定了 UTC 偏移，则转换会应用来自 UTC 的固定偏移量，该偏移对于观察日常节省时间的区域不准确。当将时间戳字段转换为不观察每天节省时间的特定时区时，提供固定的 UTC 偏移非常有用。

注意

include.list 和 exclude.list 配置选项是互斥的。您必须只指定其中一个选项。

SMT 还支持将源信息块中的事件元数据字段转换为目标时区，如 ts_ms。要转换元数据字段，您必须在 include.list 或 exclude.list 配置选项的 fieldname 中包含 源 前缀。

注意

如果源信息块中时间戳字段的模式（如 ts_ms ）当前被设置为 INT64，这不是时间戳类型，则以后的发行版本旨在通过引入时间戳模式的兼容性来支持此类字段的转换。

7.12.1. 示例：基本 Debezium 时区转换器 SMT 配置

在连接器的 Kafka Connect 配置中配置 TimezoneConverter SMT，将事件记录中的基于时间的字段转换为目标时区。

例如，要将事件记录中的所有时间戳字段从 UTC 转换为 Pacific/Easter 时区，请将以下行添加到连接器配置中： 

transforms=convertTimezone
transforms.convertTimezone.type=io.debezium.transforms.TimezoneConverter
transforms.convertTimezone.converted.timezone=Pacific/Easter

7.12.1.1. 将 TimezoneConverter SMT 应用到 Debezium 事件记录的影响

以下示例演示了 TimezoneConverter 转换如何修改事件记录中的 timestamp 字段。第一个示例演示了一个 Debezium 事件记录，它没有被转换处理；记录会保留其原始时间戳值。下一个示例演示了在应用转换后相同的事件记录。根据 基本配置示例中指定的配置，SMT 会将源消息中的原始 UTC 时间戳字段转换为 Pacific/Easter 时区值。

例 7.3. 在由 TimezoneConverter 转换处理前事件记录值

created_at 字段的值显示 UTC 时间。 

{
        "before": null,
        "after": {
            "id": 1,
            "first_name": "Anne",
            "last_name": "Kretchmar",
            "email": "annek@noanswer.org",
            "created_at": "2011-01-11T16:40:30.123456789+00:00"
        },
        "source": {
            "version": "3.0.8.Final",
            "connector": "postgresql",
            "name": "PostgreSQL_server",
            "ts_ms": 1559033904863,
            "ts_us": 1559033904863000,
            "ts_ns": 1559033904863000000,
            "snapshot": true,
            "db": "postgres",
            "sequence": "[\"24023119\",\"24023128\"]",
            "schema": "public",
            "table": "customers",
            "txId": 555,
            "lsn": 24023128,
            "xmin": null
        },
        "op": "c",
        "ts_ms": 1559033904863,
        "ts_us": 1559033904863875,
        "ts_ns": 1559033904863875124
    }
Copy to clipboard

例 7.4. 通过 TimezoneConverter 转换处理后事件记录值

SMT 将 created_at 字段的原始 UTC 值转换为 基本配置 示例中指定的目标 Pacific/Easter 时区的时间。SMT 还添加了一个 event_timestamp 字段。 

{
        "before": null,
        "after": {
            "id": 1,
            "first_name": "Anne",
            "last_name": "Kretchmar",
            "email": "annek@noanswer.org",
            "created_at": "2011-01-11T11:40:30.123456789-05:00"
        },
        "source": {
            "version": "3.0.8.Final",
            "connector": "postgresql",
            "name": "PostgreSQL_server",
            "ts_ms": 1559033904863,
            "ts_us": 1559033904863752,
            "ts_ns": 1559033904863752000,
            "snapshot": true,
            "db": "postgres",
            "sequence": "[\"24023119\",\"24023128\"]",
            "schema": "public",
            "table": "customers",
            "txId": 555,
            "lsn": 24023128,
            "xmin": null,
            "id": 100
        },
        "op": "c",
        "ts_ms": 1559033904863,
        "ts_us": 1559033904863971,
        "ts_ns": 1559033904863971541,
        "event_timestamp": 1626102708861
    }
Copy to clipboard

7.12.2. 示例：高级 Debezium converter SMT 配置

您可以将 SMT 配置为仅转换特定字段，而不是转换事件记录中的所有时间戳字段。以下示例演示了如何在 SMT 配置中使用 include.list 选项，来仅在事件记录中转换 created_at、update_at 时间戳字段。以下配置使用固定偏移而不是地理时区设计器，将时间从 UTC 转换为 +05:30。 

transforms=convertTimezone
transforms.convertTimezone.type=io.debezium.transforms.TimezoneConverter
transforms.convertTimezone.converted.timezone=+05:30
transforms.convertTimezone.include.list=source:customers:created_at,customers:updated_at

在某些情况下，您可能想要从时区转换中排除特定的时间戳字段。例如，要在事件记录从时区转换中排除 updated_at 时间戳字段，请使用 exclude.list 配置选项，如下例所示： 

transforms=convertTimezone
transforms.convertTimezone.type=io.debezium.transforms.TimezoneConverter
transforms.convertTimezone.converted.timezone=+05:30
transforms.convertTimezone.exclude.list=source:customers:updated_at

7.12.3. 用于配置 Debezium 时区转换器转换的选项

下表列出了 TimezoneConverter SMT 的配置选项。

表 7.14. TimezoneConverter SMT 配置选项

属性

描述

类型

重要信息

converted.timezone

指定应转换时间戳字段的目标时区的字符串。目标时区可以指定为地理时区，如 America/New_York 或 UTC 偏移，例如 +02:00。

string

high

include.list

以逗号分隔的规则列表，用于指定 SMT 包括的字段进行时区转换。使用以下格式之一指定规则：

source:<tablename>
将 Debezium 更改事件与具有指定表名称的源信息块匹配。SMT 转换匹配表中的所有基于时间的字段。
source:<tablename>:<fieldname>
将 Debezium 更改事件与具有指定表名称的源信息块匹配。SMT 仅转换指定字段名称的指定表中的字段。Fieldname 可以在 之前、之后 或 源前面加上 前缀，以在事件记录中包含适当的字段。如果没有指定前缀，则转换 before 和 after 字段。
topic:<topicname>
匹配指定主题名称的事件，在事件记录中转换所有基于时间的字段。
topic:<topicname>:<fieldname>
匹配指定主题名称中的事件，并仅转换指定字段的值。Fieldname 可以在 之前、之后 或 源前面加上 前缀，以在事件记录中包含适当的字段。如果没有指定前缀，则转换 before 和 after 字段。
<matchname>:<fieldname>
应用高度匹配算法，以匹配源信息块的表名称（如果存在）；否则，与主题名称匹配。SMT 仅转换指定字段名称的值。Fieldname 可以在 之前、之后 或 源前面加上 前缀，以在事件记录中包含适当的字段。如果没有指定前缀，则转换 before 和 after 字段。

list

中

exclude.list

以逗号分隔的规则列表，用于指定要从时区转换中排除的字段。使用以下格式之一指定规则：

source:<tablename>
将 Debezium 更改事件与具有指定表名称的源信息块匹配。SMT 从转换中排除匹配表中的所有基于时间的字段。
source:<tablename>:<fieldname>
将 Debezium 更改事件与具有指定表名称的源信息块匹配。SMT 从与指定字段名称匹配的指定表中的转换字段中排除。Fieldname 可以在 之前、之后 或 源前面加上 前缀，以排除事件记录中的相应字段。如果没有指定前缀，则 before 和 after 字段都会不包括在转换中。
topic:<topicname>
匹配指定主题名称的事件，并从主题中的所有基于时间的字段中排除。
topic:<topicname>:<fieldname>
匹配指定主题名称的事件，并从具有指定名称的主题中的任何字段中排除。Fieldname 可以在 之前、之后 或 源前面加上 前缀，以排除事件记录中的相应字段。如果没有指定前缀，则 before 和 after 字段都会不包括在转换中。
<matchname>:<fieldname>
应用高度匹配算法，以匹配源信息块的表名称（如果存在）；否则，与主题名称匹配。SMT 仅排除指定名称的转换字段。Fieldname 可以在 之前、之后 或 源前面加上 前缀，以排除事件记录中的相应字段。如果没有指定前缀，则 before 和 after 字段都会不包括在转换中。

list

中

返回顶部
Red Hat logoGithubredditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

通过我们的产品和服务，以及可以信赖的内容，帮助红帽用户创新并实现他们的目标。 了解我们当前的更新.

让开源更具包容性

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。欲了解更多详情，请参阅红帽博客.

關於紅帽

我们提供强化的解决方案，使企业能够更轻松地跨平台和环境（从核心数据中心到网络边缘）工作。

Theme

© 2025 Red Hat, Inc.