TiCDC OpenAPI v1

ノート
TiCDC OpenAPI v1 は非推奨となり、将来削除される予定です。 TiCDC OpenAPI v2を使用することをお勧めします。

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 タイプのシンクの場合、ディスパッチャーを使用してイベントディスパッチャーを構成できます。 4 つのディスパッチャー ( default 、 ts 、 rowid 、およびtableがサポートされています。ディスパッチャのルールは次のとおりです。

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

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

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

例

次のリクエストは、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`	削除するレプリケーションタスク (変更フィード) の ID。

例

次のリクエストは、ID test1のレプリケーションタスクを削除します。

curl -X DELETE http://127.0.0.1:8300/api/v1/changefeeds/test1

リクエストが成功すると202 Acceptedが返されます。リクエストが失敗した場合は、エラーメッセージとエラーコードが返されます。

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

チェンジフィード構成を変更するには、 pause the replication task -> modify the configuration -> resume the replication taskの手順に従います。

リクエストURI

PUT /api/v1/changefeeds/{changefeed_id}

パラメータの説明

パスパラメータ

パラメータ名	説明
`changefeed_id`	更新するレプリケーションタスク (変更フィード) の 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。
state: レプリケーションタスクの現在の州。
checkpoint_tso: レプリケーションタスクの現在のチェックポイントの TSO 表現。
checkpoint_time: レプリケーションタスクの現在のチェックポイントの形式化された時刻表現。
error: レプリケーションタスクのエラー情報。

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

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

リクエストURI

GET /api/v1/changefeeds/{changefeed_id}

パラメータの説明

パスパラメータ

パラメータ名	説明
`changefeed_id`	クエリ対象のレプリケーションタスク (変更フィード) の 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`	一時停止するレプリケーションタスク (変更フィード) の 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`	再開するレプリケーションタスク (変更フィード) の 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`	スケジュールされるレプリケーションタスク (変更フィード) の 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`	スケジュールされるレプリケーションタスク (変更フィード) の 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 OpenAPI v1

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

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

リクエストURI

例

TiCDC クラスターの健全性ステータスを確認する

リクエストURI

例

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

リクエストURI

パラメータの説明

リクエストボディのパラメータ

例

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

リクエストURI

パラメータの説明

パスパラメータ

例

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

リクエストURI

パラメータの説明

パスパラメータ

リクエストボディのパラメータ

例

レプリケーションタスクリストのクエリ

リクエストURI

パラメータの説明

クエリパラメータ

例

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

リクエストURI

パラメータの説明

パスパラメータ

例

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

リクエストURI

パラメータの説明

パスパラメータ

例

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

リクエストURI

パラメータの説明

パスパラメータ

例

レプリケーションサブタスクリストのクエリ

リクエストURI

例

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

リクエストURI

パラメータの説明

パスパラメータ

例

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

リクエストURI

例

所有者ノードを削除する

リクエストURI

例

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

リクエストURI

パラメータの説明

パスパラメータ

例

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

リクエストURI

パラメータの説明

パスパラメータ

リクエストボディのパラメータ

例

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

リクエストURI

リクエストパラメータ

リクエストボディのパラメータ

例

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

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

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

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