# Chamar a API de dados do Amazon RDS
Com a API de dados do Amazon RDS (API de dados) habilitada no cluster de banco de dados do Aurora, é possível executar instruções SQL no cluster de bancos de dados do Aurora usando a API de dados ou a AWS CLI. A API de dados é compatível com linguagens de programação aceitas pelos SDKs da AWS. Para obter mais informações, consulte o tópico sobre [Ferramentas para criar na AWS](https://aws.amazon.com/tools/).
**Topics**
+ [Referência de operações da API de dados do Amazon RDS](data-api-operations.md)
+ [Chamar a API de dados do Amazon RDS com a AWS CLI](data-api.calling.cli.md)
+ [Chamar a API de dados do Amazon RDS por meio de uma aplicação Python](data-api.calling.python.md)
+ [Chamar a API de dados do Amazon RDS por meio de uma aplicação Java](data-api.calling.java.md)
+ [Controlar o comportamento de tempo limite da API de dados](data-api-timeouts.md)
# Referência de operações da API de dados do Amazon RDS
A API de dados do Amazon RDS oferece as operações a seguir para executar instruções SQL.
****
| Operação da API de dados | AWS CLI command | Descrição |
| --- | --- | --- |
| [https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_ExecuteStatement.html](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_ExecuteStatement.html) | [https://docs.aws.amazon.com/cli/latest/reference/rds-data/execute-statement.html](https://docs.aws.amazon.com/cli/latest/reference/rds-data/execute-statement.html) | Executa uma instrução SQL em um banco de dados. |
| [https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_BatchExecuteStatement.html](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_BatchExecuteStatement.html) | [https://docs.aws.amazon.com/cli/latest/reference/rds-data/batch-execute-statement.html](https://docs.aws.amazon.com/cli/latest/reference/rds-data/batch-execute-statement.html) | Executa uma instrução SQL em lote em uma matriz de dados para atualização em massa e operações de inserção. Você pode executar uma instrução de linguagem de manipulação de dados (DML) com uma matriz de conjuntos de parâmetros. Uma instrução SQL em lote pode fornecer uma melhoria significativa de performance em relação a instruções de atualização e inserção individuais. |
Você pode usar a operação para executar instruções SQL individuais ou para executar transações. Para transações, a API de dados fornece as operações a seguir.
****
| Operação da API de dados | AWS CLI command | Descrição |
| --- | --- | --- |
| [https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_BeginTransaction.html](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_BeginTransaction.html) | [https://docs.aws.amazon.com/cli/latest/reference/rds-data/begin-transaction.html](https://docs.aws.amazon.com/cli/latest/reference/rds-data/begin-transaction.html) | Inicia uma transação SQL. |
| [https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_CommitTransaction.html](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_CommitTransaction.html) | [https://docs.aws.amazon.com/cli/latest/reference/rds-data/commit-transaction.html](https://docs.aws.amazon.com/cli/latest/reference/rds-data/commit-transaction.html) | Encerra uma transação SQL e confirma as alterações. |
| [https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_RollbackTransaction.html](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_RollbackTransaction.html) | [https://docs.aws.amazon.com/cli/latest/reference/rds-data/rollback-transaction.html](https://docs.aws.amazon.com/cli/latest/reference/rds-data/rollback-transaction.html) | Executa uma reversão de uma transação. |
As operações para executar instruções SQL e oferecer suporte a transações têm os parâmetros comuns da API de dados e as opções de AWS CLI a seguir. Algumas operações oferecem suporte a outros parâmetros ou outras opções.
****
| Parâmetro da operação da API de dados | AWS CLIOpção de comando da | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `resourceArn` | `--resource-arn` | Sim | O nome do recurso da Amazon (ARN) do cluster de banco de dados do Aurora. O cluster deve estar na mesma Conta da AWS que o perfil ou usuário do IAM que invoca a API de dados. Para acessar um cluster em uma conta diferente, assuma um perfil nessa conta. |
| `secretArn` | `--secret-arn` | Sim | O nome ou o ARN do segredo que permite o acesso ao cluster de banco de dados. |
A API de dados do RDS é compatível com os seguintes tipos de dados para o Aurora MySQL:
+ `TINYINT(1)`, `BOOLEAN`, `BOOL`
+ `TINYINT`
+ `SMALLINT` [`SIGNED` \$1 `UNSIGNED`]
+ `MEDIUMINT` [`SIGNED` \$1 `UNSIGNED`]
+ `INT` [`SIGNED` \$1 `UNSIGNED`]
+ `BIGINT` [`SIGNED` \$1 `UNSIGNED`]
+ `FLOAT`
+ `DOUBLE`
+ `VARCHAR`, `CHAR`, `TEXT`, `ENUM`
+ `VARBINARY`, `BINARY`, `BLOB`
+ `DATE`, `TIME`, `DATETIME`, `TIMESTAMP`
+ `DECIMAL`
+ `JSON`
+ `BIT`, `BIT(N)`
A API de dados do RDS é compatível com os seguintes tipos escalares do Aurora PostgreSQL:
+ `BOOL`
+ `BYTEA`
+ `DATE`
+ `CIDR`
+ `DECIMAL`, `NUMERIC`
+ `ENUM`
+ `FLOAT8`, `DOUBLE PRECISION`
+ `INET`
+ `INT`, `INT4`, `SERIAL`
+ `INT2`, `SMALLINT`, `SMALLSERIAL`
+ `INT8`, `BIGINT`, `BIGSERIAL`
+ `JSONB`, `JSON`
+ `REAL`, `FLOAT`
+ `TEXT`, `CHAR(N)`, `VARCHAR`, `NAME`
+ `TIME`
+ `TIMESTAMP`
+ `UUID`
+ `VECTOR`
A API de dados do RDS é compatível com os seguintes tipos de matriz do Aurora PostgreSQL:
+ `BOOL[]`, `BIT[]`
+ `DATE[]`
+ `DECIMAL[]`, `NUMERIC[]`
+ `FLOAT8[]`, `DOUBLE PRECISION[]`
+ `INT[]`, `INT4[]`
+ `INT2[]`
+ `INT8[]`, `BIGINT[]`
+ `JSON[]`
+ `REAL[]`, `FLOAT[]`
+ `TEXT[]`, `CHAR(N)[]`, `VARCHAR[]`, `NAME[]`
+ `TIME[]`
+ `TIMESTAMP[]`
+ `UUID[]`
Você pode usar parâmetros nas chamadas da API de dados para `ExecuteStatement` e `BatchExecuteStatement` e quando executar os comandos AWS CLI e `execute-statement` da `batch-execute-statement`. Para usar um parâmetro, especifique um par nome-valor no tipo de dados `SqlParameter`. Você especifica o valor com o tipo de dados `Field`. A tabela a seguir mapeia tipos de dados Java Database Connectivity (JDBC) para os tipos de dados especificados nas chamadas da API de dados.
****
| Tipo de dados JDBC | Tipo de dados da API de dados |
| --- | --- |
| `INTEGER, TINYINT, SMALLINT, BIGINT` | `LONG` (ou `STRING`) |
| `FLOAT, REAL, DOUBLE` | `DOUBLE` |
| `DECIMAL` | `STRING` |
| `BOOLEAN, BIT` | `BOOLEAN` |
| `BLOB, BINARY, LONGVARBINARY, VARBINARY` | `BLOB` |
| `CLOB` | `STRING` |
| Outros tipos (incluindo tipos relacionados a data e hora) | `STRING` |
**nota**
Você pode especificar o tipo de dados `LONG` ou `STRING` em sua chamada de API de dados para valores `LONG` retornados pelo banco de dados. Recomendamos que você faça isso para evitar perder precisão para números extremamente grandes, o que pode acontecer quando você trabalha com JavaScript.
Determinados tipos, como `DECIMAL` e `TIME`, exigem uma dica para que a API de dados transmita valores `String` ao banco de dados como o tipo correto. Para usar uma dica, inclua valores de `typeHint` no tipo de dados `SqlParameter`. Os valores possíveis para `typeHint` são os seguintes:
+ `DATE`: o valor de parâmetro correspondente `String` é enviado como objeto do tipo `DATE` para o banco de dados. O formato aceito é `YYYY-MM-DD`.
+ `DECIMAL`: o valor de parâmetro correspondente `String` é enviado como objeto do tipo `DECIMAL` para o banco de dados.
+ `JSON`: o valor de parâmetro correspondente `String` é enviado como objeto do tipo `JSON` para o banco de dados.
+ `TIME`: o valor de parâmetro correspondente `String` é enviado como objeto do tipo `TIME` para o banco de dados. O formato aceito é `HH:MM:SS[.FFF]`.
+ `TIMESTAMP`: o valor de parâmetro correspondente `String` é enviado como objeto do tipo `TIMESTAMP` para o banco de dados. O formato aceito é `YYYY-MM-DD HH:MM:SS[.FFF]`.
+ `UUID`: o valor de parâmetro correspondente `String` é enviado como objeto do tipo `UUID` para o banco de dados.
**nota**
No momento, a API de dados não é compatível com as matrizes de identificadores únicos universais (UUIDs).
**nota**
Para o Amazon Aurora PostgreSQL, a API de dados sempre exibe o tipo de dados `TIMESTAMPTZ` do Aurora PostgreSQL no fuso horário UTC.
# Chamar a API de dados do Amazon RDS com a AWS CLI
É possível chamar a API de dados do RDS (API de dados) usando a AWS CLI.
Os exemplos a seguir usam a AWS CLI para a API de dados. Para obter mais informações, consulte [AWS CLI Referência para a API de dados](https://docs.aws.amazon.com/cli/latest/reference/rds-data/index.html).
Em cada exemplo, substitua o nome do recurso da Amazon (ARN) do cluster de banco de dados pelo ARN do cluster de banco de dados do Aurora. Além disso, substitua o ARN do segredo pelo ARN do segredo no Secrets Manager que concede acesso ao cluster de banco de dados.
**nota**
A AWS CLI pode formatar respostas em JSON.
**Topics**
+ [Iniciar uma transação SQL](#data-api.calling.cli.begin-transaction)
+ [Executar uma instrução SQL](#data-api.calling.cli.execute-statement)
+ [Executar uma instrução SQL em lote em uma matriz de dados](#data-api.calling.cli.batch-execute-statement)
+ [Confirmar uma transação SQL](#data-api.calling.cli.commit-transaction)
+ [Reverter uma transação SQL](#data-api.calling.cli.rollback-transaction)
## Iniciar uma transação SQL
Você pode iniciar uma transação SQL usando o comando `aws rds-data begin-transaction` da CLI. A chamada retorna um identificador da transação.
**Importante**
Com a API de dados, uma transação atinge o tempo limite quando não ocorre nenhuma chamada que usa o ID da respectiva transação no espaço de três minutos. Caso uma transação atinja o tempo limite antes de ser confirmada, a API de dados a reverte automaticamente.
As instruções da linguagem de definição de dados (DDL) do MySQL dentro de uma transação causam uma confirmação implícita. Recomendamos que você execute cada instrução de DDL do MySQL em um comando `execute-statement` separado com a opção `--continue-after-timeout`.
Além das opções comuns, especifique a opção `--database`, que fornece o nome do banco de dados.
Por exemplo, o comando da CLI a seguir inicia uma transação SQL.
Para Linux, macOS ou Unix:
```
aws rds-data begin-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret"
```
Para Windows:
```
aws rds-data begin-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret"
```
Este é um exemplo da resposta.
```
{
"transactionId": "ABC1234567890xyz"
}
```
## Executar uma instrução SQL
Você pode executar uma instrução SQL usando o comando `aws rds-data execute-statement` da CLI.
Você pode executar a instrução SQL em uma transação especificando o identificador da transação com a opção `--transaction-id`. Você pode iniciar uma transação usando o comando `aws rds-data begin-transaction` da CLI. Você pode encerrar e confirmar uma transação usando o comando `aws rds-data commit-transaction` da CLI.
**Importante**
Se você não especificar a opção `--transaction-id`, as alterações resultantes da chamadas serão confirmadas automaticamente.
Além das opções comuns, especifique as opções a seguir:
+ `--sql` (obrigatório): uma instrução SQL para ser executada no cluster de banco de dados.
+ `--transaction-id` (opcional): o identificador de uma transação que foi iniciada usando o comando `begin-transaction` da CLI. Especifique o ID da transação que você deseja incluir na instrução SQL.
+ `--parameters` (opcional): os parâmetros para a instrução SQL.
+ `--include-result-metadata | --no-include-result-metadata` (opcional): um valor que indica se os metadados devem ou não ser incluídos no resultado. O padrão é `--no-include-result-metadata`.
+ `--database` (opcional): o nome do banco de dados.
A opção `--database` pode não funcionar quando você executa uma instrução SQL depois de executar `--sql "use database_name;"` na solicitação anterior. Recomendamos que você use a opção `--database` em vez de executar instruções `--sql "use database_name;"`.
+ `--continue-after-timeout | --no-continue-after-timeout` (opcional): um valor que indica se a instrução deve continuar a ser executada depois que a chamada excede o intervalo de 45 segundos do tempo limite da API de dados. O padrão é `--no-continue-after-timeout`.
Para instruções DDL (linguagem de definição de dados, data definition language), recomendamos continuar a executar a instrução depois que a chamada expira para evitar erros e a possibilidade de estruturas de dados corrompidos.
+ `--format-records-as "JSON"|"NONE"`: um valor opcional que especifica se o conjunto de resultados será formatado como uma string JSON. O padrão é `"NONE"`. Para obter informações de uso sobre o processamento de conjuntos de resultados JSON, consulte [Processar resultados de consulta da API de dados do Amazon RDS no formato JSON](data-api-json.md).
O cluster de banco de dados retorna uma resposta para a chamada.
**nota**
O limite de tamanho da resposta é de 1 MiB. Se a chamada retornar mais que 1 MiB de dados de resposta, ela será encerrada.
No Aurora Serverless v1, o número máximo de solicitações por segundo é mil. Para todos os outros bancos de dados compatíveis, não há limite.
Por exemplo, o comando da CLI a seguir executa uma única instrução SQL e omite os metadados nos resultados (o padrão).
Para Linux, macOS ou Unix:
```
aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--sql "select * from mytable"
```
Para Windows:
```
aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--sql "select * from mytable"
```
Este é um exemplo da resposta.
```
{
"numberOfRecordsUpdated": 0,
"records": [
[
{
"longValue": 1
},
{
"stringValue": "ValueOne"
}
],
[
{
"longValue": 2
},
{
"stringValue": "ValueTwo"
}
],
[
{
"longValue": 3
},
{
"stringValue": "ValueThree"
}
]
]
}
```
O comando da CLI a seguir executa uma única instrução SQL em uma transação especificando a opção `--transaction-id`.
Para Linux, macOS ou Unix:
```
aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--sql "update mytable set quantity=5 where id=201" --transaction-id "ABC1234567890xyz"
```
Para Windows:
```
aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--sql "update mytable set quantity=5 where id=201" --transaction-id "ABC1234567890xyz"
```
Este é um exemplo da resposta.
```
{
"numberOfRecordsUpdated": 1
}
```
O comando da CLI a seguir executa uma única instrução SQL com parâmetros.
Para Linux, macOS ou Unix:
```
aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--sql "insert into mytable values (:id, :val)" --parameters "[{\"name\": \"id\", \"value\": {\"longValue\": 1}},{\"name\": \"val\", \"value\": {\"stringValue\": \"value1\"}}]"
```
Para Windows:
```
aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--sql "insert into mytable values (:id, :val)" --parameters "[{\"name\": \"id\", \"value\": {\"longValue\": 1}},{\"name\": \"val\", \"value\": {\"stringValue\": \"value1\"}}]"
```
Este é um exemplo da resposta.
```
{
"numberOfRecordsUpdated": 1
}
```
O comando da CLI a seguir executa uma instrução SQL da linguagem de definição de dados (DDL). A instrução DDL renomeia a coluna `job` para coluna `role`.
**Importante**
Para instruções DDL, recomendamos continuar a executar a instrução depois que a chamada expira. Quando uma instrução DDL é encerrada antes que ela termine de ser executada, podem ocorrer erros e possivelmente estruturas de dados corrompidos. Para continuar a executar uma instrução depois que uma chamada excede o intervalo de 45 segundos do tempo limite da API de dados do RDS, especifique a opção `--continue-after-timeout`.
Para Linux, macOS ou Unix:
```
aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--sql "alter table mytable change column job role varchar(100)" --continue-after-timeout
```
Para Windows:
```
aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--sql "alter table mytable change column job role varchar(100)" --continue-after-timeout
```
Este é um exemplo da resposta.
```
{
"generatedFields": [],
"numberOfRecordsUpdated": 0
}
```
**nota**
Os dados `generatedFields` não são compatíveis com o Aurora PostgreSQL. Para obter os valores de campos gerados, use a cláusula `RETURNING`. Para obter mais informações, consulte [ Returning data from modified rows](https://www.postgresql.org/docs/10/dml-returning.html) na documentação do PostgreSQL.
## Executar uma instrução SQL em lote em uma matriz de dados
Você pode executar uma instrução SQL em lote em uma matriz de dados usando o comando `aws rds-data batch-execute-statement` da CLI. Você pode usar esse comando para executar uma importação em massa ou uma operação de atualização.
Você pode executar a instrução SQL em uma transação especificando o identificador da transação com a opção `--transaction-id`. Você pode iniciar uma transação usando o comando `aws rds-data begin-transaction` da CLI. Você pode encerrar e confirmar uma transação usando o comando `aws rds-data commit-transaction` da CLI.
**Importante**
Se você não especificar a opção `--transaction-id`, as alterações resultantes da chamadas serão confirmadas automaticamente.
Além das opções comuns, especifique as opções a seguir:
+ `--sql` (obrigatório): uma instrução SQL para ser executada no cluster de banco de dados.
**dica**
Para obter instruções compatíveis com o MySQL, não inclua ponto e vírgula no final do parâmetro `--sql`. Um ponto e vírgula à direita pode causar um erro de sintaxe.
+ `--transaction-id` (opcional): o identificador de uma transação que foi iniciada usando o comando `begin-transaction` da CLI. Especifique o ID da transação que você deseja incluir na instrução SQL.
+ `--parameter-set` (opcional): os conjuntos de parâmetros para a operação em lote.
+ `--database` (opcional): o nome do banco de dados.
O cluster de banco de dados retorna uma resposta para a chamada.
**nota**
Não há um limite posterior fixo para o número de conjuntos de parâmetros. No entanto, o tamanho máximo da solicitação HTTP enviada via API de dados é 4 MiB. Se a solicitação exceder esse limite, a API de dados exibirá um erro e não processará a solicitação. Este limite de 4 MiB inclui o tamanho dos cabeçalhos HTTP e a notação JSON na solicitação. Assim, o número de conjuntos de parâmetros que você pode incluir depende de uma combinação de fatores, como o tamanho da instrução SQL e o tamanho de cada conjunto de parâmetros.
O limite de tamanho da resposta é de 1 MiB. Se a chamada retornar mais que 1 MiB de dados de resposta, ela será encerrada.
No Aurora Serverless v1, o número máximo de solicitações por segundo é mil. Para todos os outros bancos de dados compatíveis, não há limite.
Por exemplo, o comando da CLI a seguir executa uma instrução SQL em lote em uma matriz de dados com um conjunto de parâmetros.
Para Linux, macOS ou Unix:
```
aws rds-data batch-execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--sql "insert into mytable values (:id, :val)" \
--parameter-sets "[[{\"name\": \"id\", \"value\": {\"longValue\": 1}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueOne\"}}],
[{\"name\": \"id\", \"value\": {\"longValue\": 2}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueTwo\"}}],
[{\"name\": \"id\", \"value\": {\"longValue\": 3}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueThree\"}}]]"
```
Para Windows:
```
aws rds-data batch-execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--sql "insert into mytable values (:id, :val)" ^
--parameter-sets "[[{\"name\": \"id\", \"value\": {\"longValue\": 1}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueOne\"}}],
[{\"name\": \"id\", \"value\": {\"longValue\": 2}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueTwo\"}}],
[{\"name\": \"id\", \"value\": {\"longValue\": 3}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueThree\"}}]]"
```
**nota**
Não inclua quebras de linha na opção `--parameter-sets`.
## Confirmar uma transação SQL
Com o uso do comando `aws rds-data commit-transaction` da CLI, você pode encerrar uma transação SQL que iniciou com `aws rds-data begin-transaction` e confirmar as alterações.
Além das opções comuns, especifique a opção a seguir:
+ `--transaction-id` (obrigatório): o identificador de uma transação que foi iniciada usando o comando `begin-transaction` da CLI. Especifique o ID da transação que você deseja encerrar e confirmar.
Por exemplo, o comando da CLI a seguir encerra uma transação SQL e confirma as alterações.
Para Linux, macOS ou Unix:
```
aws rds-data commit-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--transaction-id "ABC1234567890xyz"
```
Para Windows:
```
aws rds-data commit-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--transaction-id "ABC1234567890xyz"
```
Este é um exemplo da resposta.
```
{
"transactionStatus": "Transaction Committed"
}
```
## Reverter uma transação SQL
Com o uso do comando `aws rds-data rollback-transaction` da CLI, você pode reverter uma transação SQL que iniciou com `aws rds-data begin-transaction`. Reverter uma transação cancela as alterações feitas nela.
**Importante**
Se o ID da transação expirou, a transação foi revertida automaticamente. Nesse caso, um comando `aws rds-data rollback-transaction` que especifica o ID da transação expirado retorna um erro.
Além das opções comuns, especifique a opção a seguir:
+ `--transaction-id` (obrigatório): o identificador de uma transação que foi iniciada usando o comando `begin-transaction` da CLI. Especifique o ID da transação que você deseja reverter.
Por exemplo, o comando da AWS CLI a seguir reverte uma transação SQL.
Para Linux, macOS ou Unix:
```
aws rds-data rollback-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--transaction-id "ABC1234567890xyz"
```
Para Windows:
```
aws rds-data rollback-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--transaction-id "ABC1234567890xyz"
```
Este é um exemplo da resposta.
```
{
"transactionStatus": "Rollback Complete"
}
```
# Chamar a API de dados do Amazon RDS por meio de uma aplicação Python
É possível chamar a API de dados do Amazon RDS (API de dados) por meio de uma aplicação Python.
Os exemplos a seguir usam o AWSSDK for Python (Boto). Para obter mais informações sobre o Boto, consulte a [Documentação do AWSSDK for Python (Boto 3)](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html).
Em cada exemplo, substitua o nome do recurso da Amazon (ARN) do cluster de banco de dados pelo ARN do cluster de banco de dados do Aurora. Além disso, substitua o ARN do segredo pelo ARN do segredo no Secrets Manager que concede acesso ao cluster de banco de dados.
**Topics**
+ [Executar uma consulta SQL](#data-api.calling.python.run-query)
+ [Executar uma instrução SQL DML](#data-api.calling.python.run-inert)
+ [Executar uma transação SQL](#data-api.calling.python.run-transaction)
## Executar uma consulta SQL
Você pode executar uma instrução `SELECT` e obter os resultados com uma aplicação Python.
O exemplo a seguir executa uma consulta SQL.
```
import boto3
rdsData = boto3.client('rds-data')
cluster_arn = 'arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster'
secret_arn = 'arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret'
response1 = rdsData.execute_statement(
resourceArn = cluster_arn,
secretArn = secret_arn,
database = 'mydb',
sql = 'select * from employees limit 3')
print (response1['records'])
[
[
{
'longValue': 1
},
{
'stringValue': 'ROSALEZ'
},
{
'stringValue': 'ALEJANDRO'
},
{
'stringValue': '2016-02-15 04:34:33.0'
}
],
[
{
'longValue': 1
},
{
'stringValue': 'DOE'
},
{
'stringValue': 'JANE'
},
{
'stringValue': '2014-05-09 04:34:33.0'
}
],
[
{
'longValue': 1
},
{
'stringValue': 'STILES'
},
{
'stringValue': 'JOHN'
},
{
'stringValue': '2017-09-20 04:34:33.0'
}
]
]
```
## Executar uma instrução SQL DML
Você pode executar uma instrução de linguagem de manipulação de dados (DML) para inserir, atualizar ou excluir dados no banco de dados. Você também pode usar parâmetros em instruções DML.
**Importante**
Se uma chamada não faz parte de uma transação por não incluir o parâmetro `transactionID`, alterações resultantes da chamada são confirmadas automaticamente.
O exemplo a seguir executa um instrução SQL de inserção e usa parâmetros.
```
import boto3
cluster_arn = 'arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster'
secret_arn = 'arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret'
rdsData = boto3.client('rds-data')
param1 = {'name':'firstname', 'value':{'stringValue': 'JACKSON'}}
param2 = {'name':'lastname', 'value':{'stringValue': 'MATEO'}}
paramSet = [param1, param2]
response2 = rdsData.execute_statement(resourceArn=cluster_arn,
secretArn=secret_arn,
database='mydb',
sql='insert into employees(first_name, last_name) VALUES(:firstname, :lastname)',
parameters = paramSet)
print (response2["numberOfRecordsUpdated"])
```
## Executar uma transação SQL
Você pode iniciar uma transação SQL, execute uma ou mais instruções SQL e confirme as alterações com uma aplicação Python.
**Importante**
Uma transação expira se não há chamadas que usam o ID da transação em três minutos. Se uma transação expira antes de ser confirmada, ela é revertida automaticamente.
Se você não especificar um ID de transação, as alterações resultantes da chamadas serão confirmadas automaticamente.
O exemplo a seguir executa uma transação SQL que insere uma linha em uma tabela.
```
import boto3
rdsData = boto3.client('rds-data')
cluster_arn = 'arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster'
secret_arn = 'arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret'
tr = rdsData.begin_transaction(
resourceArn = cluster_arn,
secretArn = secret_arn,
database = 'mydb')
response3 = rdsData.execute_statement(
resourceArn = cluster_arn,
secretArn = secret_arn,
database = 'mydb',
sql = 'insert into employees(first_name, last_name) values('XIULAN', 'WANG')',
transactionId = tr['transactionId'])
cr = rdsData.commit_transaction(
resourceArn = cluster_arn,
secretArn = secret_arn,
transactionId = tr['transactionId'])
cr['transactionStatus']
'Transaction Committed'
response3['numberOfRecordsUpdated']
1
```
**nota**
Se você executar uma instrução de linguagem de definição de dados (DDL), recomendamos continuar a executar a instrução depois que a chamada expira. Quando uma instrução DDL é encerrada antes que ela termine de ser executada, podem ocorrer erros e possivelmente estruturas de dados corrompidos. Para continuar a executar uma instrução depois que uma chamada ultrapassa o intervalo de tempo limite de 45 segundos da API de dados do RDS, defina o parâmetro `continueAfterTimeout` como `true`.
# Chamar a API de dados do Amazon RDS por meio de uma aplicação Java
É possível chamar a API de dados do Amazon RDS (API de dados) por meio de uma aplicação Java.
Os exemplos a seguir usam o AWS SDK for Java. Para obter mais informações, consulte o [Guia do desenvolvedor do AWS SDK para Java](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/welcome.html).
Em cada exemplo, substitua o nome do recurso da Amazon (ARN) do cluster de banco de dados pelo ARN do cluster de banco de dados do Aurora. Além disso, substitua o ARN do segredo pelo ARN do segredo no Secrets Manager que concede acesso ao cluster de banco de dados.
**Topics**
+ [Executar uma consulta SQL](#data-api.calling.java.run-query)
+ [Executar uma transação SQL](#data-api.calling.java.run-transaction)
+ [Executar uma operação SQL em lote](#data-api.calling.java.run-batch)
## Executar uma consulta SQL
Você pode executar uma instrução `SELECT` e obter os resultados com uma aplicação Java.
O exemplo a seguir executa uma consulta SQL.
```
package com.amazonaws.rdsdata.examples;
import com.amazonaws.services.rdsdata.AWSRDSData;
import com.amazonaws.services.rdsdata.AWSRDSDataClient;
import com.amazonaws.services.rdsdata.model.ExecuteStatementRequest;
import com.amazonaws.services.rdsdata.model.ExecuteStatementResult;
import com.amazonaws.services.rdsdata.model.Field;
import java.util.List;
public class FetchResultsExample {
public static final String RESOURCE_ARN = "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster";
public static final String SECRET_ARN = "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret";
public static void main(String[] args) {
AWSRDSData rdsData = AWSRDSDataClient.builder().build();
ExecuteStatementRequest request = new ExecuteStatementRequest()
.withResourceArn(RESOURCE_ARN)
.withSecretArn(SECRET_ARN)
.withDatabase("mydb")
.withSql("select * from mytable");
ExecuteStatementResult result = rdsData.executeStatement(request);
for (List fields: result.getRecords()) {
String stringValue = fields.get(0).getStringValue();
long numberValue = fields.get(1).getLongValue();
System.out.println(String.format("Fetched row: string = %s, number = %d", stringValue, numberValue));
}
}
}
```
## Executar uma transação SQL
Você pode iniciar uma transação SQL, execute uma ou mais instruções SQL e confirme as alterações com uma aplicação Java.
**Importante**
Uma transação expira se não há chamadas que usam o ID da transação em três minutos. Se uma transação expira antes de ser confirmada, ela é revertida automaticamente.
Se você não especificar um ID de transação, as alterações resultantes da chamadas serão confirmadas automaticamente.
O exemplo a seguir executa uma transação SQL.
```
package com.amazonaws.rdsdata.examples;
import com.amazonaws.services.rdsdata.AWSRDSData;
import com.amazonaws.services.rdsdata.AWSRDSDataClient;
import com.amazonaws.services.rdsdata.model.BeginTransactionRequest;
import com.amazonaws.services.rdsdata.model.BeginTransactionResult;
import com.amazonaws.services.rdsdata.model.CommitTransactionRequest;
import com.amazonaws.services.rdsdata.model.ExecuteStatementRequest;
public class TransactionExample {
public static final String RESOURCE_ARN = "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster";
public static final String SECRET_ARN = "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret";
public static void main(String[] args) {
AWSRDSData rdsData = AWSRDSDataClient.builder().build();
BeginTransactionRequest beginTransactionRequest = new BeginTransactionRequest()
.withResourceArn(RESOURCE_ARN)
.withSecretArn(SECRET_ARN)
.withDatabase("mydb");
BeginTransactionResult beginTransactionResult = rdsData.beginTransaction(beginTransactionRequest);
String transactionId = beginTransactionResult.getTransactionId();
ExecuteStatementRequest executeStatementRequest = new ExecuteStatementRequest()
.withTransactionId(transactionId)
.withResourceArn(RESOURCE_ARN)
.withSecretArn(SECRET_ARN)
.withSql("INSERT INTO test_table VALUES ('hello world!')");
rdsData.executeStatement(executeStatementRequest);
CommitTransactionRequest commitTransactionRequest = new CommitTransactionRequest()
.withTransactionId(transactionId)
.withResourceArn(RESOURCE_ARN)
.withSecretArn(SECRET_ARN);
rdsData.commitTransaction(commitTransactionRequest);
}
}
```
**nota**
Se você executar uma instrução de linguagem de definição de dados (DDL), recomendamos continuar a executar a instrução depois que a chamada expira. Quando uma instrução DDL é encerrada antes que ela termine de ser executada, podem ocorrer erros e possivelmente estruturas de dados corrompidos. Para continuar a executar uma instrução depois que uma chamada ultrapassa o intervalo de tempo limite de 45 segundos da API de dados do RDS, defina o parâmetro `continueAfterTimeout` como `true`.
## Executar uma operação SQL em lote
Você pode executar operações de atualização e inserção em massa em uma matriz de dados com uma aplicação Java. Você pode executar uma instrução DML com matriz de conjuntos de parâmetros.
**Importante**
Se você não especificar um ID de transação, as alterações resultantes da chamadas serão confirmadas automaticamente.
O exemplo a seguir executa uma operação de inserção em lote.
```
package com.amazonaws.rdsdata.examples;
import com.amazonaws.services.rdsdata.AWSRDSData;
import com.amazonaws.services.rdsdata.AWSRDSDataClient;
import com.amazonaws.services.rdsdata.model.BatchExecuteStatementRequest;
import com.amazonaws.services.rdsdata.model.Field;
import com.amazonaws.services.rdsdata.model.SqlParameter;
import java.util.Arrays;
public class BatchExecuteExample {
public static final String RESOURCE_ARN = "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster";
public static final String SECRET_ARN = "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret";
public static void main(String[] args) {
AWSRDSData rdsData = AWSRDSDataClient.builder().build();
BatchExecuteStatementRequest request = new BatchExecuteStatementRequest()
.withDatabase("test")
.withResourceArn(RESOURCE_ARN)
.withSecretArn(SECRET_ARN)
.withSql("INSERT INTO test_table2 VALUES (:string, :number)")
.withParameterSets(Arrays.asList(
Arrays.asList(
new SqlParameter().withName("string").withValue(new Field().withStringValue("Hello")),
new SqlParameter().withName("number").withValue(new Field().withLongValue(1L))
),
Arrays.asList(
new SqlParameter().withName("string").withValue(new Field().withStringValue("World")),
new SqlParameter().withName("number").withValue(new Field().withLongValue(2L))
)
));
rdsData.batchExecuteStatement(request);
}
}
```
# Controlar o comportamento de tempo limite da API de dados
Todas as chamadas para a API de dados são síncronas. Suponha que você realize uma operação da API de dados que execute uma instrução SQL, como `INSERT` ou `CREATE TABLE`. Se a chamada da API de dados for retornada com êxito, o processamento de SQL será concluído quando a chamada for retornada.
Por padrão, a API de dados cancelará uma operação e retornará um erro de tempo limite se o processamento da operação não for concluído em 45 segundos. Nesse caso, os dados não são inseridos, a tabela não é criada e assim por diante.
É possível usar a API de dados para realizar operações de longa duração que não podem ser concluídas em 45 segundos. Se você espera que uma operação, como uma operação `INSERT` em massa ou uma operação de DDL em uma tabela grande, leve mais de 45 segundos, especifique o parâmetro `continueAfterTimeout` para a operação `ExecuteStatement`. A aplicação ainda recebe o erro de tempo limite. No entanto, a operação continua em execução e não é cancelada. Para obter um exemplo, consulte [Executar uma transação SQL](data-api.calling.java.md#data-api.calling.java.run-transaction).
Se o SDK da AWS da sua linguagem de programação tiver um período de tempo limite próprio para chamadas de API ou conexões de soquete HTTP, todos esses períodos de tempo limite deverão ser superiores a 45 segundos. Para alguns SDKs, o período de tempo limite é inferior a 45 segundos por padrão. Recomendamos definir qualquer período de tempo limite específico do SDK ou do cliente para pelo menos um minuto. Isso evita a possibilidade de a aplicação receber um erro de tempo limite e garante que a operação da API de dados seja concluída com êxito. Dessa forma, você pode ter certeza sobre se deve tentar novamente a operação ou não.
Por exemplo, suponha que o SDK retorne um erro de tempo limite para a aplicação, mas a operação da API de dados ainda seja concluída dentro do respectivo intervalo de tempo limite. Nesse caso, repetir a operação pode inserir dados duplicados ou produzir resultados incorretos. O SDK pode repetir a operação automaticamente, originando dados incorretos sem nenhuma ação da aplicação.
O intervalo de tempo limite é especialmente importante para o SDK para Java 2. Nesse SDK, o tempo limite da chamada de API e o tempo limite do soquete HTTP são de 30 segundos por padrão. Veja um exemplo de como configurar o tempo limite para um valor mais alto:
```
public RdsDataClient createRdsDataClient() {
return RdsDataClient.builder()
.region(Region.US_EAST_1) // Change this to your desired Region
.overrideConfiguration(createOverrideConfiguration())
.httpClientBuilder(createHttpClientBuilder())
.credentialsProvider(defaultCredentialsProvider()) // Change this to your desired credentials provider
.build();
}
private static ClientOverrideConfiguration createOverrideConfiguration() {
return ClientOverrideConfiguration.builder()
.apiCallTimeout(Duration.ofSeconds(60))
.build();
}
private HttpClientBuilder createHttpClientBuilder() {
return ApacheHttpClient.builder() // Change this to your desired HttpClient
.socketTimeout(Duration.ofSeconds(60));
}
```
Veja um exemplo equivalente usando o cliente de dados assíncrono:
```
public static RdsDataAsyncClient createRdsDataAsyncClient() {
return RdsDataAsyncClient.builder()
.region(Region.US_EAST_1) // Change this to your desired Region
.overrideConfiguration(createOverrideConfiguration())
.credentialsProvider(defaultCredentialsProvider()) // Change this to your desired credentials provider
.build();
}
private static ClientOverrideConfiguration createOverrideConfiguration() {
return ClientOverrideConfiguration.builder()
.apiCallAttemptTimeout(Duration.ofSeconds(60))
.build();
}
private HttpClientBuilder createHttpClientBuilder() {
return NettyNioAsyncHttpClient.builder() // Change this to your desired AsyncHttpClient
.readTimeout(Duration.ofSeconds(60));
}
```