快速上手

业务申请和安装络谱工具完成后,您可使用BROPTool将您的业务系统接入络谱平台。

为协助您快速接入测试,我们提供了2种不同的样例:

  • API Demo:BROPTool API中各接口的代码调用实例,目的是展示每一个接口在业务系统中的调用方式:
  • 存证简易流程:场景化描述了络谱系统写入存证信息的简易流程,目的是展示几组接口之间的使用关联,让读者能快速了解业务功能对接的流程。

API Demo

下载

您可从管理控制台菜单栏下载API Demo。

修改配置文件

打开API Demo,找到config路径下的ApplicationConfig.java文件,修改配置参数。

调用接口

运行接口,查看是否能调用成功。

若成功,可参考demo中方法实现每一个接口调用。请注意,demo仅为展示BROPTool接口调用方法,并不是代码编写规范。

存证简易流程

存证简易流程包含场景介绍、数据准备、预备知识以及实现存证业务的四组接口调用介绍。

场景介绍

设计了四个任务,完成写入存证和验证存证的功能闭环:

  1. 查询身份合约信息,收藏身份合约地址,用于后续接口
  2. 将自己加入存证合约白名单,获得写入存证信息权限
  3. 写入存证信息
  4. 查询存证信息,验证数据上链

假设:

  1. 步骤二只演示添加自己到白名单,实际业务中可添加任何一个身份合约
  2. 步骤四只为演示接口的使用,实际业务中一般由第三方验证数据上链

数据准备

本节描述了合作方在使用开发指南前,通过管理控制台、安全插件、BROPTool部署等获得的配置数据。

管理控制台:

  1. 身份代理合约的合约地址:e99b9f4cfe7124d789d915e949d1bfc9733b544e
  2. 合作方身份合约的账户ID:100000002
  3. 存证代理合约的合约地址:c2d100f42e4ed3d9cea639ce3db9211cfe3f3824

安全插件:

  1. 安全插件服务地址:HSM_HOST
  2. 合作方使用安全插件生成密钥时使用的userId,通过该userId调用私钥进行签名上链:enterpriseUser

BROPTool:

  1. 中间件服务地址:BROP_HOST;PORT默认为9999。

预备知识

若您对下述接口调用存在疑问,可先查看 预备知识 了解区块链开发特定知识。

任务一:查询身份合约信息

根据合作方的账户ID,获得身份合约的详细信息,其中身份合约地址在后续任务中会用到。

第一步:用账户ID获得身份合约的合约地址

调用身份代理合约的getAccountAddressByAccountId方法, 根据账户ID获得该身份合约的合约地址。

请求地址(POST):http://BROP_HOST:PORT/common/contract.json

请求Body:

{
  "contractAddress": "e99b9f4cfe7124d789d915e949d1bfc9733b544e",// 身份代理合约的合约地址
  "functionName": "getAccountAddressByAccountId",
  "params": [
    100000002
  ]
}

返回结果:

{
  "code": "SUCCESS",
  "detail": {
    "accountAddress": "45865da5c7013d0e5b5074fc98850ed2c8a725f1"
  }
}

其中accountAddress就是身份合约的合约地址。

第二步:用身份合约的合约地址获取身份信息

调用身份合约的getAccountDetail方法,得到身份信息。本步骤不影响后续任务。

请求地址(POST):http://BROP_HOST:PORT/common/contract.json

请求Body:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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秒左右的延迟,建议使用监听区块链事件的消息队列来替代。

请求地址(GET):

http://BROP_HOST:PORT/transaction/a054b8164786bf3ea06840357787fe34b9514fa7cc68f99fa433877fd16ee31c.json

其中,a054b8164786bf3ea06840357787fe34b9514fa7cc68f99fa433877fd16ee31c为 txHash(存证号)

返回结果:

{
  "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:

{
  "functionName": "getData",
  "contractAddress": "a4f528f949c1ed39671da722d0324d6e82657bee",
  "params": []
}

返回结果:

{
  "code": "SUCCESS",
  "detail": {
    "preSeqId": "",
    "recordData": "f2f9184ae540fb779a671dd2dce0e562d919fa28f3b66e25d68ca4fc14b0945b",
    "seqId": "test7778836871878",
    "customString": "test"
  }
}

字段包括 seqId, preSeqId, recordData, customString,具体参考 BROPTool API -> 业务接口 -> 存证业务接口 说明。

results matching ""

    No results matching ""