# BaaS存储API介绍
本文档介绍了如何快速调用公信宝BaaS 存储API,适用于API开发者,需要一定的编程基础。因主链存在存储空间大小的限制,我们的解决方法是将文件本体存储在侧链(IPFS)上,将侧链产生的文件C-ID返还至主链进行存证。在主链上保存的C-ID和时间戳可以保证上链数据不可篡改的基本原则。
# 1. 创建帐户
首先,你需要拥有一个公信宝钱包帐户,用于调用 BaaS存储服务时,支付存储费用并在区块链上记帐。
如果已经拥有公信宝钱包帐户,可以跳过此步骤。
如果还没有公信宝钱包帐户,可以通过手机钱包、网页钱包创建帐户。
PC端钱包/网页钱包使用教程:
- 注册和备份教程:http://mp.weixin.qq.com/s/eNQyqY5dyaP299J5qra0Bg (opens new window)
- 恢复和导入教程:http://mp.weixin.qq.com/s/27v540tvhfDHF6Bv5_ObKQ (opens new window)
手机钱包教程:https://forum.gxb.io/topic/130/gxs-移动端钱包发布-说明文档-ios审核已通过 (opens new window)
# 2. 导出私钥
从手机钱包或者网页钱包导出帐户的活跃权限私钥,供后面调用SDK时使用。
# 3. BaaS存储服务地址
- 主网地址:
https://baas.gxchain.cn/api/storage
- 测试网地址:
https://baas-developer.gxchain.cn/api/storage
# 4. 如何调用SDK
SDK提供了和BaaS存储服务交互的方法封装。目前暂时提供Java版本的SDK,后续会支持多种语言。
# Java - maven
- maven仓库地址(HTML View):
https://repo.gxchain.cn/service/rest/repository/browse/maven-public/
- maven仓库引入地址:
https://repo.gxchain.cn/repository/maven-public/
提示
如果无法引入包,请将https更换成http尝试一下
# maven setting.xml
<mirror>
<id>gxchain</id>
<mirrorOf>*</mirrorOf>
<url>http://repo.gxchain.cn/repository/maven-public/</url>
</mirror>
# pom dependency
<dependency>
<groupId>com.gxb.block.baas</groupId>
<artifactId>baas-sdk-client</artifactId>
<version>1.0.2-RELEASE</version>
</dependency>
# Node - npm
npm install baas-sdk-node
# 5. BaaS存储服务API接口
接口 | 描述 |
---|---|
provider | 获取服务提供方信息 |
store | 数据存储接口 |
data | 获取数据接口,根据cid获取数据 |
# provider接口
通过指定路径获取服务方提供的信息
- 请求地址
GET /provider
请求参数 无
例子(以curl为例)
curl https://baas.gxchain.cn/api/storage/provider
- 响应返回
{
"code":200,
"msg":"ok",
"data":{
"account_id":"1.2.639287", // 提供方正式环境baas account id
"name":"GXChain Official BaaS Storage",
"description":"公信宝BaaS存储+存证服务",
"fees":[ // 支持的支付资产类型以及费率
{"fee_per_kbytes": 20, "asset_id":"1.3.1"}
]
}
}
- SDK示例-JAVA
return new BaasDefaultClient(URL_HEADER + "storage/provider").execute(new ProviderReq());
可参考com.gxb.block.baas.sdk.client.api.BaasConstants类
# store接口
调用方通过该接口可把自己的数据通过baas平台服务有偿上链。
- 请求地址
POST /store
Content-Type= multipart/form-data
- 请求参数
参数 | 类型 | 必填 | 最大长度 | 描述 | 示例 |
---|---|---|---|---|---|
data | byte/File | Y | 不超过10MB | 要存储的原始数据 | 12345678asdfg()_:<>!@#$%^&*=-';" ' |
说明:
存储固定消耗GXS,最小单位为 0.0002/kb.
数据大小限制后续会放开
响应参数
参数 | 类型 | 是否必填 | 最大长度 | 描述 | 示例 |
---|---|---|---|---|---|
txid | String | Y | 64 | 区块交易ID | d4763fd0d802473579ae2dcaa2c6707adf4f2e7e |
cid | String | Y | 64 | IPFS存储的CID值 | QmaZrwThXyZm8Rxs93Tih3L6p4Q8NqYEXp32iN4PeAqDgv |
例子
{
"code":200,
"msg":"ok",
"data":{
"cid":"QmaZrwThXyZm8Rxs93Tih3L6p4Q8NqYEXp32iN4PeAqDgv",
"txid":"d4763fd0d802473579ae2dcaa2c6707adf4f2e7e"
}
}
- SDK示例-JAVA
// build store client
// EXAMPLE_ACCOUNT is your account id
// EXAMPLE_PRIVATE_KEY is your account private key
// EXAMPLE_PUBLIC_KEY is your account public key
// * Attention: Your EXAMPLE_PRIVATE_KEY and EXAMPLE_PUBLIC_KEY can not be uploaded.
StoreClient client = new StoreClient(EXAMPLE_ACCOUNT, EXAMPLE_PRIVATE_KEY, EXAMPLE_PUBLIC_KEY);
// response
StoreDataResp resp = client.store("Hello World!".getBytes());
具体参照 com.gxb.block.baas.sdk.client.api.client.StoreClient
线上帐户的id, 帐户活跃权限公钥可以在公信宝区块浏览器上根据帐户名获得:
区块浏览器地址: https://block.gxb.io/#/ (opens new window)
也可以通过provider接口接口获取到线上正式环境与开发者测试环境对应的BaaS账户id
# 以帐户名gxs-dev为例,params传入帐户名
curl --data '{"jsonrpc": "2.0", "method": "get_account_by_name", "params": ["gxs-dev"], "id": 1}' https://node1.gxb.io
# 响应
{
"id": 1,
"jsonrpc": "2.0",
"result": {
"id": "1.2.639290", // 帐户id
"membership_expiration_date": "1970-01-01T00:00:00",
...
...
"lifetime_referrer_fee_percentage": 3000,
"referrer_rewards_percentage": 0,
"name": "gxs-dev", // 帐户名
"owner": {
"weight_threshold": 1,
"account_auths": [],
"key_auths": [
["GXC85WbsFPSRjRto4n4gbopwGBEf41iroDesrNxN1WXJLTb9Mv2sc", 1]
],
"address_auths": []
},
"active": { // 活跃权限
"weight_threshold": 1,
"account_auths": [],
"key_auths": [
["GXC7xQNvkevq5fkCZPfi7rLTXZb1WKfE41sDTxqf7xUg36BLbZLvh", 1] // 活跃权限公钥
],
"address_auths": []
},
...
...
}
}
- 错误情况
code | msg | 描述 |
---|---|---|
401 | DATA_SIGN_FAILURE | 验签失败 |
402 | BALANCE_NO_ENOUGH | 账户余额不足 |
404 | REQ_EXPIRATION | 请求过期 |
405 | DATA_MD5_INVALID | 数据MD5不通过 |
406 | ACCOUNT_NO_EXIT | 账户不存在 |
407 | DATA_OVER_SIZE | 数据长度过长 |
408 | AMOUNT_INVALID | 金额不合要求 |
# data接口
通过Cid值获取对应存的数据
- 请求地址
GET /data/{cid}
- 请求参数
参数 | 类型 | 必填 | 最大长度 | 描述 | 示例 |
---|---|---|---|---|---|
cid | String | Y | 64 | 存储数据的Cid值 | QmaZrwThXyZm8Rxs93Tih3L6p4Q8NqYEXp32iN4PeAqDgv |
例子:
GET /api/data/QmaZrwThXyZm8Rxs93Tih3L6p4Q8NqYEXp32iN4PeAqDgv
- 响应返回
返回一个 QmaZrwThXyZm8Rxs93Tih3L6p4Q8NqYEXp32iN4PeAqDgv.baas 的文件
- SDK示例-JAVA
// build store client
// EXAMPLE_ACCOUNT is your account id
// EXAMPLE_PRIVATE_KEY is your account private key
// EXAMPLE_PUBLIC_KEY is your account public key
// * Attention: Your EXAMPLE_PRIVATE_KEY and EXAMPLE_PUBLIC_KEY can not be uploaded.
StoreClient client = new StoreClient(EXAMPLE_ACCOUNT, EXAMPLE_PRIVATE_KEY, EXAMPLE_PUBLIC_KEY, false);
// byte[]
byte[] result = client.getRawBytes(CID);
// String
String str = client.getRawString(CID);
// File
String file = client.downloadFile(CID,TARGET_FILE); // TARGET_FILE is java.io.File.
- 错误情况
code | msg | 描述 |
---|---|---|
401 | NO_EXIT | 不存在 |