API身份验证

申请权限

安链云-BaaS平台会为每个API调用进行身份验证,所以在使用BaaS平台API服务之前,用户需要申请权限,具体如下

  1. 登录安链云网站

  2. 创建应用

在左侧菜单栏中选择 应用与密钥管理

api-main.png

点击 创建应用

api-create.png

选择"BAAS平台API服务",创建应用

api-create-dialog.png

应用创建成功,获取${API_Key}${Secret_Key} 其中API Key用于标识用户身份,Secret Key用于客户端加密签名和服务器端验证签名,必须严格保密

api-create-key.png

身份验证

用户在调用任意API时,需要传递token来通过安链云-BaaS平台的身份验证。用户在成功申请权限后,即可自行获取token,获取方法如下: https://oauth.anlink.com/oauth/token?client_id=${API_Key}&client_secret=${Secret_Key}&grant_type=client_credentials 其中${API_Key}为API Key,${Secret_Key}为Secret Key,返回值access_token,即token,有效期为12小时,过期后需重新获取。 调用API时在地址后加上token,即可通过身份验证,示例: https://api.anlink.com/baas/chain/queryChainList?token=12345678-abcd-123456789abc

API安全验证

1.公共参数

除了身份验证之外,用户在调用任意API时,需要传递以下公共参数,来验证API调用的安全性:

字段名称 类型 必填 备注
timeStamp string Y 调用API时的Unix时间戳,精确到秒,示例:若调用API的时间为北京时间2019年3月20日10点10分10秒,则Unix时间戳为1553047810
nonce string Y 唯一随机数,用来防止重放攻击。每次调用API需要使用不同的随机数值。
sign string Y 签名,用来防止参数篡改。具体加签规则请参考2。
version string Y API版本号,取值:1.2
signMethod string Y 签名方式,取值:HMAC-SHA1

2.加签规则

参数排序: 对除了sign以外的公共参数和API私有参数,按名称字母进行升序排序,示例:

若参数为 {"param1" : "1","timeStamp" : "1553047810","nonce" : "1411388270"}

排序后的参数为:

{"nonce" : "1411388270","param1" : "1","timeStamp" : "1553047810"}

构建参数字符串:

对参数名称和参数值使用URL编码方法进行编码,并用=和&进行拼接,示例: 上述排序后的参数进行编码和拼接后的参数字符串为nonce=1411388270&param1=1&timeStamp=1553047810

加签参数字符串: 以Secret Key为密钥,使用HMAC-SHA1算法对参数字符串进行加签,获取签名

示例代码:

/ * 构建参数字符串 * @param parameters 参数集合 * @return 构建好的参数字符串 */ private static String buildSortKey(Map parameters) throws Exception { String[] sortedKeys = parameters.keySet().toArray(new String[]{}); //排序 Arrays.sort(sortedKeys); //编码和拼接 StringBuilder stringToSign = new StringBuilder(); int i = 1; for (String key : sortedKeys) { Object val = parameters.get(key); if (val == null) val = ""; stringToSign.append(percentEncode(key)).append("=").append(percentEncode(val.toString())); if (i < sortedKeys.length) { stringToSign.append("&"); } i++; } return stringToSign.toString(); } / * URL编码 / private static String percentEncode(String value) throws UnsupportedEncodingException { return value != null ? URLEncoder.encode(value, "UTF-8").replace("+", "%20") .replace("", "%2A").replace("%7E", "~") : null; } /* * 加签参数字符串 * @param plainText 构建好的参数字符串 * @param key 密钥,即Secret Key * @return 签名 / public static String encrypt(String plainText, String key) { byte[] result = null; try { SecretKeySpec signinKey = new SecretKeySpec(key.getBytes(), HMAC_SHA1_ALGORITHM); Mac mac = Mac.getInstance("HmacSHA1"); mac.init(signinKey); byte[] rawHmac = mac.doFinal(plainText.getBytes()); result = Base64.encodeBase64(rawHmac); } catch (NoSuchAlgorithmException e) { System.err.println(e.getMessage()); } catch (InvalidKeyException e) { System.err.println(e.getMessage()); } if (null != result) { return new String(result); } else { return null; } }

API接口列表

1.查询链ID列表

API地址:https://api.anlink.com/baas/chain/queryDeployedChainIdList?token=${val}

Method:POST

Content-Type:application/json

Request Body:

字段名称 类型 必填 备注
公共参数 string Y 参考上文公共参数部分

Response Body:

字段名称 类型 备注
success Boolean 调用API接口是否成功,true为成功,false为失败
errorCode String 若调用失败,返回错误代码
errorMsg String 若调用失败,返回错误信息
result JsonArray 若调用成功,返回创建成功的链账户信息,示例 "result": [{"chainId": "82f6f075-f4ba-4b64-95af-14d9a74e60fc","chainName": "众安公共测试链","remark": "众安科技安链云团队推出的公共测试链,欢迎试用!"}] 返回值描述:chainId 链Id,在指定的链chainId上操作。chainName 链名称,remark 链描述

2.创建链账户

API地址:https://api.anlink.com/baas/account/create?token=${val}

Method:POST

Content-Type:application/json

Request Body:

字段名称 类型 必填 备注
公共参数 string Y 参考上文公共参数部分

Response Body:

字段名称 类型 备注
success Boolean 调用API接口是否成功,true为成功,false为失败
errorCode String 若调用失败,返回错误代码
errorMsg String 若调用失败,返回错误信息
result JsonObject 若调用成功,返回创建成功的链账户信息,示例 "result": {"address": "0xc5ce24adc98d7e5997e4cc5cf22c5b5a08350a49"} 返回值描述:address 链账户地址

3.链上部署合约

API地址:https://api.anlink.com/baas/contract/create?token=${val}

Method:POST

Content-Type:application/json

Request Body:

字段名称 类型 必填(Y/N) 备注
address String Y 链账户地址
code String Y 合约二进制码
abiDefinition String Y 合约ABI序列化字符串
chainId String Y 链Id
params JsonArray N 合约构造参数
公共参数 String Y 参考公共参数部分

Response Body:

字段名称 类型 备注
success Boolean 调用API接口是否成功,true为成功,false为失败
errorCode String 若调用失败,返回错误代码
errorMsg String 若调用失败,返回错误信息
result JsonObject 若调用成功,返回部署成功的合约信息,示例:"result": {"contract": "0x99edb7c4ae989c9bea6dca4d863636bffe3512e9","tx": "37fdd017ce0ccaf80296a91c4019c7ae8638bb31"}返回值描述:contract 合约地址,tx:部署合约的交易哈希值

4.链上调用合约(同步读)

API地址:https://api.anlink.com/baas/contract/read?token=${val}

Method:POST

Content-Type:application/json

Request Body:

字段名称 类型 必填(Y/N) 备注
address String Y 链账户地址
contract String Y 合约地址
params JsonArray N 调用参数
method String Y 调用方法
chainId String Y 链Id
公共参数 String Y 参考公共参数部分

Response Body:

字段名称 类型 备注
success Boolean 调用API接口是否成功,true为成功,false为失败
errorCode String 若调用失败,返回错误代码
errorMsg String 若调用失败,返回错误信息
result JsonObject 若调用成功,返回同步读合约结果

5.链上调用合约(同步写)

API地址:https://api.anlink.com/baas/contract/call?token=${val}

Method:POST

Content-Type:application/json

Request Body:

字段名称 类型 必填(Y/N) 备注
address String Y 链账户地址
contract String Y 合约地址
params JsonArray N 调用参数
method String Y 调用方法
chainId String Y 链Id
公共参数 String Y 参考公共参数部分

Response Body:

字段名称 类型 备注
success Boolean 调用API接口是否成功,true为成功,false为失败
errorCode String 若调用失败,返回错误代码
errorMsg String 若调用失败,返回错误信息
result JsonObject 若调用成功,返回同步写合约的交易哈希值,示例:"result": "f774278741fbc1230380f9c4a57558204cbffaaf"

6.链上调用合约(异步写)

API地址:https://api.anlink.com/baas/contract/callAsync?token=${val}

Method:POST

Content-Type:application/json

Request Body:

字段名称 类型 必填(Y/N) 备注
address String Y 链账户地址
contract String Y 合约地址
params JsonArray N 调用参数
method String Y 调用方法
callbackUrl String Y 回调地址
chainId String Y 链Id
公共参数 String Y 参考公共参数部分

Response Body:

字段名称 类型 备注
success Boolean 调用API接口是否成功,true为成功,false为失败
errorCode String 若调用失败,返回错误代码
errorMsg String 若调用失败,返回错误信息
result JsonObject 若调用成功,返回异步写合约的交易哈希值,示例:"result": "a7dc34072e0d59ccd6ac77645ca150cb56f17309"

7.链上调用合约(批量同步写)

API地址:https://api.anlink.com/baas/contract/batchCall?token=${val}

Method:POST

Content-Type:application/json

Request Body:

字段名称 类型 必填(Y/N) 备注
address String Y 链账户地址
contract String Y 合约地址
params JsonArray N 调用参数
method String Y 调用方法
chainId String Y 链Id
公共参数 String Y 参考公共参数部分

Response Body:

字段名称 类型 备注
success Boolean 调用API接口是否成功,true为成功,false为失败
errorCode String 若调用失败,返回错误代码
errorMsg String 若调用失败,返回错误信息
result JsonObject 若调用成功,返回批量同步写合约的交易哈希值列表,示例:"result":["b6ef066b161eb0527c63835e2befaaacac67dc3d", "784716704db904315dfa403f6b49fec095d168e5"]

8.链上调用合约(批量异步写)

API地址:https://api.anlink.com/baas/contract/batchCallAsync?token=${val}

Method:POST

Content-Type:application/json

Request Body:

字段名称 类型 必填(Y/N) 备注
address String Y 链账户地址
contract String Y 合约地址
params JsonArray N 调用参数
method String Y 调用方法
callbackUrl String Y 回调地址
chainId String Y 链Id
公共参数 String Y 参考公共参数部分

Response Body:

字段名称 类型 备注
success Boolean 调用API接口是否成功,true为成功,false为失败
errorCode String 若调用失败,返回错误代码
errorMsg String 若调用失败,返回错误信息
result JsonObject 若调用成功,返回批量异步写合约的交易哈希值列表,示例:"result":["7fa5794cfa043440bde047f738b9fbd43ad08207","4790bd00201de95abd94c8ddea69262cd77ace77"

9.链上查询交易结果

API地址:https://api.anlink.com/baas/contract/query/?token=${val}

Method:POST

Content-Type:application/json

Request Body:

字段名称 类型 必填(Y/N) 备注
chainId String Y 链Id
hash String Y 哈希值
公共参数 String Y 参考公共参数部分

Response Body:

字段名称 类型 备注
success Boolean 调用API接口是否成功,true为成功,false为失败
errorCode String 若调用失败,返回错误代码
errorMsg String 若调用失败,返回错误信息
result JsonObject 若调用成功,返回交易哈希结果,示例:"result": {"code": 1,"desc": "正常处理中"}返回值描述:code 交易结果代码,范围1~4,desc 交易结果描述,包括:"正常处理中",对应code为1,"交易成功",对应code为2,"交易失败",对应code为3,"交易不存在",对应code为4