# Usar a API de dados do Amazon RDS
Usando a API de dados do RDS, é possível trabalhar com uma interface de serviços web para o cluster de banco de dados do Aurora. A API de dados não exige uma conexão persistente com o cluster do banco de dados. Em vez disso, ela oferece um endpoint HTTP seguro e uma integração com SDKs da AWS. Você pode usar o endpoint para executar instruções SQL sem gerenciar conexões.
Os usuários não precisam transmitir as credenciais com chamadas para a API de dados, porque a API de dados usa credenciais de banco de dados armazenadas no AWS Secrets Manager. Para armazenar credenciais no Secrets Manager, os usuários devem receber as permissões apropriadas para usar o Secrets Manager, bem como a API de dados. Para obter mais informações sobre como autorizar usuários, consulte [Autorizar acesso à API de dados do Amazon RDS](data-api.access.md).
Também é possível usar a API de dados para integrar o Amazon Aurora a outras aplicações da AWS, como AWS Lambda, AWS AppSync e AWS Cloud9. A API de dados oferece uma forma mais segura de usar o AWS Lambda. Ela permite que você acesse o cluster de banco de dados sem precisar configurar uma função do Lambda para acessar recursos em uma nuvem privada virtual (VPC). Para obter mais informações, consulte [AWS Lambda](https://aws.amazon.com/lambda/), [AWS AppSync](https://aws.amazon.com/appsync/) e [AWS Cloud9](https://aws.amazon.com/cloud9/).
É possível habilitar a API de dados ao criar o cluster de banco de dados do Aurora. Também é possível modificar a configuração posteriormente. Para obter mais informações, consulte [Habilitar a API de dados do Amazon RDS](data-api.enabling.md).
Depois de habilitar a API de dados, também é possível usar o editor de consultas para executar consultas ad hoc sem configurar uma ferramenta de consulta para acessar o Aurora em uma VPC. Para obter mais informações, consulte [Como usar o editor de consultas do Aurora](query-editor.md).
**Topics**
+ [Disponibilidade de região e versão para a API de dados do Amazon RDS](data-api.regions.md)
+ [Usar o IPv6 com a API de dados do Amazon RDS](data-api.ipv6.md)
+ [Limitações da API de dados do Amazon RDS](data-api.limitations.md)
+ [Comparar os comportamentos da API de dados do Amazon RDS para clusters do Aurora Serverless v2 e provisionados com clusters do Aurora Serverless v1](data-api.differences.md)
+ [Autorizar acesso à API de dados do Amazon RDS](data-api.access.md)
+ [Habilitar a API de dados do Amazon RDS](data-api.enabling.md)
+ [Criar um endpoint da Amazon VPC para a API de dados do Amazon RDS (AWS PrivateLink)](data-api.vpc-endpoint.md)
+ [Chamar a API de dados do Amazon RDS](data-api.calling.md)
+ [Usar a biblioteca do cliente Java para a API de dados do RDS](data-api.java-client-library.md)
+ [Processar resultados de consulta da API de dados do Amazon RDS no formato JSON](data-api-json.md)
+ [Solução de problemas com a API de dados do Amazon RDS](data-api.troubleshooting.md)
+ [Registrar em log chamadas da API de dados do Amazon RDS com o AWS CloudTrail](logging-using-cloudtrail-data-api.md)
+ [Monitorar consultas da API de dados do RDS com o Insights de Performance](monitoring-using-performance-insights-data-api.md)
# Disponibilidade de região e versão para a API de dados do Amazon RDS
Para ter informações sobre as regiões e as versões do mecanismo disponíveis para a API de dados, consulte as seções a seguir.
| Tipo de cluster | Disponibilidade de regiões e versões |
| --- | --- |
| Aurora PostgreSQL provisionado e Sem Servidor v2 | [API de dados do RDS para o Aurora PostgreSQL Sem Servidor v2 e provisionado](Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.md#Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.apg) |
| Aurora MySQL provisionado e Sem Servidor v2 | [API de dados com o Aurora MySQL Sem Servidor v2 e provisionado](Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.md#Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.ams) |
| Aurora PostgreSQL Sem Servidor v1 | [API de dados com o Aurora PostgreSQL Sem Servidor v1](Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.md#Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.apg-sv1) |
| Aurora MySQL Sem Servidor v1 | [API de dados com o Aurora MySQL Sem Servidor v1](Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.md#Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.amy) |
Se forem necessários módulos criptográficos validados pelo FIPS 140-2 ao acessar a API de dados por meio de uma interface de linha de comandos ou uma API, use um endpoint do FIPS. Para ter mais informações sobre endpoints do FIPS disponíveis, consulte [Federal Information Processing Standard (FIPS) 140-2](https://aws.amazon.com/compliance/fips/).
# Usar o IPv6 com a API de dados do Amazon RDS
A API de dados do Amazon RDS aceita a conectividade IPv6 por meio de endpoints de pilha dupla. Isso permite que você se conecte à API de dados usando endereços IPv6, mantendo a compatibilidade com versões anteriores com IPv4.
## Suporte a endpoints IPv6
A API de dados fornece endpoints de pilha dupla que aceitam conexões IPv4 e IPv6. Esses endpoints usam o domínio `.aws` em vez do `.amazonaws.com` tradicional.
### Tipos de endpoint disponíveis
Endpoints de pilha dupla públicos
Formato: `rds-data.region.api.aws`
Exemplo: `rds-data.us-east-1.api.aws`
Endpoints de pilha dupla FIPS
Formato: `rds-data-fips.region.api.aws`
Exemplo: `rds-data-fips.us-east-1.api.aws`
Endpoints IPv6 do PrivateLink
Disponível por meio de endpoints da VPC com suporte a IPv6
Permite conectividade IPv6 privada em sua VPC
### Endpoints legados somente para IPv4
Os endpoints `.amazonaws.com` existentes continuam aceitando conexões somente IPv4:
+ `rds-data.region.amazonaws.com`
+ `rds-data-fips.region.amazonaws.com`
**nota**
Os endpoints legados permanecem inalterados para garantir a compatibilidade com versões anteriores das aplicações existentes.
## Usar endpoints IPv6
Para usar o IPv6 com a API de dados, atualize sua aplicação para usar os novos endpoints de pilha dupla. Sua aplicação usará automaticamente o IPv6, se disponível, ou retornará ao IPv4.
Para receber orientação geral sobre como configurar o IPv6 em sua VPC, consulte [Migrar para IPv6](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-migrate-ipv6.html) no *Manual do usuário da Amazon VPC*.
É possível configurar endpoints IPv6 de duas maneiras:
+ **Usando a variável de ambiente**: defina `AWS_USE_DUALSTACK_ENDPOINT=true` em seu ambiente IPv6. Os SDKs AWS CLI e AWS construirão automaticamente os endpoints da `api.aws` apropriados sem exigir que você especifique manualmente os URLs dos endpoints.
+ **Usando URLs de endpoint explícitos**: especifique o URL do endpoint de pilha dupla diretamente em seus comandos da AWS CLI ou na configuração do SDK, conforme mostrado nos exemplos abaixo.
### AWS CLIConfiguração da
Configure a AWS CLI para usar endpoints IPv6 especificando o URL do endpoint:
Para Linux, macOS ou Unix:
```
aws rds-data execute-statement \
--endpoint-url https://rds-data.us-east-1.api.aws \
--resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:my-cluster" \
--secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:my-secret" \
--database "mydb" \
--sql "SELECT * FROM users LIMIT 10"
```
Para Windows:
```
aws rds-data execute-statement ^
--endpoint-url https://rds-data.us-east-1.api.aws ^
--resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:my-cluster" ^
--secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:my-secret" ^
--database "mydb" ^
--sql "SELECT * FROM users LIMIT 10"
```
### Configuração do AWS SDK
Configure os AWS SDKs para usar endpoints de pilha dupla:
------
#### [ Python ]
```
import boto3
# Create RDS Data API client with IPv6 dual-stack endpoint
client = boto3.client(
'rds-data',
endpoint_url='https://rds-data.us-east-1.api.aws'
)
# Execute a SQL statement
response = client.execute_statement(
resourceArn='arn:aws:rds:us-east-1:123456789012:cluster:my-cluster',
secretArn='arn:aws:secretsmanager:us-east-1:123456789012:secret:my-secret',
database='mydb',
sql='SELECT * FROM users LIMIT 10'
)
print(response['records'])
```
------
#### [ Java ]
```
import software.amazon.awssdk.services.rdsdata.RdsDataClient;
import software.amazon.awssdk.services.rdsdata.model.ExecuteStatementRequest;
import software.amazon.awssdk.services.rdsdata.model.ExecuteStatementResponse;
import java.net.URI;
// Create RDS Data API client with IPv6 dual-stack endpoint
RdsDataClient client = RdsDataClient.builder()
.endpointOverride(URI.create("https://rds-data.us-east-1.api.aws"))
.build();
// Execute a SQL statement
ExecuteStatementRequest request = ExecuteStatementRequest.builder()
.resourceArn("arn:aws:rds:us-east-1:123456789012:cluster:my-cluster")
.secretArn("arn:aws:secretsmanager:us-east-1:123456789012:secret:my-secret")
.database("mydb")
.sql("SELECT * FROM users LIMIT 10")
.build();
ExecuteStatementResponse response = client.executeStatement(request);
System.out.println(response.records());
```
------
#### [ JavaScript ]
```
const { RDSDataClient, ExecuteStatementCommand } = require("@aws-sdk/client-rds-data");
// Create RDS Data API client with IPv6 dual-stack endpoint
const client = new RDSDataClient({
endpoint: "https://rds-data.us-east-1.api.aws"
});
// Execute a SQL statement
const command = new ExecuteStatementCommand({
resourceArn: "arn:aws:rds:us-east-1:123456789012:cluster:my-cluster",
secretArn: "arn:aws:secretsmanager:us-east-1:123456789012:secret:my-secret",
database: "mydb",
sql: "SELECT * FROM users LIMIT 10"
});
const response = await client.send(command);
console.log(response.records);
```
------
## Usar AWS PrivateLink com o IPv6
Você pode criar endpoints da VPC para a API de dados que comportem a conectividade IPv6 em sua VPC. Para receber instruções detalhadas sobre a criação de endpoints da VPC para a API de dados, consulte [Criar um endpoint da Amazon VPC para a API de dados do Amazon RDS (AWS PrivateLink)](data-api.vpc-endpoint.md).
Ao criar um endpoint da VPC para suporte a IPv6, garanta que:
+ Sua VPC e sub-redes estão configuradas para comportar IPv6.
+ Grupos de segurança permitam tráfego IPv6 nas portas necessárias (normalmente 443 para HTTPS).
+ As ACLs de rede sejam configuradas para permitir tráfego IPv6.
## Considerações sobre a migração
Ao migrar para endpoints IPv6, pense no seguinte:
+ **Migração gradual**: você pode migrar aplicações gradualmente, uma por vez, atualizando os URLs dos endpoints.
+ **Compatibilidade de rede**: garanta que sua infraestrutura de rede aceite IPv6 antes de migrar.
+ **Políticas de segurança**: atualize as regras do grupo de segurança e as ACLs de rede para permitir o tráfego IPv6, se necessário.
+ **Monitoramento**: atualize as configurações de monitoramento e registro em log para lidar com endereços IPv6.
**nota**
**Endereços de conexão de banco de dados**: ao usar endpoints IPv6 para API de dados, as conexões de banco de dados subjacentes e os logs de banco de dados ainda mostrarão endereços IPv4. Esse é o comportamento esperado e não afeta a funcionalidade das aplicações habilitadas para IPv6.
## Solução de problemas de conectividade IPv6
Se você tiver problemas com a conectividade IPv6, confira o seguinte:
Configuração de rede
Confira se sua rede comporta IPv6 e se o roteamento IPv6 está configurado corretamente.
Resolução do DNS
Verifique se seu resolvedor de DNS consegue resolver registros AAAA para os endpoints de pilha dupla.
Grupos de segurança
Atualize os grupos de segurança para permitirem tráfego IPv6 nas portas necessárias (normalmente 443 para HTTPS).
Bibliotecas do cliente
Verifique se as bibliotecas do cliente HTTP aceitam conectividade IPv6 e de pilha dupla.
# Limitações da API de dados do Amazon RDS
A API de dados do RDS tem as seguintes limitações:
+ Só é possível executar consultas da API de dados em instâncias de gravador em um cluster de banco de dados. No entanto, as instâncias de gravador podem aceitar consultas de gravação e leitura.
+ Com os bancos de dados globais do Aurora, é possível habilitar a API de dados em clusters de banco de dados primários e secundários. No entanto, um cluster secundário não terá uma instância de gravador até ser promovido a primário. A API de dados requer acesso à instância de gravador para processamento de consultas, mesmo para consultas de leitura. Como resultado, as consultas de leitura e gravação enviadas ao cluster secundário falham enquanto ele não possui uma instância de gravador. Quando um cluster secundário é promovido e tem uma instância de gravador disponível, as consultas da API de dados nessa instância de banco de dados são bem-sucedidas.
+ A API de dados não é compatível com as classes de instância de banco de dados T.
+ Em relação ao Aurora Serverless v2 e aos clusters de banco de dados provisionados, a API de dados do RDS não é compatível com alguns tipos de dados. Para ver uma lista de tipos compatíveis consulte [Comparar os comportamentos da API de dados do Amazon RDS para clusters do Aurora Serverless v2 e provisionados com clusters do Aurora Serverless v1](data-api.differences.md).
+ Em bancos de dados do Aurora PostgreSQL versão 14 e posterior, a API de dados só é compatível com `scram-sha-256` para criptografia de senha.
+ 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.
+ O limite de tamanho da API de dados é de 64 KB por linha no conjunto de resultados obtido pelo banco de dados. Verifique se cada linha em um conjunto de resultados tem até 64 KB.
# Comparar os comportamentos da API de dados do Amazon RDS para clusters do Aurora Serverless v2 e provisionados com clusters do Aurora Serverless v1
Os aprimoramentos mais recentes das APIs de dados do Amazon RDS as tornam disponíveis para clusters que usam versões recentes dos mecanismos do PostgreSQL ou do MySQL. Esses clusters podem ser configurados para usar o Aurora Serverless v2 ou classes de instância provisionadas, como `db.r6g` ou `db.r6i`.
As seções a seguir descrevem as diferenças da API de dados do Amazon RDS entre clusters de banco de dados do Aurora Serverless v2 e provisionados e clusters de banco de dados do Aurora Serverless v1. Os clusters de banco de dados do Aurora Serverless v1 usam o modo de mecanismo `serverless`. Os clusters de banco de dados provisionados usam o modo de mecanismo `provisioned`. Um cluster de banco de dados Aurora Serverless v2 também usa o modo de mecanismo `provisioned` e contém uma ou mais instâncias de banco de dados Aurora Serverless v2 com a classe de instância `db.serverless`.
## Número máximo de solicitações por segundo
**Aurora Serverless v1**
As APIs de dados podem fazer até mil solicitações por segundo.
**Aurora Serverless v2**
As APIs de dados podem fazer um número ilimitado de solicitações por segundo.
## Habilitar ou desabilitar a API de dados do Amazon RDS em um banco de dados existente
**Aurora Serverless v1**
+ **Com a API do Amazon RDS**: use a operação `ModifyCluster` e especifique `True` ou `False`, conforme aplicável, para o parâmetro `EnableHttpEndpoint`.
+ **Com a AWS CLI**: use a operação `modify-db-cluster` com a opção `--enable-http-endpoint` ou `--no-enable-http-endpoint`, conforme aplicável.
**Aurora Serverless v2**
+ **Com a API do Amazon RDS**: use as operações `EnableHttpEndpoint` e `DisableHttpEndpoint`.
+ **Com a AWS CLI**: use as operações `enable-http-endpoint` e `disable-http-endpoint`.
## Eventos do CloudTrail
**Aurora Serverless v1**
Os eventos das chamadas da API de dados são eventos de gerenciamento. Esses eventos são incluídos automaticamente em uma trilha por padrão. Para obter mais informações, consulte [Excluir eventos da API de dados de uma trilha do AWS CloudTrail (somente o Aurora Serverless v1)](logging-using-cloudtrail-data-api.md#logging-using-cloudtrail-data-api.excluding-cloudtrail-events).
**Aurora Serverless v2**
Os eventos das chamadas da API de dados são eventos de dados. Esses eventos são excluídos automaticamente em uma trilha por padrão. Para obter mais informações, consulte [Incluir eventos da API de dados em uma trilha do AWS CloudTrail](logging-using-cloudtrail-data-api.md#logging-using-cloudtrail-data-api.including-cloudtrail-events).
## Suporte a várias declarações
**Aurora Serverless v1**
+ No Aurora MySQL, não há suporte para várias declarações.
+ Para o Aurora PostgreSQL, várias declarações exibem somente a primeira resposta da consulta.
**Aurora Serverless v2**
Não há suporte a várias declarações. A tentativa de executar várias instruções em uma única chamada de API exibe `“An error occurred (ValidationException) when calling the ExecuteStatement operation: Multistatements aren't supported.”`. Para executar várias instruções, faça chamadas de API `ExecuteStatement` separadas ou use `BatchExecuteStatement` para processamento em lote.
O exemplo a seguir mostra a mensagem de erro resultante de uma chamada de API que tenta executar várias instruções.
```
aws rds-data execute-statement \
--resource-arn "arn:aws:rds:region:account:cluster:cluster-name" \
--secret-arn "arn:aws:secretsmanager:region:account:secret:secret-name" \
--database "your_database" \
--sql "SELECT * FROM your_table; Select * FROM next_table;
"An error occurred (ValidationException) when calling the ExecuteStatement operation: Multistatements aren't supported.
```
O exemplo a seguir executa várias instruções com chamadas de API `ExecuteStatement` separadas.
```
aws rds-data execute-statement \
--resource-arn "arn:aws:rds:region:account:cluster:cluster-name" \
--secret-arn "arn:aws:secretsmanager:region:account:secret:secret-name" \
--database "your_database" \
--sql "SELECT * FROM your_table;"
aws rds-data execute-statement \
--resource-arn "arn:aws:rds:region:account:cluster:cluster-name" \
--secret-arn "arn:aws:secretsmanager:region:account:secret:secret-name" \
--database "your_database" \
--sql "SELECT * FROM next_table;"
```
## Solicitações simultâneas para o mesmo ID de transação
**Aurora Serverless v1**
As solicitações subsequentes aguardam até que a solicitação atual seja concluída. Sua aplicação precisará lidar com erros de tempo limite se o período de espera for muito longo.
**Aurora Serverless v2**
Quando a API de dados recebe várias solicitações com o mesmo ID de transação, ela retorna imediatamente este erro:
`DatabaseErrorException: Transaction is still running a query`
Esse erro ocorre em duas situações:
+ A aplicação faz solicitações assíncronas (como promessas de JavaScript) usando o mesmo ID de transação.
+ Uma solicitação anterior com esse ID de transação ainda está sendo processada.
O exemplo a seguir mostra todas as solicitações executadas em paralelo com `promise.all()`.
```
const api_calls = [];
for (let i = 0; i < 10; i++) {
api_calls.push(
client.send(
new ExecuteStatementCommand({
...params,
sql: `insert into table_name values (i);`,
transactionId
})
)
);
}
await Promise.all(api_calls);
```
Para resolver esse erro, aguarde a conclusão da solicitação atual antes de enviar outra solicitação com o mesmo ID de transação ou remova o ID da transação para permitir solicitações paralelas.
O exemplo a seguir mostra uma chamada de API que usa execução sequencial com o mesmo ID de transação.
```
for (let i = 0; i < 10; i++) {
await client.send(
new ExecuteStatementCommand({
...params,
sql: `insert into table_name values (i);`,
transactionId
})
).promise()
);
}
```
## Comportamento de BatchExecuteStatement
Para ter mais informações sobre `BatchExecuteStatement`, consulte [BatchExecuteStatement](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_BatchExecuteStatement.html).
**Aurora Serverless v1**
O objeto de campos gerado no resultado da atualização inclui valores inseridos.
**Aurora Serverless v2**
+ Para o Aurora MySQL, o objeto de campos gerado no resultado da atualização tem valores inseridos.
+ Para o Aurora PostgreSQL, o objeto de campos gerado não contém valores.
## Comportamento do ExecuteSQL
Para ter mais informações sobre `ExecuteSQL`, consulte [ExecuteSQL](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_ExecuteSql.html).
**Aurora Serverless v1**
A operação `ExecuteSQL` está obsoleta.
**Aurora Serverless v2**
A operação `ExecuteSQL` não é compatível.
## Comportamento de ExecuteStatement
Para ter mais informações sobre `ExecuteStatement`, consulte [ExecuteStatement](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_ExecuteStatement.html).
**Aurora Serverless v1**
O parâmetro `ExecuteStatement` é compatível com a recuperação de colunas de matriz multidimensionais e todos os tipos de dados avançados.
**Aurora Serverless v2**
O parâmetro `ExecuteStatement` não é compatível com colunas de matriz multidimensionais. Ele também não é compatível com determinados tipos de dados do PostgreSQL, como tipos geométricos e monetários. Quando uma API de dados encontra um tipo de dados incompatível, ela retorna este erro: `UnsupportedResultException: The result contains the unsupported data type data_type`.
Para contornar esse problema, converta o tipo de dados não aceito em `TEXT`. O exemplo a seguir converte um tipo de dados não compatível em `TEXT`.
```
SELECT custom_type::TEXT FROM my_table;--
ORSELECT CAST(custom_type AS TEXT) FROM my_table;
```
Para obter uma lista dos tipos de dados compatíveis com cada mecanismo de banco de dados do Aurora, consulte [Referência de operações da API de dados do Amazon RDS](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/data-api.html#data-api-operations).
## Comportamento do parâmetro de esquema
**Aurora Serverless v1**
O parâmetro `Schema` não é compatível. Quando você inclui o parâmetro `Schema` em uma chamada de API, a API de dados ignora o parâmetro.
**Aurora Serverless v2**
O parâmetro `Schema` está obsoleto. Quando você inclui o parâmetro `Schema` em uma chamada de API, a API de Dados retorna este erro: `ValidationException: The schema parameter isn't supported`. O exemplo a seguir mostra uma chamada da API de dados que retorna o erro `ValidationException`.
```
aws rds-data execute-statement \
--resource-arn "arn:aws:rds:region:account:cluster:cluster-name" \
--secret-arn "arn:aws:secretsmanager:region:account:secret:secret-name" \
--database "your_database" \
--schema "your_schema" \
--sql "SELECT * FROM your_table LIMIT 10"
```
Para resolver esse problema, remova o parâmetro `Schema` da chamada de API.
O exemplo a seguir mostra uma chamada da API de dados com o parâmetro `Schema` removido.
```
aws rds-data execute-statement \
--resource-arn "arn:aws:rds:region:account:cluster:cluster-name" \
--secret-arn "arn:aws:secretsmanager:region:account:secret:secret-name" \
--database "your_database" \
--sql "SELECT * FROM your_table LIMIT 10"
```
# Autorizar acesso à API de dados do Amazon RDS
Os usuários poderão invocar operações da API de dados do Amazon RDS (API de dados) somente se estiverem autorizados a fazê-lo. É possível conceder permissão a um usuário para usar a API de dados anexando uma política do AWS Identity and Access Management (IAM) que defina os privilégios. Também será possível anexar a política a um perfil se você estiver usando perfis do IAM. Uma política gerenciada da AWS, `AmazonRDSDataFullAccess`, inclui permissões para a API de dados.
A política `AmazonRDSDataFullAccess` também inclui permissões para que o usuário obtenha o valor de um segredo do AWS Secrets Manager. Os usuários precisam usar o Secrets Manager para armazenar os segredos que eles podem usar nas chamadas para a API de dados. Com o uso de segredos, os usuários não precisam incluir credenciais de banco de dados para os recursos que eles têm como destino nas chamadas para a API de dados. A API de dados chama de forma transparente o Secrets Manager, que permite (ou nega) a solicitação do usuário para o segredo. Para ter informações sobre como configurar segredos para usar com a API de dados, consulte [Armazenar credenciais de banco de dados no AWS Secrets Manager](#data-api.secrets).
A política `AmazonRDSDataFullAccess` concede acesso completo (por meio da API de dados) aos recursos. É possível restringir o escopo definindo suas próprias políticas que especificam o Nome de recurso da Amazon (ARN) de um recurso.
Por exemplo, a política a seguir mostra um exemplo das permissões mínimas necessárias para um usuário acessar a API de dados para o cluster de banco de dados identificado pelo ARN. A política inclui as permissões necessárias para acessar o Secrets Manager e obter autorização para a instância de banco de dados para o usuário.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "SecretsManagerDbCredentialsAccess",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": "arn:aws:secretsmanager:*:*:secret:rds-db-credentials/*"
},
{
"Sid": "RDSDataServiceAccess",
"Effect": "Allow",
"Action": [
"rds-data:BatchExecuteStatement",
"rds-data:BeginTransaction",
"rds-data:CommitTransaction",
"rds-data:ExecuteStatement",
"rds-data:RollbackTransaction"
],
"Resource": "arn:aws:rds:us-east-2:111122223333:cluster:prod"
}
]
}
```
------
Recomendamos usar um ARN específico para o elemento “Recursos” em suas instruções de política (conforme mostrado no exemplo), em vez de um caractere curinga (\$1).
## Trabalhar com autorização baseada em tags
A API de dados do RDS (API de dados) e o Secrets Manager são compatíveis com a autorização baseada em tags. As *tags* são pares de chave-valor que rotulam um recurso, como um cluster do RDS, com um valor de cadeia de caracteres adicional, por exemplo:
+ `environment:production`
+ `environment:development`
É possível aplicar tags aos recursos para alocação de custos, suporte de operações, controle de acesso e muitas outras finalidades. (Se você ainda não tiver tags em seus recursos e quiser aplicá-las, saiba mais em [Marcar recursos do Amazon RDS](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/USER_Tagging.html).) É possível usar as tags nas instruções de política para limitar o acesso aos clusters do RDS rotulados com essas tags. Como exemplo, um cluster de bancos de dados Aurora pode ter tags que identificam o ambiente como produção ou desenvolvimento.
O exemplo a seguir mostra como é possível usar tags em suas instruções de política. Esta instrução exige que o cluster e o segredo passados na solicitação da API de dados tenham uma tag `environment:production`.
Veja como a política é aplicada: quando um usuário faz uma chamada usando a API de dados, a solicitação é enviada ao serviço. A API de dados primeiro verifica se o ARN de cluster transmitido na solicitação está marcado com `environment:production`. Em seguida, ele chama o Secrets Manager para recuperar o valor do segredo do usuário na solicitação. O Secrets Manager também verifica se o segredo do usuário está marcado com `environment:production`. Em caso afirmativo, a API de dados usa o valor recuperado para a senha de banco de dados do usuário. Por fim, se isso também estiver correto, a solicitação da API de dados é invocada com êxito para o usuário.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "SecretsManagerDbCredentialsAccess",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": "arn:aws:secretsmanager:*:*:secret:rds-db-credentials/*",
"Condition": {
"StringEquals": {
"aws:ResourceTag/environment": [
"production"
]
}
}
},
{
"Sid": "RDSDataServiceAccess",
"Effect": "Allow",
"Action": [
"rds-data:*"
],
"Resource": "arn:aws:rds:us-east-2:111122223333:cluster:*",
"Condition": {
"StringEquals": {
"aws:ResourceTag/environment": [
"production"
]
}
}
}
]
}
```
------
O exemplo mostra ações separadas para `rds-data` e `secretsmanager` para a API de dados e o Secrets Manager. No entanto, é possível combinar ações e definir condições de tag de várias maneiras diferentes para oferecer suporte aos seus casos de uso específicos. Para obter mais informações, consulte [Usar políticas baseadas em identidade (políticas do IAM) para o Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access_identity-based-policies.html#permissions_grant-limited-condition).
No elemento “Condição” da política, é possível escolher chaves de tag entre as seguintes:
+ `aws:TagKeys`
+ `aws:ResourceTag/${TagKey}`
Para saber mais sobre tags de recursos e como usar `aws:TagKeys`, consulte [Como controlar o acesso a recursos da AWS usando tags de recurso](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_tags.html#access_tags_control-tag-keys).
**nota**
A API de dados e o AWS Secrets Manager autorizam usuários. Se não tiver permissões para todas as ações definidas em uma política, você receberá um erro `AccessDeniedException`.
## Armazenar credenciais de banco de dados no AWS Secrets Manager
Ao chamar a API de dados do Amazon RDS (API de dados), transmita as credenciais ao cluster de banco de dados do Aurora usando um segredo no Secrets Manager. Para passar credenciais dessa maneira, especifique o nome do segredo ou o nome de recurso da Amazon (ARN) do segredo.
**Para armazenar credenciais de cluster de banco de dados em um segredo**
1. Use o Secrets Manager para criar um segredo que contenha credenciais para o cluster de bancos de dados Aurora.
Para obter instruções, consulte [Criar um segredo de banco de dados](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_database_secret.html) no *Guia do usuário do AWS Secrets Manager*.
1. Use o console do Secrets Manager para visualizar os detalhes do segredo criado ou execute o comando `aws secretsmanager describe-secret` da AWS CLI.
Anote o nome e o ARN do segredo. É possível usá-los em chamadas para a API de dados.
Para obter mais informações sobre o uso do Secrets Manager, consulte o [Manual do usuário do AWS](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html).
Para entender como o Amazon Aurora lida com o gerenciamento de identidade e acesso, consulte [Como o Amazon Aurora funciona com o IAM](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/security_iam_service-with-iam.html).
Para obter mais informações sobre como criar uma política do IAM, consulte [Criar políticas do IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html) no *Manual do usuário do IAM*. Para obter informações sobre como adicionar uma política do IAM a um usuário, consulte [Adicionar e remover permissões de identidade do IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html) no *Manual do usuário do IAM*.
# Habilitar a API de dados do Amazon RDS
Para usar a API de dados do Amazon RDS (API de dados), habilite-a para o cluster de banco de dados do Aurora. É possível habilitar a API de dados ao criar ou modificar o cluster de banco de dados.
**nota**
A disponibilidade da API de dados para o cluster depende da versão do Aurora, do mecanismo de banco de dados e da região da AWS. Em versões mais antigas do Aurora, a API de dados só funciona com clusters do Aurora Serverless v1. Em versões mais recentes do Aurora, a API de dados funciona com clusters que usam tanto instâncias provisionadas quanto do Aurora Serverless v2. Verifique se o cluster pode usar a API de dados em [Regiões e mecanismos de banco de dados do Aurora compatíveis com a API de dados do RDS](Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.md).
**Topics**
+ [Habilitar a API de dados do RDS ao criar um banco de dados](#data-api.enabling.creating)
+ [Habilitar a API Data do RDS em um banco de dados existente](#data-api.enabling.modifying)
## Habilitar a API de dados do RDS ao criar um banco de dados
Ao criar um banco de dados compatível com a API de dados do RDS (API de dados), é possível habilitar esse recurso. Os procedimentos a seguir descrevem como fazer isso ao usar o Console de gerenciamento da AWS, a AWS CLI ou a API do RDS.
### Console
Para habilitar a API de dados ao criar um cluster de banco de dados, marque a caixa de seleção **Habilitar a API de dados do RDS** na seção **Conectividade** da página **Criar banco de dados**, como no screenshot a seguir.
![\[A seção Conectividade na página Criar banco de dados, com a caixa de seleção Habilitar a API de dados do RDS marcada.\]](http://docs.aws.amazon.com/pt_br/AmazonRDS/latest/AuroraUserGuide/images/data-api-enable-on-create.png)
Para ter instruções sobre como criar um cluster de banco de dados do Aurora que possa usar a API de dados do RDS, consulte o seguinte:
+ Para clusters do Aurora Serverless v2 e provisionados: [Criar um cluster de bancos de dados do Amazon Aurora](Aurora.CreateInstance.md)
+ Para Aurora Serverless v1: [Criar um cluster de banco de dados do Aurora Serverless v1](aurora-serverless.create.md)
### AWS CLI
Para habilitar a API de dados ao criar um cluster de banco de dados do Aurora, execute o comando [AWS CLIcreate-db-cluster](https://docs.aws.amazon.com/cli/latest/reference/rds/create-db-cluster.html) com a opção `--enable-http-endpoint`.
O exemplo a seguir cria um cluster de banco de dados do Aurora PostgreSQL com a API de dados habilitada.
Para Linux, macOS ou Unix:
```
aws rds create-db-cluster \
--db-cluster-identifier my_pg_cluster \
--engine aurora-postgresql \
--enable-http-endpoint
```
Para Windows:
```
aws rds create-db-cluster ^
--db-cluster-identifier my_pg_cluster ^
--engine aurora-postgresql ^
--enable-http-endpoint
```
### API do RDS
Para habilitar a API de dados ao criar um cluster de banco de dados do Aurora, use a operação [CreatedBCluster](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_CreateDBCluster.html) com o valor do parâmetro `EnableHttpEndpoint` definido como `true`.
## Habilitar a API Data do RDS em um banco de dados existente
É possível modificar um cluster de banco de dados compatível com a API de dados do RDS (API de dados) para habilitar ou desabilitar esse recurso.
**Topics**
+ [Habilitar ou desabilitar a API de dados (Aurora Serverless v2 e provisionado)](#data-api.enabling.modifying.all)
+ [Habilitar ou desabilitar a API de dados (somente o Aurora Serverless v1)](#data-api.enabling.modifying.sv1)
### Habilitar ou desabilitar a API de dados (Aurora Serverless v2 e provisionado)
Use os procedimentos a seguir para habilitar ou desabilitar a API de dados em bancos de dados do Aurora Serverless v2 e provisionados. Para habilitar ou desabilitar a API de dados em bancos de dados do Aurora Serverless v1, use os procedimentos em [Habilitar ou desabilitar a API de dados (somente o Aurora Serverless v1)](#data-api.enabling.modifying.sv1).
#### Console
É possível habilitar ou desabilitar a API de dados usando o console do RDS para um cluster de banco de dados que seja compatível com esse recurso. Para fazer isso, abra a página de detalhes do cluster do banco de dados no qual você deseja habilitar ou desabilitar a API de dados e, na guia **Conectividade e segurança**, vá para a seção **API de dados do RDS**. Esta seção exibe o status da API de dados e permite habilitá-la ou desabilitá-la.
O screenshot a seguir mostra que a **API de dados do RDS** não está habilitada.
![\[A seção API de dados do RDS na guia Conectividade e segurança da página de detalhes de um cluster de banco de dados. O status da API de dados é exibido como desabilitado e o botão Habilitar API de dados do RDS está presente.\]](http://docs.aws.amazon.com/pt_br/AmazonRDS/latest/AuroraUserGuide/images/data-api-enable-from-details.png)
#### AWS CLI
Para habilitar ou desabilitar a API de dados em um banco de dados existente, execute o comando [enable-http-endpoint](https://docs.aws.amazon.com/cli/latest/reference/rds/enable-http-endpoint.html) ou [disable-http-endpoint](https://docs.aws.amazon.com/cli/latest/reference/rds/disable-http-endpoint.html) da AWS CLI e especifique o ARN do cluster de banco de dados.
O exemplo a seguir habilita a API de dados.
Para Linux, macOS ou Unix:
```
aws rds enable-http-endpoint \
--resource-arn cluster_arn
```
Para Windows:
```
aws rds enable-http-endpoint ^
--resource-arn cluster_arn
```
#### API do RDS
Para habilitar ou desabilitar a API de dados em um banco de dados existente, use as operações [EnableHttpEndpoint](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_EnableHttpEndpoint.html) e [DisableHttpEndpoint](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_DisableHttpEndpoint.html).
### Habilitar ou desabilitar a API de dados (somente o Aurora Serverless v1)
Use os procedimentos a seguir para habilitar ou desabilitar a API de dados em bancos de dados do Aurora Serverless v1. Para habilitar ou desabilitar a API de dados em bancos de dados do Aurora Serverless v2 e provisionados, use os procedimentos em [Habilitar ou desabilitar a API de dados (Aurora Serverless v2 e provisionado)](#data-api.enabling.modifying.all).
#### Console
Ao modificar um cluster de banco de dados do Aurora Serverless v1, habilite a API de dados na seção **Conectividade** do console do RDS.
O screenshot a seguir mostra a **API de dados** habilitada ao modificar um cluster de banco de dados do Aurora.
![\[Na seção Conectividade na página Modificar cluster de banco de dados, a caixa de seleção API de dados está marcada.\]](http://docs.aws.amazon.com/pt_br/AmazonRDS/latest/AuroraUserGuide/images/data-api-modify-serverlessv1.png)
Para ter instruções sobre como modificar um cluster de banco de dados do Aurora Serverless v1, consulte [Modificar um cluster de banco de dados do Aurora Serverless v1](aurora-serverless.modifying.md).
#### AWS CLI
Para habilitar ou desativar a API de dados, execute o comando [modify-db-cluster](https://docs.aws.amazon.com/cli/latest/reference/rds/modify-db-cluster.html) da AWS CLI com o `--enable-http-endpoint` ou o `--no-enable-http-endpoint`, conforme aplicável.
O exemplo a seguir habilita a API de dados no `sample-cluster`.
Para Linux, macOS ou Unix:
```
aws rds modify-db-cluster \
--db-cluster-identifier sample-cluster \
--enable-http-endpoint
```
Para Windows:
```
aws rds modify-db-cluster ^
--db-cluster-identifier sample-cluster ^
--enable-http-endpoint
```
#### API do RDS
Para habilitar a API de dados, use a operação [ModifyDBCluster](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_ModifyDBCluster.html) e defina o valor de `EnableHttpEndpoint` como `true` ou `false`, conforme aplicável.
# Criar um endpoint da Amazon VPC para a API de dados do Amazon RDS (AWS PrivateLink)
A Amazon VPC permite iniciar recursos da AWS, como clusters de banco de dados e aplicações do Aurora, em uma nuvem privada virtual (VPC). O AWS PrivateLink fornece conectividade privada entre VPCs e produtos da AWS com alta segurança na rede da Amazon. Usando o AWS PrivateLink, é possível criar endpoints da Amazon VPC que permitem que você se conecte a produtos em diferentes contas e VPCs com base na Amazon VPC. Para obter mais informações sobre o AWS PrivateLink, consulte [Serviços do VPC endpoint (AWS PrivateLink)](https://docs.aws.amazon.com/vpc/latest/userguide/endpoint-service.html) no *Manual do usuário da Amazon Virtual Private Cloud*.
É possível chamar a API de dados do RDS (API de dados) com endpoints da Amazon VPC. O uso de um endpoint da Amazon VPC mantém o tráfego entre aplicações na Amazon VPC e a API de dados na rede da AWS sem usar endereços IP públicos. Os endpoints do Amazon VPC podem ajudá-lo a atender aos requisitos normativos e de compatibilidade relacionados à limitação da conectividade pública com a Internet. Por exemplo, ao usar um endpoint da Amazon VPC, é possível manter o tráfego entre uma aplicação em execução em uma instância do Amazon EC2 e a API de dados nas VPCs que as contêm.
Depois de criar o Amazon VPC endpoint, você pode começar a usá-lo sem fazer alterações no código ou na configuração de sua aplicação.
**Como criar um endpoint da Amazon VPC para a API de dados**
1. Faça login no Console de gerenciamento da AWS e abra o console da Amazon VPC em [https://console.aws.amazon.com/vpc/](https://console.aws.amazon.com/vpc/).
1. Escolha **Endpoints** e **Create Endpoint (Criar endpoint)**.
1. Na página **Criar endpoint**, para a **Categoria de serviço**, escolha **Serviços da AWS**. Em **Service Name (Nome do serviço)**, escolha **rds-data**.
![\[Criar um endpoint da Amazon VPC para a API de dados\]](http://docs.aws.amazon.com/pt_br/AmazonRDS/latest/AuroraUserGuide/images/data-api-create-endpoint.png)
1. Em **VPC**, escolha a VPC na qual criar o endpoint.
Escolha a VPC que contém a aplicação que faz chamadas da API de dados.
1. Em **Sub-redes**, escolha a sub-rede de cada zona de disponibilidade (AZ) usada pelo serviço da AWS que está executando a aplicação.
![\[Escolher sub-redes para o Amazon VPC endpoint\]](http://docs.aws.amazon.com/pt_br/AmazonRDS/latest/AuroraUserGuide/images/data-api-vpc-endpoint-subnets.png)
Para criar um Amazon VPC endpoint, especifique o intervalo de endereços IP privados no qual o endpoint estará acessível. Para fazer isso, escolha a sub-rede de cada zona de disponibilidade. Isso restringe o VPC endpoint ao intervalo de endereços IP privados específico para cada zona de disponibilidade e também cria um Amazon VPC endpoint em cada zona de disponibilidade.
1. Em **Enable DNS Name (Habilitar nome DNS)**, selecione **Enable for this endpoint (Habilitar para este endpoint)**.
![\[Habilitar nome DNS para o Amazon VPC endpoint\]](http://docs.aws.amazon.com/pt_br/AmazonRDS/latest/AuroraUserGuide/images/data-api-vpc-endpoint-enable-endpoint.png)
O DNS privado resolve o nome de host DNS da API de dados padrão (`https://rds-data.region.amazonaws.com`) para os endereços IP privados associados ao nome de host DNS específico a seu Amazon VPC endpoint. Como resultado, é possível acessar o endpoint da VPC da API de dados usando a AWS CLI ou os SDKs da AWS sem fazer alterações no código nem na configuração para atualizar o URL do endpoint da API de dados.
1. Em **Security group (Grupo de segurança)**, escolha um grupo de segurança para associar ao Amazon VPC endpoint.
Escolha o grupo de segurança que permite o acesso ao serviço da AWS que está executando sua aplicação. Por exemplo, se uma instância do Amazon EC2 estiver executando sua aplicação, escolha o grupo de segurança que permite o acesso à instância do Amazon EC2. O grupo de segurança permite que você controle o tráfego para o Amazon VPC endpoint nos recursos em sua VPC.
1. Em **Policy (Política)**, escolha **Full Access (Acesso total)** para permitir que qualquer pessoa dentro da Amazon VPC acesse a API de dados por meio desse endpoint. Ou escolha **Custom (Personalizada)** para especificar uma política que limite o acesso.
Se você escolher **Custom (Personalizada)**, insira a política na ferramenta de criação de política.
1. Escolha **Create endpoint (Criar endpoint)**.
Depois que o endpoint for criado, escolha o link no Console de gerenciamento da AWS para visualizar os detalhes do endpoint.
![\[Link para os detalhes do Amazon VPC endpoint\]](http://docs.aws.amazon.com/pt_br/AmazonRDS/latest/AuroraUserGuide/images/data-api-vpc-endpoint-link-to-details.png)
A guia **Details (Detalhes)** do endpoint mostra os nomes de host de DNS que foram gerados durante a criação do Amazon VPC endpoint.
![\[Link para os detalhes do Amazon VPC endpoint\]](http://docs.aws.amazon.com/pt_br/AmazonRDS/latest/AuroraUserGuide/images/data-api-vpc-endpoint-dns-names.png)
Você pode usar o endpoint padrão (`rds-data.region.amazonaws.com`) ou um dos endpoints específicos da VPC para chamar a API de dados dentro da Amazon VPC. O endpoint padrão da API de dados roteia automaticamente para o Amazon VPC endpoint. Esse roteamento ocorre porque o nome de host DNS privado foi habilitado quando o Amazon VPC endpoint foi criado.
Ao usar um endpoint da Amazon VPC em uma chamada da API de dados, todo tráfego entre a aplicação e a API de dados permanece nas Amazon VPCs que as contêm. Você pode usar um Amazon VPC endpoint para qualquer tipo de chamada da API de dados. Para ter informações sobre como chamar a API de dados, consulte [Chamar a API de dados do Amazon RDS](data-api.calling.md).
# 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));
}
```
# Usar a biblioteca do cliente Java para a API de dados do RDS
É possível baixar e usar uma biblioteca do cliente Java para a API de dados do RDS (API de dados). Essa biblioteca do cliente Java fornece uma forma alternativa de usar a API de dados. Usando essa biblioteca, é possível associar as classes no lado do cliente a solicitações e respostas da API de dados. Esse suporte ao mapeamento pode facilitar a integração com alguns tipos específicos de Java, como `Date`, `Time` e `BigDecimal`.
## Baixar a biblioteca cliente Java para API de dados
A biblioteca de cliente Java da API de dados é de código aberto no GitHub no seguinte local:
[ https://github.com/awslabs/rds-data-api-client-library-java](https://github.com/awslabs/rds-data-api-client-library-java)
É possível criar a biblioteca manualmente a partir de arquivos de origem, mas a melhor prática é consumir a biblioteca usando o gerenciamento de dependência do Apache Maven. Adicione a dependência a seguir ao arquivo POM Maven.
Para a versão 2.x, que é compatível com o AWS SDK 2.x, use o seguinte:
```
software.amazon.rdsdata
rds-data-api-client-library-java
2.0.0
```
Para a versão 1.x, que é compatível com o AWS SDK 1.x, use o seguinte:
```
software.amazon.rdsdata
rds-data-api-client-library-java
1.0.8
```
## Exemplos de biblioteca cliente Java
É possível encontrar a seguir alguns exemplos comuns de uso da biblioteca de cliente Java da API de dados. Estes exemplos pressupõem que você tenha uma tabela `accounts` com duas colunas: `accountId` e `name`. Você também tem o seguinte objeto de transferência de dados (DTO).
```
public class Account {
int accountId;
String name;
// getters and setters omitted
}
```
A biblioteca de cliente permite passar DTOs como parâmetros de entrada. O exemplo a seguir mostra como DTOs do cliente são mapeados para conjuntos de parâmetros de entrada.
```
var account1 = new Account(1, "John");
var account2 = new Account(2, "Mary");
client.forSql("INSERT INTO accounts(accountId, name) VALUES(:accountId, :name)")
.withParamSets(account1, account2)
.execute();
```
Em alguns casos, é mais fácil trabalhar com valores simples como parâmetros de entrada. Para isso, siga a seguinte sintaxe.
```
client.forSql("INSERT INTO accounts(accountId, name) VALUES(:accountId, :name)")
.withParameter("accountId", 3)
.withParameter("name", "Zhang")
.execute();
```
Veja a seguir outro exemplo que funciona com valores simples como parâmetros de entrada.
```
client.forSql("INSERT INTO accounts(accountId, name) VALUES(?, ?)", 4, "Carlos")
.execute();
```
A biblioteca de cliente fornece mapeamento automático para DTOs quando o resultado é retornado. Os exemplos a seguir mostram como o resultado é mapeado para os DTOs.
```
List result = client.forSql("SELECT * FROM accounts")
.execute()
.mapToList(Account.class);
Account result = client.forSql("SELECT * FROM accounts WHERE account_id = 1")
.execute()
.mapToSingle(Account.class);
```
Em vários casos, o conjunto de resultados do banco de dados inclui apenas um valor. Para simplificar a recuperação de tais resultados, a biblioteca de cliente oferece a API a seguir:
```
int numberOfAccounts = client.forSql("SELECT COUNT(*) FROM accounts")
.execute()
.singleValue(Integer.class);
```
**nota**
A função `mapToList` converte um conjunto de resultados do SQL em uma lista de objetos definida pelo usuário. Não é possível usar a instrução `.withFormatRecordsAs(RecordsFormatType.JSON)` em uma chamada de `ExecuteStatement` para a biblioteca do cliente Java, porque ela atende ao mesmo propósito. Para obter mais informações, consulte [Processar resultados de consulta da API de dados do Amazon RDS no formato JSON](data-api-json.md).
# Processar resultados de consulta da API de dados do Amazon RDS no formato JSON
Ao chamar a operação `ExecuteStatement`, você pode optar por ter os resultados da consulta retornados como uma string no formato JSON. Dessa forma, é possível usar os recursos de análise JSON da linguagem de programação para interpretar e reformatar o conjunto de resultados. Isso pode ajudar a evitar a necessidade de escrever código adicional para percorrer o conjunto de resultados e interpretar cada valor de coluna.
Para solicitar o conjunto de resultados no formato JSON, transmita o parâmetro `formatRecordsAs` opcional com um valor de `JSON`. O conjunto de resultados formatado em JSON é retornado no campo `formattedRecords` da estrutura `ExecuteStatementResponse`.
A ação `BatchExecuteStatement` não retorna um conjunto de resultados. Dessa forma, a opção JSON não se aplica a essa ação.
Para personalizar as chaves na estrutura de hash JSON, defina aliases de coluna no conjunto de resultados. Você pode fazer isso usando a cláusula `AS` na lista de colunas da consulta SQL.
É possível usar o recurso JSON para tornar o conjunto de resultados mais fácil de ler e mapear o respectivo conteúdo para frameworks específicos de linguagem. Como o volume do conjunto de resultados com codificação ASCII é maior do que a representação padrão, talvez você escolha a representação padrão para consultas que retornem números de linhas ou valores de coluna grandes que consomem mais memória do que o disponível para a aplicação.
**Topics**
+ [Recuperar resultados de consulta no formato JSON](#data-api-json-querying)
+ [Mapeamento de tipo de dados](#data-api-json-datatypes)
+ [Solução de problemas](#data-api-json-troubleshooting)
+ [Exemplos](#data-api-json-examples)
## Recuperar resultados de consulta no formato JSON
Para receber o conjunto de resultados como uma string JSON, inclua `.withFormatRecordsAs(RecordsFormatType.JSON)` na chamada `ExecuteStatement`. O valor de retorno volta como uma string JSON no campo `formattedRecords`. Nesse caso, `columnMetadata` é `null`. Os rótulos de coluna são as chaves do objeto que representa cada linha. Esses nomes de coluna são repetidos para cada linha do conjunto de resultados. Os valores de coluna são strings entre aspas, valores numéricos ou valores especiais que representam `true`, `false` ou `null`. Os metadados de coluna, como restrições de comprimento e o tipo preciso para números e strings, não são preservados na resposta JSON.
Se você omitir a chamada ao `.withFormatRecordsAs()` ou especificar um parâmetro de `NONE`, o conjunto de resultados será retornado em formato binário usando os campos `Records` e `columnMetadata`.
## Mapeamento de tipo de dados
Os valores SQL no conjunto de resultados são mapeados para um conjunto menor de tipos JSON. Os valores são representados em JSON como strings, números e algumas constantes especiais, como `true`, `false` e `null`. Você pode converter esses valores em variáveis em sua aplicação, usando digitação forte ou fraca, conforme apropriado para sua linguagem de programação.
****
| Tipo de dados JDBC | Tipo de dados do JSON |
| --- | --- |
| `INTEGER`, `TINYINT`, `SMALLINT`, `BIGINT` | Número por padrão. String se a opção `LongReturnType` for definida como `STRING`. |
| `FLOAT`, `REAL`, `DOUBLE` | Número |
| `DECIMAL` | String por padrão. Número se a opção `DecimalReturnType` for definida como `DOUBLE_OR_LONG`. |
| `STRING` | String |
| `BOOLEAN`, `BIT` | Booleano |
| `BLOB`, `BINARY`, `VARBINARY`, `LONGVARBINARY` | String na codificação base64. |
| `CLOB` | String |
| `ARRAY` | Array |
| `NULL` | `null` |
| Outros tipos (incluindo tipos relacionados a data e hora) | String |
## Solução de problemas
A resposta JSON é limitada a 10 megabytes. Se a resposta for maior que esse limite, seu programa receberá o erro `BadRequestException`. Nesse caso, você pode resolvê-lo com uma das seguintes técnicas:
+ Reduza o número de linhas no conjunto de resultados. Para fazer isso, adicione uma cláusula `LIMIT`. Você pode dividir um grande conjunto de resultados em vários menores enviando várias consultas com as cláusulas `LIMIT` e `OFFSET`.
Se o conjunto de resultados incluir linhas filtradas pela lógica da aplicação, será possível remover essas linhas do conjunto de resultados adicionando mais condições à cláusula `WHERE`.
+ Reduza o número de colunas no conjunto de resultados. Para fazer isso, remova itens da lista de seleção da consulta.
+ Reduza os rótulos da coluna usando aliases de coluna na consulta. Cada nome de coluna é repetido na string JSON para cada linha no conjunto de resultados. Dessa forma, um resultado de consulta com nomes de coluna longos e muitas linhas pode exceder o limite de tamanho. Especificamente, use aliases de coluna para expressões complicadas a fim de evitar que a expressão inteira seja repetida na string JSON.
+ Embora com o SQL você possa usar aliases de coluna para produzir um conjunto de resultados com mais de uma coluna com o mesmo nome, nomes de chave duplicados não são permitidos no JSON. A API de dados do RDS gerará um erro se você solicitar o conjunto de resultados no formato JSON e mais de uma coluna tiver o mesmo nome. Dessa forma, todos os rótulos das colunas deverão ter nomes exclusivos.
## Exemplos
Os exemplos de Java a seguir mostram como chamar o `ExecuteStatement` com a resposta como uma string formatada em JSON e como interpretar o conjunto de resultados. Substitua os valores apropriados para os parâmetros *databaseName*, *secretStoreArn* e *clusterArn*.
O exemplo Java a seguir demonstra uma consulta que retorna um valor numérico decimal no conjunto de resultados. As chamadas ao `assertThat` verificam se os campos da resposta têm as propriedades esperadas com base nas regras para conjuntos de resultados JSON.
Este exemplo funciona com o esquema e os dados de amostra a seguir:
```
create table test_simplified_json (a float);
insert into test_simplified_json values(10.0);
```
```
public void JSON_result_set_demo() {
var sql = "select * from test_simplified_json";
var request = new ExecuteStatementRequest()
.withDatabase(databaseName)
.withSecretArn(secretStoreArn)
.withResourceArn(clusterArn)
.withSql(sql)
.withFormatRecordsAs(RecordsFormatType.JSON);
var result = rdsdataClient.executeStatement(request);
}
```
O valor do campo `formattedRecords` do programa anterior é:
```
[{"a":10.0}]
```
Os campos `Records` e `ColumnMetadata` na resposta são nulos devido à presença do conjunto de resultados JSON.
O exemplo de Java a seguir demonstra uma consulta que retorna um valor numérico decimal no conjunto de resultados. No exemplo, o `getFormattedRecords` é chamado para retornar somente a string formatada em JSON e ignorar os outros campos de resposta que estão em branco ou são nulos. O exemplo desserializa o resultado em uma estrutura que representa uma lista de registros. Cada registro tem campos cujos nomes correspondem aos aliases de coluna do conjunto de resultados. Essa técnica simplifica o código que analisa o conjunto de resultados. Sua aplicação não precisa percorrer as linhas e colunas do conjunto de resultados e converter cada valor no tipo apropriado.
Este exemplo funciona com o esquema e os dados de amostra a seguir:
```
create table test_simplified_json (a int);
insert into test_simplified_json values(17);
```
```
public void JSON_deserialization_demo() {
var sql = "select * from test_simplified_json";
var request = new ExecuteStatementRequest()
.withDatabase(databaseName)
.withSecretArn(secretStoreArn)
.withResourceArn(clusterArn)
.withSql(sql)
.withFormatRecordsAs(RecordsFormatType.JSON);
var result = rdsdataClient.executeStatement(request)
.getFormattedRecords();
/* Turn the result set into a Java object, a list of records.
Each record has a field 'a' corresponding to the column
labelled 'a' in the result set. */
private static class Record { public int a; }
var recordsList = new ObjectMapper().readValue(
response, new TypeReference>() {
});
}
```
O valor do campo `formattedRecords` do programa anterior é:
```
[{"a":17}]
```
Para recuperar a coluna `a` da linha de resultado 0, a aplicação fará referência a `recordsList.get(0).a`.
Em contrapartida, o exemplo de Java a seguir mostra o tipo de código necessário para criar uma estrutura de dados que contenha o conjunto de resultados quando o formato JSON não é usado. Nesse caso, cada linha do conjunto de resultados contém campos com informações sobre um único usuário. Para criar uma estrutura de dados a fim de representar o conjunto de resultados, é necessário examinar as linhas. Para cada linha, o código recupera o valor de cada campo, realiza uma conversão de tipo apropriada e atribui o resultado ao campo correspondente no objeto que representa a linha. Depois, o código adiciona o objeto que representa cada usuário à estrutura de dados que representa todo o conjunto de resultados. Se a consulta tiver sido alterada para reordenar, adicionar ou remover campos no conjunto de resultados, o código da aplicação também precisará mudar.
```
/* Verbose result-parsing code that doesn't use the JSON result set format */
for (var row: response.getRecords()) {
var user = User.builder()
.userId(row.get(0).getLongValue())
.firstName(row.get(1).getStringValue())
.lastName(row.get(2).getStringValue())
.dob(Instant.parse(row.get(3).getStringValue()))
.build();
result.add(user);
}
```
Os valores de exemplo a seguir mostram os valores do campo `formattedRecords` para conjuntos de resultados com diferentes números e aliases de coluna, bem como tipos de dados de coluna.
Se o conjunto de resultados incluir várias linhas, cada uma será representada como um objeto que é um elemento de matriz. Cada coluna no conjunto de resultados se torna uma chave no objeto. Esses nomes de coluna são repetidos para cada linha do conjunto de resultados. Dessa forma, para conjuntos de resultados que compreendem muitas linhas e colunas, talvez seja necessário definir aliases de coluna curtos para não exceder o limite de comprimento da resposta completa.
Este exemplo funciona com o esquema e os dados de amostra a seguir:
```
create table sample_names (id int, name varchar(128));
insert into sample_names values (0, "Jane"), (1, "Mohan"), (2, "Maria"), (3, "Bruce"), (4, "Jasmine");
```
```
[{"id":0,"name":"Jane"},{"id":1,"name":"Mohan"},
{"id":2,"name":"Maria"},{"id":3,"name":"Bruce"},{"id":4,"name":"Jasmine"}]
```
Se uma coluna no conjunto de resultados for definida como uma expressão, o texto da expressão se tornará a chave JSON. Por isso, em geral é conveniente definir um alias de coluna descritivo para cada expressão na lista de seleção da consulta. Por exemplo, a consulta a seguir inclui expressões como chamadas de função e operações aritméticas em sua lista de seleção.
```
select count(*), max(id), 4+7 from sample_names;
```
Essas expressões são transmitidas para o conjunto de resultados JSON como chaves.
```
[{"count(*)":5,"max(id)":4,"4+7":11}]
```
Adicionar colunas `AS` com rótulos descritivos torna as chaves mais simples de interpretar no conjunto de resultados JSON.
```
select count(*) as rows, max(id) as largest_id, 4+7 as addition_result from sample_names;
```
Com a consulta SQL revisada, os rótulos de coluna definidos pelas cláusulas `AS` são usados como nomes de chave.
```
[{"rows":5,"largest_id":4,"addition_result":11}]
```
O valor para cada par de chave-valor na string JSON pode ser uma string entre aspas. A string pode conter caracteres unicode. Se a string contiver sequências de escape ou os caracteres `"` ou `\`, esses caracteres serão precedidos por caracteres de escape de barra invertida. Os exemplos de strings JSON a seguir demonstram essas possibilidades. Por exemplo, o resultado `string_with_escape_sequences` contém os caracteres especiais backspace, nova linha, retorno de carro, guia, feed de formulário e `\`.
```
[{"quoted_string":"hello"}]
[{"unicode_string":"邓不利多"}]
[{"string_with_escape_sequences":"\b \n \r \t \f \\ '"}]
```
O valor para cada par de chave-valor na string JSON pode ser uma string entre aspas. O número pode ser um valor inteiro, um valor de ponto flutuante, um valor negativo ou um valor representado como notação exponencial. Os exemplos de strings JSON a seguir demonstram essas possibilidades.
```
[{"integer_value":17}]
[{"float_value":10.0}]
[{"negative_value":-9223372036854775808,"positive_value":9223372036854775807}]
[{"very_small_floating_point_value":4.9E-324,"very_large_floating_point_value":1.7976931348623157E308}]
```
Valores boolianos e nulos são representados com as palavras-chave especiais `true`, `false` e `null` sem aspas. Os exemplos de strings JSON a seguir demonstram essas possibilidades.
```
[{"boolean_value_1":true,"boolean_value_2":false}]
[{"unknown_value":null}]
```
Se você selecionar um valor de um tipo BLOB, o resultado será representado na string JSON como um valor codificado em base64. Para converter o valor de volta à representação original, você pode usar a função de decodificação apropriada na linguagem da aplicação. Por exemplo, em Java, chame a função `Base64.getDecoder().decode()`. O exemplo de saída a seguir mostra o resultado da seleção de um valor BLOB de `hello world` e do retorno do conjunto de resultados como uma string JSON.
```
[{"blob_column":"aGVsbG8gd29ybGQ="}]
```
O exemplo de Python a seguir mostra como acessar os valores do resultado de uma chamada para a função `execute_statement` do Python. O conjunto de resultados é um valor de string no campo `response['formattedRecords']`. O código transforma a string JSON em uma estrutura de dados chamando a função `json.loads`. Depois, cada linha do conjunto de resultados é um elemento de lista dentro da estrutura de dados e, em cada linha, é possível fazer referência a cada campo do conjunto de resultados pelo nome.
```
import json
result = json.loads(response['formattedRecords'])
print (result[0]["id"])
```
O exemplo de Javascript a seguir mostra como acessar os valores do resultado de uma chamada para a função `executeStatement` do Javascript. O conjunto de resultados é um valor de string no campo `response.formattedRecords`. O código transforma a string JSON em uma estrutura de dados chamando a função `JSON.parse`. Depois, cada linha do conjunto de resultados é um elemento de matriz dentro da estrutura de dados e, em cada linha, é possível fazer referência a cada campo do conjunto de resultados pelo nome.
```
```
# Solução de problemas com a API de dados do Amazon RDS
Use as seções a seguir, intituladas com mensagens de erro comuns, para ajudar na solução de problemas com a API de dados do Amazon RDS (API de dados).
**Topics**
+ [Transação não encontrada](#data-api.troubleshooting.tran-id-not-found)
+ [O pacote para consulta é muito grande](#data-api.troubleshooting.packet-too-large)
+ [A resposta do banco de dados excedeu o limite de tamanho](#data-api.troubleshooting.response-size-too-large)
+ [HttpEndpoint não está habilitado para o cluster ](#data-api.troubleshooting.http-endpoint-not-enabled)
+ [DatabaseErrorException: a transação ainda está executando uma consulta](#data-api.troubleshooting.txn-concurrent-requests-rejected)
+ [Exceção de resultado não aceito](#data-api.troubleshooting.unsupported-result)
+ [Declarações múltiplas não são aceitas](#data-api.troubleshooting.multi-statements)
+ [O parâmetro schema não é aceito](#data-api.troubleshooting.schema-parameter)
+ [Problemas de conectividade IPv6](#data-api.troubleshooting.ipv6-connectivity)
## Transação não encontrada
Nesse caso, o ID da transação especificado em uma chamada de API de dados não foi encontrado. A causa desse problema é anexada à mensagem de erro e é uma das seguintes:
+ A transação pode ter expirado.
Verifique se a chamada da transação é executada três minutos depois da última.
Também é possível que o ID da transação especificada não tenha sido criado por uma chamada de [BeginTransaction](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_BeginTransaction.html). Verifique se a chamada tem um ID de transação válido.
+ Uma chamada anterior provocou o encerramento da transação.
A transação já foi encerrada pela chamada `CommitTransaction` ou `RollbackTransaction`.
+ A transação foi interrompida devido a um erro de uma chamada anterior.
Verifique se suas chamadas anteriores lançaram exceções.
Para obter informações sobre como executar transações, consulte [Chamar a API de dados do Amazon RDS](data-api.calling.md).
## O pacote para consulta é muito grande
Nesse caso, o conjunto de resultados obtido para uma linha era muito grande. O limite de tamanho da API de dados é de 64 KB por linha no conjunto de resultados obtido pelo banco de dados.
Para resolver esse problema, verifique se cada linha em um conjunto de resultados tem até 64 KB.
## A resposta do banco de dados excedeu o limite de tamanho
Nesse caso, o tamanho do conjunto de resultados obtido pelo banco de dados era muito grande. O limite de tamanho da API de dados é de 1 MiB no conjunto de resultados obtido pelo banco de dados.
Para resolver esse problema, garanta que as chamadas para a API de dados exibam até 1 MiB de dados. Se você precisar retornar mais de 1 MiB, poderá usar várias chamadas [https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_ExecuteStatement.html](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_ExecuteStatement.html) com a cláusula `LIMIT` na sua consulta.
Para obter mais informações sobre a cláusula `LIMIT`, consulte [SELECT Syntax](https://dev.mysql.com/doc/refman/8.0/en/select.html) na documentação do MySQL.
## HttpEndpoint não está habilitado para o cluster
Verifique as possíveis causas a seguir para esse problema:
+ O cluster de banco de dados do Aurora não é compatível com a API de dados. Para ter informações sobre os tipos de clusters de banco de dados compatíveis com a API de dados do RDS, consulte [Disponibilidade de região e versão para a API de dados do Amazon RDS](data-api.regions.md).
+ A API de dados não está habilitada para o cluster de banco de dados do Aurora. Para usar a API de dados com um cluster de banco de dados do Aurora, a API de dados deve estar habilitada para o cluster de banco de dados. Para ter informações sobre como habilitar a API de dados, consulte [Habilitar a API de dados do Amazon RDS](data-api.enabling.md).
+ O cluster de banco de dados foi renomeado depois que a API de dados foi habilitada para ele. Nesse caso, desative a API de dados desse cluster e, depois, habilite-a novamente.
+ O ARN especificado não corresponde com precisão ao ARN do cluster. Verifique se o ARN retornado de outra fonte ou criado pela lógica do programa corresponde exatamente ao ARN do cluster. Por exemplo, verifique se o ARN usado tem a letra correta para todos os caracteres alfabéticos.
## DatabaseErrorException: a transação ainda está executando uma consulta
Se a aplicação enviar uma solicitação com um ID de transação e essa transação estiver processando outra solicitação no momento, a API de dados retornará esse erro à aplicação imediatamente. Essa condição poderá surgir se a aplicação fizer solicitações assíncronas, usando um mecanismo como “promessas” em JavaScript.
Para resolver esse problema, aguarde até que a solicitação anterior seja concluída e repita a solicitação. Você pode continuar tentando novamente até que o erro não ocorra mais ou que a aplicação receba algum tipo diferente de erro.
Essa condição pode ocorrer com a API de dados do Aurora Serverless v2 e instâncias provisionadas. Na API de dados do Aurora Serverless v1, as solicitações subsequentes para o mesmo ID de transação aguardam automaticamente a conclusão da solicitação anterior. No entanto, esse comportamento mais antigo poderia encontrar tempos limite devido ao fato de a solicitação anterior demorar muito. Se você tiver uma aplicação antiga da API de dados que faz solicitações simultâneas, modifique sua lógica de tratamento de exceções para considerar esse novo tipo de erro.
## Exceção de resultado não aceito
A API de dados não comporta todos os tipos de dados. Esse erro ocorre quando você executa uma consulta que exibe um tipo de dados não aceito.
Para contornar esse problema, converta o tipo de dados não aceito em `TEXT`. Por exemplo:
```
SELECT custom_type::TEXT FROM my_table;
-- OR
SELECT CAST(custom_type AS TEXT) FROM my_table;
```
## Declarações múltiplas não são aceitas
Na API de dados para o Aurora Sem Servidor v2 e em clusters provisionados, não é possível usar declarações múltiplas. A tentativa de executar várias declarações em uma única chamada de API gera esse erro.
Para executar várias declarações, use chamadas de API `ExecuteStatement` separadas ou use a API `BatchExecuteStatement` para processamento em lote.
## O parâmetro schema não é aceito
O Aurora Sem Servidor v1 ignora silenciosamente o parâmetro schema. No entanto, o Aurora Sem Servidor v2 e os clusters provisionados rejeitam explicitamente as chamadas de API que incluem o parâmetro schema.
Para resolver esse problema, remova o parâmetro schema de todas as chamadas à API de dados ao usar o Aurora Sem Servidor v2 ou clusters provisionados.
## Problemas de conectividade IPv6
Se você tiver problemas ao se conectar à API de dados usando endpoints IPv6, confira as seguintes possíveis causas:
+ A **rede não aceita IPv6**: verifique se sua infraestrutura de rede comporta IPv6 e se o roteamento IPv6 está configurado corretamente.
+ **Problemas de resolução DNS**: verifique se seu resolvedor de DNS consegue resolver registros AAAA para os endpoints de pilha dupla (por exemplo, `rds-data.us-east-1.api.aws`).
+ **Configuração dos grupos de segurança**: atualize as regras do grupo de segurança para permitir o tráfego IPv6 na porta 443 (HTTPS). Adicione regras para blocos CIDR IPv6 (por exemplo, `::/0` para todos os endereços IPv6).
+ **Configuração da ACL de rede**: certifique-se de que as ACLs de rede permitam tráfego IPv6 nas portas necessárias.
+ **Compatibilidade da biblioteca de cliente**: verifique se suas bibliotecas de cliente HTTP e AWS SDKs aceitam a conectividade IPv6 e de pilha dupla.
+ **Configuração do endpoint da VPC**: se estiver usando o PrivateLink, garanta que seu endpoint da VPC esteja configurado para aceitar IPv6 e que as sub-redes associadas tenham blocos CIDR IPv6 atribuídos.
Para solucionar problemas de conectividade IPv6:
1. Teste a conectividade usando os endpoints somente IPv4 (`.amazonaws.com`) para verificar se o problema é específico do IPv6.
1. Use ferramentas de diagnóstico de rede para verificar a conectividade IPv6 com os endpoints de pilha dupla.
1. Confira se há erros de autenticação ou autorização nos logs do CloudTrail ao usar endpoints IPv6.
1. Verifique se sua aplicação está configurada corretamente para usar os novos URLs de endpoint de pilha dupla.
# Registrar em log chamadas da API de dados do Amazon RDS com o AWS CloudTrail
A API de dados do RDS (API de dados) é integrada ao AWS CloudTrail, um serviço que fornece um registro das ações realizadas por um usuário, um perfil ou um serviço da AWS na API de dados. O CloudTrail captura todas as chamadas de API para a API de dados como eventos, inclusive as chamadas do console do Amazon RDS e de chamadas do código para operações da API de dados. Se você criar uma trilha, será possível ativar a entrega contínua de eventos do CloudTrail para um bucket do Amazon S3, incluindo eventos da API Data. Ao usar os dados coletados pelo CloudTrail, é possível determinar várias informações. Essas informações incluem a solicitação feita à API Data, o endereço IP do qual a solicitação foi feita, quem fez a solicitação, quando ela foi feita, além de detalhes adicionais.
Para saber mais sobre o CloudTrail, consulte o [Manual do usuário do AWS CloudTrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/).
## Trabalhar com informações da API Data no CloudTrail
O CloudTrail é habilitado em sua conta da AWS quando ela é criada. Quando uma atividade compatível (eventos de gerenciamento) ocorre na API de dados, ela é registrada em um evento do CloudTrail além de outros eventos de serviços da AWS no **Histórico de eventos**. É possível visualizar, pesquisar e baixar eventos de gerenciamento recentes na conta da AWS. Para obter mais informações, consulte [Trabalhar com histórico de eventos do CloudTrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/view-cloudtrail-events.html) no *Guia do usuário do AWS CloudTrail*.
Para ter um registro contínuo de eventos na sua conta da AWS, incluindo os eventos da API Data, crie uma trilha. Uma *trilha* permite que o CloudTrail entregue arquivos de log a um bucket do Amazon S3. Por padrão, quando uma trilha é criada no console, a mesma é aplicada a todas as regiões da AWS. A trilha registra em log eventos de todas as regiões da AWS na partição da AWS e entrega os arquivos de log para o bucket do Amazon S3 especificado por você. Além disso, você pode configurar outros produtos da AWS para analisar mais profundamente e agir sobre os dados de eventos coletados nos logs do CloudTrail. Para obter mais informações, consulte os seguintes tópicos no *Manual do usuário do AWS CloudTrail*:
+ [Visão geral da criação de uma trilha](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-create-and-update-a-trail.html)
+ [Serviços e integrações compatíveis com o CloudTrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-aws-service-specific-topics.html#cloudtrail-aws-service-specific-topics-integrations)
+ [Configuração notificações do Amazon SNS para o CloudTrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/getting_notifications_top_level.html)
+ [Receber arquivos de log do CloudTrail de várias regiões](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/receive-cloudtrail-log-files-from-multiple-regions.html) e [Receber arquivos de log do CloudTrail de várias contas](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-receive-logs-from-multiple-accounts.html)
Todas as operações da API de dados são registradas em log pelo CloudTrail e documentadas na [https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/Welcome.html](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/Welcome.html). Por exemplo, as chamadas para as operações `BatchExecuteStatement`, `BeginTransaction`, `CommitTransaction` e `ExecuteStatement` geram entradas nos arquivos de log do CloudTrail.
Cada entrada de log ou evento contém informações sobre quem gerou a solicitação. As informações de identidade ajudam a determinar o seguinte:
+ Se a solicitação foi feita com credenciais de usuário da raiz ou do .
+ Se a solicitação foi feita com credenciais de segurança temporárias de um perfil ou de um usuário federado.
+ Se a solicitação foi feita por outro serviço da AWS.
Para saber mais, consulte [Elemento userIdentity do CloudTrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference-user-identity.html).
## Incluir e excluir eventos da API de dados de uma trilha do AWS CloudTrail
A maioria dos usuários da API de dados depende dos eventos em uma trilha do AWS CloudTrail para fornecer um registro das operações da API de dados. Os dados do evento não revelam o nome do banco de dados, o nome do esquema ou as instruções SQL nas solicitações à API de dados. No entanto, saber qual usuário fez um tipo de chamada em um cluster de banco de dados específico em determinado momento pode ajudar a detectar padrões de acesso anômalos.
### Incluir eventos da API de dados em uma trilha do AWS CloudTrail
Para o Aurora PostgreSQL Sem Servidor v2 e bancos de dados provisionados, as seguintes operações da API de dados são registradas em log como eventos de dados no AWS CloudTrail como *eventos de dados*. [Eventos de dados](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-data-events-with-cloudtrail.html#logging-data-events) são operações de API de plano de dados de alto volume que o CloudTrail não registra por padrão. Há cobranças adicionais para eventos de dados. Para obter mais informações sobre preços do CloudTrail, consulte [Preços do AWS CloudTrail](https://aws.amazon.com/cloudtrail/pricing/).
+ [BatchExecuteStatement](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_BatchExecuteStatement.html)
+ [BeginTransaction](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_BeginTransaction.html)
+ [CommitTransaction](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_CommitTransaction.html)
+ [ExecuteStatement](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_ExecuteStatement.html)
+ [RollbackTransaction](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_RollbackTransaction.html)
É possível usar o console do CloudTrail, AWS CLI, ou as operações da API do CloudTrail para registrar essas operações da API de dados. No console do CloudTrail, selecione **API de dados do RDS: cluster de banco de dados** para o tipo de evento Dados. Para ter mais informações, consulte [Logging data events with theConsole de gerenciamento da AWS](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-data-events-with-cloudtrail.html#creating-data-event-selectors-with-the-AWS-CLI), no *Manual do usuário do AWS CloudTrail*.
Usando a AWS CLI, execute o comando `aws cloudtrail put-event-selectors` para registrar essas operações da API de dados para a trilha. Para registrar todos os eventos da API de dados em clusters de banco de dados, especifique `AWS::RDS::DBCluster` para o tipo de recurso. O exemplo a seguir registra todos os eventos da API de dados em clusters de banco de dados. Para ter mais informações, consulte [Logging data events with theAWS Command Line Interface](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-create-and-update-a-trail-by-using-the-aws-cli.html), no *Manual do usuário do AWS CloudTrail*.
```
aws cloudtrail put-event-selectors --trail-name trail_name --advanced-event-selectors \
'{
"Name": "RDS Data API Selector",
"FieldSelectors": [
{
"Field": "eventCategory",
"Equals": [
"Data"
]
},
{
"Field": "resources.type",
"Equals": [
"AWS::RDS::DBCluster"
]
}
]
}'
```
É possível configurar seletores de eventos avançados para filtrar adicionalmente os campos `readOnly`, `eventName,` e `resources.ARN`. Para ter mais informações sobre esses campos, consulte [AdvancedFieldSelector](https://docs.aws.amazon.com/awscloudtrail/latest/APIReference/API_AdvancedFieldSelector.html).
### Excluir eventos da API de dados de uma trilha do AWS CloudTrail (somente o Aurora Serverless v1)
Para o Aurora Serverless v1, os eventos da API de dados são eventos de gerenciamento. Por padrão, todos os eventos da API de dados são incluídos em uma trilha do AWS CloudTrail. No entanto, como a API de dados pode gerar um grande número de eventos, é possível excluir esses eventos da trilha do CloudTrail. A configuração **Excluir eventos da API de dados do Amazon RDS** exclui todos os eventos da API de dados da trilha. Não é possível excluir eventos específicos da API de dados.
Para excluir eventos da API de da dados de uma trilha, faça o seguinte:
+ No console do CloudTrail, escolha a opção **Exclude Amazon RDS Data API events** (Excluir eventos da API de dados do Amazon RDS) quando você [criar uma trilha](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-create-a-trail-using-the-console-first-time.html) ou [atualizar uma trilha](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-update-a-trail-console.html).
+ Na API do CloudTrail, use a operação [PutEventSelectors](https://docs.aws.amazon.com/awscloudtrail/latest/APIReference/API_PutEventSelectors.html). Se estiver usando seletores de eventos avançados, você poderá excluir eventos da API de dados definindo o campo `eventSource` diferente de `rdsdata.amazonaws.com`. Se estiver usando seletores de eventos básicos, você poderá excluir eventos da API de dados definindo o valor do atributo `ExcludeManagementEventSources` como `rdsdata.amazonaws.com`. Consulte mais informações em [Logging data events with the AWS Command Line Interface](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-management-events-with-cloudtrail.html#creating-mgmt-event-selectors-with-the-AWS-CLI), no *Guia do usuário do AWS CloudTrail*.
**Atenção**
Excluir eventos da API de dados de um log do CloudTrail pode ocultar ações da API de dados. Tenha cuidado ao conceder aos principais a permissão `cloudtrail:PutEventSelectors` que é necessária para executar essa operação.
É possível desativar essa exclusão a qualquer momento alterando a configuração do console ou os seletores de eventos de uma trilha. Então, a trilha começará a gravar os eventos da API de dados . No entanto, não pode recuperar eventos da API de dados que ocorreram enquanto a exclusão estava em vigor.
Ao excluir eventos da API de dados usando o console ou a API, a operação `PutEventSelectors` da API do CloudTrail também é registrada nos logs do CloudTrail. Se os eventos da API de dados não aparecerem nos logs do CloudTrail, procure um evento `PutEventSelectors` com o atributo `ExcludeManagementEventSources` definido como `rdsdata.amazonaws.com`.
Para obter mais informações, consulte [Logging management events for trails](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-management-events-with-cloudtrail.html) (Registro de eventos de dados para trilhas) no *Manual do usuário do AWS CloudTrail*.
## Noções básicas sobre as entradas do arquivo de log da API Data
Uma *trilha* é uma configuração que permite a entrega de eventos como registros de log a um bucket do Amazon S3 especificado. Os arquivos de log do CloudTrail contêm uma ou mais entradas de log. Um *evento* representa uma única solicitação de qualquer origem e inclui informações sobre a ação solicitada, a data e a hora da ação, os parâmetros de solicitação e assim por diante. Os arquivos de log do CloudTrail não são um rastreamento de pilha ordenada de chamadas de API pública, portanto, não são exibidos em uma ordem específica.
**Aurora PostgreSQL Sem Servidor v2 e provisionado**
O exemplo a seguir mostra uma entrada de log do CloudTrail que demonstra a operação `ExecuteStatement` do Aurora PostgreSQL Sem Servidor v2 e dos bancos de dados provisionados. Para esses bancos de dados, todos os eventos da API de dados são eventos de dados em que a origem do evento é **rdsdataapi.amazonaws.com** e o tipo de evento é **Rds Data Service**.
```
{
"eventVersion": "1.05",
"userIdentity": {
"type": "IAMUser",
"principalId": "AKIAIOSFODNN7EXAMPLE",
"arn": "arn:aws:iam::123456789012:user/johndoe",
"accountId": "123456789012",
"accessKeyId": "AKIAI44QH8DHBEXAMPLE",
"userName": "johndoe"
},
"eventTime": "2019-12-18T00:49:34Z",
"eventSource": "rdsdataapi.amazonaws.com",
"eventName": "ExecuteStatement",
"awsRegion": "us-east-1",
"sourceIPAddress": "192.0.2.0",
"userAgent": "aws-cli/1.16.102 Python/3.7.2 Windows/10 botocore/1.12.92",
"requestParameters": {
"continueAfterTimeout": false,
"database": "**********",
"includeResultMetadata": false,
"parameters": [],
"resourceArn": "arn:aws:rds:us-east-1:123456789012:cluster:my-database-1",
"schema": "**********",
"secretArn": "arn:aws:secretsmanager:us-east-1:123456789012:secret:dataapisecret-ABC123",
"sql": "**********"
},
"responseElements": null,
"requestID": "6ba9a36e-b3aa-4ca8-9a2e-15a9eada988e",
"eventID": "a2c7a357-ee8e-4755-a0d0-aed11ed4253a",
"eventType": "Rds Data Service",
"recipientAccountId": "123456789012"
}
```
**Aurora Serverless v1**
O exemplo a seguir mostra como o exemplo anterior da entrada de log do CloudTrail aparece para o Aurora Serverless v1. Para o Aurora Serverless v1, todos os eventos são eventos de gerenciamento em que a origem do evento é **rdsdata.amazonaws.com** e o tipo de evento é **AwsApiCall**.
```
{
"eventVersion": "1.05",
"userIdentity": {
"type": "IAMUser",
"principalId": "AKIAIOSFODNN7EXAMPLE",
"arn": "arn:aws:iam::123456789012:user/johndoe",
"accountId": "123456789012",
"accessKeyId": "AKIAI44QH8DHBEXAMPLE",
"userName": "johndoe"
},
"eventTime": "2019-12-18T00:49:34Z",
"eventSource": "rdsdata.amazonaws.com",
"eventName": "ExecuteStatement",
"awsRegion": "us-east-1",
"sourceIPAddress": "192.0.2.0",
"userAgent": "aws-cli/1.16.102 Python/3.7.2 Windows/10 botocore/1.12.92",
"requestParameters": {
"continueAfterTimeout": false,
"database": "**********",
"includeResultMetadata": false,
"parameters": [],
"resourceArn": "arn:aws:rds:us-east-1:123456789012:cluster:my-database-1",
"schema": "**********",
"secretArn": "arn:aws:secretsmanager:us-east-1:123456789012:secret:dataapisecret-ABC123",
"sql": "**********"
},
"responseElements": null,
"requestID": "6ba9a36e-b3aa-4ca8-9a2e-15a9eada988e",
"eventID": "a2c7a357-ee8e-4755-a0d0-aed11ed4253a",
"eventType": "AwsApiCall",
"recipientAccountId": "123456789012"
}
```
# Monitorar consultas da API de dados do RDS com o Insights de Performance
Se o cluster do Aurora estiver executando instâncias do Aurora Serverless v2 ou provisionadas, você poderá usar o Insights de Performance com a API de dados do RDS.
Consulte mais informações sobre como usar o Insights de Performance com o Aurora em [Monitorar a carga de banco de dados com o Performance Insights no Amazon Aurora](USER_PerfInsights.md).
## Como as consultas da API de dados do RDS são representadas no Insights de Performance
Com a API de dados, o cluster do Aurora processa consultas com base nas chamadas da API de dados que você envia da aplicação. A API de dados também executa algumas instruções SQL como parte de seu próprio funcionamento interno, como cancelar consultas que excedam o tempo limite. Os dois tipos de operações SQL são mostrados em estatísticas e gráficos do Insights de Performance.
+ Para consultas da API de dados que você envia para um cluster do Aurora, o campo **Host** no painel do PI é marcado como **API de dados do RDS**. Para o Aurora PostgreSQL, o campo **application\$1name** tem o valor `rds-data-api`. Procure esses rótulos ao analisar a carga do banco de dados usando **Principais hosts** ou **Principais aplicações** como uma dimensão.
+ Todas as consultas internas que a API de dados executa para gerenciar aspectos do banco de dados, como o grupo de conexões e o tempo limite de consulta, são anotadas com o prefixo **API de dados do RDS**. Exemplo: `/* RDS Data API */ select * from my_table;` procura esses prefixos ao analisar a carga do banco de dados por **Principal SQL** como uma dimensão. As instruções são anotadas com um comentário de SQL da `/* RDS Data API */`.