TiCDC OpenAPI

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

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

TiCDC ノードのステータス情報を取得する
TiCDC クラスターのヘルスステータスを確認する
レプリケーションタスクを作成する
レプリケーションタスクを削除する
レプリケーション構成を更新する
レプリケーションタスクリストを照会する
特定のレプリケーションタスクを照会する
レプリケーションタスクを一時停止する
レプリケーションタスクを再開する
レプリケーションサブタスクリストを照会する
特定のレプリケーションサブタスクを照会する
TiCDC サービスプロセスリストのクエリ
所有者ノードを削除する
レプリケーションタスクですべてのテーブルの負荷分散を手動でトリガーする
テーブルを別のノードに手動でスケジュールする
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 、 start_ts 、 target_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 タイプのシンクの場合、ディスパッチャーを使用してイベントディスパッチャーを構成できます。 default 、 ts 、 rowid 、およびtableの 4 つのディスパッチャがサポートされています。ディスパッチャのルールは次のとおりです。

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

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

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

例

次のリクエストは、ID がtest5でsink_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が返されます。リクエストが失敗すると、エラーメッセージとエラーコードが返されます。

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

リクエスト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が返されます。リクエストが失敗すると、エラーメッセージとエラーコードが返されます。

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

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

リクエストURI

PUT /api/v1/changefeeds/{changefeed_id}

パラメータの説明

パスパラメータ

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

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

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

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

例

次のリクエストは、レプリケーションタスクの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の値のオプションはall 、 normal 、 stopped 、 error 、 failed 、および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": {}
        }
    ]
}

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

リクエスト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が返されます。リクエストが失敗すると、エラーメッセージとエラーコードが返されます。

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

リクエスト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_idがtestでcapture_idが561c3784-77f0-4863-ad52-65a3436db6afのサブタスクの詳細情報を照会します。サブタスクはchangefeed_idとcapture_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"
    }
]

所有者ノードを削除する

リクエストURI

POST /api/v1/owner/resign

例

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

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

リクエストが成功した場合、 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が返されます。リクエストが失敗すると、エラーメッセージとエラーコードが返されます。

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

リクエスト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_levelはzap によって提供されるログレベルをサポートします: "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が返されます。リクエストが失敗すると、エラーメッセージとエラーコードが返されます。

TiCDC OpenAPI

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

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

リクエストURI

例

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

リクエストURI

例

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

リクエストURI

パラメータの説明

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

例

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

リクエストURI

パラメータの説明

パス パラメータ

例

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

リクエストURI

パラメータの説明

パス パラメータ

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

例

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

リクエストURI

パラメータの説明

クエリ パラメータ

例

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

リクエストURI

パラメータの説明

パス パラメータ

例

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

リクエストURI

パラメータの説明

パス パラメータ

例

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

リクエストURI

パラメータの説明

パス パラメータ

例

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

リクエストURI

例

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

リクエストURI

パラメータの説明

パス パラメータ

例

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

リクエストURI

例

所有者ノードを削除する

リクエストURI

例

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

リクエストURI

パラメータの説明

パス パラメータ

例

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

リクエストURI

パラメータの説明

パス パラメータ

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

例

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

リクエストURI

リクエストパラメータ

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

例

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

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

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

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

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

パスパラメータ

パスパラメータ

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

クエリパラメータ

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

パスパラメータ

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

パスパラメータ

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

パスパラメータ

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

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

パスパラメータ

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

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

パスパラメータ

パスパラメータ