menu

上链及查询相关接口

更新时间: 2019-12-24 18:10:38 · 编辑者:宇链科技

批量上链接口

单个或批量提交一批信息到区块链上,支持明文和加密数据。

接口地址

POST https://v1.api.tc.vastchain.ltd/common-chain-upload/

本请求需要携带签名。请参考 API 签名算法

请求参数

本接口的请求参数使用 JSON 格式通过 body 来传输。请确保在请求中设置了合适的 HTTP Header(即 Content-Type: application/json)。

下面是一个请求的例子:

{
  // items: 上链项目数组,具体请参考下文
    "items": [
        {
          // type, args 的解释请参考下文
            "type": "intelligent-doorlock-model",
            "args": {
                // 任何一个上链项目都有一个 id 属性,用于上链之后的状态查询和其他相关操作,请妥善保管
                // 此 id 建议采用该条数据在您的本地数据库中的相关 id
                "id": "door1"
            }
        },
        {
          // 下一个上链项目...
        }
    ]
}

请求体中字段的解释:

名称 数据类型 说明
items RequestItem[] 包含一个或多个上链项目的数组,RequestItem 的详细定义请参考下文。目前,每次最多批量上传 50 条记录。items 数组里的每一项的大小不能超过 50 KB

其中,RequestItem 类型定义如下;

名称 数据类型 说明
type string 上链的动作(action)类别,如 voluntary-activity-register 代表公共活动注册。每个动作的定义请参考 API 参考 中以「动作」结尾的相关页面。
args object 上链动作(action)的具体参数,针对不同的上链动作,参数的字段定义是不同的,但是,任何项目都有一个 id,此 id 建议采用该条数据在您的本地数据库中的相关 id。具体的参数要求请参考 API 参考 中以「动作」结尾的相关页面。

对于相同的数据,args 中的 id 请全程保持不变,无论上链是否失败,都不要更换该 id,应该使用该 id 继续尝试。宇链云会自动去重,防止相同 id 的数据被多次上传。

响应

当上链推送成功(参数校验无误且成功送入上链队列)时,系统将返回 200 的状态代码,并返回下列响应:

{
    "status": "pending", // pending 代表已进入上链队列,处于「待定」状态
    "version": "1"
}

此时代表数据提交成功,系统会在后台排队上链。

pending 状态不代表最终上链成功,关于上链最终是否成功的判断,请参考本页面下方的「fetchOnChainIds」接口的相关说明。

返回 pending 之前我们会尽量检查参数的正确性,确保参数正确且送入上链队列才返回;所以返回 pending 后有极大的概率能够最终上链成功。但是,由于上链是异步排队进行的,且任何区块链都需要全网达成共识,所以在极低概率下(如海底光缆中断)可能造成区块链共识失败。

当上链失败时,响应如下所示:

{
    "version": "1",
    "status": "fail",             // 失败状态
    "error": "xxxx",              // 具体的错误标识
    "code": "E0XXXXX",            // 错误代码
    "msg": "xxxx",                // 错误的详细说明
    "traceId": "X50wccmvqkhq"     // 用于在宇链云平台追溯请求的请求 ID
}

此时,宇链云将不会继续上链过程。请修正错误,然后重新尝试直到成功,以避免链上记录和数据库不符。

获取链上 ID 接口

此接口用来通过同步的方式查询上链结果,包括链上 ID(OnChainId)、区块 ID(Block Num)、事务 ID(Transaction Id),用来获知上链的最终确认状态。

不同的上链动作(action),在得到上链 ID 之前所需要等待的时延是不同的。对于 everiPayeveriPass 动作,一般只需 1 秒即可完成。一些请求可能要在上链 3 - 4 分钟之后才可以获得链上 ID。

查询到的 “链上 ID” 是宇链云中上链数据在区块链中的唯一标识。区块 ID、交易 ID 则是区块链本身用来定位交易的索引方式。

接口地址

POST https://v1.api.tc.vastchain.ltd/common-chain-upload/fetchOnChainIds

请求参数

本接口的请求参数使用 JSON 格式通过 body 来传输。请确保在请求中设置了合适的 HTTP Header(即 Content-Type: application/json)。

下面是一个请求的例子:

{
    "items": [
        {
            "type": "intelligent-doorlock-register",
            "id": "doortest3d6",
            "queryType": "i2c"
        },
        {
            "type": "everiPass",
            "id": "b364c14821e0722f196e9da08d556ddc",
            "queryType": "i2c"
        },
        {
            "type": "intelligent-doorlock-register",
            "id": "doortest",
            "queryType": "i2c"
        },
        {
            "type": "everiPass",
            "id": "b364c14821e0722f196e9da08d556ddc",
            "queryType": "i2c"
        }
    ]
}

请求体中字段的解释:

名称 数据类型 说明
items object[] 包含一个或多个上链项目信息的数组,每个项目的字段定义请参考下文。目前,每次最多批量查询 500 条记录。
type string 上链的动作(action)类别,此参数的值必须和上链时传递的 type 参数一致。每个动作的定义请参考 API 参考 中以「动作」结尾的相关页面。
id string 要查询上链状态的上链项目的 id,这个 id 要和上链时在 args 中提供的 id 保持一致。
queryType string 值必须为 i2cc2i 之一。前者代表通过本地的数据 id(即上链时提供的 id) 获取链上 id,后者代表通过 链上 id 获取本地 id

响应

当调用成功时,系统将返回 200 的状态代码。下面是响应的一个例子:

{
  "status": "success",
  "version": "1",
  // 下面演示了三种可能的不同返回值,分别为最终确认成功、上链失败、上链已提交,尚未确认状态
  "items": [
    // 上链最终确认成功
    {
      "id": "GAl5lGFgLKi",
      "chainTrxId": "a281fa0f5484fe49e5bc28291e4436d7dbfdaf956fbef0fb1685b0ea93756825",
      "chainBlockNum": "4363434"
    },
    // 上链最终确认成功
    {
      "id": "edd9b0a405de941ae06991cc5f59fba014ed028a4761d3f837a1454262492ae4",
      "chainTrxId": "a281fa0f5484fe49e5bc28291e4436d7dbfdaf956fbef0fb1685b0ea93756825",
      "chainBlockNum": "4363434"
    },
    // 上链失败
    {}, 
    // 上链已提交,尚未确认状态
    {
      "id": ""
    }
  ]
}

响应字段的解释如下:

  1. 响应包含一个 items 字段,该字段中的每一项代表请求参数的 items 数组中相应位置的查询的结果。例如响应的第 2 项即代表请求参数中 items 第二项的结果。
  2. 对于 items 中的每个结果,如果上链已失败,则结果为一个空对象(也就是 JSON 中的 { });如果上链成功或正在排队,则会包含下列字段:
    • id:代表该数据在链上的唯一标志,此标志在宇链云内部通用,相同的上链数据生成的链上 ID 是相同的,这可以防止重复上链。如果 id 为空字符串(""),说明上链已提交,但正在排队或尚未确认最终状态。
    • chainTrxId:代表此次上链在链上所对应的事务 ID(Transaction Id),可以通过区块链浏览器查询。如果该上链被分为多个事务(Transaction),则请参考相应文档的说明。
    • chainBlockNum:代表此次上链的区块号(Block Num)。一个区块里可能有很多个事务(transaction),所以仅凭区块号不能完全定位到某条数据。

注意区分“上链失败”和“上链尚未成功”两种状态。具体解释如下:

  • 如果响应的 items 数组的某一项为空对象({ }),也就是没有 id 字段,说明上链已彻底失败,或者查询的 id 不存在,请重新提交。
  • 如果响应的 items 数组的某一项的 id 为空字符串({ "id": "" }),则代表上链已提交,尚未获取到最终确认结果,请耐心等待再查询。

API 已经内置去重功能,多次提交同一数据时,请不要更换 argsid,API 将自动判断是否重复上链。

获得链上 id 后,可以在你的 App 中添加指向该链上 id 的区块链浏览器链接,方便你的用户查询。我们也可以提供专用的区块链浏览器,以适配你的 App 的 Logo 和主题色。