TiCDC オープン API v1

注記
TiCDC OpenAPI v1 は非推奨であり、将来的に削除される予定です。 TiCDC オープン API v2使用することをお勧めします。

TiCDC は、 cdc cliツールの機能に類似した、TiCDC クラスターのクエリと操作のための OpenAPI 機能を提供します。

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
}

上記の出力のフィールドは次のように説明されます。

バージョン: 現在の 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の意味と形式sink_uri start_ts cdc cliを使用してレプリケーションタスクを作成するドキュメントで説明されているものsink_uri同じです。これらのパラメータの詳細な説明target_tsは、このドキュメントを参照してください。11 で証明書パスを指定する場合は、対応する証明書を対応する 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":"index-value"}
  ],
  "protocol":"canal-json"
}

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

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

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

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

例

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

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 経由で変更できるのは次の構成のみです。

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

例

次のリクエストは、ID test1のレプリケーションタスクのmounter_worker_num 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の変更フィード内のすべてのテーブルの負荷分散をトリガーします。

 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の変更フィード内の 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が返されます。要求が失敗した場合は、エラーメッセージとエラーコードが返されます。

TiCDC オープン API v1

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

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

リクエストURI

例

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

リクエストURI

例

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

リクエストURI

パラメータの説明

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

例

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

リクエストURI

パラメータの説明

パスパラメータ

例

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

リクエストURI

パラメータの説明

パスパラメータ

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

例

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

リクエストURI

パラメータの説明

クエリパラメータ

例

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

リクエストURI

パラメータの説明

パスパラメータ

例

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

リクエストURI

パラメータの説明

パスパラメータ

例

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

リクエストURI

パラメータの説明

パスパラメータ

例

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

リクエストURI

例

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

リクエストURI

パラメータの説明

パスパラメータ

例

TiCDC サービス プロセス リストを照会する

リクエストURI

例

所有者ノードの削除

リクエストURI

例

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

リクエストURI

パラメータの説明

パスパラメータ

例

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

リクエストURI

パラメータの説明

パスパラメータ

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

例

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

リクエストURI

リクエストパラメータ

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

例

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

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

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

TiCDC サービスプロセスリストを照会する