Debezium シリーズ: コンテンツベースのルーティング

1. コンテンツベースルーティングの概念

デフォルトでは、Debezium はテーブルから読み取られたすべての変更イベントを単一の静的トピックにストリーミングします。ただし、場合によっては、イベントの内容に基づいて、選択したイベントを他のトピックに再ルーティングすることが望ましい場合があります。コンテンツに基づいてメッセージをルーティングするプロセスについては、「コンテンツ ベースのルーティング メッセージング パターン」で説明されています。Debezium でこのパターンを適用するには、コンテンツベースのルーティングのシングル メッセージ変換 (SMT) を使用して、イベントごとに評価される式を作成できます。

イベントの評価方法に応じて、SMT はイベント メッセージを元のターゲット トピックにルーティングするか、式で指定されたトピックに再ルーティングします。

知らせ：

• コンテンツベースのルーティング SMT は現在開発中です。発行されるメッセージの構造やその他の詳細は、開発の進行に応じて変更される可能性があります。

Java でカスタム SMT を作成してルーティング ロジックをコード化することは可能ですが、カスタム コード化された SMT の使用には欠点があります。例えば：

• 変換を事前にコンパイルし、Kafka Connect にデプロイする必要があります。
• 変更を加えるたびにコードの再コンパイルと再デプロイが必要となり、その結果、操作が柔軟性に欠けていました。

コンテンツベースのルーティング SMT は、JSR 223 (Java™ Platform Scripting) と統合されたスクリプト言語をサポートします。

Debezium には、JSR 223 API の実装は同梱されていません。Debezium で式言語を使用するには、その言語の JSR 223 スクリプト エンジン実装をダウンロードする必要があります。たとえば、Groovy 3 の場合、その JSR 223 実装を https://groovy-lang.org/ からダウンロードできます。GraalVM JavaScript の JSR223 実装は、https://github.com/graalvm/graaljs で入手できます。スクリプト エンジン ファイルを取得したら、言語実装で使用される他の JAR ファイルとともに、それらを Debezium コネクタ プラグイン ディレクトリに追加します。

2.展開

• セキュリティ上の理由から、コンテンツベースのルーティング SMT は Debezium コネクタの tarball には含まれていません。
• 代わりに、別のアーティファクト debezium-scripting-2.2.1.Final.tar.gz で提供されます。

Debezium コネクタ プラグインでコンテンツ ベースのルーティング SMT を使用するには、SMT アーティファクトを Kafka Connect 環境に明示的に追加する必要があります。重要: ルーティング SMT が Kafka Connect インスタンスに存在すると、そのインスタンスへのコネクタの追加を許可されたユーザーはスクリプト式を実行できます。承認されたユーザーのみがスクリプト式を実行できるようにするには、ルーティング SMT を追加する前に、Kafka Connect インスタンスとその構成インターフェイスを必ず保護してください。

Zookeeper、Kafka、Kafka Connect、および 1 つ以上の Debezium コネクタをインストールした後、フィルター SMT をインストールするための残りのタスクは次のとおりです。

1. スクリプト SMT アーカイブをダウンロードする
2. アーカイブの内容を Kafka Connect 環境の Debezium プラグイン ディレクトリに抽出します。
3. JSR-223 スクリプト エンジン実装を取得し、その内容を Kafka Connect 環境の Debezium プラグイン ディレクトリに追加します。
4. Kafka Connect プロセスを再起動して、新しい JAR ファイルを取得します。

Groovy 言語では、クラスパス上に次のライブラリが必要です。

• グルーヴィーな
• groovy-json (オプション)
• groovy-jsr223

JavaScript 言語では、クラスパスに次のライブラリが必要です。

• graalvm.js
• graalvm.js.scriptエンジン

3. 例：基本構成

イベントの内容に基づいて変更イベント レコードをルーティングするように Debezium コネクタを構成するには、コネクタの Kafka Connect 構成で ContentBasedRouter SMT を構成できます。

コンテンツベース ルーティング SMT を構成するには、フィルター条件を定義する正規表現を指定する必要があります。設定では、ルーティング条件を定義する正規表現を作成します。この式は、イベント レコードを評価するパターンを定義します。また、パターンに一致するイベントのルーティング先となるターゲット トピックの名前も指定します。指定されたスキーマは、テーブルの挿入、更新、削除操作などのイベント タイプを指定する場合があります。特定の列または行の値と一致するパターンを定義することもできます。

たとえば、すべての更新 (u) レコードを更新トピックに再ルーティングするには、次の構成をコネクタ構成に追加します。

...
transforms=route
transforms.route.type=io.debezium.transforms.ContentBasedRouter
transforms.route.language=jsr223.groovy
transforms.route.topic.expression=value.op == 'u' ? 'updates' : null
...

前述の例では、Groovy 式言語の使用を指定しています。

パターンに一致しないレコードは、デフォルトのトピックにルーティングされます。

カスタム構成
前述の例は、アクション フィールドを含む DML イベントのみを処理するように設計された単純な SMT 構成を示しています。コネクタが発行する可能性のある他の種類のメッセージ (ハートビート メッセージ、トゥームストーン メッセージ、またはトランザクションまたはスキーマの変更に関するメタデータ メッセージ) には、このフィールドは含まれません。処理の失敗を避けるために、特定のイベントにのみ変換を選択的に適用する SMT 述語ステートメントを定義できます。

4. コンテンツベースのルーティング式で使用される変数

Debezium は、特定の変数を SMT の評価コンテキストにバインドします。ルーティング ターゲットを制御する条件を指定する式を作成する場合、SMT はこれらの変数の値を検索して解釈し、式内の条件を評価できます。

次の表は、Debezium がコンテンツベースのルーティング SMT にバインドする評価コンテキストの変数を示しています。

表 1. コンテンツベースのルーティング式変数

名前	説明	タイプ
鍵	メッセージのキー。	org.apache.kafka.connect .data .Struct
価値	メッセージの値。	org.apache.kafka.connect .data .Struct
キースキーマ	メッセージキーのスキーマ。	org.apache.kafka.connect .data .Schema
値スキーマ	メッセージキーの構造。	org.apache.kafka.connect .data .Schema
トピック	対象のトピックの名前。	弦
ヘッダー	メッセージヘッダーの Java マッピング。キーフィールドはタイトル名です。headers 変数は次のプロパティを公開します: 値 (オブジェクト タイプ) スキーマ (org.apache.kafka.connect.data.Schema タイプ)	java.util.Map<String, io.debezium.transforms.scripting.RecordHeader>

式は変数に対して任意のメソッドを呼び出すことができます。式は、SMT がメッセージを処理する方法を決定するブール値に解決される必要があります。式内のルーティング条件が true と評価されると、メッセージは保持されます。ルーティング条件が false と評価されると、メッセージはドロップされます。

式によって副作用が発生してはなりません。つまり、渡す変数を変更してはなりません。

5. 変換を選択的に適用するオプション

データベースの変更が発生したときに Debezium コネクタが発行する変更イベント メッセージに加えて、コネクタは、ハートビート メッセージや、スキーマの変更とトランザクションに関するメタデータ メッセージなど、他の種類のメッセージも発行します。これらの他のメッセージの構造は、SMT が処理するように設計された変更イベント メッセージの構造とは異なるため、予想されるデータ変更メッセージのみを処理するように、SMT を選択的に適用するようにコネクタを構成することが最善です。次のいずれかの方法を使用して、SMT を選択的に適用するようにコネクタを構成できます。

• 変換用の SMT 動詞を構成します。
• SMT の topic.regex 設定オプションを使用します。

詳細については、以下のブロガーの技術ブログを参照してください。

• Debezium シリーズ: SMT、述語、論理名前空間拡張に基づく debezium のアプリケーション機能の詳細な紹介

6. 言語の詳細

コンテンツベースのルーティング条件を表現する方法は、使用されるスクリプト言語によって異なります。たとえば、基本的な構成例に示すように、Groovy を式言語として使用する場合、次の式はすべての更新 (u) レコードを更新トピックに再ルーティングし、他のレコードをデフォルト トピックにルーティングします。

value.op == 'u' ? 'updates' : null

他の言語では、同じ条件を表現するのに異なる方法が使用されます。

Debezium MongoDB コネクタは、after フィールドと patch フィールドを構造体ではなくシリアル化された JSON ドキュメントとして出力します。MongoDB コネクタで ContentBasedRouting SMT を使用するには、まず 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' ? 'updates' : null

Graal.js を使用した Javascript

Graal.js で JavaScript を使用してコンテンツベースのルーティング条件を作成する場合、使用されるアプローチは Groovy で使用されるものと似ています。例えば：

value.op == 'u' ? 'updates' : null

7、設定オプション

属性	デフォルト	説明
トピック.正規表現		イベントのターゲット サブジェクトの名前を評価して、条件付きロジックを適用するかどうかを決定するオプションの正規表現。ターゲット トピックの名前が topic.regex の値と一致する場合、変換ではイベントをトピックに渡す前に条件付きロジックが適用されます。トピック名が topic.regex の値と一致しない場合、SMT はイベントを変更せずにトピックに渡します。
言語		式を記述する言語。jsr223. で始まる必要があります (例: jsr223.groovy または jsr223.graal.js)。Debezium は、JSR 223 API (「Java™ プラットフォーム スクリプト」) を介したブートストラップのみをサポートします。
トピック.式		各メッセージに対して評価される式。String 値に評価される必要があります。null 以外の結果はメッセージを新しいトピックに再ルーティングし、null 値はメッセージをデフォルトのトピックにルーティングします。
null.handling.mode	保つ	変換が空の (廃棄された) メッセージを処理する方法を指定します。次のオプションのいずれかを指定できます: 保持: デフォルト、メッセージを配信します。下段：メッセージを完全に削除します。評価: 条件付きロジックをメッセージに適用します。