TiCDC OpenAPI

TiCDC は、TiCDC クラスターを照会および操作するための OpenAPI 機能を提供します。これはcdc cliツールの機能に似ています。

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

すべての API の要求本文と戻り値は JSON 形式です。以下のセクションでは、API の特定の使用法について説明します。

次の例では、TiCDCサーバーのリッスン IP アドレスは127.0.0.1で、ポートは8300です。 TiCDCサーバーの起動時に、指定した IP とポートを--addr=ip:port経由でバインドできます。

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

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

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

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

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

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

リクエストURI

GET /api/v1/status

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

curl -X GET http://127.0.0.1:8300/api/v1/status
{ "version": "v5.2.0-master-dirty", "git_hash": "f191cd00c53fdf7a2b1c9308a355092f9bf8824e", "id": "c6a43c16-0717-45af-afd6-8b3e01e44f5d", "pid": 25432, "is_owner": true }

上記の出力のフィールドは次のとおりです。

  • version: 現在の TiCDC のバージョン番号。
  • git_hash: Git ハッシュ値。
  • id: ノードのキャプチャ ID。
  • pid: ノードのキャプチャ プロセス PID。
  • is_owner: ノードが所有者かどうかを示します。

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

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

リクエストURI

GET /api/v1/health

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

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

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

リクエストURI

POST /api/v1/changefeeds

パラメータの説明

cliコマンドを使用してレプリケーション タスクを作成するためのオプション パラメータと比較すると、API を使用してそのようなタスクを作成するためのオプション パラメータは完全ではありません。この API は、次のパラメーターをサポートしています。

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

| |パラメータ名 |説明 | | | :------------------------ | : ---------------------- --------------------------- ---- | | | changefeed_id | STRINGタイプ。レプリケーション タスクの ID。 (オプション) | | | start_ts | UINT64型。 changefeed の開始 TSO を指定します。 (オプション) | | | target_ts | UINT64型。 changefeed のターゲット TSO を指定します。 (オプション) | | | sink_uri | STRING型。レプリケーション タスクのダウンストリーム アドレス。 (必須) | | | force_replicate | BOOLEAN型。一意のインデックスを持たないテーブルを強制的にレプリケートするかどうかを決定します。 (オプション) | | | ignore_ineligible_table | BOOLEAN型。レプリケートできないテーブルを無視するかどうかを決定します。 (オプション) | | | filter_rules | STRING型配列。テーブル スキーマ フィルタリングのルール。 (オプション) | | | ignore_txn_start_ts | UINT64型配列。指定した start_ts のトランザクションを無視します。 (オプション) | | | mounter_worker_num | INT型。マウンターのスレッド番号。 (オプション) | | | sink_config |シンクの構成パラメーター。 (オプション) |

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

上記の表のその他のパラメータについては、以下で詳しく説明します。

force_replicate : このパラメータのデフォルトはfalseです。 trueと指定すると、TiCDC はユニーク インデックスを持たないテーブルを強制的に複製しようとします。

ignore_ineligible_table : このパラメータのデフォルトはfalseです。 trueと指定すると、TiCDC はレプリケートできないテーブルを無視します。

filter_rules : filter_rules = ['foo*.*','bar*.*']などのテーブル スキーマ フィルタリングのルール。詳細はテーブル フィルタードキュメントを参照してください。

ignore_txn_start_ts : このパラメーターを指定すると、指定された start_ts は無視されます。たとえば、 ignore-txn-start-ts = [1, 2]です。

mounter_worker_num : マウンタのスレッド番号。マウンタは、TiKV から出力されたデータをデコードするために使用されます。デフォルト値は16です。

シンクの構成パラメーターは次のとおりです。

{ "dispatchers":[ {"matcher":["test1.*", "test2.*"], "dispatcher":"ts"}, {"matcher":["test3.*", "test4.*"], "dispatcher":"rowid"} ], "protocal":"canal-json" }

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

  • default : 複数の一意のインデックス (主キーを含む) が存在する場合、または古い値機能が有効になっている場合、イベントはtableモードでディスパッチされます。一意のインデックス (または主キー) が 1 つだけ存在する場合、イベントはrowidモードで送出されます。
  • ts : 行変更の commitTs を使用してハッシュ値を作成し、イベントをディスパッチします。
  • rowid : 選択した HandleKey 列の名前と値を使用してハッシュ値を作成し、イベントをディスパッチします。
  • table : テーブルのスキーマ名とテーブル名を使用してハッシュ値を作成し、イベントをディスパッチします。

matcher : マッチャーのマッチング構文は、フィルター ルールの構文と同じです。

protocol : MQ タイプのシンクの場合、メッセージのプロトコル形式を指定できます。現在、次のプロトコルがサポートされています: canal-jsonopen-protocolcanalavro 、およびmaxwell

次のリクエストは、ID がtest5sink_uri of blackhome://のレプリケーション タスクを作成します。

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

リクエストが成功した場合、 202 Acceptedが返されます。リクエストが失敗すると、エラー メッセージとエラー コードが返されます。

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

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

リクエストURI

DELETE /api/v1/changefeeds/{changefeed_id}

パラメータの説明

パス パラメータ

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

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

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

リクエストが成功した場合、 202 Acceptedが返されます。リクエストが失敗すると、エラー メッセージとエラー コードが返されます。

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

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

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

リクエストURI

PUT /api/v1/changefeeds/{changefeed_id}

パラメータの説明

パス パラメータ

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

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

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

| |パラメータ名 |説明 | | | :-------------------- | : -------------------------- ----------------------------------- ---- | | | target_ts | UINT64タイプ。 changefeed のターゲット TSO を指定します。 (オプション) | | | sink_uri | STRING型。レプリケーション タスクのダウンストリーム アドレス。 (オプション) | | | filter_rules | STRING型配列。テーブル スキーマ フィルタリングのルール。 (オプション) | | | ignore_txn_start_ts | UINT64型配列。指定した start_ts のトランザクションを無視します。 (オプション) | | | mounter_worker_num | INT型。マウンターのスレッド番号。 (オプション) | | | sink_config |シンクの構成パラメーター。 (オプション) |

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

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

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

リクエストが成功した場合、 202 Acceptedが返されます。リクエストが失敗すると、エラー メッセージとエラー コードが返されます。

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

この API は同期インターフェースです。リクエストが成功すると、TiCDC クラスター内のすべてのノードの基本情報が返されます。

リクエストURI

GET /api/v1/changefeeds

パラメータの説明

クエリ パラメータ

| |パラメータ名 |説明 | | | :-------- | :-------------------------------------------- ----- | | | state |このパラメーターを指定すると、この状態のレプリケーション ステータス情報のみが返されます。

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

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

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

curl -X GET http://127.0.0.1:8300/api/v1/changefeeds?state=normal
[ { "id": "test1", "state": "normal", "checkpoint_tso": 426921294362574849, "checkpoint_time": "2021-08-10 14:04:54.242", "error": null }, { "id": "test2", "state": "normal", "checkpoint_tso": 426921294362574849, "checkpoint_time": "2021-08-10 14:04:54.242", "error": null } ]

上記の返された結果のフィールドは次のとおりです。

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

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

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

リクエストURI

GET /api/v1/changefeeds/{changefeed_id}

パラメータの説明

パス パラメータ

パラメータ名説明
changefeed_id照会する複製タスク (changefeed) の ID。

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

curl -X GET http://127.0.0.1:8300/api/v1/changefeeds/test1
{ "id": "test1", "sink_uri": "blackhole://", "create_time": "2021-08-10 11:41:30.642", "start_ts": 426919038970232833, "target_ts": 0, "checkpoint_tso": 426921014615867393, "checkpoint_time": "2021-08-10 13:47:07.093", "sort_engine": "unified", "state": "normal", "error": null, "error_history": null, "creator_version": "", "task_status": [ { "capture_id": "d8924259-f52f-4dfb-97a9-c48d26395945", "table_ids": [ 63, 65 ], "table_operations": {} } ] }

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

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

リクエストURI

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

パラメータの説明

パス パラメータ

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

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

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

リクエストが成功した場合、 202 Acceptedが返されます。リクエストが失敗すると、エラー メッセージとエラー コードが返されます。

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

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

リクエストURI

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

パラメータの説明

パス パラメータ

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

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

curl -X POST http://127.0.0.1:8300/api/v1/changefeeds/test1/resume

リクエストが成功した場合、 202 Acceptedが返されます。リクエストが失敗すると、エラー メッセージとエラー コードが返されます。

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

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

リクエストURI

GET /api/v1/processors

curl -X GET http://127.0.0.1:8300/api/v1/processors
[ { "changefeed_id": "test1", "capture_id": "561c3784-77f0-4863-ad52-65a3436db6af" } ]

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

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

リクエストURI

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

パラメータの説明

パス パラメータ

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

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

curl -X GET http://127.0.0.1:8300/api/v1/processors/test1/561c3784-77f0-4863-ad52-65a3436db6af
{ "checkpoint_ts": 426919123303006208, "resolved_ts": 426919123369066496, "table_ids": [ 63, 65 ], "error": null }

TiCDC サービス プロセス リストのクエリ

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

リクエストURI

GET /api/v1/captures

curl -X GET http://127.0.0.1:8300/api/v1/captures
[ { "id": "561c3784-77f0-4863-ad52-65a3436db6af", "is_owner": true, "address": "127.0.0.1:8300" } ]

所有者ノードを削除する

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

リクエストURI

POST /api/v1/owner/resign

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

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

リクエストが成功した場合、 202 Acceptedが返されます。リクエストが失敗すると、エラー メッセージとエラー コードが返されます。

レプリケーション タスクですべてのテーブルの負荷分散を手動でトリガーする

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

リクエストURI

POST /api/v1/changefeeds/{changefeed_id}/tables/rebalance_table

パラメータの説明

パス パラメータ

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

次のリクエストは、ID がtest1の changefeed 内のすべてのテーブルの負荷分散をトリガーします。

curl -X POST http://127.0.0.1:8300/api/v1/changefeeds/test1/tables/rebalance_table

リクエストが成功した場合、 202 Acceptedが返されます。リクエストが失敗すると、エラー メッセージとエラー コードが返されます。

テーブルを別のノードに手動でスケジュールする

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

リクエストURI

POST /api/v1/changefeeds/{changefeed_id}/tables/move_table

パラメータの説明

パス パラメータ

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

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

パラメータ名説明
target_capture_idターゲット キャプチャの ID。
table_idスケジュールするテーブルの ID。

次のリクエストは、ID test1の changefeed 内の ID 49のテーブルを ID 6f19a6d9-0f8c-4dc9-b299-3ba7c0f216f5のキャプチャにスケジュールします。

curl -X POST -H "'Content-type':'application/json'" http://127.0.0.1:8300/api/v1/changefeeds/changefeed-test1/tables/move_table -d '{"capture_id":"6f19a6d9-0f8c-4dc9-b299-3ba7c0f216f5","table_id":49}'

リクエストが成功した場合、 202 Acceptedが返されます。リクエストが失敗すると、エラー メッセージとエラー コードが返されます。

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

この API は同期インターフェースです。リクエストが成功した場合、 202 OKが返されます。

リクエストURI

POST /api/v1/log

リクエストパラメータ

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

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

log_levelzap によって提供されるログ レベルをサポートします: "debug""info""warn""error""dpanic""panic"、および "fatal"

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

リクエストが成功した場合、 202 OKが返されます。リクエストが失敗すると、エラー メッセージとエラー コードが返されます。