亚马逊托管区块链 (AMB) 查询入门 - Amazon Managed Blockchain 查询
创建 IAM 策略使用 Go 的示例使用 Node.js 的示例使用 Python 的示例使用示例 AWS Management Console

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

亚马逊托管区块链 (AMB) 查询入门

使用本节中的 step-by-step 教程来学习如何使用亚马逊托管区块链 (AMB) 查询来执行任务。这些过程需要一些先决条件。如果您不熟悉 AMB Query，可以查看本指南的设置部分。有关更多信息，请参阅 设置亚马逊托管区块链 (AMB) 查询。

注意

这些示例中的一些变量是故意混淆的。在运行这些示例之前，请将它们替换为您自己的有效版本。

创建用于访问 AMB 查询 API 操作的 IAM 策略

要发出 AMB 查询 API 请求，您必须使用对亚马逊托管区块链 (AMB) 查询具有相应 IAM 权限的用户证书（AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_ACCESS_KEY）。在 AWS CLI 安装了的终端中，运行以下命令创建用于访问 AMB Query API 操作的 IAM 策略：

cat <<EOT > ~/amb-query-access-policy.json
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid" : "AMBQueryAccessPolicy",
            "Effect": "Allow",
            "Action": [
                "managedblockchain-query:*"
            ],
            "Resource": "*"
        }
    ]
}
EOT
aws iam create-policy --policy-name AmazonManagedBlockchainQueryAccess --policy-document file://$HOME/amb-query-access-policy.json

创建策略后，将该策略附加到 IAM 用户的角色以使其生效。在中 AWS Management Console，导航到 IAM 服务，并将策略附加AmazonManagedBlockchainQueryAccess到分配给将使用该服务的 IAM 用户的角色。有关更多信息，请参阅创建角色并分配给 IAM 用户。

注意

AWS 建议您授予对特定 API 操作的访问权限，而不是使用通配符。*有关更多信息，请参阅 访问特定的 Amazon Managed Blockchain (AMB) 查询API操作。

使用 Go 发出亚马逊托管区块链 (AMB) 查询 API 请求

借助 Amazon Managed Blockchain (AMB) 查询，即使区块链数据尚未最终确定，您也可以构建依赖于即时访问区块链数据的应用程序。AMB Query 支持多种用例，例如填充钱包的交易历史记录、根据交易哈希提供有关交易的上下文信息，或者获取原生代币以及 ERC-721、ERC-1155 和 ERC-20 代币的余额。

以下示例使用 Go 语言创建，并使用 AMB 查询 API 操作。有关 Go 的更多信息，请参阅 Go 文档。有关 AMB 查询 API 的更多信息，请参阅亚马逊托管区块链 (AMB) 查询 API 参考文档。

以下示例使用ListTransactions和 GetTransaction API 操作首先获取以太坊主网上给定外部拥有地址 (EOA) 的所有交易的列表，然后下一个示例从列表中检索单笔交易的交易详细信息。

例 — 使用 Go 进行 ListTransactions API 操作

将以下代码复制到ListTransactions目录listTransactions.go中名为的文件中。

package main

import (
    "fmt"
    "github.com/aws/aws-sdk-go/aws"
    "github.com/aws/aws-sdk-go/aws/session"
    "github.com/aws/aws-sdk-go/service/managedblockchainquery"
    "time"
)

func main() {

    // Set up a session
    ambQuerySession := session.Must(session.NewSessionWithOptions(session.Options{
        Config: aws.Config{
            Region: aws.String("us-east-1"),
        },
    }))
    client := managedblockchainquery.New(ambQuerySession)

    // Inputs for ListTransactions API
    ownerAddress := "0x00000bf26964af9d7eed9e03e53415d********"
    network := managedblockchainquery.QueryNetworkEthereumMainnet
    sortOrder := managedblockchainquery.SortOrderAscending
    fromTime := time.Date(1971, 1, 1, 1, 1, 1, 1, time.UTC)
    toTime := time.Now()
    nonFinal := "NONFINAL"
    // Call ListTransactions API. Transactions that have reached finality are always returned
    listTransactionRequest, listTransactionResponse := client.ListTransactionsRequest(&managedblockchainquery.ListTransactionsInput{
        Address: &ownerAddress,
        Network: &network,
        Sort: &managedblockchainquery.ListTransactionsSort{
            SortOrder: &sortOrder,
        },
        FromBlockchainInstant: &managedblockchainquery.BlockchainInstant{
            Time: &fromTime,
        },
        ToBlockchainInstant: &managedblockchainquery.BlockchainInstant{
            Time: &toTime,
        },
        
        ConfirmationStatusFilter: &managedblockchainquery.ConfirmationStatusFilter{
            Include: []*string{&nonFinal},
          },
    })
    errors := listTransactionRequest.Send()

    if errors == nil {
        // handle API response
        fmt.Println(listTransactionResponse)
    } else {
        // handle API errors
        fmt.Println(errors)
    }
}

保存文件后，在ListTransactions目录中使用以下命令运行代码：go run listTransactions.go。

以下输出类似于以下内容：

{
  Transactions: [
    {
      ConfirmationStatus: "FINAL",
      Network: "ETHEREUM_MAINNET",
      TransactionHash: "0x12345ea404b45323c0cf458ac755ecc45985fbf2b18e2996af3c8e8693354321",
      TransactionTimestamp: 2020-06-01 01:59:11 +0000 UTC
    },
    {
      ConfirmationStatus: "FINAL",
      Network: "ETHEREUM_MAINNET",
      TransactionHash: "0x1234547c65675d867ebd2935bb7ebe0996e9ec8e432a579a4516c7113bf54321",
      TransactionTimestamp: 2021-09-01 20:06:59 +0000 UTC
    },
     {
      ConfirmationStatus: "NONFINAL",
      Network: "ETHEREUM_MAINNET",
      TransactionHash: "0x123459df7c1cd42336cd1c444cae0eb660ccf13ef3a159f05061232a24954321",
      TransactionTimestamp: 2024-01-23 17:10:11 +0000 UTC
    }
  ]
}
例 — 使用 Go 进行 GetTransaction API 操作

此示例使用先前输出中的交易哈希。将以下代码复制到GetTransaction目录GetTransaction.go中名为的文件中。

package main

import (
    "fmt"
    "github.com/aws/aws-sdk-go/aws"
    "github.com/aws/aws-sdk-go/aws/session"
    "github.com/aws/aws-sdk-go/service/managedblockchainquery"
)

func main() {

    // Set up a session
    ambQuerySession := session.Must(session.NewSessionWithOptions(session.Options{
        Config: aws.Config{
            Region: aws.String("us-east-1"),
        },
    }))
    client := managedblockchainquery.New(ambQuerySession)

    // inputs for GetTransaction API
    transactionHash := "0x123452695a82868950d9db8f64dfb2f6f0ad79284a6c461d115ede8930754321"
    network := managedblockchainquery.QueryNetworkEthereumMainnet

    // Call GetTransaction API. This operation will return transaction details for all 
    // transactions that are confirmed on the blockchain, even if they have not 
    // reached finality.
    getTransactionRequest, getTransactionResponse := client.GetTransactionRequest(&managedblockchainquery.GetTransactionInput{
        Network:         &network,
        TransactionHash: &transactionHash,
    })

    errors := getTransactionRequest.Send()
    if errors == nil {
        // handle API response
        fmt.Println(getTransactionResponse)
    } else {
        // handle API errors
        fmt.Println(errors)
    }
}

保存文件后，在GetTransaction目录中使用以下命令运行代码：go run GetTransaction.go。

以下输出类似于以下内容：

{
  Transaction: {
    BlockHash: "0x000005c6a71d1afbc005a652b6ceca71cd516d97b0fc514c2a1d0f2ca3912345",
    BlockNumber: "11111111",
    CumulativeGasUsed: "5555555",
    EffectiveGasPrice: "44444444444",
    From: "0x9157f4de39ab4c657ad22b9f19997536********",
    GasUsed: "22222",
    Network: "ETHEREUM_MAINNET",
    NumberOfTransactions: 111,
    SignatureR: "0x99999894fd2df2d039b3555dab80df66753f84be475069dfaf6c6103********",
    SignatureS: "0x77777a101e7f37dd2dd0bf878b39080d5ecf3bf082c9bd4f40de783e********",
    SignatureV: 0,
    ConfirmationStatus: "FINAL", 
    ExecutionStatus: "SUCCEEDED", 
    To: "0x5555564f282bf135d62168c1e513280d********",
    TransactionHash: "0x123452695a82868950d9db8f64dfb2f6f0ad79284a6c461d115ede8930754321",
    TransactionIndex: 11,
    TransactionTimestamp: 2022-02-02 01:01:59 +0000 UTC
  }
}

该 GetTokenBalance API为您提供了一种获取原生代币（ETH和BTC）余额的方法，该余额可用于获取某个时间点外部拥有的账户（EOA）的当前余额。

例 — 使用 GetTokenBalance API 操作获取 Go 中原生代币的余额

在以下示例中，您使用 GetTokenBalance API 在以太坊主网上获取地址以太坊 (ETH) 余额。将以下代码复制到GetTokenBalance目录GetTokenBalanceEth.go中名为的文件中。

package main

import (
    "fmt"
    "github.com/aws/aws-sdk-go/aws"
    "github.com/aws/aws-sdk-go/aws/session"
    "github.com/aws/aws-sdk-go/service/managedblockchainquery"
)

func main() {
    // Set up a session
    ambQuerySession := session.Must(session.NewSessionWithOptions(session.Options{
        Config: aws.Config{
            Region: aws.String("us-east-1"),
        },
    }))
    client := managedblockchainquery.New(ambQuerySession)

    // inputs for GetTokenBalance API
    ownerAddress := "0xBeE510AF9804F3B459C0419826b6f225********"
    network := managedblockchainquery.QueryNetworkEthereumMainnet
    nativeTokenId  := "eth" //Ether on Ethereum mainnet

    // call GetTokenBalance API
    getTokenBalanceRequest, getTokenBalanceResponse := client.GetTokenBalanceRequest(&managedblockchainquery.GetTokenBalanceInput{
        TokenIdentifier: &managedblockchainquery.TokenIdentifier{
            Network:         &network,
            TokenId: &nativeTokenId,
        },
        OwnerIdentifier: &managedblockchainquery.OwnerIdentifier{
            Address: &ownerAddress,
        },
    })
    errors := getTokenBalanceRequest.Send()

    if errors == nil {
        // process API response
        fmt.Println(getTokenBalanceResponse)
    } else {
        // process API errors
        fmt.Println(errors)
    }
}

保存文件后，在GetTokenBalance目录中使用以下命令运行代码：go run GetTokenBalanceEth.go。

以下输出类似于以下内容：

{
  AtBlockchainInstant: {
    Time: 2020-12-05 11:51:01 +0000 UTC
  },
  Balance: "4343260710",
  LastTransactionHash: "0x00000ce94398e56641888f94a7d586d51664eb9271bf2b3c48297a50a0711111",
  LastTransactionTime: 2023-03-14 18:33:59 +0000 UTC,
  OwnerIdentifier: {
    Address: "0x12345d31750D727E6A3a7B534255BADd********"
  },
  TokenIdentifier: {
    Network: "ETHEREUM_MAINNET",
    TokenId: "eth"
  }
}

使用 Node.js 发出亚马逊托管区块链 (AMB) 查询 API 请求

要运行这些 Node 示例，需要满足以下先决条件：

  1. 您的计算机上必须安装节点版本管理器 (nvm) 和 Node.js。您可以在此处找到操作系统的安装说明。

  2. 使用node --version命令并确认您使用的是 Node 版本 14 或更高版本。如果需要，您可以使用nvm install 14命令和nvm use 14命令安装版本 14。

  3. 环境变量AWS_ACCESS_KEY_ID和AWS_SECRET_ACCESS_KEY必须包含与账户关联的凭证。

    使用以下命令将这些变量作为字符串导出到客户端。将以下突出显示的值替换为 IAM 用户账户中的相应值。

    export AWS_ACCESS_KEY_ID="AKIAIOSFODNN7EXAMPLE"
export AWS_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
注意

  • 完成所有先决条件后，您可以通过 HTTPS 提交签名的请求以访问亚马逊托管区块链 (AMB) 查询 API 操作并使用 Node.js 中的原生 https 模块提出请求，也可以使用 AXIO S 等第三方库并从 AMB 查询中检索数据。

  • 这些示例使用第三方 HTTP 客户端 Node.js，但您也可以使用 AWS JavaScript 软件开发工具包向 AMB Query 发出请求。

  • 以下示例向您展示了如何使用 Axios 和 Sigv4 的 AWS SDK 模块发出 AMB 查询 API 请求。

将以下package.json文件复制到本地环境的工作目录中：

{
  "name": "amb-query-examples",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "",
  "license": "ISC",
  "dependencies": {
    "@aws-crypto/sha256-js": "^4.0.0",
    "@aws-sdk/credential-provider-node": "^3.360.0",
    "@aws-sdk/protocol-http": "^3.357.0",
    "@aws-sdk/signature-v4": "^3.357.0",
    "axios": "^1.4.0"
  }
}
例 — 使用 AMB 查询 API 从特定的外部所有地址 (EOA) 检索历史代币余额 GetTokenBalance

您可以使用 GetTokenBalance API 获取各种代币（例如 ERC20、ERC721 和 ERC1155）和原生代币（例如 ETH 和 BTC）的余额，您可以使用这些余额根据历史timestamp（Unix 时间戳-秒）获取外部拥有的账户 (EOA) 的当前余额。在此示例中，您使用 GetTokenBalanceAPI 在以太坊主网上获取 ERC20 代币 USDC 的地址余额。

要测试 GetTokenBalance API，请将以下代码复制到名为的文件中token-balance.js，并将该文件保存到同一个工作目录中：

const axios = require('axios').default;
const SHA256 = require('@aws-crypto/sha256-js').Sha256
const defaultProvider = require('@aws-sdk/credential-provider-node').defaultProvider
const HttpRequest = require('@aws-sdk/protocol-http').HttpRequest
const SignatureV4 = require('@aws-sdk/signature-v4').SignatureV4

// define a signer object with AWS service name, credentials, and region
const signer = new SignatureV4({
  credentials: defaultProvider(),
  service: 'managedblockchain-query',
  region: 'us-east-1',
  sha256: SHA256,
});

const queryRequest = async (path, data) => {
  //query endpoint
  let queryEndpoint = `https://managedblockchain-query.us-east-1.amazonaws.com/${path}`;
  
  // parse the URL into its component parts (e.g. host, path)
  const url = new URL(queryEndpoint);
  
  // create an HTTP Request object
  const req = new HttpRequest({
    hostname: url.hostname.toString(),
    path: url.pathname.toString(),
    body: JSON.stringify(data),
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Accept-Encoding': 'gzip',
      host: url.hostname,
    }
  });

  
  // use AWS SignatureV4 utility to sign the request, extract headers and body
  const signedRequest = await signer.sign(req, { signingDate: new Date() });
  
  try {
    //make the request using axios
    const response = await axios({...signedRequest, url: queryEndpoint, data: data})

    console.log(response.data)
  } catch (error) {
    console.error('Something went wrong: ', error)
    throw error
  } 

 
}


let methodArg = 'get-token-balance';

let dataArg = {
  " atBlockchainInstant": {
    "time": 1688071493
  },  
  "ownerIdentifier": {
      "address": "0xf3B0073E3a7F747C7A38B36B805247B2********" // externally owned address
  },
  "tokenIdentifier": {
      "contractAddress":"0xA0b86991c6218b36c1d19D4a2e9Eb0cE********", //USDC contract address 
      "network":"ETHEREUM_MAINNET"
  }
}

//Run the query request.
queryRequest(methodArg, dataArg);

要运行代码，请在文件所在目录下打开终端，然后运行以下命令：

npm i
node token-balance.js

此命令运行脚本，传入代码中定义的参数，以请求以太坊主网上列出的 EOA 的 ERC20 USDC 余额。响应类似于以下内容：

 {
  atBlockchainInstant: { time: 1688076218 },
  balance: '140386693440144',
  lastUpdatedTime: { time: 1688074727 },
  ownerIdentifier: { address: '0xf3b0073e3a7f747c7a38b36b805247b2********' },
  tokenIdentifier: {
    contractAddress: '0xa0b86991c6218b36c1d19d4a2e9eb0ce********',
    network: 'ETHEREUM_MAINNET'
  }

使用 Python 发出亚马逊托管区块链 (AMB) 查询 API 请求

要运行这些 Python 示例，需要满足以下先决条件：

  1. 你的计算机上必须安装了 Python。您可以在此处找到操作系统的安装说明。

  2. 安装适用于 Python 的 AWS 开发工具包 (Boto3)。

  3. 安装AWS 命令行界面并运行命令aws configure为Access Key IDSecret Access Key、和设置变量Region。

完成所有先决条件后，您可以通过 HTTPS 使用 AWS 适用于 Python 的软件开发工具包来发出亚马逊托管区块链 (AMB) 查询 API 请求。

以下 Python 示例使用 boto3 中的模块向 AMB 查询 API 操作发送附有必要 Sigv4 标头的请求。ListTransactionEvents此示例检索以太坊主网上给定交易发出的事件列表。

将以下list-transaction-events.py文件复制到本地环境的工作目录中：

import json
from botocore.auth import SigV4Auth
from botocore.awsrequest import AWSRequest
from botocore.session import Session
from botocore.httpsession import URLLib3Session

def signed_request(url, method,  params, service, region):

    session = Session()
    sigv4 = SigV4Auth(session.get_credentials(), service, region)
    data = json.dumps(params)
    request = AWSRequest(method, url, data=data)
    sigv4.add_auth(request)
    http_session = URLLib3Session()
    response = http_session.send(request.prepare())

    return(response)

url = 'https://managedblockchain-query.us-east-1.amazonaws.com/list-transaction-events'
method = 'POST'
params = {
'network': 'ETHEREUM_MAINNET', 
'transactionHash': '0x125714bb4db48757007fff2671b37637bbfd6d47b3a4757ebbd0c5222984f905'
}
service = 'managedblockchain-query'
region = 'us-east-1'

# Call the listTransactionEvents operation. This operation will return transaction details for 
# all transactions that are confirmed on the blockchain, even if they have not reached 
# finality.
listTransactionEvents = signed_request(url, method, params, service, region)

print(json.loads(listTransactionEvents.content.decode('utf-8')))

要将示例代码运行到ListTransactionEvents，请将文件保存在工作目录中，然后运行该命令python3 list-transaction-events.py。此命令运行脚本，传入代码中定义的参数，以请求以太坊主网上与给定交易哈希相关的事件。响应类似于以下内容：

{
 'events': 
 [
  {
      'contractAddress': '0x95ad61b0a150d79219dcf64e1e6cc01f********',
      'eventType': 'ERC20_TRANSFER',
      'from': '0xab5801a7d398351b8be11c439e05c5b3********',
      'network': 'ETHEREUM_MAINNET',
      'to': '0xdead0000000000000000420694206942********',
      'transactionHash': '0x125714bb4db48757007fff2671b37637bbfd6d47b3a4757ebbd0c522********',
      'value': '410241996771871894771826174755464'
  }
 ]
}

使用上的 Amazon Managed Blockchain (AMB) 查询 AWS Management Console 来运行操作 GetTokenBalance

以下示例展示了如何使用亚马逊托管区块链 (AMB) 查询在以太坊主网上获取代币余额 AWS Management Console

  1. 打开 Amazon Managed Blockchain 控制台，网址为 https://console.aws.amazon.com/managedblockchain/。

  2. 从 “查询” 部分中选择 “查询编辑器”。

  3. 选择以太坊主网作为区块链网络。

  4. 选择GetTokenBalance作为查询类型。

  5. 输入代币的区块链地址。

  6. 输入代币的合约地址。

  7. 输入令牌的可选令牌 ID。

  8. 选择代币余额的截止日期。

  9. 为代币余额输入可选的 A t tim e。

  10. 选择运行查询。

AMB Query 将运行您的查询，您将在查询结果窗口中看到结果。