文档

业务视图接口说明

更新时间:

本文为您介绍业务视图提供的RESTful API接口。

功能概述

蚂蚁区块链业务视图(Bizview)服务,是独立于区块链的可独立部署组件,主要为开发者提供以下能力。

  1. 提供了数据上链和数据查询的RESTful接口,如果您不希望使用Java SDK进行开发,业务视图可以帮助您快捷的和区块链交互。

  2. 支持MySQL数据库作为链下数据存储库,提供了接近实时的自动将链上数据导入至链下数据库的功能,延时不超过10秒,便于对链上数据做统计分析。

  3. 根据 数据分类配置 对链上数据做自动解析,便于您对业务关键字进行检索, 也降低了对区块链读计算的负荷。该服务可进一步结合数据分析工具或解决方案,从而实现进一步挖掘区块链上的数据价值的目的。如Bizview与阿里云MySQL和BI结合实现数据分析视图解决方案。

业务视图接口主要分为以下两类:

  • 存证数据上链(接口1)、存证数据筛选(接口2)、大文件存证数据上链(接口3)和大文件存证数据查询(接口4)与数据分类(Schema)的配置紧密相关,用户可以在链上配置多个数据类型(Category),对于用户配置的每一个数据类型,Bizview服务根据配置提供专用的数据上链和数据查询接口。这也是我们推荐的实践方式。

  • 除上述接口外,蚂蚁区块链还支持更多的存证模型,比如密文存证、哈希存证等,可通过接口5,接口6,接口7来进行交互。具体的存证格式介绍,可以参考蚂蚁区块链的 存证交易模型

1. 存证数据上链

根据配置的Schema数据格式自动生成,为每个Category生成一个数据上链接口,提交Category对应格式的数据上链。

  • RESTful URL:api/{categoryName}

  • HTTP Methond:POST

  • 请求参数说明

    根据Category的定义,提交一个完整的Category信息即可。

  • 返回JSON结构

    RESPONSE

参数名

类型

是否必选

说明

responseData

string

交易hash

success

bool

是否成功

errMessage

string

错误信息

以下是调用示例。假设schema.txt文件中定义了了一个Category如下所示:

GuestInfo {
// 姓名,非空。    
String userName;
// 邮箱,非空。
String email;
// 生日,非空
String birthday
}

那么对应这个Category的数据上链接口是:http://{your_server_ip}:8080/api/guestInfo ,注意接口的URL Path是以小写字母开头,所以GuestInfo对应的是guestInfo。

HTTP Request Headers 设置:Content-Type:application/json,HTTP Request Body根据GuestInfo的数据类型定义,本用例使用的数据是:

{
  "userName":"Kate",
  "email":"kate@163.com",
  "birthday":"20180101"
}

使用CURL测试接口如下:

curl -X POST \
  http://{your_server_ip}:8080/api/certFile \
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  -F 'userName=Kate' \
  -F 'email=kate@163.com' \
  -F 'birthday=20180101'

返回的HTTP Response如下:

{
  "errMessage" : "",
  "responseData": "1d33029f014096d98f2265222d5aef3bebac5de00aadf0a5f370256be243a48c",
  "success" : true,
}

2. 存证数据查询

根据配置的Schema数据格式自动生成,为每个Category生成一个对应的数据查询接口,可以将Category中定义的字段做为查询条件key,获取符合查询条件的存证数据。同时也可以使用存证接口返回的交易hash作为key,查询存证数据。

  • RESTful URL:api/{categoryName}Get

  • HTTP Methond:POST

  • 请求参数说明

参数名

类型

是否必选

说明

key

string

用做查询的字段名

value

string

查询的字段值

pageSize

int

分页长度,建议不要超过100

pageNumber

int

分页起始坐标,从1开始

  • 返回JSON结构

RESPONSE

参数名

类型

是否必选

说明

responseData

list

交易信息,如果为空返回null

success

bool

是否成功

errMessage

string

错误信息

totalCount

int

记录列表长度

以下是调用示例。以接口1中定义的GuestInfo为例,数据查询的接口是:http://{your_server_ip}:8080/api/guestInfoGet ,注意接口的Path是以小写字母开头。

HTTP Request Headers 设置 :Content-Type:application/json ,HTTP Request Body根据查询接口的定义传入相应的数据。假设需要查询userName=Bob的存证数据,分页长度为5,获取第1页的数据,则HTTP Request Body传入以下数据:

{
  "key":"userName",
  "value":"Bob",
  "pageSize":5,
  "pageNumber":1
}

使用CURL测试接口如下:

curl -X POST \
  http://{your_server_ip}:8080/api/guestInfoGet \
  -H 'Content-Type: application/json' \
  -d '{"key":"userName","value":"Bob","pageSize":5,"pageNumber":1}'

返回的HTTP Response如下:

{
    "errMessage": "",
    "success": true,
    "responseData": [
        {
            "userName": "Bob",
            "birthday": "2000-01-01",
            "email": "bob@inc.com"
        },
        {
            "userName": "Bob",
            "birthday": "2001-01-01",
            "email": "bob1@inc.com"
        },
        {
            "userName": "Bob",
            "birthday": "2002-01-01",
            "email": "bob2@inc.com"
        },
        {
            "userName": "Bob",
            "birthday": "2003-01-01",
            "email": "bob3@inc.com"
        },
        {
            "userName": "Bob",
            "birthday": "2004-01-01",
            "email": "bob4@inc.com"
        }
    ],
    "totalCount": 5
}

3. 大文件存证数据上链

如果需要存证的数据是较大的文件,在配置Schema的时候,可以将数据类型Type设置为File,存证文件会存储在application.properties中配置的OSS上,Bizview服务会为设置了File数据类型的Category生成对应的数据上链接口。

  • RESTful URL:api/{categoryName}

  • HTTP Methond:POST

  • 请求参数说明

    根据Category的定义,提交一个完整的Category信息即可。

  • 返回JSON结构

RESPONSE

参数名

类型

是否必选

说明

responseData

string

交易hash

success

bool

是否成功

errMessage

string

错误信息

以下是调用示例假设schema.txt文件中定义了了一个Category如下所示:

CertFile {
//证书图片,非空。
File image;
//证书文本,非空。
File text;
//证书名,非空
String name;
}

那么对应这个Category的大文件上链接口是:http://{your_server_ip}:8080/api/certFile ,注意接口的URL Path是以小写字母开头。

HTTP Request Headers 设置:Content-Type:multipart/form-data ,HTTP Request Body根据CertFile的数据类型定义。

使用CURL测试接口如下:

curl -X POST \
  http://{your_server_ip}:8080/api/certFile \
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  -F image=@/home/file/cert_image.pgn \
  -F text=@/home/file/cert_text.txt \
  -F 'name=my_file'

返回的HTTP Response如下:

{
  "errMessage" : "",
  "responseData": "1d33029f014096d98f2265222d5aef3bebac5de00aadf0a5f370256be243a48c",
  "success" : true,
}

4. 大文件存证数据查询

根据数据类型包含File的Schema配置自动生成,为每个Category生成一个对应的文件查询接口,可以将Category中定义的非File类型字段做为查询条件key,获取符合查询条件的文件。同时也可以使用存证接口返回的交易hash作为key,查询存证数据。

  • RESTful URL:api/{categoryName}GetFiles

  • HTTP Methond:POST

  • 请求参数说明

参数名

类型

是否必选

说明

key

string

用做查询的字段名

value

string

查询的字段值

pageSize

int

分页长度,建议不要超过100

pageNumber

int

分页起始坐标,从1开始

  • 返回数据结构

    该接口的HTTP Response Headers设置为:Content-Type:application/zip,HTTP Response Body包含一个zip数据流,包括所有符合查询条件的文件。

以下是调用示例。以接口3中定义的CertFile为例,文件查询的接口是:http://{your_server_ip}:8080/api/certFileGetFiles ,注意接口的Path是以小写字母开头。

HTTP Request Headers 设置 :Content-Type:application/json ,HTTP Request Body根据文件查询接口的定义传入相应的数据。注意:大文件存证查询使用的key不能是File类型的字段名,本例中CertFile中定义的image、text不能作为查询的关键字。假设需要查询name=my_file的文件,分页长度为5,获取第1页的文件数据,则HTTP Request Body传入以下数据:

{
  "key":"name",
  "value":"my_file",
  "pageSize":5,
  "pageNumber":1
}

使用CURL测试接口如下:

curl -X POST \
  http://{your_server_ip}:8080/api/certFileGetFiles \
  -H 'Content-Type: application/json' \
  -d '{"key":"name","value":"my_file","pageSize":5,"pageNumber":1}' >> output-file.zip

解压output-file.zip可以看到返回的符合查询条件的文件。

files_dowloaded

5. 获取交易信息列表(分页)

根据分页条件检索交易信息。

  • RESTful URL:api/transactions

  • HTTP Methond:GET

  • 请求参数说明

    Path参数定义如下:

参数名

类型

是否必选

说明

pageSize

int

分页起始坐标:从1开始

pageNumber

int

分页长度,建议不要超过100

  • 返回JSON结构

RESPONSE

参数名

类型

是否必选

说明

responseData

list

记录列表,记录为空时返回null

success

bool

是否成功

errMessage

string

错误信息

totalCount

int

记录列表长度

TransDetail信息说明

参数名

类型

是否必选

说明

txHash

string

交易hash

type

int

存证类型

category

int

schema类别

height

int

交易所在块高

blockHash

string

交易所在块hash

blockVersion

int

交易结构版本号

createTime

string

创建时间

referenceCount

int

引用次数

content

string

存证明文数据

link

string

存证链接

contentHash

string

存证数据hash

nonce

string

加密密文时的随机iv

encryptContent

string

存证密文

keyName

string

密钥的kdf推导路径

keyWrap

string

密钥key的key wrap

以下是调用示例。假设分页长度是5,需要查询第1页的交易信息,那么调用的接口是http://{your_server_ip}:8080/api/transactions?pageSize=1&pageNumber=5

使用CURL测试接口如下:

curl -X GET \
  'http://{your_server_ip}:8080/api/transactions?pageSize=1&pageNumber=5'

返回的HTTP Response如下:

{
    "errorMsg": "",
    "totalCount": 2,
    "responseData": [
      {
        "txHash": "1d33029f014096d98f2265222d5aef3bebac5de00aadf0a5f370256be243a48c",
        "type": 4,
        "category": -1,
        "height": 273852,
        "blockHash": "9c3308565b934ec65a312b423b1697a955bc0912baf1f80b1a043097e1674c36",
        "blockVersion": 1,
        "createTime": "2018-05-30T03:35:50.000Z",
        "referenceCount": 0,
        "content": "eyJjZXJ0Tm8iOiJiNTc3ZTFhZmE0YWUwOWY3Zjk4YjAzMWMyOTJmMmEyOWE3NjE3NzlmOTEzNTZlZjk4M2Q2NjdmODAwYjBlNThlIiwidmVyc2lvbiI6MSwiaXNDZXJ0QWN0aXZlIjp0cnVlLCJhY3RpdmVCaXoiOjEsImNpZCI6IjEwMCJ9",
        "link": null,
        "contentHash": null,
        "nonce": null,
        "encryptContent": null,
        "keyName": null,
        "keyWrap": null
      },
      {
        "txHash": "1ed22275a0f0f425c5556efc580b86582189b1628cfbab78bbae9e1fe8ca4927",
        "type": 4,
        "category": 65537,
        "height": 212282,
        "blockHash": "91da9bd833b2e0c7bd68215d3b41bf7c0d016f0b0320bedab05d0cc8e0b67335",
        "blockVersion": 1,
        "createTime": "2018-05-29T12:43:57.000Z",
        "referenceCount": 0,
        "content": "rO0ABXNyADVjb20uYWxpcGF5Lm15Y2hhaW4uc2RrLnBsdXMuZW50aX",
        "link": null,
        "contentHash": null,
        "nonce": null,
        "encryptContent": null,
        "keyName": null,
        "keyWrap": null
      }
    ],
    "success": true
}

6. 通过txHash获取交易详细信息

通过txhash获取交易信息。

  • RESTful URL:api/transactions/{txhash}

  • HTTP Methond:GET

  • 请求参数说明

参数名

类型

是否必选

说明

txHash

hash hex string

txhash:交易hash值

  • 返回JSON结构

RESPONSE

本接口返回值可参考获取交易信息列表接口(接口5)的返回值,唯一区别是totalCount最大为1。

TransDetail

可参见获取交易信息列表接口(接口5)。

增加payloadType字段,如果type为明文存证,则返回responseDataList,若为其它类型,则返回payload的link、hash、nonce、encryptcontent、keyname、keywrap。

调用示例:

假设查询txHash为1d33029f014096d98f2265222d5aef3bebac5de00aadf0a5f370256be243a48c的交易详情,则使用CURL测试接口如下:

curl -X GET \
 'http://{your_server_ip}:8080/api/transactions/1d33029f014096d98f2265222d5aef3bebac5de00aadf0a5f370256be243a48c'

返回的HTTP Response如下:

{
  "errMessage" : "",
  "totalCount" : 1,
  "responseData" : [
    {
      "txHash": "1d33029f014096d98f2265222d5aef3bebac5de00aadf0a5f370256be243a48c",
      "type": 4,
      "category": -1,
      "height": 273852,
      "blockHash": "9c3308565b934ec65a312b423b1697a955bc0912baf1f80b1a043097e1674c36",
      "blockVersion": 1,
      "createTime": "2018-05-30T03:35:50.000Z",
      "referenceCount": 0,
      "content": "eyJjZXJ0Tm8iOiJiNTc3ZTFhZmE0YWUwOWY3Zjk4YjAzMWMyOTJmMmEyOWE3NjE3NzlmOTEzNTZlZjk4M2Q2NjdmODAwYjBlNThlIiwidmVyc2lvbiI6MSwiaXNDZXJ0QWN0aXZlIjp0cnVlLCJhY3RpdmVCaXoiOjEsImNpZCI6IjEwMCJ9",
      "link": null,
      "contentHash": null,
      "nonce": null,
      "encryptContent": null,
      "keyName": null,
      "keyWrap": null
    }
  ],
  "success" : true,
}

7. 使用更多数据模型存证数据上链

  • 接口说明

    提交一个交易,可提交的交易为除明文存证外的其它数据种类。

  • RESTful URL:api/transactions

  • HTTP Methond:POST

  • 请求参数说明

    TransDetail

参数名

类型

是否必选

说明

type

int

存证类型(见下方注解)

category

int

schema类别

blockVersion

int

交易结构版本号

createTime

string

创建时间

referenceCount

int

引用次数

content

string

存证明文数据

link

string

存证链接

contentHash

string

存证数据hash

nonce

string

加密密文时的随机iv

encryptContent

string

存证密文

keyName

string

密钥的kdf推导路径

keyWrap

string

密钥key的key wrap

注:接口支持蚂蚁区块链的以下存证类型,使用接口前请在SDK的Readme文件中查看不通存证的详细说明。特别说明的是,接口1至接口4已经结合数据格式配置对明文存证模型实现了更好的封装,故本接口不支持明文存证模型。

存证类型

type

说明

HashOnlyNotaryPayloadDO

3

哈希存证模型

LinkNotaryPayloadDO

5

链接存证模型

EncryptNotaryPayloadDO

6

隐私存证模型

EncryptContentOnlyNotaryPayloadDO

7

密文隐私存证模型

EncryptShareNotaryPayloadDO

8

分享隐私存证模型

ContentOnlyNotaryPayloadDO

明文存证模型(本接口不支持)

  • 返回JSON结构

RESPONSE

参数名

类型

是否必选

说明

success

bool

是否成功,查找不到返回false

errorMsg

string

错误信息

txHash

string

交易hash

增加payloadType字段,如果type为明文存证,则返回responseDataList,若为其它类型,则返回payload的link、hash、nonce、encryptcontent、keyname、keywrap。

  • 返回JSON示例

{
    "errorMsg": "",
    "txHash": "1d33029f014096d98f2265222d5aef3bebac5de00aadf0a5f370256be243a48c",
    "success": true
}
  • 本页导读 (0)
文档反馈