Hyperledger Fabric链码API文档

最近更新时间:2018-08-30 11:09:54

Hyperledger Fabric提供的链码API可以分为四类:账本状态交互API、交易信息相关API、参数读取API、其他API,下面分别介绍。

1、账本状态交互API

链码需要将一些数据记录在分布式账本中。需要记录的数据称为状态(state),以键值对(key-value)的形式存储。账本状态交互API的大致功能参见下表。

API 方法格式 说明
GetState GetState(key string) ([]byte, error) 负责查询账本,返回指定键对应的值
PutState PutState(key string, value []byte) error 尝试在账本中添加或更新一对键值。这一对键值会被添加到写集合中,等待Committer进一步的验证,验证通过后会真正写入账本
DelState DelState(key string) error 在账本中删除一对键值。同样,将对键值的删除记录到交易提案的写集合中,等待Committer进一步的验证,验证通过后会真正写入到账本
GetStateByRange GetStateByRange (startKey, endKey string) (StateQueryIteratorInterface, error) 查询指定范围内的键值,startKey、endKey分别制定起始(包括)和终止(不包括),当为空时默认是最大范围。返回结果是一个迭代器StateQueryIteratorInterface结构,可以按照字典序迭代每个键值对,最后需调用Close()方法关闭
GetStateByPartialCompositeKey GetStateByPartialCompositeKey(objectType string, keys []string) (StateQueryIteratorInterface, error) 根据局部的复合键(前缀)返回所有匹配的键值。返回结果也是一个迭代器StateQueryIteratorInterface结构,可以按照字典序迭代每个键值对,最后需调用Close()方法关闭
GetHistoryForKey GetHistoryForKey(key string) (HistoryQueryIteratorInterface, error) 返回某个键的所有历史值。需要在节点配置中打开历史数据库特性(ledger.history.enableHistoryDatabase = true)
GetQueryResult GetQueryResult(query string) (StateQueryIteratorInterface, error) 对(支持富查询功能的)状态数据库进行富查询(rich query)。返回结果为迭代器结构StateQueryIteratorInterface。注意该方法不会被Committer重新执行进行验证,因此,不应该用于更新账本状态的交易中。目前仅有CouchDB类型的状态数据库支持富查询

2、交易相关API

交易信息相关API可以获取到与交易自身相关的数据。用户对链码的调用(初始化和升级时调用Init()方法,运行时调用Invoke()方法)过程中会产生交易提案。这些API支持查询当前交易提案结构的一些属性,具体信息参考下表。

API 方法格式 说明
GetTxID GetTxID() string 该方法返回交易提案中指定的交易ID。一般情况下,交易ID是在客户端生成提案时候产生的数字摘要,由Nonce随机串和签名者身份信息,一起进行SHA256哈希运行生成
GetTxTimestamp GetTxTimestamp() (*timestamp.Timestamp, error) 返回交易被创建时的客户端打上的时间戳,这个时间戳是直接从交易ChannelHeader中提取的,所以在所有背书节点(endorsers)处看到的值都相同
GetBinding GetBinding () ([]byte, error) 返回交易的binding信息注意:交易的binding信息是将交易提案的nonce、Creator、epoch等信息组合起来,再进行哈希得到的数字摘要
GetSignedProposal GetSignedProposal() (*pb.SignedProposal, error) 返回该stub的SignedProposal结构,包括了跟交易提案相关的所有数据
GetCreator GetCreator() ([]byte, error) 返回该交易的提交者的身份信息,从signedProposal中的SignatureHeader.Creater提取
GetTransient GetTransient() (map[string][]byte, error) 返回交易中带有的一些临时信息,从ChancodePorposal-Payload.transient域提取,可以存放一些应用相关的保密信息,这些信息不会被写到账本中

3、参数读取API

调用链码时支持传入若干参数,参数可通过API读取。具体信息参考下表。

API 方法格式 说明
GetArgs GetArgs() [][]byte 提取调用链码时交易Proposal中指定的参数,以字节串(Byte Array)数组形式返回。可以在Init或Invoke方法中使用。这些参数从ChaincodeSpec结构 的Input域直接提取
GetArgsSlice GetArgsSlice() ([]byte, error) 提取调用链码时交易Proposal中指定的参数,以字节串形式返回
GetFunctionAndParameters GetFunctionAndParameters() (string, []string) 提取调用链码时交易Proposal中指定的参数,其中第一个参数作为被调用的函数名称,剩下的参数作为函数的执行参数。这是链码开发者和用户约定俗成的习惯,即在Init/Invoke方法中编写实现若干子函数,用户调用时以第一个参数作为函数名,链码中的代码根据函数名称可以仅执行对应的分支处理逻辑
GetStringArgs GetStringArgs() []string 提取调用链码时交易Proposal中指定的参数,以字符串(String)数组形式返回

4、其他API

一些辅助API,如下表所示。

API 方法格式 说明
CreateCompositeKey CreateCompositeKey(objectType string, attributes []string) (string, error) 给定一组属性(attributes),该API将这些属性组合起来构造返回一个复合键。返回的复合键可以被PutState等方法使用。ObjectType和attributes只允许合法的utf8字符串,并且不能包含U+0000和U+10FFFF
SplitCompositeKey SplitCompositeKey(compositeKey string) (string, []string, error) 给定一组属性(attributes),该API将这些属性组合起来构造返回一个复合键。返回的复合键可以被PutState等方法使用。ObjectType和attributes只允许合法的utf8字符串,并且不能包含U+0000和U+10FFFF
InvokeChaincode InvokeChaincode(chaincodeName string, args [][]byte, channel string) pb.Response 调用另一个链码中的Invoke方法,如果被调用链码在同一个通道内,则添加其读写集合信息到调用交易;否则执行调用但不影响读写集合信息。如果channel为空,则默认为当前通道。目前仅限于读操作,同时不会生成新的交易
SetEvent SetEvent(name string, payload []byte) error 设定当这个交易在Committer处被认证通过,写入到区块时发送的事件(event)

金山云开启您的云计算之旅

立即注册