时区转换器

Debezium 发出事件记录时，记录中时间戳字段的时区值可能各不相同，具体取决于数据源的类型和配置。为了在数据处理管道和应用中保持数据的一致性和精确性，你可以使用 Timezone Converter 单消息转换（SMT），确保事件记录使用统一的时区来表示时间戳数据。

该 SMT 使用 converted.timezone 配置选项，将指定字段的值转换为目标时区。目标时区可以指定为地理时区，例如 America/New_York，也可以指定为 UTC 偏移量，例如 +02:00。默认假定记录中的字段使用 UTC。除了指定时区之外，该 SMT 还提供配置选项，可通过 include.list 和 exclude.list 配置选项来包含或排除需要进行时区转换的特定字段。

该 SMT 支持所有 Debezium 和 Kafka Connect 的时间类型与非时间类型。

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

示例：基本配置

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

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

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

应用 TimezoneConverter 的效果

以下示例展示 TimezoneConverter 转换如何修改事件记录中的时间戳字段。第一个示例展示的是未经过该转换处理的 Debezium 事件记录，记录保留其原始的时间戳值。下一个示例展示的是应用该转换之后的同一事件记录。按照基本配置示例中指定的配置，SMT 会将源消息中时间戳字段的原始 UTC 值转换为 Pacific/Easter 时区的值。

示例 1. 经 TimezoneConverter 转换处理之前的事件记录值

created_at 字段的值显示的是 UTC 时间。

{
        "before": null,
        "after": {
            "id": 1,
            "first_name": "Anne",
            "last_name": "Kretchmar",
            "email": "[email protected]",
            "created_at": "2011-01-11T16:40:30.123456789+00:00"
        },
        "source": {
            "version": "3.6.3.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
    }

示例 2. 经 TimezoneConverter 转换处理后的事件记录值

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

{
        "before": null,
        "after": {
            "id": 1,
            "first_name": "Anne",
            "last_name": "Kretchmar",
            "email": "[email protected]",
            "created_at": "2011-01-11T11:40:30.123456789-05:00"
        },
        "source": {
            "version": "3.6.3.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
    }

示例：高级配置

SMT 并非只能转换事件记录中的所有时间戳字段，您也可以配置它只转换特定字段。下面的示例展示了如何在 SMT 配置中使用 include.list 选项，仅转换事件记录中的 created_at 和 updated_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

配置选项

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

表 1. TimezoneConverter SMT 配置选项

属性

说明

类型

重要性

converted.timezone

一个字符串，用于指定时间戳字段应转换到的目标时区。目标时区可以指定为地理时区（例如 America/New_York），也可以指定为 UTC 偏移量（例如 +02:00）。

string

高

include.list

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

source:<tablename>

匹配源信息块中具有指定表名的 Debezium 更改事件。SMT 会转换匹配表中的所有基于时间的字段。

source:<tablename>:<fieldname>

匹配源信息块中具有指定表名的 Debezium 更改事件。SMT 仅转换指定表中具有指定字段名的字段。fieldname 可以添加 before、after 或 source 前缀，以包含事件记录中的相应字段。如果未指定前缀，则 before 和 after 字段都会被转换。

topic:<topicname>

匹配来自指定主题名的事件，并转换事件记录中的所有基于时间的字段。

topic:<topicname>:<fieldname>

匹配来自指定主题名的事件，且仅转换指定字段的值。fieldname 可以添加 before、after 或 source 前缀，以包含事件记录中的相应字段。如果未指定前缀，则 before 和 after 字段都会被转换。

<matchname>:<fieldname>

采用启发式匹配算法，在源信息块存在时与其表名进行匹配，否则与主题名进行匹配。SMT 仅转换指定字段名的值。fieldname 可以添加 before、after 或 source 前缀，以包含事件记录中的相应字段。如果未指定前缀，则 before 和 after 字段都会被转换。

list

中

exclude.list

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

source:<tablename>

匹配源信息块中具有指定表名的 Debezium 更改事件。SMT 会将匹配表中的所有基于时间的字段排除在转换之外。

source:<tablename>:<fieldname>

table:<tablename>

匹配与源信息块中具有指定表名的 Debezium 更改事件。该 SMT 会从转换中排除指定表内与指定字段名匹配的字段。fieldname 可以加上 before、after 或 source 前缀，以排除事件记录中相应部分的字段。如果未指定前缀，则 before 和 after 中的字段都会被排除在转换之外。

table:<tablename>:<fieldname>

匹配与源信息块中具有指定表名的 Debezium 更改事件。该 SMT 会从转换中排除指定表内字段名匹配的字段。fieldname 可以加上 before、after 或 source 前缀，以排除事件记录中相应部分的字段。如果未指定前缀，则 before 和 after 中的字段都会被排除在转换之外。

topic:<topicname>

匹配来自指定主题名的事件，并从转换中排除该主题中所有基于时间的字段。

topic:<topicname>:<fieldname>

匹配来自指定主题名的事件，并从转换中排除该主题中具有指定名称的字段。fieldname 可以加上 before、after 或 source 前缀，以排除事件记录中相应部分的字段。如果未指定前缀，则 before 和 after 中的字段都会被排除在转换之外。

<matchname>:<fieldname>

使用启发式匹配算法与源信息块的表名进行匹配（如果存在）；否则与主题名进行匹配。该 SMT 仅从转换中排除具有指定名称的字段。fieldname 可以加上 before、after 或 source 前缀，以排除事件记录中相应部分的字段。如果未指定前缀，则 before 和 after 中的字段都会被排除在转换之外。

list

medium