您正在查看: 2021年1月

dfuse-eosio 常用GraphQL API接口整理

测试例子

https://github.com/dfuse-io/docs/tree/master/quickstarts

@ dfuse/client使用例子

global.fetch = require('node-fetch');
global.WebSocket = require('ws');

// CODE:BEGIN:quickstarts_javascript_node_eos_section1
const { createDfuseClient } = require('@dfuse/client');

const client = createDfuseClient({
  network: '39.106.103.152:8080',
  authentication: false,
  secure: false,
});
// CODE:END:quickstarts_javascript_node_eos_section1
// CODE:BEGIN:quickstarts_javascript_node_eos_section2
// You must use a `$cursor` variable so stream starts back at last marked cursor on reconnect!
const operation = `subscription($cursor: String!) {
  searchTransactionsForward(query:"receiver:eosio.token action:transfer -data.quantity:'0.0001 EOS'", cursor: $cursor) {
    undo cursor
    trace { id matchingActions { json } }
  }
}`;
// CODE:END:quickstarts_javascript_node_eos_section2
// CODE:BEGIN:quickstarts_javascript_node_eos_section3
async function main() {
  const stream = await client.graphql(operation, message => {
    if (message.type === 'data') {
      const {
        undo,
        cursor,
        trace: { id, matchingActions }
      } = message.data.searchTransactionsForward;
      matchingActions.forEach(({ json: { from, to, quantity } }) => {
        console.log(
          `Transfer ${from} -> ${to} [${quantity}]${undo ? ' REVERTED' : ''}`
        );
      });

      // Mark stream at cursor location, on re-connect, we will start back at cursor
      stream.mark({ cursor });
    }

    if (message.type === 'error') {
      console.log('An error occurred', message.errors, message.terminal);
    }

    if (message.type === 'complete') {
      console.log('Completed');
    }
  });

  // Waits until the stream completes, or forever
  await stream.join();
  await client.release();
}
// CODE:END:quickstarts_javascript_node_eos_section3
// CODE:BEGIN:quickstarts_javascript_node_eos_section4
main().catch(error => console.log('Unexpected error', error));
// CODE:END:quickstarts_javascript_node_eos_section4

接口文档

https://docs.dfuse.io/eosio/public-apis/reference/graphql-api/

常用接口整理

稍后补充

GraphQL 与 REST 相比的优势和短板

https://zhuanlan.zhihu.com/p/95521039

dfuse/client 如何配置访问权限

如何在我自己构建和运行的@dfuse/client中配置apiKey
由于dfuse官方权限这块并没有开源,可以先把权限相关关闭
可以只用测试例子演示

const client = createDfuseClient({
  network: '39.106.103.152:8080',
  authentication: false,
  secure: false,
});

参考

https://github.com/dfuse-io/dfuse-eosio/issues/206

https://github.com/dfuse-io/client-js/blob/e86735957d348ced88f141720979dec8516db5ef/examples/basic/dfuse-for-eosio.ts#L13

如何让dfuse-eosio 的dashboard 可以外网访问

由于部署的服务器一般为server版,没有UI界面,所以目前dfuse-eosio默认的本地访问地址很不方便,为了外部访问,编译前,需要修改下配置,

要修改的配置在https://github.com/dfuse-io/dlauncher 项目中,当编译dfuse-eosio时,./scripts/build.sh会自动在当前目录的上层目录下,获取dlauncher源码。

当dlauncher代码获取完,再将dlauncher\dashboard\client\src\.env中的 http://localhost:8080修改成对应的地址

REACT_APP_DASHBOARD_GRPC_WEB_URL=http://localhost:8080/api

比如修改成

REACT_APP_DASHBOARD_GRPC_WEB_URL=http://39.106.103.152:8080/api

然后重新编译即可。

当然我们只是为了测试演示,生产环境中,并不会直接暴露在外网,因为此后台并没有权限验证,一般是外层再加层防护,比如VPN

dfuse-eosio 如何添加自定义查询条件,例如transfer中的memo

为了业务的需要的,我们常常需要查询交易中的一些自定义的参数,比如transfer 中的memo
当我们按找REST API文档使用时,

http://39.106.103.152:8080/v0/search/transactions?start_block=0&block_count=327722&limit=10&sort=desc&q=receiver:eosio.token+action:transfer+data.memo:return

会报不支持

"server error: unable to initiate to search: The following fields you are trying to search are not currently indexed: 'data.memo'. Contact our support team for more."

解决方案

被索引的操作的数据字段定义为search-common-indexed-terms默认配置为"receiver, account, action, auth, scheduled, status, notif, input, event, ram.consumed, ram.released, db.key, db.table, data.account, data.active, data.active_key, data.actor, data.amount, data.auth, data.authority, data.bid, data.bidder, data.canceler, data.creator, data.executer, data.from, data.is_active, data.is_priv, data.isproxy, data.issuer, data.level, data.location, data.maximum_supply, data.name, data.newname, data.owner, data.parent, data.payer, data.permission, data.producer, data.producer_key, data.proposal_name, data.proposal_hash, data.proposer, data.proxy, data.public_key, data.producers, data.quant, data.quantity, data.ram_payer, data.receiver, data.requested, data.requirement, data.symbol, data.threshold, data.to, data.transfer, data.voter, data.voter_name, data.weight, data.abi, data.code"

所有不以data.“.”开头的字段都是“固定的”,这意味着您可以将它们包含在列表中以对其进行索引或关闭以禁用对其的索引编制,但是我们不能添加新的字段(block_timestamp例如,将被拒绝)。

所有开始data.都是动态的字段,并且可以是任何字段,如果它们与操作的字段名称匹配,则将对其进行索引,例如,如果您部署了具有操作event_id且data.event_id列表中有的智能合约,则可以按receiver:mycontract data.event_id:something。

现在,大约data.memo可以将其添加到列表中,它将起作用,但是它将是完全匹配的,在memo数据上没有标记化,也没有解释。一个手段memo形式first second third,data.memo:first将不匹配,只有data.memo:'first second third'将匹配字段。

最终修改

编译dfuse.yaml,在flags中添加

search-common-indexed-terms: "receiver, account, action, auth, scheduled, status, notif, input, event, ram.consumed, ram.released, db.key, db.table, data.account, data.active, data.active_key, data.actor, data.amount, data.auth, data.authority, data.bid, data.bidder, data.canceler, data.creator, data.executer, data.from, data.is_active, data.is_priv, data.isproxy, data.issuer, data.level, data.location, data.maximum_supply, data.name, data.newname, data.owner, data.parent, data.payer, data.permission, data.producer, data.producer_key, data.proposal_name, data.proposal_hash, data.proposer, data.proxy, data.public_key, data.producers, data.quant, data.quantity, data.ram_payer, data.receiver, data.requested, data.requirement, data.symbol, data.threshold, data.to, data.transfer, data.voter, data.voter_name, data.weight, data.abi, data.code, data.memo"

原有数据基础上增加data.memo,重新运行dfuseeos 即可

参考

https://github.com/dfuse-io/dfuse-eosio/issues/209

dfuse-eosio 常用REST API接口整理

测试环境

目前在http://39.106.103.152:8080 搭建了一个测试服务,我们基于测试服务做接口测试

REST API

1. 查询交易

官方文档

https://docs.dfuse.io/eosio/public-apis/reference/rest/get-search-transactions/

测试查询
http://39.106.103.152:8080/v0/search/transactions?start_block=0&block_count=100000&limit=10&sort=desc&q=receiver:eosio.token+action:transfer+data.to:xihzz2blorkc

这个查询交易相当的灵活,不但能根据区块区间,还能根据查询action相应参数做查询

2. 根据时间查询区块

官方文档

https://docs.dfuse.io/eosio/public-apis/reference/rest/get-block_id-by_time/

测试查询
http://39.106.103.152:8080/v0/block_id/by_time?time=2021-01-27T10:36:14.5Z&comparator=gte

comparator参数

  • gt 大于
  • gte 大于等于
  • lt 小于
  • lte 小于等于
  • eq 相等

3. 任意块高度获取给定合同帐户的ABI

官方文档

https://docs.dfuse.io/eosio/public-apis/reference/rest/get-state-abi/

测试查询
http://39.106.103.152:8080/v0/state/abi?account=eosio&block_num=10000&json=true

4. 任意块高度获取由给定公钥控制的帐户

官方文档

https://docs.dfuse.io/eosio/public-apis/reference/rest/get-state-key_accounts/

测试查询
http://39.106.103.152:8080/v0/state/key_accounts?public_key=EOS8G6gjXRpMHdaQhZr2DU1myKKf7RgsT5MXaggBYxtqfaTnNgazf

5. 在任何块高度上,获取区块链上任何帐户的链接授权的快照

官方文档

https://docs.dfuse.io/eosio/public-apis/reference/rest/get-state-permission_links/

测试查询

我们先在测试网上设置好测试数据

cleos -u http://47.94.225.179:2222 set account permission xihzz2blorkc claimer '{"threshold":1, "keys":[], "accounts":[{"permission":{"actor":"bcskillsurou","permission":"active"},"weight":1}],"waits":[]}' active -p xihzz2blorkc
cleos -u http://47.94.225.179:2222 set action permission xihzz2blorkc eosio claimrewards claimer

测试查询

http://39.106.103.152:8080/v0/state/permission_links?account=xihzz2blorkc&block_num=327722

6. 在任何块高度获取任何表的状态

官方文档

https://docs.dfuse.io/eosio/public-apis/reference/rest/get-state-table/

测试查询
http://39.106.103.152:8080/v0/state/table?account=eosio.token&scope=xihzz2blorkc&table=accounts&block_num=327722&json=true

7. 从任何表的状态以任何块高度获取单行

官方文档

https://docs.dfuse.io/eosio/public-apis/reference/rest/get-state-table-row/

测试查询
http://39.106.103.152:8080/v0/state/table/row?account=eosio.token&scope=xihzz2blorkc&table=accounts&primary_key=RES&key_type=symbol_code&block_num=327722&json=true

8. 以任意块高度获取合同帐户上给定表的合并范围列表

官方文档

https://docs.dfuse.io/eosio/public-apis/reference/rest/get-state-table_scopes/

测试用例
http://39.106.103.152:8080/v0/state/table_scopes?account=eosio.token&table=accounts

9. 从任何块高度的合同帐户组中获取一张表

比较常见的用途就是,从多个代币合约中查询某个账户各个代币余额

官方文档

https://docs.dfuse.io/eosio/public-apis/reference/rest/get-state-tables-accounts/

测试查询

测试前先再发一个代币

cleos -u http://47.94.225.179:2222 set contract xihzz2blorkc contracts/eosio.token 
cleos -u http://47.94.225.179:2222 push action xihzz2blorkc create '{"issuer":"xihzz2blorkc", "maximum_supply": "10000000000.00000000 BCS"}' -p xihzz2blorkc 
cleos -u http://47.94.225.179:2222 push action xihzz2blorkc issue '{"to":"xihzz2blorkc","quantity":"1000000000.00000000 BCS","memo":"issue"}' -p xihzz2blorkc 
cleos -u http://47.94.225.179:2222 transfer xihzz2blorkc bcskillsurou "0.00000001 BCS" "transfer" -p xihzz2blorkc -c xihzz2blorkc

测试查询
查询bcskillsurou在eosio.token和xihzz2blorkc两个代币合约中的代币余额

http://39.106.103.152:8080/v0/state/tables/accounts?accounts=eosio.token|xihzz2blorkc&scope=bcskillsurou&table=accounts&block_num=336806&json=true

10. 在任意块高度处,为一组范围的给定协定获取表中的所有行

比较常见的用途就是,从单个代币合约中查询多个账户余额

官方文档

https://docs.dfuse.io/eosio/public-apis/reference/rest/get-state-tables-scopes/

测试查询
http://39.106.103.152:8080/v0/state/tables/scopes?account=eosio.token&scopes=xihzz2blorkc|bcskillsurou&table=accounts&block_num=327722&json=true

11. 获取与提供的参数关联的事务生命周期:id

官方文档

https://docs.dfuse.io/eosio/public-apis/reference/rest/get-transactions/

测试查询
http://39.106.103.152:8080/v0/transactions/53e4f9b831b347a33c43807777552029fc73d176905d757d93be97acb7b2e24e

12. 在任何块高度,根据给定合约帐户的ABI解码给定表的二进制行(以十六进制字符串)

官方文档

https://docs.dfuse.io/eosio/public-apis/reference/rest/post-state-abi-bin_to_json/

测试查询
curl -X POST -d '{"account":"eosio.token","table":"accounts","block_num":327722,"hex_rows":["aa2c0b010000000004454f5300000000"]}' "http://39.106.103.152:8080/v0/state/abi/bin_to_json"

13. 用于将事务提交到网络的直接替换,但是可以选择阻止请求,直到事务处于一个块或不可逆的块中

官方文档

https://docs.dfuse.io/eosio/public-apis/reference/rest/post-chain-push_transaction/
https://docs.dfuse.io/eosio/public-apis/tutorials/writing-on-chain/

测试查询
cleos --header "X-Eos-Push-Guarantee: in-block" push transaction mytx.json
cleos --header "X-Eos-Push-Guarantee: handoffs:2" push transaction mytx.json

将交易推送到区块链,并可能要求其他担保:

  • 使用HTTP Header:时X-Eos-Push-Guarantee: in-block,调用将一直阻塞,直到事务将其变为有效块为止
  • 使用HTTP标头:时X-Eos-Push-Guarantee: handoff:1,调用一直处于阻塞状态,直到事务将其变成一个块之后,该块仍在块生产移交给另一个BP 1、2或3次(使用handoffs:2和handoffs:3)之后仍处于最长链中
  • 使用HTTP Header:时X-Eos-Push-Guarantee: irreversible,调用将一直阻塞,直到插入事务的块不可逆为止。

请求和响应的内容与常规“ push_transaction”端点相同,除了:

  • 响应将包含这些额外的字段:block_id并 block_num通知您包含该事务的实际块。
  • 返回的跟踪(在之下processed)来自块的实际执行,而不是边缘节点的推测性跟踪(通常如此)

错误码

所述dfuse API使用下面的HTTP错误代码

错误代码 含义
400 错误的请求-您的请求无效
401 未经授权-您的API密钥错误
403 禁止-您的请求Origin不匹配或通过身份验证后,您无权访问指定的资源
404 找不到-找不到指定的资源
405 不允许的方法–您正在使用此资源不允许的HTTP动词
500 内部服务器错误–我们的服务器出现问题。稍后再试
503 服务不可用-我们暂时处于离线状态以进行维护。请稍后再试

错误格式

REST API和WebSocket API的每个错误消息结构在我们所有的API调用中都已完全标准化。

{
    "code": "a_unique_error_code_for_this_specific_error",
    "trace_id": "unique_id_identifying_your_request",
    "message": "A descriptive error message about the problem.",
    "details": {
        "key": "contextual key/values pairs specific to each error"
    }
}

官方文档:https://docs.dfuse.io/eosio/public-apis/reference/rest/errors/