TiCDC OpenAPI v2

TiCDC は、TiCDC クラスターを照会および操作するための OpenAPI 機能を提供します。 OpenAPI 機能はcdc cliツールのサブセットです。

ノート：

• TiCDC は、v6.5.x リリース シリーズの v6.5.2 から始まる OpenAPI v2 をサポートします。 TiCDC のバージョンが v6.5.0 または v6.5.1 の場合は、代わりにTiCDC OpenAPI v1を使用してください。
• TiCDC OpenAPI v1 は、将来のリリースで削除される予定です。 TiCDC OpenAPI v2 を使用することをお勧めします。

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

• TiCDC ノードのステータス情報を取得する
• TiCDC クラスターのヘルス ステータスを確認する
• レプリケーション タスクを作成する
• レプリケーション タスクを削除する
• レプリケーション構成を更新する
• レプリケーション タスク リストを照会する
• 特定のレプリケーション タスクを照会する
• レプリケーション タスクを一時停止する
• レプリケーション タスクを再開する
• レプリケーション サブタスク リストを照会する
• 特定のレプリケーション サブタスクを照会する
• TiCDC サービス プロセス リストのクエリ
• 所有者ノードを削除する
• TiCDCサーバーのログレベルを動的に調整する

すべての API の要求本文と戻り値は JSON 形式です。リクエストが成功すると、 200 OKメッセージが返されます。以下のセクションでは、API の特定の使用法について説明します。

次の例では、TiCDCサーバーのリッスン IP アドレスは127.0.0.1で、ポートは8300です。 TiCDCサーバーの起動時に、 --addr=ip:port経由で TiCDC にバインドされた IP アドレスとポートを指定できます。

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

API リクエストの送信後にエラーが発生した場合、次の形式のエラー メッセージが返されます。

{
    "error_msg": "",
    "error_code": ""
}

上記の JSON 出力で、 error_msgエラー メッセージを表し、 error_codeは対応するエラー コードです。

API リスト インターフェイスの戻り形式

API リクエストがリソースのリスト (たとえば、すべてCapturesのリスト) を返す場合、TiCDC の戻り形式は次のとおりです。

{
  "total": 2,
  "items": [
    {
      "id": "d2912e63-3349-447c-90ba-wwww",
      "is_owner": true,
      "address": "127.0.0.1:8300"
    },
    {
      "id": "d2912e63-3349-447c-90ba-xxxx",
      "is_owner": false,
      "address": "127.0.0.1:8302"
    }
  ]
}

上記の例では:

• total : リソースの総数を示します。
• items : このリクエストによって返されるすべてのリソースを含む配列。配列のすべての要素は同じリソースです。

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

この API は同期インターフェースです。リクエストが成功すると、対応するノードのステータス情報が返されます。

リクエストURI

GET /api/v2/status

例

次のリクエストは、IP アドレスが127.0.0.1でポート番号が8300 TiCDC ノードのステータス情報を取得します。

curl -X GET http://127.0.0.1:8300/api/v2/status

{
  "version": "v7.0.0-master-dirty",
  "git_hash": "10413bded1bdb2850aa6d7b94eb375102e9c44dc",
  "id": "d2912e63-3349-447c-90ba-72a4e04b5e9e",
  "pid": 1447,
  "is_owner": true,
  "liveness": 0
}

上記の出力のパラメータは次のとおりです。

• version : TiCDC の現在のバージョン番号。
• git_hash : Git ハッシュ値。
• id : ノードのキャプチャ ID。
• pid : ノードのキャプチャ プロセス ID (PID)。
• is_owner : ノードが所有者かどうかを示します。
• liveness : このノードがライブかどうか。 0通常を意味します。 1ノードがgraceful shutdown状態であることを意味します。

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

この API は同期インターフェースです。クラスターが正常な場合、 200 OKが返されます。

リクエストURI

GET /api/v2/health

例

curl -X GET http://127.0.0.1:8300/api/v2/health

クラスターが正常な場合、応答は200 OKで、空の JSON オブジェクトです。

{}

クラスターが正常でない場合、応答はエラー メッセージを含む JSON オブジェクトです。

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

このインターフェイスは、レプリケーション タスクを TiCDC に送信するために使用されます。リクエストが成功した場合、 200 OKが返されます。返された結果は、サーバーがコマンドの実行に同意したことを意味するだけで、コマンドが正常に実行されることを保証するものではありません。

リクエストURI

POST /api/v2/changefeeds

パラメータの説明

{
  "changefeed_id": "string",
  "replica_config": {
    "bdr_mode": true,
    "case_sensitive": true,
    "check_gc_safe_point": true,
    "consistent": {
      "flush_interval": 0,
      "level": "string",
      "max_log_size": 0,
      "storage": "string"
    },
    "enable_old_value": true,
    "enable_sync_point": true,
    "filter": {
      "do_dbs": [
        "string"
      ],
      "do_tables": [
        {
          "database_name": "string",
          "table_name": "string"
        }
      ],
      "event_filters": [
        {
          "ignore_delete_value_expr": "string",
          "ignore_event": [
            "string"
          ],
          "ignore_insert_value_expr": "string",
          "ignore_sql": [
            "string"
          ],
          "ignore_update_new_value_expr": "string",
          "ignore_update_old_value_expr": "string",
          "matcher": [
            "string"
          ]
        }
      ],
      "ignore_dbs": [
        "string"
      ],
      "ignore_tables": [
        {
          "database_name": "string",
          "table_name": "string"
        }
      ],
      "ignore_txn_start_ts": [
        0
      ],
      "rules": [
        "string"
      ]
    },
    "force_replicate": true,
    "ignore_ineligible_table": true,
    "memory_quota": 0,
    "mounter": {
      "worker_num": 0
    },
    "sink": {
      "column_selectors": [
        {
          "columns": [
            "string"
          ],
          "matcher": [
            "string"
          ]
        }
      ],
      "csv": {
        "delimiter": "string",
        "include_commit_ts": true,
        "null": "string",
        "quote": "string"
      },
      "date_separator": "string",
      "dispatchers": [
        {
          "matcher": [
            "string"
          ],
          "partition": "string",
          "topic": "string"
        }
      ],
      "enable_partition_separator": true,
      "encoder_concurrency": 0,
      "protocol": "string",
      "schema_registry": "string",
      "terminator": "string",
      "transaction_atomicity": "string"
    },
    "sync_point_interval": "string",
    "sync_point_retention": "string"
  },
  "sink_uri": "string",
  "start_ts": 0,
  "target_ts": 0
}

パラメータの説明は次のとおりです。

changefeed_id 、 start_ts 、 target_ts 、およびsink_uriの意味と形式は、 cdc cliを使用してレプリケーション タスクを作成するドキュメントで説明されているものと同じです。これらのパラメーターの詳細な説明については、そのドキュメントを参照してください。 sink_uriで証明書パスを指定するときは、対応する証明書を対応する TiCDCサーバーにアップロードしたことを確認してください。

replica_configパラメータの説明は次のとおりです。

consistentパラメータは次のように説明されています。

filterパラメータは次のように説明されています。

filter.event_filtersパラメータの説明は次のとおりです。詳細については、 Changefeed ログ フィルタを参照してください。

mounterパラメータの説明は次のとおりです。

sinkパラメータは次のように説明されています。

sink.column_selectorsは配列です。パラメータの説明は次のとおりです。

sink.csvパラメータは次のように説明されています。

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

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

sink.dispatchersは配列です。パラメータの説明は次のとおりです。

例

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

curl -X POST -H "'Content-type':'application/json'" http://127.0.0.1:8300/api/v2/changefeeds -d '{"changefeed_id":"test5","sink_uri":"blackhole://"}'

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

応答本文の形式

{
  "admin_job_type": 0,
  "checkpoint_time": "string",
  "checkpoint_ts": 0,
  "config": {
    "bdr_mode": true,
    "case_sensitive": true,
    "check_gc_safe_point": true,
    "consistent": {
      "flush_interval": 0,
      "level": "string",
      "max_log_size": 0,
      "storage": "string"
    },
    "enable_old_value": true,
    "enable_sync_point": true,
    "filter": {
      "do_dbs": [
        "string"
      ],
      "do_tables": [
        {
          "database_name": "string",
          "table_name": "string"
        }
      ],
      "event_filters": [
        {
          "ignore_delete_value_expr": "string",
          "ignore_event": [
            "string"
          ],
          "ignore_insert_value_expr": "string",
          "ignore_sql": [
            "string"
          ],
          "ignore_update_new_value_expr": "string",
          "ignore_update_old_value_expr": "string",
          "matcher": [
            "string"
          ]
        }
      ],
      "ignore_dbs": [
        "string"
      ],
      "ignore_tables": [
        {
          "database_name": "string",
          "table_name": "string"
        }
      ],
      "ignore_txn_start_ts": [
        0
      ],
      "rules": [
        "string"
      ]
    },
    "force_replicate": true,
    "ignore_ineligible_table": true,
    "memory_quota": 0,
    "mounter": {
      "worker_num": 0
    },
    "sink": {
      "column_selectors": [
        {
          "columns": [
            "string"
          ],
          "matcher": [
            "string"
          ]
        }
      ],
      "csv": {
        "delimiter": "string",
        "include_commit_ts": true,
        "null": "string",
        "quote": "string"
      },
      "date_separator": "string",
      "dispatchers": [
        {
          "matcher": [
            "string"
          ],
          "partition": "string",
          "topic": "string"
        }
      ],
      "enable_partition_separator": true,
      "encoder_concurrency": 0,
      "protocol": "string",
      "schema_registry": "string",
      "terminator": "string",
      "transaction_atomicity": "string"
    },
    "sync_point_interval": "string",
    "sync_point_retention": "string"
  },
  "create_time": "string",
  "creator_version": "string",
  "error": {
    "addr": "string",
    "code": "string",
    "message": "string"
  },
  "id": "string",
  "resolved_ts": 0,
  "sink_uri": "string",
  "start_ts": 0,
  "state": "string",
  "target_ts": 0,
  "task_status": [
    {
      "capture_id": "string",
      "table_ids": [
        0
      ]
    }
  ]
}

パラメータの説明は次のとおりです。

task_statusパラメータは次のように説明されています。

errorパラメータは次のように説明されています。

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

この API は、レプリケーション タスクを削除するためのべき等インターフェイスです (つまり、最初の適用を超えて結果を変更することなく、複数回適用できます)。リクエストが成功した場合、 200 OKが返されます。返された結果は、サーバーがコマンドの実行に同意したことを意味するだけで、コマンドが正常に実行されることを保証するものではありません。

リクエストURI

DELETE /api/v2/changefeeds/{changefeed_id}

パラメータの説明

パス パラメータ

例

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

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

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

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

この API は、レプリケーション タスクの更新に使用されます。リクエストが成功した場合、 200 OKが返されます。返された結果は、サーバーがコマンドの実行に同意したことを意味するだけで、コマンドが正常に実行されることを保証するものではありません。

changefeed 構成を変更するには、 pause the replication task -> modify the configuration -> resume the replication taskの手順に従います。

リクエストURI

PUT /api/v2/changefeeds/{changefeed_id}

パラメータの説明

パス パラメータ

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

{
  "replica_config": {
    "bdr_mode": true,
    "case_sensitive": true,
    "check_gc_safe_point": true,
    "consistent": {
      "flush_interval": 0,
      "level": "string",
      "max_log_size": 0,
      "storage": "string"
    },
    "enable_old_value": true,
    "enable_sync_point": true,
    "filter": {
      "do_dbs": [
        "string"
      ],
      "do_tables": [
        {
          "database_name": "string",
          "table_name": "string"
        }
      ],
      "event_filters": [
        {
          "ignore_delete_value_expr": "string",
          "ignore_event": [
            "string"
          ],
          "ignore_insert_value_expr": "string",
          "ignore_sql": [
            "string"
          ],
          "ignore_update_new_value_expr": "string",
          "ignore_update_old_value_expr": "string",
          "matcher": [
            "string"
          ]
        }
      ],
      "ignore_dbs": [
        "string"
      ],
      "ignore_tables": [
        {
          "database_name": "string",
          "table_name": "string"
        }
      ],
      "ignore_txn_start_ts": [
        0
      ],
      "rules": [
        "string"
      ]
    },
    "force_replicate": true,
    "ignore_ineligible_table": true,
    "memory_quota": 0,
    "mounter": {
      "worker_num": 0
    },
    "sink": {
      "column_selectors": [
        {
          "columns": [
            "string"
          ],
          "matcher": [
            "string"
          ]
        }
      ],
      "csv": {
        "delimiter": "string",
        "include_commit_ts": true,
        "null": "string",
        "quote": "string"
      },
      "date_separator": "string",
      "dispatchers": [
        {
          "matcher": [
            "string"
          ],
          "partition": "string",
          "topic": "string"
        }
      ],
      "enable_partition_separator": true,
      "encoder_concurrency": 0,
      "protocol": "string",
      "schema_registry": "string",
      "terminator": "string",
      "transaction_atomicity": "string"
    },
    "sync_point_interval": "string",
    "sync_point_retention": "string"
  },
  "sink_uri": "string",
  "target_ts": 0
}

現在、API を介して変更できるのは次の構成のみです。

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

例

次のリクエストは、レプリケーション タスクのtarget_ts ID test1から32に更新します。

 curl -X PUT -H "'Content-type':'application/json'" http://127.0.0.1:8300/api/v2/changefeeds/test1 -d '{"target_ts":32}'

リクエストが成功した場合、 200 OKが返されます。リクエストが失敗すると、エラー メッセージとエラー コードが返されます。 JSON レスポンスボディの意味は、セクションレプリケーション タスクを作成すると同じです。詳細については、そのセクションを参照してください。

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

この API は同期インターフェースです。リクエストが成功すると、TiCDC クラスター内のすべてのレプリケーション タスク (changefeed) の基本情報が返されます。

リクエストURI

GET /api/v2/changefeeds

パラメータの説明

クエリ パラメータ

stateの値のオプションはall 、 normal 、 stopped 、 error 、 failed 、およびfinishedです。

このパラメータが指定されていない場合、デフォルトでnormal 、 stopped 、またはfailed状態のレプリケーション タスクの基本情報が返されます。

例

次のリクエストは、状態normalのすべてのレプリケーション タスクの基本情報を照会します。

curl -X GET http://127.0.0.1:8300/api/v2/changefeeds?state=normal

{
  "total": 2,
  "items": [
    {
      "id": "test",
      "state": "normal",
      "checkpoint_tso": 439749918821711874,
      "checkpoint_time": "2023-02-27 23:46:52.888",
      "error": null
    },
    {
      "id": "test2",
      "state": "normal",
      "checkpoint_tso": 439749918821711874,
      "checkpoint_time": "2023-02-27 23:46:52.888",
      "error": null
    }
  ]
}

上記の返された結果のパラメータは次のとおりです。

• id : レプリケーション タスクの ID。
• state : レプリケーション タスクの現在の州 。
• checkpoint_tso : レプリケーション タスクの現在のチェックポイントの TSO。
• checkpoint_time : レプリケーション タスクの現在のチェックポイントのフォーマットされた時刻。
• error : レプリケーション タスクのエラー情報。

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

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

リクエストURI

GET /api/v2/changefeeds/{changefeed_id}

パラメータの説明

パス パラメータ

例

次のリクエストは、ID test1のレプリケーション タスクの詳細情報を照会します。

curl -X GET http://127.0.0.1:8300/api/v2/changefeeds/test1

JSON レスポンスボディの意味は、 レプリケーション タスクを作成する節と同じです。詳細については、そのセクションを参照してください。

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

この API は、レプリケーション タスクを一時停止します。リクエストが成功した場合、 200 OKが返されます。返された結果は、サーバーがコマンドの実行に同意したことを意味するだけで、コマンドが正常に実行されることを保証するものではありません。

リクエストURI

POST /api/v2/changefeeds/{changefeed_id}/pause

パラメータの説明

パス パラメータ

例

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

curl -X POST http://127.0.0.1:8300/api/v2/changefeeds/test1/pause

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

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

この API は、レプリケーション タスクを再開します。リクエストが成功した場合、 200 OKが返されます。返された結果は、サーバーがコマンドの実行に同意したことを意味するだけで、コマンドが正常に実行されることを保証するものではありません。

リクエストURI

POST /api/v2/changefeeds/{changefeed_id}/resume

パラメータの説明

パス パラメータ

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

{
  "overwrite_checkpoint_ts": 0
}

例

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

curl -X POST http://127.0.0.1:8300/api/v2/changefeeds/test1/resume -d '{}'

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

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

この API は同期インターフェースです。リクエストが成功すると、すべてのレプリケーション サブタスクの基本情報 ( processor ) が返されます。

リクエストURI

GET /api/v2/processors

例

curl -X GET http://127.0.0.1:8300/api/v2/processors

{
  "total": 3,
  "items": [
    {
      "changefeed_id": "test2",
      "capture_id": "d2912e63-3349-447c-90ba-72a4e04b5e9e"
    },
    {
      "changefeed_id": "test1",
      "capture_id": "d2912e63-3349-447c-90ba-72a4e04b5e9e"
    },
    {
      "changefeed_id": "test",
      "capture_id": "d2912e63-3349-447c-90ba-72a4e04b5e9e"
    }
  ]
}

パラメータの説明は次のとおりです。

• changefeed_id : 変更フィード ID。
• capture_id : キャプチャ ID。

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

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

リクエストURI

GET /api/v2/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/v2/processors/test/561c3784-77f0-4863-ad52-65a3436db6af

{
  "table_ids": [
    80
  ]
}

パラメータは次のように記述されます。

• table_ids : このキャプチャでレプリケートされるテーブル ID。

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

この API は同期インターフェースです。リクエストが成功すると、すべてのレプリケーション プロセスの基本情報 ( capture ) が返されます。

リクエストURI

GET /api/v2/captures

例

curl -X GET http://127.0.0.1:8300/api/v2/captures

{
  "total": 1,
  "items": [
    {
      "id": "d2912e63-3349-447c-90ba-72a4e04b5e9e",
      "is_owner": true,
      "address": "127.0.0.1:8300"
    }
  ]
}

パラメータの説明は次のとおりです。

• id : キャプチャ ID。
• is_owner : キャプチャが所有者かどうか。
• address : キャプチャのアドレス。

所有者ノードを削除する

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

リクエストURI

POST /api/v2/owner/resign

例

次のリクエストは、TiCDC の現在の所有者ノードを削除し、新しい所有者ノードを生成するための新しいラウンドの選挙をトリガーします。

curl -X POST http://127.0.0.1:8300/api/v2/owner/resign

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

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

この API は同期インターフェースです。リクエストが成功した場合、 200 OKが返されます。

リクエストURI

POST /api/v2/log

リクエストパラメータ

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

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/v2/log -d '{"log_level":"debug"}'

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