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 | 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_id 、およびstart_tsの意味と形式は、 target_tsのcdc cliを使用してレプリケーションタスクを作成しますで説明されているものと同じsink_uri 。これらのパラメータの詳細については、このドキュメントを参照してください。 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タイプのシンクの場合、ディスパッチャーを使用してイベントディスパッチャーを構成できます。 ts tableのディスパッチャがサポートされています： default 、およびrowid 。ディスパッチャのルールは次のとおりです。

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

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

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

例

次のリクエストは、IDがtest5のblackhome://タスクを作成しsink_uri 。

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}

パラメータの説明

パスパラメータ

例

次のリクエストは、 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}

パラメータの説明

パスパラメータ

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

現在、APIを介して変更できるのは次の構成のみです。

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

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

例

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

 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の値normal finished 、 all 、 error stopped failed 。

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

例

次のリクエストは、状態が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_tso：レプリケーションタスクの現在のチェックポイントのフォーマットされた時間表現。
• error：レプリケーションタスクのエラー情報。

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

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

URIをリクエストする

GET /api/v1/changefeeds/{changefeed_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

パラメータの説明

パスパラメータ

例

次のリクエストは、 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

パラメータの説明

パスパラメータ

例

次のリクエストは、 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が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"
    }
]

所有者ノードを削除します

この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

パラメータの説明

パスパラメータ

例

次のリクエストは、 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

パラメータの説明

パスパラメータ

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

例

次のリクエストは、 test1のチェンジフィードにある49のテーブルを、 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は、「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が返されます。リクエストが失敗した場合、エラーメッセージとエラーコードが返されます。