As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Introdução à Amazon Managed Blockchain (AMB) Query
Use os step-by-step tutoriais desta seção para aprender a realizar tarefas usando o Amazon Managed Blockchain (AMB) Query. Esses procedimentos exigem alguns pré-requisitos. Se você não conhece o AMB Query, consulte a seção *Configuração* deste guia. Para obter mais informações, consulte [Configurando a consulta Amazon Managed Blockchain (AMB)](ambq-setting-up.md).
**nota**
Algumas variáveis nesses exemplos foram deliberadamente ofuscadas. Substitua-os por outros válidos antes de executar esses exemplos.
**Topics**
+ [Crie uma política do IAM para acessar as operações da API AMB Query](#getting-started-iam-policy)
+ [Faça solicitações de API de consulta do Amazon Managed Blockchain (AMB) usando Go](#getting-started-go-example)
+ [Faça solicitações de API de consulta do Amazon Managed Blockchain (AMB) usando o Node.js](#node-amb-query-requests)
+ [Faça solicitações de API de consulta do Amazon Managed Blockchain (AMB) usando Python](#python-amb-query-requests)
+ [Use a consulta Amazon Managed Blockchain (AMB) no Console de gerenciamento da AWS para executar a GetTokenBalance operação](#query-console-gettokenbalance-example)
## Crie uma política do IAM para acessar as operações da API AMB Query
Para fazer solicitações da API AMB Query, você deve usar as credenciais do usuário (AWS\$1ACCESS\$1KEY\$1ID e a AWS\$1SECRET \$1ACCESS\$1KEY) que tenham as permissões apropriadas do IAM para a Amazon Managed Blockchain (AMB) Query. Em um terminal com o AWS CLI instalado, execute o comando a seguir para criar uma política do IAM para acessar as operações da API AMB Query:
```
cat < ~/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
```
Depois de criar a política, anexe essa política à função de um usuário do IAM para que ela entre em vigor. No Console de gerenciamento da AWS, navegue até o serviço do IAM e anexe a política `AmazonManagedBlockchainQueryAccess` à função atribuída ao usuário do IAM que usará o serviço. Para obter mais informações, consulte [Como criar uma função e atribuir a um usuário do IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user.html).
**nota**
AWS recomenda que você dê acesso a operações específicas da API em vez de usar o curinga`*`. Para obter mais informações, consulte [Acessando ações específicas da API de consulta do Amazon Managed Blockchain (AMB)](security_iam_id-based-policy-examples.md#security_iam_id-based-policy-examples-access-ambquery-apis).
## Faça solicitações de API de consulta do Amazon Managed Blockchain (AMB) usando Go
Com o Amazon Managed Blockchain (AMB) Query, você pode criar aplicativos que dependem do acesso instantâneo aos dados do blockchain, uma vez confirmados no blockchain, mesmo que ainda não tenham atingido a *finalidade*. O AMB Query permite vários casos de uso, como preencher o histórico de transações de uma carteira, fornecer informações contextuais sobre uma transação com base em seu hash de transação ou obter o saldo de tokens nativos, bem como dos tokens ERC-721, ERC-1155 e ERC-20.
Os exemplos a seguir são criados na linguagem Go e usam as operações da API AMB Query. Para obter mais informações sobre Go, consulte a [documentação do Go](https://go.dev/doc/). Para obter mais informações sobre a API de consulta AMB, consulte a documentação de [referência da API de consulta do Amazon Managed Blockchain (AMB)](https://docs.aws.amazon.com/managed-blockchain/latest/AMBQ-APIReference/API_Operations.html).
Os exemplos a seguir usam as ações `ListTransactions` e a `GetTransaction` API para primeiro obter uma lista de todas as transações de um determinado endereço de propriedade externa (EOA) na Ethereum Mainnet e, em seguida, o próximo exemplo recupera os detalhes da transação de uma única transação da lista.
**Example — Faça a ação `ListTransactions` da API usando Go**
Copie o código a seguir em um arquivo nomeado `listTransactions.go` no *ListTransactions*diretório.
```
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)
}
}
```
Depois de salvar o arquivo, execute o código usando o seguinte comando dentro do *ListTransactions*diretório:`go run listTransactions.go`.
A saída a seguir é semelhante à seguinte:
```
{
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
}
]
}
```
**Example — Faça a ação `GetTransaction` da API usando Go**
Este exemplo usa um hash de transação da saída anterior. Copie o código a seguir em um arquivo nomeado `GetTransaction.go` no *GetTransaction*diretório.
```
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)
}
}
```
Depois de salvar o arquivo, execute o código usando o seguinte comando dentro do *GetTransaction*diretório:`go run GetTransaction.go`.
A saída a seguir é semelhante à seguinte:
```
{
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
}
}
```
A `GetTokenBalance` API fornece uma maneira de obter o saldo de tokens nativos (ETH e BTC), que podem ser usados para obter o saldo atual de uma conta externa (EOA) em um determinado momento.
**Example — Use a ação `GetTokenBalance` da API para obter o equilíbrio de um token nativo em Go**
No exemplo a seguir, você usa a `GetTokenBalance` API para obter um saldo de endereço Ether (ETH) na Ethereum Mainnet. Copie o código a seguir em um arquivo nomeado `GetTokenBalanceEth.go` no *GetTokenBalance*diretório.
```
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)
}
}
```
Depois de salvar o arquivo, execute o código usando o seguinte comando dentro do *GetTokenBalance*diretório:`go run GetTokenBalanceEth.go`.
A saída a seguir é semelhante à seguinte:
```
{
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"
}
}
```
## Faça solicitações de API de consulta do Amazon Managed Blockchain (AMB) usando o Node.js
Para executar esses exemplos de Node, os seguintes pré-requisitos se aplicam:
1. Você deve ter o node version manager (nvm) e o Node.js instalados em sua máquina. Você pode encontrar instruções de instalação para seu sistema operacional [aqui](https://github.com/nvm-sh/nvm).
1. Use o `node --version` comando e confirme se você está usando a *versão 14 ou superior do Node*. Se necessário, você pode usar o `nvm install 14` comando seguido pelo `nvm use 14` comando para instalar a *versão 14*.
1. As variáveis `AWS_ACCESS_KEY_ID` de ambiente `AWS_SECRET_ACCESS_KEY` devem conter as credenciais associadas à conta.
Exporte essas variáveis como cadeias de caracteres em seu cliente usando os comandos a seguir. Substitua os valores destacados a seguir pelos valores apropriados da conta de usuário do IAM.
```
export AWS_ACCESS_KEY_ID="AKIAIOSFODNN7EXAMPLE"
export AWS_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
```
**nota**
Depois de concluir todos os pré-requisitos, você pode enviar solicitações assinadas via HTTPS para acessar as operações da API de consulta do Amazon Managed Blockchain (AMB) e fazer solicitações usando o [módulo https nativo em Node.js](https://nodejs.org/api/https.html), ou você pode usar uma biblioteca de terceiros, como a [AXIOS](https://www.npmjs.com/package/axios), e recuperar dados do AMB Query.
Esses exemplos usam um cliente HTTP de terceiros para Node.js, mas você também pode usar o AWS JavaScript SDK para fazer solicitações ao AMB Query.
O exemplo a seguir mostra como fazer solicitações da API AMB Query usando o Axios e os módulos AWS SDK para SigV4.
Copie o `package.json` arquivo a seguir no diretório de trabalho do seu ambiente local:
```
{
"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"
}
}
```
**Example — Recupere o saldo histórico de tokens de um endereço externo específico (EOA) usando a API AMB Query `GetTokenBalance`**
Você pode usar a `GetTokenBalance` API para obter o saldo de vários tokens (por exemplo, ERC20 ERC721, e ERC1155) e moedas nativas (por exemplo, ETH e BTC), que você pode usar para obter o saldo atual de uma conta externa (EOA) com base em um histórico `timestamp` (timestamp Unix - segundos). Neste exemplo, você usa a [https://docs.aws.amazon.com/managed-blockchain/latest/AMBQ-APIReference/GetTokenBalance.html](https://docs.aws.amazon.com/managed-blockchain/latest/AMBQ-APIReference/GetTokenBalance.html)API para obter o saldo de endereço de um ERC20 token, USDC, na rede principal do Ethereum.
Para testar a `GetTokenBalance` API, copie o código a seguir em um arquivo chamado `token-balance.js` e salve-o no mesmo diretório de trabalho:
```
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);
```
Para executar o código, abra um terminal no mesmo diretório dos seus arquivos e execute o seguinte comando:
```
npm i
node token-balance.js
```
Esse comando executa o script, passando os argumentos definidos no código para solicitar o saldo ERC20 USDC do EOA listado na Ethereum Mainnet. A resposta é semelhante à seguinte:
```
{
atBlockchainInstant: { time: 1688076218 },
balance: '140386693440144',
lastUpdatedTime: { time: 1688074727 },
ownerIdentifier: { address: '0xf3b0073e3a7f747c7a38b36b805247b2********' },
tokenIdentifier: {
contractAddress: '0xa0b86991c6218b36c1d19d4a2e9eb0ce********',
network: 'ETHEREUM_MAINNET'
}
```
## Faça solicitações de API de consulta do Amazon Managed Blockchain (AMB) usando Python
Para executar esses exemplos de Python, os seguintes pré-requisitos se aplicam:
1. Você deve ter o Python instalado em sua máquina. Você pode encontrar instruções de instalação para seu sistema operacional [aqui](https://wiki.python.org/moin/BeginnersGuide/Download).
1. Instale o [SDK da AWS para Python (](https://aws.amazon.com/sdk-for-python/)Boto3).
1. Instale a [AWS interface de linha](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) de comando e execute o comando `aws configure` para definir as variáveis para seu `Access Key ID``Secret Access Key`, `Region` e.
Depois de concluir todos os pré-requisitos, você pode usar o AWS SDK para Python via HTTPS para fazer solicitações à API de consulta do Amazon Managed Blockchain (AMB).
O exemplo de Python a seguir usa módulos do boto3 para enviar solicitações afixadas com os cabeçalhos SigV4 necessários para a operação da API AMB Query. `ListTransactionEvents` Este exemplo recupera uma lista de eventos emitidos por uma determinada transação na Ethereum Mainnet.
Copie o `list-transaction-events.py` arquivo a seguir no diretório de trabalho do seu ambiente local:
```
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')))
```
Para executar o código de amostra em`ListTransactionEvents`, salve o arquivo em seu diretório de trabalho e execute o comando`python3 list-transaction-events.py`. Esse comando executa o script, passando os argumentos definidos no código para solicitar os eventos associados ao hash da transação em questão na rede principal do Ethereum. A resposta é semelhante à seguinte:
```
{
'events':
[
{
'contractAddress': '0x95ad61b0a150d79219dcf64e1e6cc01f********',
'eventType': 'ERC20_TRANSFER',
'from': '0xab5801a7d398351b8be11c439e05c5b3********',
'network': 'ETHEREUM_MAINNET',
'to': '0xdead0000000000000000420694206942********',
'transactionHash': '0x125714bb4db48757007fff2671b37637bbfd6d47b3a4757ebbd0c522********',
'value': '410241996771871894771826174755464'
}
]
}
```
## Use a consulta Amazon Managed Blockchain (AMB) no Console de gerenciamento da AWS para executar a GetTokenBalance operação
O exemplo a seguir mostra como obter o saldo de um token na *rede principal do Ethereum* usando a consulta Amazon Managed Blockchain (AMB) no Console de gerenciamento da AWS
**Example**
1. Abra o console do Amazon Managed Blockchain em [https://console.aws.amazon.com/managedblockchain/](https://console.aws.amazon.com/managedblockchain/).
1. Escolha **Editor de consultas** na seção **Consulta**.
1. **Escolha **ETHEREUM\$1MAINNET** como a rede Blockchain.**
1. Escolha **GetTokenBalance**como o **tipo de consulta**.
1. Insira seu **endereço Blockchain** para o token.
1. Insira o **endereço do contrato** para o token.
1. Insira o **ID do token** opcional para o token.
1. Escolha a **data de validade** para o saldo do token.
1. Insira o opcional **No momento** para o saldo do token.
1. Selecione **Executar consulta**.
O AMB Query executará sua consulta e você verá os resultados na janela **Resultados da consulta**.