TiCDC OpenAPI v2

TiCDC は、TiCDC クラスターのクエリと操作のための OpenAPI 機能を提供します。 OpenAPI 機能はcdc cliツールのサブセットです。

注記：

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.1.3",
  "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": false,
    "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パラメータは次のように説明されます。詳細については、 変更フィードログフィルターを参照してください。

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

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

sink.column_selectorsは配列です。パラメータは次のように説明されます。

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

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

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

sink.dispatchersは配列です。パラメータは次のように説明されます。

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

例

次のリクエストは、ID がtest5およびsink_uri 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": false,
    "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が返されます。返された結果は、サーバーがコマンドの実行に同意したことを意味するだけで、コマンドが正常に実行されることを保証するものではありません。

チェンジフィード構成を変更するには、 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": false,
    "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 経由で変更できるのは次の構成のみです。

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

例

次のリクエストは、ID がtest1レプリケーション タスクのtarget_tsを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 クラスター内のすべてのレプリケーション タスク (変更フィード) の基本情報が返されます。

リクエスト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 は同期インターフェイスです。リクエストが成功すると、指定したレプリケーションタスクの詳細情報（変更フィード）が返されます。

リクエスト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 「debug」、「info」、「warn」、「error」、「dpanic」、「panic」、および「fatal」のzap によって提供されるログ レベルをサポートします。

例

curl -X POST -H "'Content-type':'application/json'" http://127.0.0.1:8300/api/v2/log -d '{"log_level":"debug"}'

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