Node.js API¶
标签:java-sdk
Client
Node.js SDK为区块链应用开发者提供了Node.js API接口,以服务的形式供外部调用。按照功能,Node.js API可以分为如下几类:
Web3jService:提供访问FISCO BCOS 2.0+节点JSON-RPC接口支持;提供部署及调用合约的支持。
PrecompiledService:
Precompiled合约(预编译合约)是一种FISCO BCOS底层内嵌的、通过C++实现的高效智能合约,提供包括分布式权限控制、CNS、系统属性配置、节点类型配置等功能。PrecompiledService是调用这类功能的API的统称,分为:
- PermissionService:提供对分布式权限控制的支持
- CNSService:提供对CNS的支持
- SystemConfigService:提供对系统配置的支持
- ConsensusService:提供对节点类型配置的支持
- CRUDService:提供对CRUD(增删改查)操作的支持,可以创建表或对表进行增删改查操作。
API调用约定¶
- 使用服务之前,首先需要初始化全局的
Configuration
对象,用以为各个服务提供必要的配置信息。Configuration
对象位于nodejs-sdk/packages/api/common/configuration.js
,其初始化参数为一个配置文件的路径或包含配置项的对象。配置文件的配置项说明见配置说明 - 如无特殊说明,Node.js SDK提供的API均为异步API。异步API的实际返回值是一个包裹了API返回值的Promise对象,开发者可以使用async/await语法或then...catch...finally方法操作该Promise对象以实现自己的程序逻辑
- 当API内部出现错误导致逻辑无法继续执行时(如合约地址不存在),均会直接抛出异常,所有异常均继承自Error类
Web3jService¶
位置:nodejs-sdk/packages/api/web3j
功能:访问FISCO BCOS 2.0+节点JSON-RPC;部署合约;调用合约
接口名 | 描述 | 参数 | 返回值 |
---|---|---|---|
getBlockNumber | 获取最新块高 | 无 | Object,结果位于result字段** |
getPbftView | 获取PBFT视图 | 无 | 同上 |
getObserverList | 获取观察者节点列表 | 无 | 同上 |
getSealerList | 获取共识节点列表 | 无 | 同上 |
getConsensusStatus | 获取区块链节点共识状态 | 无 | 同上 |
getSyncStatus | 获取区块链节点同步状态 | 无 | 同上 |
getClientVersion | 获取区块链节点版本信息 | 无 | 同上 |
getPeers | 获取区块链节点的连接信息 | 无 | 同上 |
getNodeIDList | 获取节点及其连接节点的列表 | 无 | 同上 |
getGroupPeers | 获取指定群组的共识节点 和观察节点列表 |
同上 | |
getGroupList | 获取节点所属群组的群组ID列表 | 无 | 同上 |
getBlockByHash | 根据区块哈希获取区块信息 | 区块哈希 | 同上 |
getBlockByNumber | 根据区块高度获取区块信息 | 区块高度 | 同上 |
getBlockHashByNumber | 根据区块高度获取区块哈希 | 区块高度 | 同上 |
getTransactionByHash | 根据交易哈希获取交易信息 | 交易哈希 | 同上 |
getTransactionByBlockHashAndIndex | 根据交易所属的区块哈希、 交易索引获取交易信息 |
交易所属的区块哈希 交易索引 |
同上 |
getTransactionByBlockNumberAndIndex | 根据交易所属的区块高度、 交易索引获取交易信息 |
交易所属的区块高度 交易索引 |
同上 |
getPendingTransactions | 获取交易池内所有未上链的交易 | 无 | 同上 |
getPendingTxSize | 获取交易池内未上链的交易数目 | 无 | 同上 |
getTotalTransactionCount | 获取指定群组的上链交易数目 | 无 | 同上 |
getTransactionReceipt | 根据交易哈希获取交易回执 | 交易哈希 | 同上 |
getCode | 根据合约地址查询的合约数据 | 合约地址 | 同上 |
getSystemConfigByKey | 获取系统配置 | 系统配置关键字,目前支持 : - tx_count_limit - tx_gas_limit |
同上 |
sendRawTransaction | 发送一个经过签名的交易,该交易随后会被链上节点执行并共识 | 接受数量可变的参数:当参数数量为1时,参数应为交易的RLP编码;当参数数量为3时,参数应为合约地址、方法签名及方法参数 | 同上 |
deploy | 部署合约 | 合约路径 输出路径 |
同上 |
call | 调用只读合约 | 合约地址 调用接口* 参数列表 |
同上 |
*调用接口:函数名(参数类型,...),例如:func(uint256,uint256),参数类型之间不能有空格
PrecompiledService¶
PermissionService¶
位置:nodejs-sdk/packages/api/precompiled/permission
功能:提供对分布式权限控制的支持
接口名 | 描述 | 参数 | 返回值 |
---|---|---|---|
grantUserTableManager | 根据用户表名和外部账户地址设置权限信息 | 表名 外部账户地址 |
Number,表示成功改写权限表的行数 |
revokeUserTableManager | 根据用户表名和外部账户地址去除权限信息 | 表名 外部账户地址 |
Number,表示成功改写权限表的行数 |
listUserTableManager | 根据用户表名查询设置的权限记录列表(每条记录包含外部账户地址和生效块高) | 表名 | Array,查询到的记录 |
grantDeployAndCreateManager | 增加外部账户地址的部署合约和创建用户表权限 | 外部账户地址 | Number,表示成功改写权限表的行数 |
revokeDeployAndCreateManager | 移除外部账户地址的部署合约和创建用户表权限 | 外部账户地址 | Number,表示成功改写权限表的行数 |
listDeployAndCreateManager | 查询拥有部署合约和创建用户表权限的权限记录列表 | 无 | Array,查询到的记录 |
grantPermissionManager | 增加外部账户地址的管理权限的权限 | 外部账户地址 | Number,表示成功改写权限表的行数 |
revokePermissionManager | 移除外部账户地址的管理权限的权限 | 外部账户地址 | Number,表示成功改写权限表的行数 |
listPermissionManager | 查询拥有管理权限的权限记录列表 | 无 | Array,查询到的记录 |
grantNodeManager | 增加外部账户地址的节点管理权限 | 外部账户地址 | Number,表示成功改写权限表的行数 |
revokeNodeManager | 移除外部账户地址的节点管理权限 | 外部账户地址 | Number,表示成功改写权限表的行数 |
listNodeManager | 查询拥有节点管理的权限记录列表 | 无 | Array,查询到的记录 |
grantCNSManager | 增加外部账户地址的使用CNS权限 | 外部账户地址 | Number,表示成功改写权限表的行数 |
revokeCNSManager | 移除外部账户地址的使用CNS权限 | 外部账户地址 | Number,表示成功改写权限表的行数 |
listCNSManager | 查询拥有使用CNS的权限记录列表 | 无 | Array,查询到的记录 |
grantSysConfigManager | 增加外部账户地址的系统参数管理权限 | 外部账户地址 | Number,表示成功改写权限表的行数 |
revokeSysConfigManager | 移除外部账户地址的系统参数管理权限 | 外部账户地址 | Number,表示成功改写权限表的行数 |
listSysConfigManager | 查询拥有系统参数管理的权限记录列表 | 无 | Array,查询到的记录 |
CNSService¶
位置:nodejs-sdk/packages/api/precompiled/cns
功能:提供对节点类型配置的支持
接口名 | 描述 | 参数 | 返回值 |
---|---|---|---|
registerCns | 根据合约名、合约版本号、合约地址和合约abi注册CNS信息 | 合约名 合约版本号 合约地址 合约abi |
Number,表示成功增加的CNS条目记录数 |
getAddressByContractNameAndVersion | 根据合约名和合约版本号(合约名和合约版本号用英文冒号连接)查询合约地址。若缺失合约版本号,默认使用合约最新版本 | 合约名 + ':' + 版本号 | Object,查询到的CNS信息 |
queryCnsByName | 根据合约名查询CNS信息 | 合约名 | Array,查询到的CNS信息 |
queryCnsByNameAndVersion | 根据合约名和合约版本号查询CNS信息 | 合约名 版本号 |
同上 |
SystemConfigService¶
位置:nodejs-sdk/packages/api/precompiled/systemConfig
功能:提供对系统配置的支持
接口名 | 描述 | 参数 | 返回值 |
---|---|---|---|
setValueByKey | 根据键设置对应的值(查询键对应的值,参考Web3jService中的getSystemConfigByKey 接口) |
键名 值 |
Number,表示成功修改的系统配置的数目 |
ConsensusService¶
位置:nodejs-sdk/packages/api/precompiled/consensus
功能:提供对节点类型配置的支持
接口名 | 描述 | 参数 | 返回值 |
---|---|---|---|
addSealer | 根据节点NodeID设置对应节点为共识节点 | 节点ID | Number,表示成功增加的共识节点数目 |
addObserver | 根据节点NodeID设置对应节点为观察者节点 | 节点ID | Number,表示成功增加的观察数目 |
removeNode | 根据节点NodeID设置对应节点为游离节点 | 节点ID | Number,表示成功增加的游离数目 |
CRUDService¶
位置:nodejs-sdk/packages/api/precompiled/crud
功能:提供对CRUD(增删改查)操作的支持
接口名 | 描述 | 参数 | 返回值 |
---|---|---|---|
createTable | 创建表 | 表对象 表对象需要设置其表名,主键字段名和其他字段名。其中,其他字段名是以英文逗号分隔拼接的字符串 |
Number,状态码,0代表创建成功 |
insert | 插入记录 | 表对象 Entry对象 表对象需要设置表名和主键字段名;Entry是map对象,提供插入的字段名和字段值,注意必须设置主键字段 |
Number,表示插入的记录数 |
update | 更新记录 | 表对象 Entry对象 Condtion对象 表对象需要设置表名和主键字段名;Condition对象是条件对象,可以设置查询的匹配条件 |
Array,查询到的记录 |
remove | 移除记录 | 表对象 条件对象 |
表对象需要设置表名和主键字段名;Condition对象是条件对象,可以设置移除的匹配条件 |
Select | 查询记录 | 表对象:表对象需要设置表名和主键字段值 Condtion对象:Condition对象是条件对象,可以设置查询的匹配条件 |
Number,成功查询的记录数 |
desc | 根据表名查询表的信息 | 表名 | Object,主要包含表的主键字段名和其他属性字段 |