TiCDC OpenAPI v1

注記

TiCDC OpenAPI v1 は非推奨となり、将来削除される予定です。 TiCDC OpenAPI v2を使用することをお勧めします。

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型。変更フィードの開始 TSO を指定します。 (オプション) | | target_ts | UINT64型。変更フィードのターゲット 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_tssink_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 タイプのシンクの場合、ディスパッチャーを使用してイベント ディスパッチャーを構成できます。 4 つのディスパッチャー ( defaulttsrowid 、およびtableがサポートされています。ディスパッチャのルールは次のとおりです。

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

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

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

次のリクエストは、ID がtest5およびsink_uriblackhole://のレプリケーション タスクを作成します。

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削除するレプリケーション タスク (変更フィード) の ID。

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

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

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

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

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

チェンジフィード構成を変更するには、 pause the replication task -> modify the configuration -> resume the replication taskの手順に従います。

リクエストURI

PUT /api/v1/changefeeds/{changefeed_id}

パラメータの説明

パスパラメータ

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

リクエストボディのパラメータ

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

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

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

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

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。
  • state: レプリケーションタスクの現在の
  • checkpoint_tso: レプリケーション タスクの現在のチェックポイントの TSO 表現。
  • checkpoint_time: レプリケーション タスクの現在のチェックポイントの形式化された時刻表現。
  • error: レプリケーションタスクのエラー情報。

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

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

リクエストURI

GET /api/v1/changefeeds/{changefeed_id}

パラメータの説明

パスパラメータ

パラメータ名説明
changefeed_idクエリ対象のレプリケーション タスク (変更フィード) の 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一時停止するレプリケーション タスク (変更フィード) の 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再開するレプリケーション タスク (変更フィード) の 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スケジュールされるレプリケーション タスク (変更フィード) の ID。

次のリクエストは、ID test1を持つ変更フィード内のすべてのテーブルの負荷分散をトリガーします。

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スケジュールされるレプリケーション タスク (変更フィード) の ID。

リクエストボディのパラメータ

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

次のリクエストは、ID test1の変更フィード内の 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_level 「debug」、「info」、「warn」、「error」、「dpanic」、「panic」、および「fatal」のzap によって提供されるログ レベルをサポートします。

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

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

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

Playground
新規
登録なしで TiDB の機能をワンストップでインタラクティブに体験できます。
製品
TiDB Cloud
TiDB
価格
PoC お問い合わせ
エコシステム
TiKV
TiFlash
OSS Insight
© 2024 PingCAP. All Rights Reserved.
Privacy Policy.