TiCDC OpenAPI v1

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 : Mounter のスレッド数。Mounter は 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、debezium、simpleのプロトコルがサポートされています。

例

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

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

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

リクエストURI

DELETE /api/v1/changefeeds/{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}

パラメータの説明

パスパラメータ

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

現在、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の値のオプションはall 、 normal 、 stopped 、 error 、 failed 、 finishedです。

このパラメータを指定しない場合は、状態が normal、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。
• state: レプリケーションタスクの現在の状態。
• checkpoint_tso: レプリケーションタスクの現在のチェックポイントの TSO 表現。
• checkpoint_time: レプリケーションタスクの現在のチェックポイントのフォーマットされた時間表現。
• error: レプリケーションタスクのエラー情報。

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

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

リクエストURI

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

パラメータの説明

パスパラメータ

例

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

パラメータの説明

パスパラメータ

例

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

パラメータの説明

パスパラメータ

例

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

パラメータの説明

パスパラメータ

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

例

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