HTTP 参考

概述

DTM 可以通过HTTP协议交互。因为事务本身具有特殊性，它和普通的api调用只区分成功和失败不同，DTM的结果状态详情，请参考接口协议

接口主要分为三类： AP调用TM的接口、AP调用RM的接口、TM调用RM的接口。本文主要讲解AP调用TM的接口，其他两类接口参见dtm 架构

AP调用TM的接口

这部分接口的路径前缀为/api/dtmsvr。例如后面介绍的prepare，实际路径为/api/dtmsvr/prepare

这部分接口如果对事务状态进行变更，则dtm会对事务状态做相关的校验，有可能校验失败，而返回错误。以一个实际的例子说明：

如果调用prepare时，这个事务状态已经是failed，那么dtm将返回错误码409，错误内容：

  1. {
  2.     "dtm_result":"FAILURE",
  3.     "message":"current status 'failed', cannot prepare"
  4. }

每个接口的详细说明如下：

newGid 获取Gid

此接口用于获取gid。dtm的gid生成采用ip+snowflake。如果发生短时间内ip重用的情况，有极低概率发生gid重复情况。

因为几乎每个公司都会有自己的唯一id生成基础设置，建议在dtm中使用的gid，采用自己公司内部的唯一id生成算法。

接口名称 请求方法 请求格式 适用事务
newGid GET - -

请求示例

  1. curl 'localhost:36789/api/dtmsvr/newGid'

响应示例

  1. {
  2.     "dtm_result":"SUCCESS",
  3.     "gid":"c0a8038b_4nxAcyxSX8N"
  4. }

prepare 准备事务

此接口用于准备事务，正常情况下，后续将提交事务。

接口名称 请求方法 请求格式 适用事务
prepare POST JSON MSG, TCC, XA

请求示例

  1. curl --location --request POST 'localhost:36789/api/dtmsvr/prepare' \
  2. --header 'Content-Type: application/json' \
  3. --data-raw '{
  4.     "gid": "xxx",
  5.     "trans_type": "tcc"
  6. }'

响应示例

  1. {
  2.     "dtm_result":"SUCCESS"
  3. }

MSG 的prepare请求还会携带分支信息

MSG的prepare示例

请求示例

  1. curl --location --request POST 'localhost:36789/api/dtmsvr/prepare' \
  2. --header 'Content-Type: application/json' \
  3. --data-raw '{
  4.     "gid":"TestMsgTimeoutSuccess",
  5.     "trans_type":"msg",
  6.     "steps":[
  7.         {
  8.             "action":"http://localhost:8081/api/busi/TransOut"
  9.         },
  10.         {
  11.             "action":"http://localhost:8081/api/busi/TransIn"
  12.         }
  13.     ],
  14.     "payloads":[
  15.         "{\"amount\":30,\"transInResult\":\"SUCCESS\",\"transOutResult\":\"SUCCESS\"}",
  16.         "{\"amount\":30,\"transInResult\":\"SUCCESS\",\"transOutResult\":\"SUCCESS\"}"
  17.     ],
  18.     "query_prepared":"http://localhost:8081/api/busi/CanSubmit"
  19. }'
  • steps 指定整个事务会分成多个步骤，每个步骤的正向操作url为action
  • payloads 表示每个步骤中进行http请求时的body
  • query_prepared 指定事务消息超时后进行查询的url

submit 提交事务

此接口用于提交全局事务

接口名称 请求方法 请求格式 适用事务
submit POST JSON MSG, SAGA, TCC, XA

请求示例

  1. curl --location --request POST 'localhost:36789/api/dtmsvr/submit' \
  2. --header 'Content-Type: application/json' \
  3. --data-raw '{
  4.     "gid": "xxx",
  5.     "trans_type": "tcc"
  6. }'

响应示例

  1. {
  2.     "dtm_result":"SUCCESS"
  3. }

其中MSG和SAGA的submit还会携带分支信息

MSG的submit示例

请求示例

  1. curl --location --request POST 'localhost:36789/api/dtmsvr/submit' \
  2. --header 'Content-Type: application/json' \
  3. --data-raw '{
  4.     "gid":"TestMsgNormal",
  5.     "trans_type":"msg",
  6.     "steps":[
  7.         {
  8.             "action":"http://localhost:8081/api/busi/TransOut"
  9.         },
  10.         {
  11.             "action":"http://localhost:8081/api/busi/TransIn"
  12.         }
  13.     ],
  14.     "payloads":[
  15.         "{\"amount\":30,\"transInResult\":\"SUCCESS\",\"transOutResult\":\"SUCCESS\"}",
  16.         "{\"amount\":30,\"transInResult\":\"SUCCESS\",\"transOutResult\":\"SUCCESS\"}"
  17.     ]
  18. }'

详细字段含义见上述MSG的prepare示例

SAGA的submit示例

请求示例

  1. curl --location --request POST 'localhost:36789/api/dtmsvr/submit' \
  2. --header 'Content-Type: application/json' \
  3. --data-raw '{
  4.     "gid":"TestSagaNormal",
  5.     "trans_type":"saga",
  6.     "steps":[
  7.         {
  8.             "action":"http://localhost:8081/api/busi/TransOut",
  9.             "compensate":"http://localhost:8081/api/busi/TransOutRevert"
  10.         },
  11.         {
  12.             "action":"http://localhost:8081/api/busi/TransIn",
  13.             "compensate":"http://localhost:8081/api/busi/TransInRevert"
  14.         }
  15.     ],
  16.     "payloads":[
  17.         "{\"amount\":30,\"transInResult\":\"SUCCESS\",\"transOutResult\":\"SUCCESS\"}",
  18.         "{\"amount\":30,\"transInResult\":\"SUCCESS\",\"transOutResult\":\"SUCCESS\"}"
  19.     ]
  20. }'
  • steps 指定整个事务会分成多个步骤，每个步骤的正向操作url为action，补偿操作url为compensate
  • payloads 每个步骤http请求的body

abort 回滚事务

此接口用于回滚全局事务

接口名称 请求方法 请求格式 适用事务
abort POST JSON TCC, XA

请求示例

  1. curl --location --request POST 'localhost:36789/api/dtmsvr/abort' \
  2. --header 'Content-Type: application/json' \
  3. --data-raw '{
  4.     "gid": "xxx",
  5.     "trans_type": "tcc"
  6. }'

响应示例

  1. {
  2.     "dtm_result":"SUCCESS"
  3. }

registerBranch

此接口用于TCC, XA事务模式中，注册事务分支

接口名称 请求方法 请求格式 适用事务
registerBranch POST JSON XA TCC

注册XA分支请求示例

  1. curl --location --request POST 'localhost:36789/api/dtmsvr/registerBranch' \
  2. --header 'Content-Type: application/json' \
  3. --data-raw '{
  4.     "branch_id":"0101",
  5.     "gid":"c0a8038b_4nxEEB1M7K3",
  6.     "trans_type":"xa",
  7.     "url":"http://localhost:8081/api/busi/xa"
  8. }'
  • url: xa事务模式最后进行commit/rollback的服务地址

注册TCC分支请求示例

  1. curl --location --request POST 'localhost:36789/api/dtmsvr/registerTccBranch' \
  2. --header 'Content-Type: application/json' \
  3. --data-raw '{
  4.     "branch_id":"01",
  5.     "cancel":"http://localhost:8081/api/busi/TransOutRevert",
  6.     "confirm":"http://localhost:8081/api/busi/TransOutConfirm",
  7.     "data":"{\"amount\":30,\"transInResult\":\"\",\"transOutResult\":\"\"}",
  8.     "gid":"c0a8038b_4nxEEGy7W5h",
  9.     "trans_type":"tcc"
  10. }'
  • cancel：指定cancel操作的url
  • confirm：指定confirm操作的url
  • data：调用cancel/confirm时需要传递的body

响应示例

  1. {
  2.     "dtm_result":"SUCCESS"
  3. }

query 查询事务

此接口用于查询指定gid的事务。

接口名称 请求方法 请求格式 适用事务
query GET - -

请求示例

  1. curl 'localhost:36789/api/dtmsvr/query?gid=xxx'

成功响应示例

  1. {
  2.     "branches":[
  3.     ],
  4.     "transaction":{
  5.         "ID":69,
  6.         "CreateTime":"2021-10-25T08:51:27+08:00",
  7.         "UpdateTime":"2021-10-25T08:51:39+08:00",
  8.         "gid":"xxx",
  9.         "trans_type":"tcc",
  10.         "data":"",
  11.         "status":"failed",
  12.         "query_prepared":"",
  13.         "protocol":"http",
  14.         "CommitTime":null,
  15.         "FinishTime":null,
  16.         "RollbackTime":"2021-10-25T08:51:39+08:00",
  17.         "Options":"{}",
  18.         "NextCronInterval":10,
  19.         "NextCronTime":"2021-10-25T08:51:49+08:00"
  20.     }
  21. }

未找到gid的响应示例

  1. {
  2.     "branches":[
  3.     ],
  4.     "transaction":null
  5. }

all 批量查询事务

此接口用于批量查询事务。dtm将返回id小于last_id，按照id从大到小排序的100条数据

接口名称 请求方法 请求格式 适用事务
all GET - -

请求示例

  1. curl 'localhost:36789/api/dtmsvr/all?last_id='

参数last_id: 上一次请求返回数据的最小id。

成功响应示例

  1. {
  2.     "transactions":[
  3.         {
  4.             "ID":69,
  5.             "CreateTime":"2021-10-25T08:51:27+08:00",
  6.             "UpdateTime":"2021-10-25T08:51:39+08:00",
  7.             "gid":"xxx",
  8.             "trans_type":"tcc",
  9.             "data":"",
  10.             "status":"failed",
  11.             "query_prepared":"",
  12.             "protocol":"http",
  13.             "CommitTime":null,
  14.             "FinishTime":null,
  15.             "RollbackTime":"2021-10-25T08:51:39+08:00",
  16.             "Options":"{}",
  17.             "NextCronInterval":10,
  18.             "NextCronTime":"2021-10-25T08:51:49+08:00"
  19.         }
  20.     ]
  21. }

空响应示例

  1. {
  2.     "transactions":[
  3.     ]
  4. }

事务选项

事务支持以下选项，具体含义参加事务选项文档：

  • wait_result: 等待事务结果
  • retry_interval: 重试间隔
  • timeout_to_fail: 超时失败时间
  • branch_headers: 自定义header

这些事务选项可以在prepare/submit请求中，发送给TM，请求示例

  1. curl --location --request POST 'localhost:36789/api/dtmsvr/prepare' \
  2. --header 'Content-Type: application/json' \
  3. --data-raw '{
  4.     "gid": "xxx",
  5.     "trans_type": "tcc",
  6.     "wait_result": true,
  7.     "retry_interval": 15,
  8.     "branch_headers":{"test_header":"test"},
  9.     "timeout_to_fail": 60
  10. }'

响应示例

  1. {
  2.     "dtm_result":"SUCCESS"
  3. }