快速上手

业务申请和安装络谱工具完成后，您可使用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
  4. 存证专区编号（专区链需要使用）：0x000000000000047f000000005c7e384f00000000

安全插件：

  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：

{
  "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 -> 业务接口 -> 存证业务接口 说明。

results matching ""

    No results matching ""