TiCDC オープンAPI v1

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

TiCDC は、TiCDC クラスターを照会および操作するための OpenAPI 機能を提供します。これは、 cdc cliツールの機能に似ています。

API を使用して、TiCDC クラスターで次のメンテナンス操作を実行できます。

TiCDCノードのステータス情報を取得する
TiCDC クラスターのヘルスステータスを確認する
レプリケーションタスクを作成する
レプリケーションタスクを削除する
レプリケーション構成を更新する
レプリケーションタスクリストをクエリする
特定のレプリケーションタスクをクエリする
レプリケーションタスクを一時停止する
Resume a replication task
レプリケーションサブタスクリストを照会する
特定のレプリケーションサブタスクをクエリする
TiCDC サービスプロセスリストを照会する
所有者ノードの退去
レプリケーションタスク内のすべてのテーブルの負荷分散を手動でトリガーする
テーブルを別のノードに手動でスケジュールする
TiCDCサーバーのログレベルを動的に調整する

すべてのAPIのリクエストボディと戻り値はJSON形式です。以下のセクションでは、APIの具体的な使用方法について説明します。

以下の例では、TiCDCサーバーのリスニングIPアドレスは127.0.0.1 、ポートは8300です。TiCDCサーバーの起動時に、指定したIPアドレスとポートを--addr=ip:portでバインドできます。

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

After sending an API request, if an error occurs, the returned error message is in the following format:

{
    "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 target_ts意味と形式は、 cdc cliを使用してレプリケーションタスクを作成するドキュメントに記載されているものと同じです。 sink_uri start_tsパラメータの詳細については、こちらのドキュメントを参照してくださいsink_uriで証明書パスを指定する際は、対応する証明書が対応する TiCDCサーバーにアップロードされていることを確認してください。

上記の表のその他のパラメータについては、次のようにさらに詳しく説明します。

force_replicate : このパラメータのデフォルトはfalseです。4 true指定すると、TiCDC は一意のインデックスを持たないテーブルを強制的に複製しようとします。

ignore_ineligible_table : このパラメータのデフォルトはfalseです。4 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です。

The configuration parameters of sink are as follows:

{
  "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: uses the name and value of the selected HandleKey column to create the hash value and dispatch events.
table : テーブルのスキーマ名とテーブル名を使用してハッシュ値を作成し、イベントをディスパッチします。

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

protocol : MQタイプのシンクの場合、メッセージのプロトコル形式を指定できます。現在、 canal-json debeziumプロトコルopen-protocolサポートsimpleれています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 経由で変更できるのは次の構成のみです。

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

例

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

Query the replication task list

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

パラメータの説明

Path parameters

パラメータ名	説明
`changefeed_id`	The ID of the replication task (changefeed) to be scheduled.

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

パラメータ名	説明
`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

Request parameters

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

パラメータ名	説明
`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

パラメータの説明

パスパラメータ

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

例

Query the replication task list

リクエストURI

パラメータの説明

クエリパラメータ

例

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

リクエストURI

パラメータの説明

パスパラメータ

例

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

リクエストURI

パラメータの説明

パスパラメータ

例

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

リクエストURI

パラメータの説明

パスパラメータ

例

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

リクエストURI

例

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

リクエストURI

パラメータの説明

パスパラメータ

例

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

リクエストURI

例

所有者ノードの退去

リクエストURI

例

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

リクエストURI

パラメータの説明

パスパラメータ

例

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

リクエストURI

パラメータの説明

Path parameters

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

例

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

リクエストURI

Request parameters

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

例

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

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