TiDB Self-Managed
Learning Center
お問い合わせ

TiCDC OpenAPI

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型。 changefeed の開始 TSO を指定します。 (オプション) | | | target_ts | UINT64型。 changefeed のターゲット 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 、および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が返されます。リクエストが失敗すると、エラー メッセージとエラー コードが返されます。

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

この API は非同期インターフェースです。リクエストが成功した場合、 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が返されます。リクエストが失敗すると、エラー メッセージとエラー コードが返されます。

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

この API は非同期インターフェースです。リクエストが成功した場合、 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 経由で変更できるのは次の構成のみです。

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

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

例

次のリクエストは、レプリケーション タスクの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_tso: レプリケーション タスクの現在のチェックポイントのフォーマットされた時間表現。
  • 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": {}
        }
    ]
}

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

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

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

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

この API は非同期インターフェースです。リクエストが成功した場合、 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"
    }
]

所有者ノードを削除する

この 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スケジュールするレプリケーション タスク (changefeed) の ID。

例

次のリクエストは、ID がtest1の changefeed 内のすべてのテーブルの負荷分散をトリガーします。

 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スケジュールするレプリケーション タスク (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が返されます。リクエストが失敗すると、エラー メッセージとエラー コードが返されます。