Debezium系列之：消息过滤

相关技术博客：

• Debezium系列之：基于内容的路由

一、消息过滤

默认情况下，Debezium 将它接收到的每个数据更改事件传递给 Kafka 代理。但是，在许多情况下，您可能只对生产者发出的事件的一个子集感兴趣。为了使您能够仅处理与您相关的记录，Debezium 提供了过滤器单消息转换 (SMT)。

注意：

• 过滤器 SMT 正在积极开发中。发出的消息的结构或其他细节可能会随着开发的进行而改变。

虽然可以使用 Java 创建自定义 SMT 来编码过滤逻辑，但使用自定义编码的 SMT 有其缺点。例如：

• 有必要预先编译转换并将其部署到 Kafka Connect。
• 每次更改都需要重新编译和重新部署代码，导致操作不灵活。

过滤器 SMT 支持与 JSR 223（Java™ 平台脚本）集成的脚本语言。

Debezium 不附带任何 JSR 223 API 的实现。要在 Debezium 中使用表达式语言，您必须下载该语言的 JSR 223 脚本引擎实现。例如，对于 Groovy 3，您可以从 https://groovy-lang.org/ 下载其 JSR 223 实现。 GraalVM JavaScript 的 JSR223 实现可在 https://github.com/graalvm/graaljs 获得。获得脚本引擎文件后，将它们与语言实现使用的任何其他 JAR 文件一起添加到 Debezium 连接器插件目录中。

二、部署

出于安全原因，过滤器 SMT 不包含在 Debezium 连接器档案中。相反，它在单独的工件 debezium-scripting-2.2.1.Final.tar.gz 中提供。

要将基于内容的路由 SMT 与 Debezium 连接器插件一起使用，您必须将 SMT 构件显式添加到您的 Kafka Connect 环境中。重要提示：过滤器 SMT 出现在 Kafka Connect 实例中后，任何被允许向实例添加连接器的用户都可以运行脚本表达式。为确保脚本表达式只能由授权用户运行，请确保在添加过滤器 SMT 之前保护 Kafka Connect 实例及其配置接口。

安装 Zookeeper、Kafka、Kafka Connect 和一个或多个 Debezium 连接器后，安装过滤器 SMT 的剩余任务是：

• 下载脚本 SMT 存档
• 将存档的内容提取到 Kafka Connect 环境的 Debezium 插件目录中。
• 获取 JSR-223 脚本引擎实现并将其内容添加到 Kafka Connect 环境的 Debezium 插件目录中。
• 重新启动 Kafka Connect 进程以获取新的 JAR 文件。

Groovy 语言需要类路径中的以下库：

• groovy
• groovy-json（可选）
• groovy-jsr223

JavaScript 语言在类路径中需要以下库：

• graalvm.js
• graalvm.js.scriptengine

三、示例：基本配置

您可以在 Debezium 连接器的 Kafka Connect 配置中配置过滤器转换。在配置中，您通过定义基于业务规则的过滤条件来指定您感兴趣的事件。当过滤器 SMT 处理事件流时，它会根据配置的过滤条件评估每个事件。只有满足过滤条件的事件才会传递给代理。

要配置 Debezium 连接器以过滤更改事件记录，请在 Debezium 连接器的 Kafka Connect 配置中配置过滤器 SMT。过滤器 SMT 的配置要求您指定定义过滤条件的正则表达式。

例如，您可以在连接器配置中添加以下配置。

transforms=filter
transforms.filter.type=io.debezium.transforms.Filter
transforms.filter.language=jsr223.groovy
transforms.filter.condition=value.op == 'u' && value.before.id == 2

前面的示例指定使用 Groovy 表达式语言。正则表达式 value.op == ‘u’ && value.before.id == 2 删除所有消息，除了那些表示 id 值等于 2 的更新 (u) 记录的消息。

自定义配置
前面的示例显示了一个简单的 SMT 配置，该配置旨在仅处理包含操作字段的 DML 事件。连接器可能发出的其他类型的消息（心跳消息、墓碑消息或关于架构更改和事务的元数据消息）不包含此字段。为避免处理失败，您可以定义一个 SMT 谓词语句，选择性地将转换仅应用于特定事件。

四、过滤器表达式中使用的变量

Debezium 将某些变量绑定到过滤器 SMT 的评估上下文中。当您创建表达式来指定过滤条件时，您可以使用 Debezium 绑定到评估上下文中的变量。通过绑定变量，Debezium 使 SMT 能够在评估表达式中的条件时查找和解释它们的值。

下表列出了 Debezium 绑定到过滤器 SMT 的评估上下文中的变量：
表 1. 过滤器表达式变量

Name	Description	Type
key	消息的键	org.apache.kafka.connect​.data​.Struct
value	消息的值。	org.apache.kafka.connect.data​.Struct
keySchema	消息键的架构。	org.apache.kafka.connect​.data​.Schema
valueSchema	消息值的架构。	org.apache.kafka.connect​.data​.Schema
topic	目标主题的名称。	String
headers	消息头的 Java 映射。关键字段是标题名称。 headers 变量公开以下属性：值（对象类型），模式（类型为 org.apache.kafka .connect .data .Schema）	java.util.Map​<String, ​io.debezium.transforms​.scripting​.RecordHeader>

表达式可以对其变量调用任意方法。表达式应解析为一个布尔值，该值确定 SMT 如何处理消息。当表达式中的筛选条件计算结果为真时，将保留消息。当过滤条件的计算结果为假时，消息将被删除。

表达式不应导致任何副作用。也就是说，他们不应该修改他们传递的任何变量。

五、有选择地应用转换的选项

除了 Debezium 连接器在发生数据库更改时发出的更改事件消息外，连接器还会发出其他类型的消息，包括心跳消息以及关于架构更改和事务的元数据消息。由于这些其他消息的结构不同于 SMT 旨在处理的更改事件消息的结构，因此最好将连接器配置为有选择地应用 SMT，以便它仅处理预期的数据更改消息。您可以使用以下方法之一将连接器配置为有选择地应用 SMT：

• 为转换配置 SMT 谓词。
• 使用 SMT 的 topic.regex 配置选项。

更多内容可以参考博主下面的博文：

• Debezium系列之：详细介绍基于SMT、predicates、逻辑命名空间扩展debezium的应用功能

六、语言细节

表达过滤条件的方式取决于您使用的脚本语言。

例如，如基本配置示例所示，当您使用 Groovy 作为表达式语言时，以下表达式将删除所有消息，id 值设置为 2 的更新记录除外：

value.op == 'u' && value.before.id == 2

其他语言使用不同的方法来表达相同的条件。

注意：
Debezium MongoDB 连接器将 after 和 patch 字段作为序列化的 JSON 文档而不是结构发出。
要将过滤器 SMT 与 MongoDB 连接器一起使用，必须首先将 JSON 中的数组字段展开到单独的文档中。
可以通过应用 MongoDB ExtractNewDocumentState SMT 来执行此操作。

还可以采用在表达式中使用 JSON 解析器的方法，为每个数组项生成单独的输出文档。
例如，如果使用 Groovy 作为表达式语言，请将 groovy-json 工件添加到类路径中，然后添加一个表达式，例如 (new groovy.json.JsonSlurper()).parseText(value.after).last_name == ‘Kretchmar’。

Javascript
如果使用JavaScript作为表达式语言，可以调用Struct#get()方法指定过滤条件，如下例：

value.get('op') == 'u' && value.get('before').get('id') == 2

Javascript 与 Graal.js
如果将 JavaScript 与 Graal.js 一起使用来定义过滤条件，则您使用的方法类似于您在 Groovy 中使用的方法。例如：

value.op == 'u' && value.before.id == 2

七、配置选项

下表列出了可用于过滤器 SMT 的配置选项。

表 2. 过滤器 SMT 配置选项

属性	默认值	描述
topic.regex		一个可选的正则表达式，用于评估事件的目标主题名称以确定是否应用过滤逻辑。如果目标主题的名称与 topic.regex 中的值匹配，则转换会在将事件传递给主题之前应用过滤器逻辑。如果主题名称与 topic.regex 中的值不匹配，则 SMT 将事件原封不动地传递给主题。
language		编写表达式所用的语言。必须以 jsr223. 开头，例如 jsr223.groovy 或 jsr223.graal.js。 Debezium 仅支持通过 JSR 223 API（“Java™ 平台脚本”）进行引导。
condition		要为每条消息计算的表达式。必须评估为布尔值，其中 true 的结果保留消息，false 的结果删除它。
null.handling.mode	keep	指定转换如何处理空（逻辑删除）消息。您可以指定以下选项之一：保持：（默认）传递消息。降低：完全删除消息。评价：将过滤条件应用于消息。