TiCDC OpenAPI v2
TiCDC は、TiCDC クラスターを照会および操作するための OpenAPI 機能を提供します。 OpenAPI 機能はcdc cliツールのサブセットです。
ノート：
- TiCDC は、v6.5.x リリース シリーズの v6.5.2 から始まる OpenAPI v2 をサポートします。 TiCDC のバージョンが v6.5.0 または v6.5.1 の場合は、代わりにTiCDC OpenAPI v1を使用してください。
- TiCDC OpenAPI v1 は、将来のリリースで削除される予定です。 TiCDC OpenAPI v2 を使用することをお勧めします。
API を使用して、TiCDC クラスターで次のメンテナンス操作を実行できます。
- TiCDC ノードのステータス情報を取得する
- TiCDC クラスターのヘルス ステータスを確認する
- レプリケーション タスクを作成する
- レプリケーション タスクを削除する
- レプリケーション構成を更新する
- レプリケーション タスク リストを照会する
- 特定のレプリケーション タスクを照会する
- レプリケーション タスクを一時停止する
- レプリケーション タスクを再開する
- レプリケーション サブタスク リストを照会する
- 特定のレプリケーション サブタスクを照会する
- TiCDC サービス プロセス リストのクエリ
- 所有者ノードを削除する
- 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": "v7.0.0-master-dirty",
"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: このノードがライブかどうか。0通常を意味します。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": true,
"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": {
"do_dbs": [
"string"
],
"do_tables": [
{
"database_name": "string",
"table_name": "string"
}
],
"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_dbs": [
"string"
],
"ignore_tables": [
{
"database_name": "string",
"table_name": "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_id 、 start_ts 、 target_ts 、およびsink_uriの意味と形式は、 cdc cliを使用してレプリケーション タスクを作成するドキュメントで説明されているものと同じです。これらのパラメーターの詳細な説明については、そのドキュメントを参照してください。 sink_uriで証明書パスを指定するときは、対応する証明書を対応する TiCDCサーバーにアップロードしたことを確認してください。
replica_configパラメータの説明は次のとおりです。
consistentパラメータは次のように説明されています。
filterパラメータは次のように説明されています。
filter.event_filtersパラメータの説明は次のとおりです。詳細については、 Changefeed ログ フィルタを参照してください。
mounterパラメータの説明は次のとおりです。
sinkパラメータは次のように説明されています。
sink.column_selectorsは配列です。パラメータの説明は次のとおりです。
sink.csvパラメータは次のように説明されています。
sink.dispatchers : MQ タイプのシンクの場合、このパラメーターを使用してイベント ディスパッチャーを構成できます。次のディスパッチャーがサポートされています: default 、 ts 、 rowid 、およびtable 。ディスパッチャのルールは次のとおりです。
default: 複数の一意のインデックス (主キーを含む) が存在する場合、イベントはテーブル モードでディスパッチされます。一意のインデックス (または主キー) が 1 つだけ存在する場合、イベントは行 ID モードでディスパッチされます。古い値機能が有効になっている場合、イベントはテーブル モードでディスパッチされます。ts: 行変更の commitTs を使用してハッシュ値を作成し、イベントをディスパッチします。rowid: 選択した HandleKey 列の名前と値を使用して、ハッシュ値を作成し、イベントをディスパッチします。table: テーブルのスキーマ名とテーブル名を使用してハッシュ値を作成し、イベントをディスパッチします。
sink.dispatchersは配列です。パラメータの説明は次のとおりです。
例
次のリクエストは、ID がtest5とsink_uri of blackhome://のレプリケーション タスクを作成します。
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": true,
"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": {
"do_dbs": [
"string"
],
"do_tables": [
{
"database_name": "string",
"table_name": "string"
}
],
"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_dbs": [
"string"
],
"ignore_tables": [
{
"database_name": "string",
"table_name": "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
]
}
]
}
パラメータの説明は次のとおりです。
task_statusパラメータは次のように説明されています。
errorパラメータは次のように説明されています。
レプリケーション タスクを削除する
この API は、レプリケーション タスクを削除するためのべき等インターフェイスです (つまり、最初の適用を超えて結果を変更することなく、複数回適用できます)。リクエストが成功した場合、 200 OKが返されます。返された結果は、サーバーがコマンドの実行に同意したことを意味するだけで、コマンドが正常に実行されることを保証するものではありません。
リクエストURI
DELETE /api/v2/changefeeds/{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}
パラメータの説明
パス パラメータ
リクエスト本文のパラメータ
{
"replica_config": {
"bdr_mode": true,
"case_sensitive": true,
"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": {
"do_dbs": [
"string"
],
"do_tables": [
{
"database_name": "string",
"table_name": "string"
}
],
"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_dbs": [
"string"
],
"ignore_tables": [
{
"database_name": "string",
"table_name": "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_ts ID test1から32に更新します。
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の値のオプションはall 、 normal 、 stopped 、 error 、 failed 、およびfinishedです。
このパラメータが指定されていない場合、デフォルトでnormal 、 stopped 、または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}
パラメータの説明
パス パラメータ
例
次のリクエストは、ID test1のレプリケーション タスクの詳細情報を照会します。
curl -X GET http://127.0.0.1:8300/api/v2/changefeeds/test1
JSON レスポンスボディの意味は、 レプリケーション タスクを作成する節と同じです。詳細については、そのセクションを参照してください。
レプリケーション タスクを一時停止する
この API は、レプリケーション タスクを一時停止します。リクエストが成功した場合、 200 OKが返されます。返された結果は、サーバーがコマンドの実行に同意したことを意味するだけで、コマンドが正常に実行されることを保証するものではありません。
リクエストURI
POST /api/v2/changefeeds/{changefeed_id}/pause
パラメータの説明
パス パラメータ
例
次のリクエストは、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
パラメータの説明
パス パラメータ
リクエスト本文のパラメータ
{
"overwrite_checkpoint_ts": 0
}
例
次のリクエストは、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がtestでcapture_idが561c3784-77f0-4863-ad52-65a3436db6afのサブタスクの詳細情報を照会します。サブタスクはchangefeed_idとcapture_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 zap によって提供されるログ レベルサポートします: "debug"、"info"、"warn"、"error"、"dpanic"、"panic"、および "fatal"。
例
curl -X POST -H "'Content-type':'application/json'" http://127.0.0.1:8300/api/v2/log -d '{"log_level":"debug"}'
リクエストが成功した場合、 200 OKが返されます。リクエストが失敗すると、エラー メッセージとエラー コードが返されます。