全部产品
  • 首页 > 
  • 业务视图接口说明

业务视图接口说明

本文为您介绍业务视图提供的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如下所示:

  1. GuestInfo {
  2. // 姓名,非空。
  3. String userName;
  4. // 邮箱,非空。
  5. String email;
  6. // 生日,非空
  7. String birthday
  8. }

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

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

  1. {
  2. "userName":"Kate",
  3. "email":"kate@163.com",
  4. "birthday":"20180101"
  5. }

使用CURL测试接口如下:

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

返回的HTTP Response如下:

  1. {
  2. "errMessage" : "",
  3. "responseData": "1d33029f014096d98f2265222d5aef3bebac5de00aadf0a5f370256be243a48c"
  4. "success" : true,
  5. }

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传入以下数据:

  1. {
  2. "key":"userName",
  3. "value":"Bob",
  4. "pageSize":5,
  5. "pageNumber":1
  6. }

使用CURL测试接口如下:

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

返回的HTTP Response如下:

  1. {
  2. "errMessage": "",
  3. "success": true,
  4. "responseData": [
  5. {
  6. "userName": "Bob",
  7. "birthday": "2000-01-01",
  8. "email": "bob@inc.com"
  9. },
  10. {
  11. "userName": "Bob",
  12. "birthday": "2001-01-01",
  13. "email": "bob1@inc.com"
  14. },
  15. {
  16. "userName": "Bob",
  17. "birthday": "2002-01-01",
  18. "email": "bob2@inc.com"
  19. },
  20. {
  21. "userName": "Bob",
  22. "birthday": "2003-01-01",
  23. "email": "bob3@inc.com"
  24. },
  25. {
  26. "userName": "Bob",
  27. "birthday": "2004-01-01",
  28. "email": "bob4@inc.com"
  29. }
  30. ],
  31. "totalCount": 5
  32. }

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如下所示:

  1. CertFile {
  2. //证书图片,非空。
  3. File image;
  4. //证书文本,非空。
  5. File text;
  6. //证书名,非空
  7. String name;
  8. }

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

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

使用CURL测试接口如下:

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

返回的HTTP Response如下:

  1. {
  2. "errMessage" : "",
  3. "responseData": "1d33029f014096d98f2265222d5aef3bebac5de00aadf0a5f370256be243a48c"
  4. "success" : true,
  5. }

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传入以下数据:

  1. {
  2. "key":"name",
  3. "value":"my_file",
  4. "pageSize":5,
  5. "pageNumber":1
  6. }

使用CURL测试接口如下:

  1. curl -X POST \
  2. http://{your_server_ip}:8080/api/certFileGetFiles \
  3. -H 'Content-Type: application/json' \
  4. -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测试接口如下:

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

返回的HTTP Response如下:

  1. {
  2. "errorMsg": "",
  3. "totalCount": 2,
  4. "responseData": [
  5. {
  6. "txHash": "1d33029f014096d98f2265222d5aef3bebac5de00aadf0a5f370256be243a48c",
  7. "type": 4,
  8. "category": -1,
  9. "height": 273852,
  10. "blockHash": "9c3308565b934ec65a312b423b1697a955bc0912baf1f80b1a043097e1674c36",
  11. "blockVersion": 1,
  12. "createTime": "2018-05-30T03:35:50.000Z",
  13. "referenceCount": 0,
  14. "content": "eyJjZXJ0Tm8iOiJiNTc3ZTFhZmE0YWUwOWY3Zjk4YjAzMWMyOTJmMmEyOWE3NjE3NzlmOTEzNTZlZjk4M2Q2NjdmODAwYjBlNThlIiwidmVyc2lvbiI6MSwiaXNDZXJ0QWN0aXZlIjp0cnVlLCJhY3RpdmVCaXoiOjEsImNpZCI6IjEwMCJ9",
  15. "link": null,
  16. "contentHash": null,
  17. "nonce": null,
  18. "encryptContent": null,
  19. "keyName": null,
  20. "keyWrap": null
  21. },
  22. {
  23. "txHash": "1ed22275a0f0f425c5556efc580b86582189b1628cfbab78bbae9e1fe8ca4927",
  24. "type": 4,
  25. "category": 65537,
  26. "height": 212282,
  27. "blockHash": "91da9bd833b2e0c7bd68215d3b41bf7c0d016f0b0320bedab05d0cc8e0b67335",
  28. "blockVersion": 1,
  29. "createTime": "2018-05-29T12:43:57.000Z",
  30. "referenceCount": 0,
  31. "content": "rO0ABXNyADVjb20uYWxpcGF5Lm15Y2hhaW4uc2RrLnBsdXMuZW50aX",
  32. "link": null,
  33. "contentHash": null,
  34. "nonce": null,
  35. "encryptContent": null,
  36. "keyName": null,
  37. "keyWrap": null
  38. }
  39. ],
  40. "success": true
  41. }

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测试接口如下:

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

返回的HTTP Response如下:

  1. {
  2. "errMessage" : "",
  3. "totalCount" : 1,
  4. "responseData" : [
  5. {
  6. "txHash": "1d33029f014096d98f2265222d5aef3bebac5de00aadf0a5f370256be243a48c",
  7. "type": 4,
  8. "category": -1,
  9. "height": 273852,
  10. "blockHash": "9c3308565b934ec65a312b423b1697a955bc0912baf1f80b1a043097e1674c36",
  11. "blockVersion": 1,
  12. "createTime": "2018-05-30T03:35:50.000Z",
  13. "referenceCount": 0,
  14. "content": "eyJjZXJ0Tm8iOiJiNTc3ZTFhZmE0YWUwOWY3Zjk4YjAzMWMyOTJmMmEyOWE3NjE3NzlmOTEzNTZlZjk4M2Q2NjdmODAwYjBlNThlIiwidmVyc2lvbiI6MSwiaXNDZXJ0QWN0aXZlIjp0cnVlLCJhY3RpdmVCaXoiOjEsImNpZCI6IjEwMCJ9",
  15. "link": null,
  16. "contentHash": null,
  17. "nonce": null,
  18. "encryptContent": null,
  19. "keyName": null,
  20. "keyWrap": null
  21. }
  22. ],
  23. "success" : true,
  24. }

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示例
  1. {
  2. "errorMsg": "",
  3. "txHash": "1d33029f014096d98f2265222d5aef3bebac5de00aadf0a5f370256be243a48c",
  4. "success": true
  5. }