快速上手
业务申请和安装络谱工具完成后,您可使用BROPTool将您的业务系统接入络谱平台。
为协助您快速接入测试,我们提供了2种不同的样例:
- API Demo:BROPTool API中各接口的代码调用实例,目的是展示每一个接口在业务系统中的调用方式:
- 存证简易流程:场景化描述了络谱系统写入存证信息的简易流程,目的是展示几组接口之间的使用关联,让读者能快速了解业务功能对接的流程。
API Demo
下载
您可从管理控制台菜单栏下载API Demo。
修改配置文件
打开API Demo,找到config路径下的ApplicationConfig.java文件,修改配置参数。
调用接口
运行接口,查看是否能调用成功。
若成功,可参考demo中方法实现每一个接口调用。请注意,demo仅为展示BROPTool接口调用方法,并不是代码编写规范。
存证简易流程
存证简易流程包含场景介绍、数据准备、预备知识以及实现存证业务的四组接口调用介绍。
场景介绍
设计了四个任务,完成写入存证和验证存证的功能闭环:
- 查询身份合约信息,收藏身份合约地址,用于后续接口
- 将自己加入存证合约白名单,获得写入存证信息权限
- 写入存证信息
- 查询存证信息,验证数据上链
假设:
- 步骤二只演示添加自己到白名单,实际业务中可添加任何一个身份合约
- 步骤四只为演示接口的使用,实际业务中一般由第三方验证数据上链
数据准备
本节描述了合作方在使用开发指南前,通过管理控制台、安全插件、BROPTool部署等获得的配置数据。
管理控制台:
- 身份代理合约的合约地址:
e99b9f4cfe7124d789d915e949d1bfc9733b544e
- 合作方身份合约的账户ID:
100000002
- 存证代理合约的合约地址:
c2d100f42e4ed3d9cea639ce3db9211cfe3f3824
- 存证专区编号(专区链需要使用):
0x000000000000047f000000005c7e384f00000000
安全插件:
- 安全插件服务地址:HSM_HOST
- 合作方使用安全插件生成密钥时使用的
userId
,通过该userId调用私钥进行签名上链:enterpriseUser
BROPTool:
- 中间件服务地址:BROP_HOST;PORT默认为9999。
预备知识
若您对下述接口调用存在疑问,可先查看 预备知识 了解区块链开发特定知识。
任务一:查询身份合约信息
根据合作方的账户ID,获得身份合约的详细信息,其中身份合约地址在后续任务中会用到。
第一步:用账户ID获得身份合约的合约地址
调用身份代理合约的getAccountAddressByAccountId方法, 根据账户ID获得该身份合约的合约地址。
请求地址(POST):http://BROP_HOST:PORT/common/contract.json
请求Body:
{
"regionId": "0x000000000000047f000000005c7e384f00000000",// 专区编号,使用专区链的时候需要传该参数
"contractAddress": "e99b9f4cfe7124d789d915e949d1bfc9733b544e",// 身份代理合约的合约地址
"functionName": "getAccountAddressByAccountId",
"params": [
100000002
]
}
返回结果:
{
"code": "SUCCESS",
"detail": {
"accountAddress": "45865da5c7013d0e5b5074fc98850ed2c8a725f1"
}
}
其中accountAddress就是身份合约的合约地址。
第二步:用身份合约的合约地址获取身份信息
调用身份合约的getAccountDetail方法,得到身份信息。本步骤不影响后续任务。
请求地址(POST):http://BROP_HOST:PORT/common/contract.json
请求Body:
{
"regionId": "0x000000000000047f000000005c7e384f00000000",// 专区编号,使用专区链的时候需要传该参数
"contractAddress": "45865da5c7013d0e5b5074fc98850ed2c8a725f1",// 身份合约的合约地址
"functionName": "getAccountDetail",
"params": []
}
返回结果:
{
"code": "SUCCESS",
"detail": {
"contractDigest": "1234",
"accountInfo": "",
"accountId": 100000002,
"publicKeyAddresses": [
"a5f4cd76e3f5d947a8823e312b3e0af8c78f70aa"
],
"recordPermission": true,
"credentialPermission": true,
"accountName": "zcTEST",
"accountPermission": true,
"certificate": "",
"authType": "REALNAME"
}
}
返回结果是身份信息,具体字段的解释请参考 BROPTool API -> 业务接口 -> 身份业务接口 章节。
任务二:将自己加入存证合约白名单
加入白名单,获得该存证合约的写入存证记录权限。
第一步:获取当前区块链的块号
请求地址(GET):http://BROP_HOST:PORT/common/blockNumber.json
返回结果:
{
"code": "SUCCESS",
"detail": 595469
}
第二步:数据上链(新增白名单用户)
方式1
1:生成上链数据的待签名原文
请求地址(POST):http://BROP_HOST:PORT/common/buildSendInfo.json
请求Body:
{
"regionId": "0x000000000000047f000000005c7e384f00000000",// 专区编号,使用专区链的时候需要传该参数
"blockLimit": 595818,//上一步结果+等待块数(一般为10)
"method": "addUserToWhiteList",
"bizId": "429558012568311",
"contractAddress": "c2d100f42e4ed3d9cea639ce3db9211cfe3f3824", // 存证代理合约的合约地址
"params": [
"61887b928c43e9d8bf324c189a60fa06359a3741",// 存证合约的合约地址
100000002//加入白名单的身份合约的账户ID
]
}
返回结果:
{
"code": "SUCCESS",
"detail": "da665a367aec13f1a63ff7aa699aa1a39957f23dddfa4d028137631cdfd6e279"
}
返回的 detail 就是待签名原文,下面会用到。
2:用账户 100000002 的私钥对待签原文进行签名
请求地址(GET):http://HSM_HOST:PORT/hsmServer/crypt/sign.json?userId=enterpriseUser&messageHash=da665a367aec13f1a63ff7aa699aa1a39957f23dddfa4d028137631cdfd6e279
其中,合作方使用安全插件生成账户100000002的密钥时使用的userId为enterpriseUser。
返回结果:
{
"code": "SUCCESS",
"detail": "GydcwLwmB41ULOoP0NKy/9oyTwSsUUBw23FI3jDQYQX4ddo18xblwmBkH72gHzUoNRabbZWD/koEpNaIvQh95v4="
}
返回的 detail 是已签名数据。
3:数据上链(新增白名单用户)
请求地址(POST):http://BROP_HOST:PORT/common/sendTx.json
请求Body:
{
"regionId": "0x000000000000047f000000005c7e384f00000000",// 专区编号,使用专区链的时候需要传该参数
"blockLimit": 595818,
"method": "addUserToWhiteList",
"bizId": "421402112788194",
"contractAddress": "c2d100f42e4ed3d9cea639ce3db9211cfe3f3824",
"signatureInBase64": "GydcwLwmB41ULOoP0NKy/9oyTwSsUUBw23FI3jDQYQX4ddo18xblwmBkH72gHzUoNRabbZWD/koEpNaIvQh95v4=",//第三步返回的签名数据
"params": [
"61887b928c43e9d8bf324c189a60fa06359a3741",
100000002
]
}
返回结果:
{
"code": "SUCCESS",
"detail": "e65d510fcbad0af8bd2140620016609bbc38eed7b294eacedca89a75650785a6"
}
返回的 detail 是txHash
。
方式2
请求地址(POST):http://BROP_HOST:PORT/transaction/sendTransaction.json
请求Body:
{
"regionId": "0x000000000000047f000000005c7e384f00000000",// 专区编号,使用专区链的时候需要传该参数
"blockLimit": 595818,//上一步结果+等待块数(一般为10)
"method": "addUserToWhiteList",
"bizId": "429558012568311",
"contractAddress": "c2d100f42e4ed3d9cea639ce3db9211cfe3f3824", // 存证代理合约的合约地址
"params": [
"61887b928c43e9d8bf324c189a60fa06359a3741",// 存证合约的合约地址
100000002//加入白名单的身份合约的账户ID
],
"hsmUserId": "enterpriseUser"// 加密机用户索引
}
返回结果:
{
"code": "SUCCESS",
"detail": "e65d510fcbad0af8bd2140620016609bbc38eed7b294eacedca89a75650785a6"
}
返回的 detail 是txHash
。
任务三:写入存证信息
使用已加入白名单的账户100000002
,向存证合约写入信息。
第一步:获取当前区块链的块号
参考任务二的第一步。
第二步:数据上链(写入存证信息)
方式1
1:生成上链数据的待签名原文
请求地址(POST):http://BROP_HOST:PORT/common/buildSendInfo.json
请求Body:
{
"regionId": "0x000000000000047f000000005c7e384f00000000",// 专区编号,使用专区链的时候需要传该参数
"blockLimit":596743, // 上一步结果+等待块数(一般为10)
"method":"createRecord",
"bizId":"432423430387376",
"contractAddress":"c2d100f42e4ed3d9cea639ce3db9211cfe3f3824", // 存证代理合约的合约地址
"params":[
"61887b928c43e9d8bf324c189a60fa06359a3741", // 存证合约的合约地址
"test7778836871878", // 存证流水号
"", // 前序存证流水号,此处为空
"f2f9184ae540fb779a671dd2dce0e562d919fa28f3b66e25d68ca4fc14b0945b", // 存证信息
"test", // 自定义字段
"45865da5c7013d0e5b5074fc98850ed2c8a725f1" // 调用者身份合约地址
]
}
返回结果:
{
"code": "SUCCESS",
"detail": "286c6e6d777dbaaf09b892118496c8ca5f28671bcfeb22057ef53ebd26b7acf7"
}
返回的 detail 就是待签名原文,下面会用到。
2:用账户100000002的私钥对待签原文进行签名
请求地址(GET):http:// HSM_HOST:PORT /hsmServer/crypt/sign.json?userId=enterpriseUser&messageHash=286c6e6d777dbaaf09b892118496c8ca5f28671bcfeb22057ef53ebd26b7acf7
返回结果:
{
"code": "SUCCESS",
"detail": "G9i6OX0Y8zLD29x/ii3K/un9tozYqFlptN/FrV1ffG0wFpBWknDs2XPLyl2uMv9ddoSmFcoM3/TfkAOyRKfjMgM="
}
返回的 detail 是已签名数据。
3:数据上链(写入存证信息)
请求地址(POST):http://BROP_HOST:PORT/common/sendTx.json
请求Body:
{
"regionId": "0x000000000000047f000000005c7e384f00000000",// 专区编号,使用专区链的时候需要传该参数
"blockLimit": 596743,
"method": "createRecord",
"bizId": "424774206589462",
"contractAddress": "c2d100f42e4ed3d9cea639ce3db9211cfe3f3824",
"signatureInBase64": "G9i6OX0Y8zLD29x/ii3K/un9tozYqFlptN/FrV1ffG0wFpBWknDs2XPLyl2uMv9ddoSmFcoM3/TfkAOyRKfjMgM=",
"params": [
"61887b928c43e9d8bf324c189a60fa06359a3741",
"test7778836871878",
"",
"f2f9184ae540fb779a671dd2dce0e562d919fa28f3b66e25d68ca4fc14b0945b",
"test",
"45865da5c7013d0e5b5074fc98850ed2c8a725f1"
]
}
返回结果:
{
"code": "SUCCESS",
"detail": "a054b8164786bf3ea06840357787fe34b9514fa7cc68f99fa433877fd16ee31c"
}
返回的 detail 是 txHash(存证号)。
方式2
请求地址(POST):http://BROP_HOST:PORT/transaction/sendTransaction.json
请求Body:
{
"regionId": "0x000000000000047f000000005c7e384f00000000",// 专区编号,使用专区链的时候需要传该参数
"blockLimit":596743, // 上一步结果+等待块数(一般为10)
"method":"createRecord",
"bizId":"432423430387376",
"contractAddress":"c2d100f42e4ed3d9cea639ce3db9211cfe3f3824", // 存证代理合约的合约地址
"params":[
"61887b928c43e9d8bf324c189a60fa06359a3741", // 存证合约的合约地址
"test7778836871878", // 存证流水号
"", // 前序存证流水号,此处为空
"f2f9184ae540fb779a671dd2dce0e562d919fa28f3b66e25d68ca4fc14b0945b", // 存证信息
"test", // 自定义字段
"45865da5c7013d0e5b5074fc98850ed2c8a725f1" // 调用者身份合约地址
]
"hsmUserId": "enterpriseUser"// 加密机用户索引
}
返回结果:
{
"code": "SUCCESS",
"detail": "a054b8164786bf3ea06840357787fe34b9514fa7cc68f99fa433877fd16ee31c"
}
返回的 detail 是 txHash(存证号)。
第三步:用txHash(存证号)获取交易信息
由于区块链数据同步有一定延迟,所以此方法会有3秒左右的延迟,建议使用监听区块链事件的消息队列来替代。
请求地址(POST):http://BROP_HOST:PORT/transaction/getDBTransactionByTxHash.json
请求Body:
{
"txHash": "a054b8164786bf3ea06840357787fe34b9514fa7cc68f99fa433877fd16ee31c"// 存证号
}
返回结果:
{
"code": "SUCCESS",
"detail": {
"transaction": {
"txHash": "8145994901f5502350845cd65c69abf1e459e905711e044d77f7e1ff4054e5ae",
"bizId": "27166825700357261012445867",
"sender": "b416ec0250b842aaa3e9c3a210fcdec9e23b0b1e",
"resultCode": 0,
"blockNumber": 960198,
"blockTime": "2018-03-29T19:30:49+08:00",
"dataSnapshots": [
{
"contractAddress": "62a4e077cd237020566645ab5131662da6ebf57f",
"contractName": "Record",
"operateType": "CREATE",
"contractData": {
"updatorAddress": "a99489f927cf9ea7e1e0c3a83fbbc79ddfa91ada",
"registryAddress": "f2895d25b84682f1f5167800176488d6d95d8597",
"preSeqId": "seqid2716678840849366",
"bizId": "27166825700357261012445867",
"contractAddress": "62a4e077cd237020566645ab5131662da6ebf57f",
"recordData": "123",
"creatorAddress": "a99489f927cf9ea7e1e0c3a83fbbc79ddfa91ada",
"seqId": "seqid2716682570029416",
"customString": "456"
}
}
]
}
}
}
向存证合约中写一条存证记录,区块链上会生成一个存证记录合约,可通过返回的contractAddress (存证记录合约地址)进行查询。详细查看任务四。
任务四:查询存证信息
根据存证记录合约地址查询存证记录。
获取存证记录合约的信息
请求地址(POST):http://BROP_HOST:PORT/common/contract.json
请求Body:
{
"regionId": "0x000000000000047f000000005c7e384f00000000",// 专区编号,使用专区链的时候需要传该参数
"functionName": "getData",
"contractAddress": "a4f528f949c1ed39671da722d0324d6e82657bee",
"params": []
}
返回结果:
{
"code": "SUCCESS",
"detail": {
"preSeqId": "",
"recordData": "f2f9184ae540fb779a671dd2dce0e562d919fa28f3b66e25d68ca4fc14b0945b",
"seqId": "test7778836871878",
"customString": "test"
}
}
字段包括 seqId
, preSeqId
, recordData
, customString
,具体参考 BROPTool API -> 业务接口 -> 存证业务接口 说明。