使用 OpenAPI 运维集群

使用 OpenAPI 运维集群

DM 提供 OpenAPI 功能，您可以通过 OpenAPI 方便地对 DM 集群进行查询和运维操作。OpenAPI 的功能范围和 dmctl 工具相当。如需开启 OpenAPI，请在 DM-master 的配置文件中增加如下配置项：

1. openapi = true

注意：

DM 提供符合 OpenAPI 3.0.0 标准的 Spec 文档，其中包含了所有 API 的请求参数和返回体，你可自行复制到如 Swagger Editor 等工具中在线预览文档。

部署 DM-master 后，你可访问 http://{master-addr}/api/v1/docs 在线预览文档。

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

数据源相关 API

创建数据源
获取数据源列表
删除数据源
获取数据源状态
对数据源开启 relay-log 功能
对数据源停止 relay-log 功能
对数据源暂停 relay-log 功能
对数据源恢复 relay-log 功能
更改数据源和 DM-worker 的绑定关系
获取数据源的数据库名列表
获取数据源的指定数据库的表名列表

同步任务相关 API

创建同步任务
获取同步任务列表
停止同步任务
获取同步任务状态
暂停同步任务
恢复同步任务
获取同步任务关联数据源的数据库名列表
获取同步任务关联数据源的数据表名列表
获取同步任务关联数据源的数据表的创建语句
更新同步任务关联数据源的数据表的创建语句
删除同步任务关联数据源的数据表

本文档以下部分描述当前提供的 API 的具体使用方法。

API 统一错误格式

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

1. {
2. "error_msg": "",
3. "error_code": ""
4. }

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

获取 DM-master 节点信息

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

请求 URI

GET /api/v1/cluster/masters

使用样例

1. curl -X 'GET' \
2. 'http://127.0.0.1:8261/api/v1/cluster/masters' \
3. -H 'accept: application/json'

1. {
2. "total": 1,
3. "data": [
4. {
5. "name": "master1",
6. "alive": true,
7. "leader": true,
8. "addr": "127.0.0.1:8261"
9. }
10. ]
11. }

下线 DM-master 节点

该接口是一个同步接口，请求成功后返回体的 Status Code 是 204。

请求 URI

DELETE /api/v1/cluster/masters/{master-name}

使用样例

1. curl -X 'DELETE' \
2. 'http://127.0.0.1:8261/api/v1/cluster/masters/master1' \
3. -H 'accept: */*'

获取 DM-worker 节点信息

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

请求 URI

GET /api/v1/cluster/workers

使用样例

1. curl -X 'GET' \
2. 'http://127.0.0.1:8261/api/v1/cluster/workers' \
3. -H 'accept: application/json'

1. {
2. "total": 1,
3. "data": [
4. {
5. "name": "worker1",
6. "addr": "127.0.0.1:8261",
7. "bound_stage": "bound",
8. "bound_source_name": "mysql-01"
9. }
10. ]
11. }

下线 DM-worker 节点

该接口是一个同步接口，请求成功后返回体的 Status Code 是 204。

请求 URI

DELETE /api/v1/cluster/workers/{worker-name}

使用样例

1. curl -X 'DELETE' \
2. 'http://127.0.0.1:8261/api/v1/cluster/workers/worker1' \
3. -H 'accept: */*'

创建数据源

该接口是一个同步接口，请求成功会返回对应数据源信息。

请求 URI

POST /api/v1/sources

使用样例

1. curl -X 'POST' \
2. 'http://127.0.0.1:8261/api/v1/sources' \
3. -H 'accept: application/json' \
4. -H 'Content-Type: application/json' \
5. -d '{
6. "source_name": "mysql-01",
7. "host": "127.0.0.1",
8. "port": 3306,
9. "user": "root",
10. "password": "123456",
11. "enable_gtid": false,
12. "security": {
13. "ssl_ca_content": "",
14. "ssl_cert_content": "",
15. "ssl_key_content": "",
16. "cert_allowed_cn": [
17. "string"
18. ]
19. },
20. "purge": {
21. "interval": 3600,
22. "expires": 0,
23. "remain_space": 15
24. }
25. }'

1. {
2. "source_name": "mysql-01",
3. "host": "127.0.0.1",
4. "port": 3306,
5. "user": "root",
6. "password": "123456",
7. "enable_gtid": false,
8. "security": {
9. "ssl_ca_content": "",
10. "ssl_cert_content": "",
11. "ssl_key_content": "",
12. "cert_allowed_cn": [
13. "string"
14. ]
15. },
16. "purge": {
17. "interval": 3600,
18. "expires": 0,
19. "remain_space": 15
20. },
21. "status_list": [
22. {
23. "source_name": "mysql-replica-01",
24. "worker_name": "worker-1",
25. "relay_status": {
26. "master_binlog": "(mysql-bin.000001, 1979)",
27. "master_binlog_gtid": "e9a1fc22-ec08-11e9-b2ac-0242ac110003:1-7849",
28. "relay_dir": "./sub_dir",
29. "relay_binlog_gtid": "e9a1fc22-ec08-11e9-b2ac-0242ac110003:1-7849",
30. "relay_catch_up_master": true,
31. "stage": "Running"
32. },
33. "error_msg": "string"
34. }
35. ]
36. }

获取数据源列表

该接口是一个同步接口，请求成功会返回数据源列表信息。

请求 URI

GET /api/v1/sources

使用样例

1. curl -X 'GET' \
2. 'http://127.0.0.1:8261/api/v1/sources?with_status=true' \
3. -H 'accept: application/json'

1. {
2. "data": [
3. {
4. "enable_gtid": false,
5. "host": "127.0.0.1",
6. "password": "******",
7. "port": 3306,
8. "purge": {
9. "expires": 0,
10. "interval": 3600,
11. "remain_space": 15
12. },
13. "security": null,
14. "source_name": "mysql-01",
15. "user": "root"
16. },
17. {
18. "enable_gtid": false,
19. "host": "127.0.0.1",
20. "password": "******",
21. "port": 3307,
22. "purge": {
23. "expires": 0,
24. "interval": 3600,
25. "remain_space": 15
26. },
27. "security": null,
28. "source_name": "mysql-02",
29. "user": "root"
30. }
31. ],
32. "total": 2
33. }

删除数据源

该接口是一个同步接口，请求成功后返回体的 Status Code 是 204。

请求 URI

DELETE /api/v1/sources/{source-name}

使用样例

1. curl -X 'DELETE' \
2. 'http://127.0.0.1:8261/api/v1/sources/mysql-01?force=true' \
3. -H 'accept: application/json'

获取数据源状态

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

请求 URI

GET /api/v1/sources/{source-name}/status

使用样例

1. curl -X 'GET' \
2. 'http://127.0.0.1:8261/api/v1/sources/mysql-replica-01/status' \
3. -H 'accept: application/json'

1. {
2. "total": 1,
3. "data": [
4. {
5. "source_name": "mysql-replica-01",
6. "worker_name": "worker-1",
7. "relay_status": {
8. "master_binlog": "(mysql-bin.000001, 1979)",
9. "master_binlog_gtid": "e9a1fc22-ec08-11e9-b2ac-0242ac110003:1-7849",
10. "relay_dir": "./sub_dir",
11. "relay_binlog_gtid": "e9a1fc22-ec08-11e9-b2ac-0242ac110003:1-7849",
12. "relay_catch_up_master": true,
13. "stage": "Running"
14. },
15. "error_msg": "string"
16. }
17. ]
18. }

对数据源开启 relay-log 功能

这是一个异步接口，请求成功的 Status Code 是 200，可通过获取数据源状态接口获取最新的状态。

请求 URI

POST /api/v1/sources/{source-name}/start-relay

使用样例

1. curl -X 'POST' \
2. 'http://127.0.0.1:8261/api/v1/sources/mysql-01/start-relay' \
3. -H 'accept: */*' \
4. -H 'Content-Type: application/json' \
5. -d '{
6. "worker_name_list": [
7. "worker-1"
8. ],
9. "relay_binlog_name": "mysql-bin.000002",
10. "relay_binlog_gtid": "e9a1fc22-ec08-11e9-b2ac-0242ac110003:1-7849",
11. "relay_dir": "./relay_log"
12. }'

对数据源停止 relay-log 功能

这是一个异步接口，请求成功的 Status Code 是 200，可通过获取数据源状态接口获取最新的状态。

请求 URI

POST /api/v1/sources/{source-name}/stop-relay

使用样例

1. curl -X 'POST' \
2. 'http://127.0.0.1:8261/api/v1/sources/mysql-01/stop-relay' \
3. -H 'accept: */*' \
4. -H 'Content-Type: application/json' \
5. -d '{
6. "worker_name_list": [
7. "worker-1"
8. ]
9. }'

对数据源暂停 relay-log 功能

这是一个异步接口，请求成功的 Status Code 是 200，可通过获取数据源状态接口获取最新的状态。

请求 URI

POST /api/v1/sources/{source-name}/pause-relay

使用样例

1. curl -X 'POST' \
2. 'http://127.0.0.1:8261/api/v1/sources/mysql-01/pause-relay' \
3. -H 'accept: */*'

对数据源恢复 relay-log 功能

这是一个异步接口，请求成功的 Status Code 是 200，可通过获取数据源状态接口获取最新的状态。

请求 URI

POST /api/v1/sources/{source-name}/resume-relay

使用样例

1. curl -X 'POST' \
2. 'http://127.0.0.1:8261/api/v1/sources/mysql-01/resume-relay' \
3. -H 'accept: */*'

更改数据源和 DM-worker 的绑定关系

这是一个异步接口，请求成功的 Status Code 是 200，可通过获取 DM-worker 节点信息接口获取最新的状态。

请求 URI

POST /api/v1/sources/{source-name}/transfer

使用样例

1. curl -X 'POST' \
2. 'http://127.0.0.1:8261/api/v1/sources/mysql-01/transfer' \
3. -H 'accept: */*' \
4. -H 'Content-Type: application/json' \
5. -d '{
6. "worker_name": "worker-1"
7. }'

获取数据源的数据库名列表

该接口是一个同步接口，请求成功会返回对应的列表。

请求 URI

GET /api/v1/sources/{source-name}/schemas

使用样例

1. curl -X 'GET' \
2. 'http://127.0.0.1:8261/api/v1/sources/source-1/schemas' \
3. -H 'accept: application/json'

1. [
2. "db1"
3. ]

获取数据源的指定数据库的表名列表

该接口是一个同步接口，请求成功会返回对应的列表。

请求 URI

GET /api/v1/sources/{source-name}/schemas/{schema-name}

使用样例

1. curl -X 'GET' \
2. 'http://127.0.0.1:8261/api/v1/sources/source-1/schemas/db1' \
3. -H 'accept: application/json'

1. [
2. "table1"
3. ]

创建同步任务

这是一个异步接口，请求成功的 Status Code 是 200，可通过获取同步任务状态接口获取最新的状态。

请求 URI

POST /api/v1/tasks

使用样例

1. curl -X 'POST' \
2. 'http://127.0.0.1:8261/api/v1/tasks' \
3. -H 'accept: application/json' \
4. -H 'Content-Type: application/json' \
5. -d '{
6. "remove_meta": false,
7. "task": {
8. "name": "task-1",
9. "task_mode": "all",
10. "shard_mode": "pessimistic",
11. "meta_schema": "dm-meta",
12. "enhance_online_schema_change": true,
13. "on_duplicate": "overwrite",
14. "target_config": {
15. "host": "127.0.0.1",
16. "port": 3306,
17. "user": "root",
18. "password": "123456",
19. "security": {
20. "ssl_ca_content": "",
21. "ssl_cert_content": "",
22. "ssl_key_content": "",
23. "cert_allowed_cn": [
24. "string"
25. ]
26. }
27. },
28. "binlog_filter_rule": {
29. "rule-1": {
30. "ignore_event": [
31. "all dml"
32. ],
33. "ignore_sql": [
34. "^Drop"
35. ]
36. },
37. "rule-2": {
38. "ignore_event": [
39. "all dml"
40. ],
41. "ignore_sql": [
42. "^Drop"
43. ]
44. },
45. "rule-3": {
46. "ignore_event": [
47. "all dml"
48. ],
49. "ignore_sql": [
50. "^Drop"
51. ]
52. }
53. },
54. "table_migrate_rule": [
55. {
56. "source": {
57. "source_name": "source-name",
58. "schema": "db-*",
59. "table": "tb-*"
60. },
61. "target": {
62. "schema": "db1",
63. "table": "tb1"
64. },
65. "binlog_filter_rule": [
66. "rule-1",
67. "rule-2",
68. "rule-3",
69. ]
70. }
71. ],
72. "source_config": {
73. "full_migrate_conf": {
74. "export_threads": 4,
75. "import_threads": 16,
76. "data_dir": "./exported_data",
77. "consistency": "auto"
78. },
79. "incr_migrate_conf": {
80. "repl_threads": 16,
81. "repl_batch": 100
82. },
83. "source_conf": [
84. {
85. "source_name": "mysql-replica-01",
86. "binlog_name": "binlog.000001",
87. "binlog_pos": 4,
88. "binlog_gtid": "03fc0263-28c7-11e7-a653-6c0b84d59f30:1-7041423,05474d3c-28c7-11e7-8352-203db246dd3d:1-170"
89. }
90. ]
91. }
92. },
93. "source_name_list": [
94. "source-1"
95. ]
96. }'

1. {
2. "name": "task-1",
3. "task_mode": "all",
4. "shard_mode": "pessimistic",
5. "meta_schema": "dm-meta",
6. "enhance_online_schema_change": true,
7. "on_duplicate": "overwrite",
8. "target_config": {
9. "host": "127.0.0.1",
10. "port": 3306,
11. "user": "root",
12. "password": "123456",
13. "security": {
14. "ssl_ca_content": "",
15. "ssl_cert_content": "",
16. "ssl_key_content": "",
17. "cert_allowed_cn": [
18. "string"
19. ]
20. }
21. },
22. "binlog_filter_rule": {
23. "rule-1": {
24. "ignore_event": [
25. "all dml"
26. ],
27. "ignore_sql": [
28. "^Drop"
29. ]
30. },
31. "rule-2": {
32. "ignore_event": [
33. "all dml"
34. ],
35. "ignore_sql": [
36. "^Drop"
37. ]
38. },
39. "rule-3": {
40. "ignore_event": [
41. "all dml"
42. ],
43. "ignore_sql": [
44. "^Drop"
45. ]
46. }
47. },
48. "table_migrate_rule": [
49. {
50. "source": {
51. "source_name": "source-name",
52. "schema": "db-*",
53. "table": "tb-*"
54. },
55. "target": {
56. "schema": "db1",
57. "table": "tb1"
58. },
59. "binlog_filter_rule": [
60. "rule-1",
61. "rule-2",
62. "rule-3",
63. ]
64. }
65. ],
66. "source_config": {
67. "full_migrate_conf": {
68. "export_threads": 4,
69. "import_threads": 16,
70. "data_dir": "./exported_data",
71. "consistency": "auto"
72. },
73. "incr_migrate_conf": {
74. "repl_threads": 16,
75. "repl_batch": 100
76. },
77. "source_conf": [
78. {
79. "source_name": "mysql-replica-01",
80. "binlog_name": "binlog.000001",
81. "binlog_pos": 4,
82. "binlog_gtid": "03fc0263-28c7-11e7-a653-6c0b84d59f30:1-7041423,05474d3c-28c7-11e7-8352-203db246dd3d:1-170"
83. }
84. ]
85. }
86. }

获取同步任务列表

该接口是一个同步接口，请求成功会返回对应的同步任务信息。

请求 URI

GET /api/v1/tasks

使用样例

1. curl -X 'GET' \
2. 'http://127.0.0.1:8261/api/v1/tasks' \
3. -H 'accept: application/json'

1. {
2. "total": 2,
3. "data": [
4. {
5. "name": "task-1",
6. "task_mode": "all",
7. "shard_mode": "pessimistic",
8. "meta_schema": "dm-meta",
9. "enhance_online_schema_change": true,
10. "on_duplicate": "overwrite",
11. "target_config": {
12. "host": "127.0.0.1",
13. "port": 3306,
14. "user": "root",
15. "password": "123456",
16. "security": {
17. "ssl_ca_content": "",
18. "ssl_cert_content": "",
19. "ssl_key_content": "",
20. "cert_allowed_cn": [
21. "string"
22. ]
23. }
24. },
25. "binlog_filter_rule": {
26. "rule-1": {
27. "ignore_event": [
28. "all dml"
29. ],
30. "ignore_sql": [
31. "^Drop"
32. ]
33. },
34. "rule-2": {
35. "ignore_event": [
36. "all dml"
37. ],
38. "ignore_sql": [
39. "^Drop"
40. ]
41. },
42. "rule-3": {
43. "ignore_event": [
44. "all dml"
45. ],
46. "ignore_sql": [
47. "^Drop"
48. ]
49. }
50. },
51. "table_migrate_rule": [
52. {
53. "source": {
54. "source_name": "source-name",
55. "schema": "db-*",
56. "table": "tb-*"
57. },
58. "target": {
59. "schema": "db1",
60. "table": "tb1"
61. },
62. "binlog_filter_rule": [
63. "rule-1",
64. "rule-2",
65. "rule-3",
66. ]
67. }
68. ],
69. "source_config": {
70. "full_migrate_conf": {
71. "export_threads": 4,
72. "import_threads": 16,
73. "data_dir": "./exported_data",
74. "consistency": "auto"
75. },
76. "incr_migrate_conf": {
77. "repl_threads": 16,
78. "repl_batch": 100
79. },
80. "source_conf": [
81. {
82. "source_name": "mysql-replica-01",
83. "binlog_name": "binlog.000001",
84. "binlog_pos": 4,
85. "binlog_gtid": "03fc0263-28c7-11e7-a653-6c0b84d59f30:1-7041423,05474d3c-28c7-11e7-8352-203db246dd3d:1-170"
86. }
87. ]
88. }
89. }
90. ]
91. }

停止同步任务

这是一个异步接口，请求成功的 Status Code 是 204，可通过获取同步任务状态接口获取最新的状态。

请求 URI

DELETE /api/v1/tasks/{task-name}

使用样例

1. curl -X 'DELETE' \
2. 'http://127.0.0.1:8261/api/v1/tasks/task-1' \
3. -H 'accept: */*'

获取同步任务状态

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

请求 URI

GET /api/v1/tasks/task-1/status

使用样例

1. curl -X 'GET' \
2. 'http://127.0.0.1:8261/api/v1/tasks/task-1/status?stage=running' \
3. -H 'accept: application/json'

1. {
2. "total": 1,
3. "data": [
4. {
5. "name": "string",
6. "source_name": "string",
7. "worker_name": "string",
8. "stage": "runing",
9. "unit": "sync",
10. "unresolved_ddl_lock_id": "string",
11. "load_status": {
12. "finished_bytes": 0,
13. "total_bytes": 0,
14. "progress": "string",
15. "meta_binlog": "string",
16. "meta_binlog_gtid": "string"
17. },
18. "sync_status": {
19. "total_events": 0,
20. "total_tps": 0,
21. "recent_tps": 0,
22. "master_binlog": "string",
23. "master_binlog_gtid": "string",
24. "syncer_binlog": "string",
25. "syncer_binlog_gtid": "string",
26. "blocking_ddls": [
27. "string"
28. ],
29. "unresolved_groups": [
30. {
31. "target": "string",
32. "ddl_list": [
33. "string"
34. ],
35. "first_location": "string",
36. "synced": [
37. "string"
38. ],
39. "unsynced": [
40. "string"
41. ]
42. }
43. ],
44. "synced": true,
45. "binlog_type": "string",
46. "seconds_behind_master": 0
47. }
48. }
49. ]
50. }

暂停同步任务

这是一个异步接口，请求成功的 Status Code 是 200，可通过获取同步任务状态接口获取最新的状态。

请求 URI

POST /api/v1/tasks/task-1/pause

使用样例

1. curl -X 'POST' \
2. 'http://127.0.0.1:8261/api/v1/tasks/task-1/pause' \
3. -H 'accept: */*' \
4. -H 'Content-Type: application/json' \
5. -d '[
6. "source-1"
7. ]'

恢复同步任务

这是一个异步接口，请求成功的 Status Code 是 200，可通过获取同步任务状态接口获取最新的状态。

请求 URI

POST /api/v1/tasks/task-1/resume

使用样例

1. curl -X 'POST' \
2. 'http://127.0.0.1:8261/api/v1/tasks/task-1/resume' \
3. -H 'accept: */*' \
4. -H 'Content-Type: application/json' \
5. -d '[
6. "source-1"
7. ]'

获取同步任务关联数据源的数据库名列表

该接口是一个同步接口，请求成功会返回对应的列表。

请求 URI

GET /api/v1/tasks/{task-name}/sources/{source-name}/schemas

使用样例

1. curl -X 'GET' \
2. 'http://127.0.0.1:8261/api/v1/tasks/task-1/sources/source-1/schemas' \
3. -H 'accept: application/json'

1. [
2. "db1"
3. ]

获取同步任务关联数据源的数据表名列表

该接口是一个同步接口，请求成功会返回对应的列表。

请求 URI

GET /api/v1/tasks/{task-name}/sources/{source-name}/schemas/{schema-name}

使用样例

1. curl -X 'GET' \
2. 'http://127.0.0.1:8261/api/v1/tasks/task-1/sources/source-1/schemas/db1' \
3. -H 'accept: application/json'

1. [
2. "table1"
3. ]

获取同步任务关联数据源的数据表的创建语句

该接口是一个同步接口，请求成功会返回对应的创建语句。

请求 URI

GET /api/v1/tasks/{task-name}/sources/{source-name}/schemas/{schema-name}/{table-name}

使用样例

1. curl -X 'GET' \
2. 'http://127.0.0.1:8261/api/v1/tasks/task-1/sources/source-1/schemas/db1/table1' \
3. -H 'accept: application/json'

1. {
2. "schema_name": "db1",
3. "table_name": "table1",
4. "schema_create_sql": "CREATE TABLE `t1` (`id` int(11) NOT NULL AUTO_INCREMENT,PRIMARY KEY (`id`) /*T![clustered_index] CLUSTERED */) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin"
5. }

更新同步任务关联数据源的数据表的创建语句

该接口是一个同步接口，返回体的 Status Code 是 200。

请求 URI

POST /api/v1/tasks/{task-name}/sources/{source-name}/schemas/{schema-name}/{table-name}

使用样例

1. curl -X 'PUT' \
2. 'http://127.0.0.1:8261/api/v1/tasks/task-1/sources/task-1/schemas/db1/table1' \
3. -H 'accept: */*' \
4. -H 'Content-Type: application/json' \
5. -d '{
6. "sql_content": "CREATE TABLE `t1` ( `c1` int(11) DEFAULT NULL, `c2` int(11) DEFAULT NULL, `c3` int(11) DEFAULT NULL) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin;",
7. "flush": true,
8. "sync": true
9. }'

删除同步任务关联数据源的数据表

该接口是一个同步接口，返回体的 Status Code 是 200。

请求 URI

DELETE /api/v1/tasks/{task-name}/sources/{source-name}/schemas/{schema-name}/{table-name}

使用样例

1. curl -X 'DELETE' \
2. 'http://127.0.0.1:8261/api/v1/tasks/task-1/sources/source-1/schemas/db1/table1' \
3. -H 'accept: */*'