TiDB
社区
联系我们

TiCDC OpenAPI

TiCDC 提供 OpenAPI 功能，你可以通过 OpenAPI 对 TiCDC 集群进行查询和运维操作。OpenAPI 的总体功能和 cdc cli 工具类似。

你可以通过 OpenAPI 完成 TiCDC 集群的如下运维操作：

所有 API 的请求体与返回值统一使用 JSON 格式数据。本文档以下部分描述当前提供的 API 的具体使用方法。

在下文的示例描述中，假设 TiCDC server 的监听 IP 地址为 127.0.0.1，端口为 8300（在启动 TiCDC server 时可以通过 --addr=ip:port 指定绑定的 IP 和端口）。

API 统一错误格式

对 API 发起的请求后，如发生错误，返回错误信息的格式如下所示：

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

如上所示，error_msg 描述错误信息，error_code 则是对应的错误码。

获取 TiCDC 节点状态信息

该接口是一个同步接口，请求成功会返回对应节点的状态信息。

请求 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：该节点的 capture ID。
  • pid：该节点 capture 进程的 PID。
  • is_owner：表示该节点是否是 owner。

检查 TiCDC 集群的健康状态

该接口是一个同步接口，在集群健康的时候会返回 200 OK。

请求 URI

GET /api/v1/health

使用样例

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

创建同步任务

该接口是一个异步接口，请求成功会返回 202 Accepted。该返回结果只代表服务器答应执行该命令，不保证命令会被成功的执行。

请求 URI

POST /api/v1/changefeeds

参数说明

使用 API 创建同步任务可选的参数不如使用 cli 命令创建同步任务的参数完备，以下是该 API 支持的参数。

请求体参数

参数名说明
changefeed_idSTRING 类型，同步任务的 ID。 （非必选）
start_tsUINT64 类型，指定 changefeed 的开始 TSO。（非必选）
target_tsUINT64 类型，指定 changefeed 的目标 TSO。（非必选）
sink_uriSTRING 类型，同步任务下游的地址。（必选）
force_replicateBOOLEAN 类型，是否强制同步没有唯一索引的表。（非必选）
ignore_ineligible_tableBOOLEAN 类型，是否忽略无法进行同步的表。（非必选）
filter_rulesSTRING 类型数组，表库过滤的规则。（非必选）
ignore_txn_start_tsUINT64 类型数组，忽略指定 start_ts 的事务。 （非必选）
mounter_worker_numINT 类型，Mounter 线程数。（非必选）
sink_configsink 的配置参数。（非必选）

changefeed_id、start_ts、target_ts、sink_uri 的含义和格式与使用 cli 创建同步任务中所作的解释相同，具体解释请参见该文档。需要注意，当在 sink_uri 中指定证书的路径时，须确保已将对应证书上传到对应的 TiCDC server 上。

下面会对一些需要补充说明的参数进行进一步阐述。

force_replicate：该值默认为 false，当指定为 true 时，同步任务会尝试强制同步没有唯一索引的表。

ignore_ineligible_table：该值默认为 false，当指定为 true 时，同步任务会忽略无法进行同步的表。

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。

sink_config：sink 的配置参数，如下

{
  "dispatchers":[
    {"matcher":["test1.*", "test2.*"], "dispatcher":"ts"},
    {"matcher":["test3.*", "test4.*"], "dispatcher":"rowid"}
  ],
  "protocol":"canal-json"
}

dispatchers：对于 MQ 类的 Sink，可以通过 dispatchers 配置 event 分发器，支持 default、ts、rowid、table 四种分发器，分发规则如下：

  • default：有多个唯一索引（包括主键）时按照 table 模式分发；只有一个唯一索引（或主键）按照 rowid 模式分发；如果开启了 old value 特性，按照 table 分发。
  • ts：以行变更的 commitTs 做 Hash 计算并进行 event 分发。
  • rowid：以所选的 HandleKey 列名和列值做 Hash 计算并进行 event 分发。
  • table：以表的 schema 名和 table 名做 Hash 计算并进行 event 分发。

matcher：匹配语法和过滤器规则语法相同。

protocol：对于 MQ 类的 Sink，可以指定消息的协议格式。目前支持 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，若请求失败，则返回错误信息和错误码。

删除同步任务

该接口是一个异步接口，请求成功会返回 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，若请求失败，则返回错误信息和错误码。

更新同步任务配置

该接口是一个异步接口，请求成功会返回 202 Accepted，它只代表服务器答应执行该命令，不保证命令会被成功的执行。

修改 changefeed 配置需要按照暂停任务 -> 修改配置 -> 恢复任务的流程。

请求 URI

PUT /api/v1/changefeeds/{changefeed_id}

参数说明

路径参数

参数名说明
changefeed_id需要更新的同步任务 (changefeed) 的 ID

请求体参数

目前仅支持通过 API 修改同步任务的如下配置。

参数名说明
target_tsUINT64 类型，指定 changefeed 的目标 TSO。（非必选）
sink_uriSTRING 类型，同步任务下游的地址。（非必选)
filter_rulesSTRING 类型数组，表库过滤的规则。（非必选）
ignore_txn_start_tsUINT64 类型数组，忽略指定 start_ts 的事务。 （非必选）
mounter_worker_numINT 类型，mounter 线程数。（非必选）
sink_configsink 的配置参数。（非必选）

以上参数含义与创建同步任务中的参数相同，此处不再赘述。

使用样例

以下请求会更新 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，若请求失败，则返回错误信息和错误码。

查询同步任务列表

该接口是一个同步接口，请求成功会返回 TiCDC 集群中所有同步任务 (changefeed) 的基本信息。

请求 URI

GET /api/v1/changefeeds

参数说明

查询参数

参数名说明
state非必选，指定后将会只返回该状态的同步任务的信息

state 可选值为 all、normal、stopped、error、failed、finished。

若不指定该参数，则默认返回处于 normal、stopped、failed 状态的同步任务基本信息。

使用样例

以下请求查询所有状态 (state) 为 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：同步任务当前 checkpoint 的 TSO 表示。
  • checkpoint_time：同步任务当前 checkpoint 的格式化时间表示。
  • error：同步任务的错误信息。

查询特定同步任务

该接口是一个同步接口，请求成功会返回指定同步任务 (changefeed) 的详细信息。

请求 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": {}
        }
    ]
}

暂停同步任务

该接口是一个异步接口，请求成功会返回 202 Accepted，它只代表服务器答应执行该命令，不保证命令会被成功的执行。

请求 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，若请求失败，则返回错误信息和错误码。

恢复同步任务

该接口是一个异步接口，请求成功会返回 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，若请求失败，则返回错误信息和错误码。

查询同步子任务列表

该接口是一个同步接口，请求成功会返回当前 TiCDC 集群中的所有同步子任务 (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"
    }
]

查询特定同步子任务

该接口是一个同步接口，请求成功会返回指定同步子任务 (processor) 的详细信息。

请求 URI

GET /api/v1/processors/{changefeed_id}/{capture_id}

参数说明

路径参数

参数名说明
changefeed_id需要查询的子任务的 Changefeed ID
capture_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 服务进程列表

该接口是一个同步接口，请求成功会返回当前 TiCDC 集群中的所有服务进程 (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"
    }
]

驱逐 owner 节点

该接口是一个异步的请求，请求成功会返回 202 Accepted，它只代表服务器答应执行该命令，不保证命令会被成功的执行。

请求 URI

POST /api/v1/owner/resign

使用样例

以下请求会驱逐 TiCDC 当前的 owner 节点，并会触发新一轮的选举，产生新的 owner 节点。

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

若是请求成功，则返回 202 Accepted，若请求失败，则返回错误信息和错误码。

手动触发表的负载均衡

该接口是一个异步的请求，请求成功会返回 202 Accepted它只代表服务器答应执行该命令，不保证命令会被成功的执行。

请求 URI

POST /api/v1/changefeeds/{changefeed_id}/tables/rebalance_table

参数说明

路径参数

参数名说明
changefeed_id进行调度的 Changefeed ID

使用样例

以下请求会触发 ID 为 test1 的 changefeed 表的负载均衡。

 curl -X POST http://127.0.0.1:8300/api/v1/changefeeds/test1/tables/rebalance_table

若是请求成功，则返回 202 Accepted，若请求失败，则返回错误信息和错误码。

手动调度表到其他节点

该接口是一个异步的请求，请求成功会返回 202 Accepted，它只代表服务器答应执行该命令，不保证命令会被成功的执行。

请求 URI

POST /api/v1/changefeeds/{changefeed_id}/tables/move_table

参数说明

路径参数

参数名说明
changefeed_id进行调度的 Changefeed ID

请求体参数

参数名说明
target_capture_id目标 Capture ID
table_id需要调度的 Table ID

使用样例

以下请求会将 ID 为 test1 的 changefeed 中 ID 为 49 的 table 调度到 ID 为 6f19a6d9-0f8c-4dc9-b299-3ba7c0f216f5 的 capture 上去。

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 Server 日志级别

该接口是一个同步接口，请求成功会返回 200 OK。

请求 URI

POST /api/v1/log

请求参数

请求体参数

参数名说明
log_level想要设置的日志等级

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

若是请求成功，则返回 200 OK，若请求失败，则返回错误信息和错误码。

下载 PDF