TiCDC オープン API v2

TiCDC は、TiCDC クラスターのクエリと操作を行うための OpenAPI 機能を提供します。OpenAPI 機能は、 cdc cliツールのサブセットです。

注記:

TiCDC OpenAPI v1 は将来削除されます。TiCDC OpenAPI v2 を使用することをお勧めします。

API を使用して、TiCDC クラスターで次のメンテナンス操作を実行できます。

すべての API のリクエスト本文と戻り値は JSON 形式です。リクエストが成功すると、 200 OKメッセージが返されます。次のセクションでは、API の具体的な使用方法について説明します。

以下の例では、TiCDCサーバーのリスニング IP アドレスは127.0.0.1 、ポートは8300です。TiCDCサーバーの起動時に、 --addr=ip:port介して TiCDC にバインドされた IP アドレスとポートを指定できます。

API エラー メッセージ テンプレート

API リクエストが送信された後にエラーが発生した場合、返されるエラー メッセージは次の形式になります。

{ "error_msg": "", "error_code": "" }

上記の JSON 出力では、 error_msgエラー メッセージを示し、 error_code対応するエラー コードを示します。

API リスト インターフェースの戻り形式

API リクエストがリソースのリスト (たとえば、すべてのCapturesのリスト) を返す場合、TiCDC の戻り形式は次のようになります。

{ "total": 2, "items": [ { "id": "d2912e63-3349-447c-90ba-wwww", "is_owner": true, "address": "127.0.0.1:8300" }, { "id": "d2912e63-3349-447c-90ba-xxxx", "is_owner": false, "address": "127.0.0.1:8302" } ] }

上記の例では、

  • total : リソースの合計数を示します。
  • items : このリクエストによって返されるすべてのリソースを含む配列。配列のすべての要素は同じリソースです。

TiCDCノードのステータス情報を取得する

この API は同期インターフェースです。リクエストが成功すると、対応するノードのステータス情報が返されます。

リクエストURI

GET /api/v2/status

次のリクエストは、IP アドレスが127.0.0.1でポート番号が8300ある TiCDC ノードのステータス情報を取得します。

curl -X GET http://127.0.0.1:8300/api/v2/status
{ "version": "v8.5.0", "git_hash": "10413bded1bdb2850aa6d7b94eb375102e9c44dc", "id": "d2912e63-3349-447c-90ba-72a4e04b5e9e", "pid": 1447, "is_owner": true, "liveness": 0 }

上記の出力のパラメータは次のように記述されます。

  • version : TiCDC の現在のバージョン番号。
  • git_hash : Git ハッシュ値。
  • id : ノードのキャプチャ ID。
  • pid : ノードのキャプチャ プロセス ID (PID)。
  • is_owner : ノードが所有者であるかどうかを示します。
  • liveness : このノードがライブかどうか。2 0正常を意味します。4 1ノードがgraceful shutdown状態にあることを意味します。

TiCDC クラスターのヘルス ステータスを確認する

この API は同期インターフェースです。クラスターが正常な場合は200 OKが返されます。

リクエストURI

GET /api/v2/health

curl -X GET http://127.0.0.1:8300/api/v2/health

クラスターが正常な場合、応答は200 OKと空の JSON オブジェクトになります。

{}

クラスターが正常でない場合、応答はエラー メッセージを含む JSON オブジェクトになります。

レプリケーションタスクを作成する

このインターフェイスは、レプリケーション タスクを TiCDC に送信するために使用されます。要求が成功すると、 200 OKが返されます。返される結果は、サーバーがコマンドの実行に同意したことを意味するだけで、コマンドが正常に実行されることを保証するものではありません。

リクエストURI

POST /api/v2/changefeeds

パラメータの説明

{ "changefeed_id": "string", "replica_config": { "bdr_mode": true, "case_sensitive": false, "check_gc_safe_point": true, "consistent": { "flush_interval": 0, "level": "string", "max_log_size": 0, "storage": "string" }, "enable_old_value": true, "enable_sync_point": true, "filter": { "event_filters": [ { "ignore_delete_value_expr": "string", "ignore_event": [ "string" ], "ignore_insert_value_expr": "string", "ignore_sql": [ "string" ], "ignore_update_new_value_expr": "string", "ignore_update_old_value_expr": "string", "matcher": [ "string" ] } ], "ignore_txn_start_ts": [ 0 ], "rules": [ "string" ] }, "force_replicate": true, "ignore_ineligible_table": true, "memory_quota": 0, "mounter": { "worker_num": 0 }, "sink": { "column_selectors": [ { "columns": [ "string" ], "matcher": [ "string" ] } ], "csv": { "delimiter": "string", "include_commit_ts": true, "null": "string", "quote": "string" }, "date_separator": "string", "dispatchers": [ { "matcher": [ "string" ], "partition": "string", "topic": "string" } ], "enable_partition_separator": true, "encoder_concurrency": 0, "protocol": "string", "schema_registry": "string", "terminator": "string", "transaction_atomicity": "string" }, "sync_point_interval": "string", "sync_point_retention": "string" }, "sink_uri": "string", "start_ts": 0, "target_ts": 0 }

パラメータの説明は次のとおりです。

パラメータ名説明
changefeed_idSTRINGタイプ。レプリケーション タスクの ID。(オプション)
replica_configレプリケーション タスクのコンフィグレーションパラメータ。(オプション)
sink_uriSTRINGタイプ。レプリケーション タスクのダウンストリーム アドレス。(必須)
start_tsUINT64タイプ。変更フィードの開始 TSO を指定します。TiCDC クラスターはこの TSO からデータの取得を開始します。デフォルト値は現在の時刻です。(オプション)
target_tsUINT64タイプ。変更フィードのターゲット TSO を指定します。TiCDC クラスターは、この TSO に到達するとデータのプルを停止します。デフォルト値は空で、TiCDC は自動的に停止しません。(オプション)

changefeed_idの意味と形式は、 sink_uri cdc cli使用してレプリケーションタスクを作成するドキュメントで説明されているものと同じです。 target_tsのパラメータの詳細な説明については、そのドキュメントを参照してくださいsink_uriで証明書パスを指定start_ts場合は、対応する証明書を対応する TiCDCサーバーにアップロードしたことを確認してください。

replica_configパラメータの説明は次のとおりです。

パラメータ名説明
bdr_modeBOOLEANタイプ。 双方向レプリケーション有効にするかどうかを決定します。デフォルト値はfalseです。(オプション)
case_sensitiveBOOLEAN型。テーブル名をフィルタリングするときに大文字と小文字を区別するかどうかを決定します。v6.5.6、v7.1.3、v7.5.0 以降では、デフォルト値はtrueからfalseに変更されます。(オプション)
check_gc_safe_pointBOOLEANタイプ。レプリケーション タスクの開始時刻が GC 時間よりも早いかどうかを確認するかどうかを決定します。デフォルト値はtrueです。(オプション)
consistentREDO ログの構成パラメータ。(オプション)
enable_sync_pointBOOLEANタイプ。2 sync point有効にするかどうかを決定します。(オプション)
filterfilterの設定パラメータ。(オプション)
force_replicateBOOLEANタイプ。デフォルト値はfalseです。 trueに設定すると、レプリケーション タスクは一意のインデックスのないテーブルを強制的にレプリケートします。(オプション)
ignore_ineligible_tableBOOLEANタイプ。デフォルト値はfalseです。 trueに設定すると、レプリケーション タスクはレプリケートできないテーブルを無視します。(オプション)
memory_quotaUINT64タイプ。レプリケーション タスクのメモリクォータ。(オプション)
mountermounterの設定パラメータ。(オプション)
sinksinkの設定パラメータ。(オプション)
sync_point_intervalSTRING型。返される値はUINT64型のナノ秒単位の時間であることに注意してください。4 sync pointが有効な場合、このパラメータは、Syncpoint が上流スナップショットと下流スナップショットを揃える間隔を指定します。デフォルト値は10mで、最小値は30sです。(オプション)
sync_point_retentionSTRING型。返される値はUINT64型のナノ秒単位の時間であることに注意してください。4 sync pointが有効な場合、このパラメータは、ダウンストリーム テーブルで同期ポイントによってデータが保持される期間を指定します。この期間を超えると、データはクリーンアップされます。デフォルト値は24hです。(オプション)

consistentパラメータは次のように記述されます。

パラメータ名説明
flush_intervalUINT64タイプ。REDO ログ ファイルをフラッシュする間隔。(オプション)
levelSTRINGタイプ。複製されたデータの一貫性レベル。(オプション)
max_log_sizeUINT64型。REDOログの最大値。(オプション)
storageSTRINGタイプ。storageの宛先アドレス。(オプション)
use_file_backendBOOLタイプ。REDO ログをローカル ファイルに保存するかどうかを指定します。(オプション)
encoding_worker_numINTタイプ。REDO モジュール内のエンコードおよびデコード ワーカーの数。(オプション)
flush_worker_numINTタイプ。REDO モジュール内のフラッシュワーカーの数。(オプション)
compressionSTRINGタイプ。REDO ログ ファイルを圧縮する動作。使用可能なオプションは"""lz4"です。デフォルト値は""で、圧縮しないことを意味します。(オプション)
flush_concurrencyINTタイプ。単一ファイルのアップロードの同時実行性。デフォルト値は1で、同時実行性が無効であることを意味します。(オプション)

filterパラメータは次のように記述されます。

パラメータ名説明
event_filtersイベントをフィルタリングするための設定。(オプション)
ignore_txn_start_tsUINT64 ARRAYタイプ。これを指定すると、 [1, 2]などのstart_tsを指定するトランザクションは無視されます。(オプション)
rulesSTRING ARRAYタイプ。テーブル スキーマ フィルタリングのルール (例: ['foo*.*', 'bar*.*'] )。詳細については、 テーブルフィルター参照してください。(オプション)

filter.event_filtersパラメータの説明は以下のとおりです。詳細についてはチェンジフィードログフィルター参照してください。

パラメータ名説明
ignore_delete_value_exprSTRING ARRAY型。たとえば、 "name = 'john'" name = 'john'条件を含む DELETE DML ステートメントを除外することを意味します。(オプション)
ignore_eventSTRING ARRAYタイプ。たとえば、 ["insert"] INSERT イベントが除外されることを示します。(オプション)
ignore_insert_value_exprSTRING ARRAY型。たとえば、 "id >= 100" id >= 100条件に一致する INSERT DML ステートメントを除外することを意味します。(オプション)
ignore_sqlSTRING ARRAY型。たとえば、 ["^drop", "add column"] DROPで始まるかADD COLUMN含む DDL ステートメントを除外することを意味します。(オプション)
ignore_update_new_value_exprSTRING ARRAY型。たとえば、 "gender = 'male'" 、新しい値gender = 'male'を持つ UPDATE DML ステートメントを除外することを意味します。(オプション)
ignore_update_old_value_exprSTRING ARRAY型。たとえば、 "age < 18"古い値age < 18を持つ UPDATE DML ステートメントを除外することを意味します。(オプション)
matcherSTRING ARRAYタイプ。許可リストとして機能します。たとえば、 ["test.worker"] 、フィルター ルールがtestデータベースのworkerテーブルにのみ適用されることを意味します。(オプション)

mounterパラメータは次のように記述されます。

パラメータ名説明
worker_numINT型。マウントスレッドの数。マウントは TiKV から出力されたデータをデコードするために使用されます。デフォルト値は16です。(オプション)

sinkパラメータは次のように記述されます。

パラメータ名説明
column_selectors列セレクターの構成。(オプション)
csvCSV 構成。(オプション)
date_separatorSTRINGタイプ。ファイル ディレクトリの日付区切り文字のタイプを示します。値のオプションはnoneyearmonth 、およびdayです。 noneデフォルト値で、日付が区切られないことを意味します。(オプション)
dispatchersイベントディスパッチ用の構成配列。(オプション)
encoder_concurrencyINTタイプ。MQ シンク内のエンコーダー スレッドの数。デフォルト値は16です。(オプション)
protocolSTRINGタイプ。MQ シンクの場合、メッセージのプロトコル形式を指定できます。現在サポートされているプロトコルはcanal-jsonopen-protocolavrodebezium 、およびsimpleです。
schema_registrySTRINGタイプ。スキーマ レジストリ アドレス。(オプション)
terminatorSTRING型。ターミネータは 2 つのデータ変更イベントを区切るために使用されます。デフォルト値は null で、 "\r\n"ターミネータとして使用されることを意味します。(オプション)
transaction_atomicitySTRINGタイプ。トランザクションのアトミック性レベル。(オプション)
only_output_updated_columnsBOOLEANタイプ。2 またはcanal-jsonプロトコルを使用する MQ シンクの場合、変更された列のみを出力するかopen-protocolかを指定できます。デフォルト値はfalseです。(オプション)
cloud_storage_configstorageシンクの構成。(オプション)
openオープン プロトコルの構成。(オプション)
debeziumDebezium プロトコルの設定。(オプション)

sink.column_selectors配列です。パラメータは次のように記述されます。

パラメータ名説明
columnsSTRING ARRAY型。列配列。
matcherSTRING ARRAYタイプ。マッチャー構成。フィルター ルールと同じマッチング構文を持ちます。

sink.csvパラメータは次のように記述されます。

パラメータ名説明
delimiterSTRINGタイプ。CSV ファイル内のフィールドを区切るために使用される文字。値は ASCII 文字である必要があり、デフォルトは,です。
include_commit_tsBOOLEANタイプ。CSV 行にコミット ts を含めるかどうか。デフォルト値はfalseです。
nullSTRING型。CSV 列が null の場合に表示される文字。デフォルト値は\Nです。
quoteSTRINGタイプ。CSV ファイル内のフィールドを囲むために使用される引用符文字。値が空の場合、引用符は使用されません。デフォルト値は"です。
binary_encoding_methodSTRING型。バイナリデータのエンコード方式。 "base64"または"hex"を指定できます。デフォルト値は"base64"です。

sink.dispatchers : MQ タイプのシンクの場合、このパラメータを使用してイベント ディスパッチャを構成できます。 defaulttsindex-value 、およびtableのディスパッチャがサポートされています。 ディスパッチャのルールは次のとおりです。

  • default : tableモードでイベントを送信します。
  • ts : 行変更の commitTs を使用してハッシュ値を作成し、イベントをディスパッチします。
  • index-value : 選択した HandleKey 列の名前と値を使用してハッシュ値を作成し、イベントをディスパッチします。
  • table : テーブルのスキーマ名とテーブル名を使用してハッシュ値を作成し、イベントをディスパッチします。

sink.dispatchers配列です。パラメータは次のように記述されます。

パラメータ名説明
matcherSTRING ARRAYタイプ。フィルター ルールと同じ一致構文を持ちます。
partitionSTRINGタイプ。イベントをディスパッチするターゲット パーティション。
topicSTRINGタイプ。イベントをディスパッチするターゲット トピック。

sink.cloud_storage_configパラメータは次のように記述されます。

パラメータ名説明
worker_countINTタイプ。下流のクラウドstorageへのデータ保存の同時実行性が変更されます。
flush_intervalSTRINGタイプ。下流のクラウドstorageにデータを保存する間隔が変更されます。
file_sizeINTタイプ。このファイル内のバイト数がこのパラメータの値を超えると、データ変更ファイルがクラウドstorageに保存されます。
file_expiration_daysINTタイプ。ファイルを保持する期間date-separatordayに設定されている場合にのみ有効になります。
file_cleanup_cron_specSTRINGタイプ。スケジュールされたクリーンアップ タスクの実行サイクル。crontab 構成と互換性があり、形式は<Second> <Minute> <Hour> <Day of the month> <Month> <Day of the week (Optional)>です。
flush_concurrencyINTタイプ。単一ファイルのアップロードの同時実行性。
output_raw_change_eventBOOLEANタイプ。MySQL 以外のシンクの元のデータ変更イベントを出力するかどうかを制御します。

sink.openパラメータは次のように記述されます。

パラメータ名説明
output_old_valueBOOLEAN型。行データが変更される前に値を出力するかどうかを制御します。デフォルト値はtrueです。無効にすると、UPDATE イベントは "p" フィールドを出力しません。

sink.debeziumパラメータは次のように記述されます。

パラメータ名説明
output_old_valueBOOLEAN型。行データが変更される前の値を出力するかどうかを制御します。デフォルト値は true です。無効にすると、UPDATE イベントは "before" フィールドを出力しません。

次のリクエストは、 ID がtest5blackhome://のうちsink_uriであるレプリケーション タスクを作成します。

curl -X POST -H "'Content-type':'application/json'" http://127.0.0.1:8300/api/v2/changefeeds -d '{"changefeed_id":"test5","sink_uri":"blackhole://"}'

要求が成功した場合は200 OKが返されます。要求が失敗した場合は、エラー メッセージとエラー コードが返されます。

レスポンス本文のフォーマット

{ "admin_job_type": 0, "checkpoint_time": "string", "checkpoint_ts": 0, "config": { "bdr_mode": true, "case_sensitive": false, "check_gc_safe_point": true, "consistent": { "flush_interval": 0, "level": "string", "max_log_size": 0, "storage": "string" }, "enable_old_value": true, "enable_sync_point": true, "filter": { "event_filters": [ { "ignore_delete_value_expr": "string", "ignore_event": [ "string" ], "ignore_insert_value_expr": "string", "ignore_sql": [ "string" ], "ignore_update_new_value_expr": "string", "ignore_update_old_value_expr": "string", "matcher": [ "string" ] } ], "ignore_txn_start_ts": [ 0 ], "rules": [ "string" ] }, "force_replicate": true, "ignore_ineligible_table": true, "memory_quota": 0, "mounter": { "worker_num": 0 }, "sink": { "column_selectors": [ { "columns": [ "string" ], "matcher": [ "string" ] } ], "csv": { "delimiter": "string", "include_commit_ts": true, "null": "string", "quote": "string" }, "date_separator": "string", "dispatchers": [ { "matcher": [ "string" ], "partition": "string", "topic": "string" } ], "enable_partition_separator": true, "encoder_concurrency": 0, "protocol": "string", "schema_registry": "string", "terminator": "string", "transaction_atomicity": "string" }, "sync_point_interval": "string", "sync_point_retention": "string" }, "create_time": "string", "creator_version": "string", "error": { "addr": "string", "code": "string", "message": "string" }, "id": "string", "resolved_ts": 0, "sink_uri": "string", "start_ts": 0, "state": "string", "target_ts": 0, "task_status": [ { "capture_id": "string", "table_ids": [ 0 ] } ] }

パラメータの説明は次のとおりです。

パラメータ名説明
admin_job_typeINTEGERタイプ。管理ジョブ タイプ。
checkpoint_timeSTRINGタイプ。レプリケーション タスクの現在のチェックポイントのフォーマットされた時刻。
checkpoint_tsSTRINGタイプ。レプリケーション タスクの現在のチェックポイントの TSO。
configレプリケーション タスクの構成。構造と意味は、レプリケーション タスクを作成する場合のreplica_config番目の構成と同じです。
create_timeSTRINGタイプ。レプリケーション タスクが作成された時刻。
creator_versionSTRINGタイプ。レプリケーション タスクが作成された時点の TiCDC バージョン。
errorレプリケーション タスク エラー。
idSTRINGタイプ。レプリケーション タスク ID。
resolved_tsUINT64タイプ。レプリケーション タスクは ts を解決しました。
sink_uriSTRINGタイプ。レプリケーション タスク シンク URI。
start_tsUINT64タイプ。レプリケーション タスクが開始されます。
stateSTRINGタイプ。レプリケーション タスクのステータス。 normalstoppederrorfailed 、またはfinishedになります。
target_tsUINT64タイプ。レプリケーション タスク ターゲット ts。
task_statusレプリケーション タスクのディスパッチの詳細なステータス。

task_statusパラメータは次のように記述されます。

パラメータ名説明
capture_idSTRING型。キャプチャID。
table_idsUINT64 ARRAYタイプ。このキャプチャで複製されるテーブルの ID。

errorパラメータは次のように記述されます。

パラメータ名説明
addrSTRING型。キャプチャアドレス。
codeSTRING型。エラーコード。
messageSTRING型。エラーの詳細。

レプリケーションタスクを削除する

この API は、レプリケーション タスクを削除するためのべき等インターフェイス (つまり、最初の適用後、結果を変更することなく複数回適用できる) です。要求が成功した場合は、 200 OKが返されます。返された結果は、サーバーがコマンドの実行に同意したことを意味するだけで、コマンドが正常に実行されることを保証するものではありません。

リクエストURI

DELETE /api/v2/changefeeds/{changefeed_id}

パラメータの説明

パスパラメータ

パラメータ名説明
changefeed_id削除するレプリケーション タスク (changefeed) の ID。

次のリクエストは、ID test1のレプリケーション タスクを削除します。

curl -X DELETE http://127.0.0.1:8300/api/v2/changefeeds/test1

要求が成功した場合は200 OKが返されます。要求が失敗した場合は、エラー メッセージとエラー コードが返されます。

レプリケーション構成を更新する

この API は、レプリケーション タスクを更新するために使用されます。要求が成功した場合、 200 OKが返されます。返された結果は、サーバーがコマンドの実行に同意したことを意味するだけで、コマンドが正常に実行されることを保証するものではありません。

changefeed 設定を変更するには、 pause the replication task -> modify the configuration -> resume the replication taskの手順に従います。

リクエストURI

PUT /api/v2/changefeeds/{changefeed_id}

パラメータの説明

パスパラメータ

パラメータ名説明
changefeed_id更新するレプリケーション タスク (changefeed) の ID。

リクエスト本文のパラメータ

{ "replica_config": { "bdr_mode": true, "case_sensitive": false, "check_gc_safe_point": true, "consistent": { "flush_interval": 0, "level": "string", "max_log_size": 0, "storage": "string" }, "enable_old_value": true, "enable_sync_point": true, "filter": { "event_filters": [ { "ignore_delete_value_expr": "string", "ignore_event": [ "string" ], "ignore_insert_value_expr": "string", "ignore_sql": [ "string" ], "ignore_update_new_value_expr": "string", "ignore_update_old_value_expr": "string", "matcher": [ "string" ] } ], "ignore_txn_start_ts": [ 0 ], "rules": [ "string" ] }, "force_replicate": true, "ignore_ineligible_table": true, "memory_quota": 0, "mounter": { "worker_num": 0 }, "sink": { "column_selectors": [ { "columns": [ "string" ], "matcher": [ "string" ] } ], "csv": { "delimiter": "string", "include_commit_ts": true, "null": "string", "quote": "string" }, "date_separator": "string", "dispatchers": [ { "matcher": [ "string" ], "partition": "string", "topic": "string" } ], "enable_partition_separator": true, "encoder_concurrency": 0, "protocol": "string", "schema_registry": "string", "terminator": "string", "transaction_atomicity": "string" }, "sync_point_interval": "string", "sync_point_retention": "string" }, "sink_uri": "string", "target_ts": 0 }

現在、API 経由で変更できるのは次の構成のみです。

パラメータ名説明
target_tsUINT64タイプ。変更フィードのターゲット TSO を指定します。(オプション)
sink_uriSTRINGタイプ。レプリケーション タスクのダウンストリーム アドレス。(オプション)
replica_configシンクの構成パラメータ。完全である必要があります。(オプション)

上記のパラメータの意味はセクションレプリケーションタスクを作成すると同じです。詳細については、そのセクションを参照してください。

次のリクエストは、ID test1のレプリケーション タスクのtarget_ts32に更新します。

curl -X PUT -H "'Content-type':'application/json'" http://127.0.0.1:8300/api/v2/changefeeds/test1 -d '{"target_ts":32}'

リクエストが成功した場合は200 OKが返されます。リクエストが失敗した場合は、エラー メッセージとエラー コードが返されます。JSON レスポンス ボディの意味はレプリケーションタスクを作成するのセクションと同じです。詳細については、そのセクションを参照してください。

レプリケーションタスクリストをクエリする

この API は同期インターフェイスです。リクエストが成功すると、TiCDC クラスター内のすべてのレプリケーション タスク (changefeed) の基本情報が返されます。

リクエストURI

GET /api/v2/changefeeds

パラメータの説明

クエリパラメータ

パラメータ名説明
stateこのパラメータを指定すると、指定された状態のレプリケーション タスクの情報が返されます。(オプション)

stateの値のオプションはallnormalstoppederrorfailed 、およびfinishedです。

このパラメータを指定しない場合は、デフォルトでnormalstopped 、またはfailed状態のレプリケーション タスクの基本情報が返されます。

次のリクエストは、状態normalにあるすべてのレプリケーション タスクの基本情報を照会します。

curl -X GET http://127.0.0.1:8300/api/v2/changefeeds?state=normal
{ "total": 2, "items": [ { "id": "test", "state": "normal", "checkpoint_tso": 439749918821711874, "checkpoint_time": "2023-02-27 23:46:52.888", "error": null }, { "id": "test2", "state": "normal", "checkpoint_tso": 439749918821711874, "checkpoint_time": "2023-02-27 23:46:52.888", "error": null } ] }

上記の返された結果のパラメータは次のように説明されます。

  • id : レプリケーション タスクの ID。
  • state : レプリケーション タスクの現在の
  • checkpoint_tso : レプリケーション タスクの現在のチェックポイントの TSO。
  • checkpoint_time : レプリケーション タスクの現在のチェックポイントのフォーマットされた時刻。
  • error : レプリケーション タスクのエラー情報。

特定のレプリケーションタスクをクエリする

この API は同期インターフェイスです。リクエストが成功すると、指定されたレプリケーション タスク (changefeed) の詳細情報を返します。

リクエストURI

GET /api/v2/changefeeds/{changefeed_id}

パラメータの説明

パスパラメータ

パラメータ名説明
changefeed_idクエリするレプリケーション タスク (changefeed) の ID。

次のリクエストは、ID test1のレプリケーション タスクの詳細情報を照会します。

curl -X GET http://127.0.0.1:8300/api/v2/changefeeds/test1

JSON レスポンス本文の意味はセクションレプリケーションタスクを作成すると同じです。詳細については、そのセクションを参照してください。

特定のレプリケーションタスクが完了したかどうかを照会する

この API は同期インターフェイスです。要求が成功すると、指定されたレプリケーション タスク (changefeed) の同期ステータス (タスクが完了したかどうかや追加の詳細など) が返されます。

リクエストURI

GET /api/v2/changefeed/{changefeed_id}/synced

パラメータの説明

パスパラメータ

パラメータ名説明
changefeed_idクエリするレプリケーション タスク (changefeed) の ID。

次のリクエストは、ID test1のレプリケーション タスクの同期ステータスを照会します。

curl -X GET http://127.0.0.1:8300/api/v2/changefeed/test1/synced

例1: 同期が完了しました

{ "synced": true, "sink_checkpoint_ts": "2023-11-30 15:14:11.015", "puller_resolved_ts": "2023-11-30 15:14:12.215", "last_synced_ts": "2023-11-30 15:08:35.510", "now_ts": "2023-11-30 15:14:11.511", "info": "Data syncing is finished" }

応答には次のフィールドが含まれます。

  • synced : このレプリケーション タスクが完了しているかどうか。 trueタスクが完了したことを意味し、 false潜在的な不完全性を意味します。 falseの場合は、特定のステータスについてはinfoフィールドとその他のフィールドの両方を確認する必要があります。
  • sink_checkpoint_ts : シンク モジュールのチェックポイント ts 値 (PD 時間単位)。
  • puller_resolved_ts : PD 時間での、プラー モジュールのresolved-ts値。
  • last_synced_ts : TiCDC によって処理された最新のデータの commit-ts 値 (PD 時間単位)。
  • now_ts : 現在のPD時間。
  • info : 特にsyncedfalse場合に、同期ステータスの判別を支援する補足情報。

例2: 同期が完了していない

{ "synced": false, "sink_checkpoint_ts": "2023-11-30 15:26:31.519", "puller_resolved_ts": "2023-11-30 15:26:23.525", "last_synced_ts": "2023-11-30 15:24:30.115", "now_ts": "2023-11-30 15:26:31.511", "info": "The data syncing is not finished, please wait" }

この例は、進行中のレプリケーション タスクの応答を示しています。1 フィールドとsyncedフィールドinfo両方を確認すると、レプリケーション タスクがまだ完了しておらず、さらに待機する必要があることがわかります。

例3: 同期ステータスをさらに確認する必要がある

{ "synced":false, "sink_checkpoint_ts":"2023-12-13 11:45:13.515", "puller_resolved_ts":"2023-12-13 11:45:13.525", "last_synced_ts":"2023-12-13 11:45:07.575", "now_ts":"2023-12-13 11:50:24.875", "info":"Please check whether PD is online and TiKV Regions are all available. If PD is offline or some TiKV regions are not available, it means that the data syncing process is complete. To check whether TiKV regions are all available, you can view 'TiKV-Details' > 'Resolved-Ts' > 'Max Leader Resolved TS gap' on Grafana. If the gap is large, such as a few minutes, it means that some regions in TiKV are unavailable. Otherwise, if the gap is small and PD is online, it means the data syncing is incomplete, so please wait" }

この API を使用すると、上流クラスターが災害に遭遇した場合でも、同期ステータスを照会できます。状況によっては、TiCDC の現在のデータ複製タスクが完了しているかどうかを直接判断できない場合があります。そのような場合は、この API を要求し、応答のinfoフィールドと上流クラスターの現在のステータスの両方をチェックして、具体的なステータスを判断できます。

この例では、 sink_checkpoint_ts now_tsより遅れていますが、これは TiCDC がまだデータ レプリケーションに追いついていないか、PD または TiKV に障害が発生したためです。これが TiCDC がまだデータ レプリケーションに追いついていないためである場合、レプリケーション タスクがまだ完了していないことを意味します。これが PD または TiKV の障害によるものである場合、レプリケーション タスクが完了していることを意味します。したがって、クラスターの状態を判断するには、 infoフィールドを確認する必要があります。

例4: クエリエラー

{ "error_msg": "[CDC:ErrPDEtcdAPIError]etcd api call error: context deadline exceeded", "error_code": "CDC:ErrPDEtcdAPIError" }

アップストリーム クラスターの PD が長時間にわたって障害を起こした場合、この API をクエリすると、前述のエラーと同様のエラーが返されることがあります。このエラーでは、さらに確認するための情報は提供されません。PD 障害は TiCDC のデータ レプリケーションに直接影響するため、このようなエラーが発生した場合は、TiCDC が可能な限りデータ レプリケーションを完了したと想定できますが、PD 障害によりダウンストリーム クラスターでデータ損失が発生する可能性が依然としてあります。

レプリケーションタスクを一時停止する

この API はレプリケーション タスクを一時停止します。要求が成功した場合は200 OKが返されます。返された結果は、サーバーがコマンドの実行に同意したことを意味するだけで、コマンドが正常に実行されることを保証するものではありません。

リクエストURI

POST /api/v2/changefeeds/{changefeed_id}/pause

パラメータの説明

パスパラメータ

パラメータ名説明
changefeed_id一時停止するレプリケーション タスク (changefeed) の ID。

次のリクエストは、ID test1のレプリケーション タスクを一時停止します。

curl -X POST http://127.0.0.1:8300/api/v2/changefeeds/test1/pause

要求が成功した場合は200 OKが返されます。要求が失敗した場合は、エラー メッセージとエラー コードが返されます。

レプリケーションタスクを再開する

この API はレプリケーション タスクを再開します。要求が成功した場合は200 OKが返されます。返された結果は、サーバーがコマンドの実行に同意したことを意味するだけで、コマンドが正常に実行されることを保証するものではありません。

リクエストURI

POST /api/v2/changefeeds/{changefeed_id}/resume

パラメータの説明

パスパラメータ

パラメータ名説明
changefeed_id再開するレプリケーション タスク (changefeed) の ID。

リクエスト本文のパラメータ

{ "overwrite_checkpoint_ts": 0 }
パラメータ名説明
overwrite_checkpoint_tsUINT64タイプ。レプリケーション タスク (changefeed) を再開するときにチェックポイント TSO を再割り当てします。

次のリクエストは、ID test1のレプリケーション タスクを再開します。

curl -X POST http://127.0.0.1:8300/api/v2/changefeeds/test1/resume -d '{}'

要求が成功した場合は200 OKが返されます。要求が失敗した場合は、エラー メッセージとエラー コードが返されます。

レプリケーションサブタスクリストをクエリする

このAPIは同期インターフェースです。リクエストが成功すると、すべてのレプリケーションサブタスク( processor )の基本情報が返されます。

リクエストURI

GET /api/v2/processors

curl -X GET http://127.0.0.1:8300/api/v2/processors
{ "total": 3, "items": [ { "changefeed_id": "test2", "capture_id": "d2912e63-3349-447c-90ba-72a4e04b5e9e" }, { "changefeed_id": "test1", "capture_id": "d2912e63-3349-447c-90ba-72a4e04b5e9e" }, { "changefeed_id": "test", "capture_id": "d2912e63-3349-447c-90ba-72a4e04b5e9e" } ] }

パラメータの説明は次のとおりです。

  • changefeed_id : 変更フィード ID。
  • capture_id : キャプチャ ID。

特定のレプリケーションサブタスクをクエリする

このAPIは同期インターフェースです。リクエストが成功すると、指定されたレプリケーションサブタスク( processor )の詳細情報を返します。

リクエストURI

GET /api/v2/processors/{changefeed_id}/{capture_id}

パラメータの説明

パスパラメータ

パラメータ名説明
changefeed_idクエリするレプリケーション サブタスクの変更フィード ID。
capture_idクエリするレプリケーション サブタスクのキャプチャ ID。

次のリクエストは、 changefeed_idtestcapture_id 561c3784-77f0-4863-ad52-65a3436db6afあるサブタスクの詳細情報を照会します。サブタスクはchangefeed_idcapture_idで識別できます。

curl -X GET http://127.0.0.1:8300/api/v2/processors/test/561c3784-77f0-4863-ad52-65a3436db6af
{ "table_ids": [ 80 ] }

パラメータの説明は次のとおりです。

  • table_ids : このキャプチャで複製されるテーブル ID。

TiCDC サービス プロセス リストを照会する

このAPIは同期インターフェースです。リクエストが成功すると、すべてのレプリケーションプロセスの基本情報( capture )が返されます。

リクエストURI

GET /api/v2/captures

curl -X GET http://127.0.0.1:8300/api/v2/captures
{ "total": 1, "items": [ { "id": "d2912e63-3349-447c-90ba-72a4e04b5e9e", "is_owner": true, "address": "127.0.0.1:8300" } ] }

パラメータの説明は次のとおりです。

  • id : キャプチャ ID。
  • is_owner : キャプチャが所有者であるかどうか。
  • address : キャプチャのアドレス。

所有者ノードの削除

この API は非同期インターフェイスです。リクエストが成功すると、 200 OKが返されます。返された結果は、サーバーがコマンドの実行に同意したことを意味するだけで、コマンドが正常に実行されることを保証するものではありません。

リクエストURI

POST /api/v2/owner/resign

次のリクエストは、TiCDC の現在の所有者ノードを削除し、新しい所有者ノードを生成するための新しいラウンドの選出をトリガーします。

curl -X POST http://127.0.0.1:8300/api/v2/owner/resign

要求が成功した場合は200 OKが返されます。要求が失敗した場合は、エラー メッセージとエラー コードが返されます。

TiCDCサーバーのログレベルを動的に調整する

この API は同期インターフェースです。リクエストが成功すると200 OKが返されます。

リクエストURI

POST /api/v2/log

リクエストパラメータ

リクエスト本文のパラメータ

パラメータ名説明
log_level設定するログ レベル。

log_level 、「debug」、「info」、「warn」、「error」、「dpanic」、「panic」、および「fatal」のzap が提供するログレベルをサポートします。

curl -X POST -H "'Content-type':'application/json'" http://127.0.0.1:8300/api/v2/log -d '{"log_level":"debug"}'

要求が成功した場合は200 OKが返されます。要求が失敗した場合は、エラー メッセージとエラー コードが返されます。

このページは役に立ちましたか?