本文为您介绍业务视图提供的RESTful API接口。
功能概述
蚂蚁区块链业务视图(Bizview)服务,是独立于区块链的可独立部署组件,主要为开发者提供以下能力。
提供了数据上链和数据查询的RESTful接口,如果您不希望使用Java SDK进行开发,业务视图可以帮助您快捷的和区块链交互。
支持MySQL数据库作为链下数据存储库,提供了接近实时的自动将链上数据导入至链下数据库的功能,延时不超过10秒,便于对链上数据做统计分析。
根据 数据分类配置 对链上数据做自动解析,便于您对业务关键字进行检索, 也降低了对区块链读计算的负荷。该服务可进一步结合数据分析工具或解决方案,从而实现进一步挖掘区块链上的数据价值的目的。如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可以看到返回的符合查询条件的文件。
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)