Usar a API de dados do 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.
Todas as chamadas para a API de dados são síncronas. Por padrão, uma chamada atingirá o tempo limite se o processamento não for concluído em 45 segundos. No entanto, é possível continuar executando uma instrução SQL se a chamada expira usando o parâmetro continueAfterTimeout. Para ver um exemplo, consulte Executar uma transação SQL.
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 RDS.
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
É 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 RDS.
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 consulta .
Tópicos
- Disponibilidade de região e versão
- Limitações com a API de dados do RDS
- Comparação da API de dados do RDS com Sem Servidor v2 e provisionado e o Aurora Serverless v1
- Autorizar acesso à API de dados do RDS
- Habilitar a API de dados do RDS
- Criar um endpoint da Amazon VPC para a API de dados do RDS (AWS PrivateLink)
- Chamar a API de dados do RDS
- Usar a biblioteca do cliente Java para a API de dados do RDS
- Processar resultados de consulta em formato JSON
- Solução de problemas da API de dados do RDS
- Registrar em log chamadas da API de dados com o AWS CloudTrail
Disponibilidade de região e versão
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ão e versão |
|---|---|
Aurora PostgreSQL provisionado e Sem Servidor v2 |
API de dados do RDS para o Aurora PostgreSQL Sem Servidor v2 e provisionado |
Aurora PostgreSQL Sem Servidor v1 |
|
Aurora MySQL Sem Servidor v1 |
nota
Atualmente, a API de dados não está disponível para clusters de banco de dados do Aurora MySQL provisionados ou Sem Servidor v2.
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, consulte Federal Information Processing Standard (FIPS) 140-2.
Limitações com a API de dados do RDS
A API de dados do RDS (API de dados) 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, até que um cluster secundário seja promovido a primário, ele não tem instância de gravador. Assim, as consultas da API de dados enviadas ao cluster secundário falham. Depois que um cluster secundário promovido tiver uma instância de gravador disponível, as consultas da API de dados nessa instância de banco de dados devem ser bem-sucedidas.
O Performance Insights não é compatível com o monitoramento de consultas de banco de dados feitas com a API de dados.
A API de dados não é compatível com as classes de instância de banco de dados T.
Para o Aurora PostgreSQL Sem Servidor v2 e clusters de banco de dados provisionados, a API de dados do RDS não é compatível com tipos enumerados. Para ver uma lista de tipos compatíveis consulte Comparação da API de dados do RDS com Sem Servidor v2 e provisionado e o Aurora Serverless v1.
Para bancos de dados do Aurora PostgreSQL versão 14 e versões posteriores, a API Data só é compatível com scram-sha-256 para criptografia de senha.
Comparação da API de dados do RDS com Sem Servidor v2 e provisionado e o Aurora Serverless v1
A tabela a seguir descreve as diferenças entre a API de dados do RDS (API de dados) com o Aurora PostgreSQL Sem Servidor v2, os clusters de banco de dados provisionados e os clusters de banco de dados do Aurora Serverless v1.
| Diferença | Aurora PostgreSQL Sem Servidor v2 e provisionado | Aurora Serverless v1 |
|---|---|---|
| Número máximo de solicitações por segundo | Ilimitado | 1.000 |
| Habilitar ou desabilitar a API de dados em um banco de dados existente usando a API do RDS ou a AWS CLI |
|
|
| Eventos do CloudTrail | 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. | 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). |
| Suporte a várias declarações | Não há suporte a várias declarações. Nesse caso, a API de dados lança ValidationException: Multistatements aren't
supported. |
Para o Aurora PostgreSQL, várias declarações exibem somente a primeira resposta da consulta. No Aurora MySQL, não há suporte para várias declarações. |
| BatchExecuteStatement | O objeto de campos gerado no resultado da atualização é vazio. | O objeto de campos gerado no resultado da atualização inclui valores inseridos. |
| ExecuteSQL | Não suportado | Preterido |
| ExecuteStatement |
A API de dados não é compatível com alguns tipos de dados, como tipos geométricos e monetários. Nesse caso, a API de dados lança Apenas os seguintes tipos são compatíveis:
Apenas os seguintes tipos de matriz são compatíveis:
|
ExecuteStatement é compatível com a recuperação de colunas de matriz multidimensionais e todos os tipos de dados avançados. |
Autorizar acesso à API de dados do RDS
Os usuários poderão invocar operações da API de dados (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.
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.
{ "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 (*).
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:productionenvironment: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.) É 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.
{ "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.
No elemento “Condição” da política, é possível escolher chaves de tag entre as seguintes:
aws:TagKeysaws: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.
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 RDS (API de dados), transmita as credenciais para o 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
-
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 no Guia do usuário do AWS Secrets Manager.
-
Use o console do Secrets Manager para visualizar os detalhes do segredo criado ou execute o comando
aws secretsmanager describe-secretda 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 Guia do usuário do AWS.
Para entender como o Amazon Aurora lida com o gerenciamento de identidade e acesso, consulte Como o Amazon Aurora funciona com o IAM.
Para obter mais informações sobre como criar uma política do IAM, consulte Criar políticas do IAM no Guia 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 no Guia do usuário do IAM.
Habilitar a API de dados do RDS
Para usar a API de dados do 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
Para o Aurora PostgreSQL, a API de dados é compatível com o Aurora Serverless v2, o Aurora Serverless v1 e bancos de dados provisionados. No Aurora MySQL, a API de dados só é compatível com bancos de dados do Aurora Serverless v1.
Tópicos
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 AWS Management Console, a AWS CLI ou a API do RDS.
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.
Para ter instruções sobre como criar um banco de dados, consulte o seguinte:
No Aurora PostgreSQL Sem Servidor v2 e em bancos de dados provisionados: Criar um cluster de bancos de dados do Amazon Aurora
Para Aurora Serverless v1: Criar um cluster de banco de dados do Aurora Serverless v1
Para habilitar a API de dados ao criar um cluster de banco de dados do Aurora, execute o comando AWS CLIcreate-db-cluster 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-identifiermy_pg_cluster\ --engine aurora-postgresql \ --enable-http-endpoint
Para Windows:
aws rds create-db-cluster ^ --db-cluster-identifiermy_pg_cluster^ --engine aurora-postgresql ^ --enable-http-endpoint
Para habilitar a API de dados ao criar um cluster de banco de dados do Aurora, use a operação CreatedBCluster 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.
Tópicos
Habilitar ou desabilitar a API de dados (Aurora PostgreSQL Sem Servidor v2 e provisionado)
Use os procedimentos a seguir para habilitar ou desabilitar a API de dados no Aurora PostgreSQL Sem Servidor v2 e em bancos de dados 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).
É 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.
Para habilitar ou desabilitar a API de dados em um banco de dados existente, execute o comando enable-http-endpoint ou disable-http-endpoint 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-arncluster_arn
Para Windows:
aws rds enable-http-endpoint ^ --resource-arncluster_arn
Para habilitar ou desabilitar a API de dados em um banco de dados existente, use as operações EnableHttpEndpoint e DisableHttpEndpoint.
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 no Aurora PostgreSQL Sem Servidor v2 e em bancos de dados provisionados, use os procedimentos em Habilitar ou desabilitar a API de dados (Aurora PostgreSQL Sem Servidor v2 e provisionado).
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.
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.
Para habilitar ou desativar a API de dados, execute o comando modify-db-cluster 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
Para habilitar a API de dados, use a operação ModifyDBCluster 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 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) no Guia 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
Faça login no AWS Management Console e abra o console do Amazon VPC em https://console.aws.amazon.com/vpc/
. -
Escolha Endpoints e Create Endpoint (Criar endpoint).
-
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.
-
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.
-
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.
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.
-
Em Enable DNS Name (Habilitar nome DNS), selecione Enable for this endpoint (Habilitar para este endpoint).
O DNS privado resolve o nome de host DNS da API de dados padrão (
https://rds-data.) 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.region.amazonaws.com -
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.
-
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.
-
Escolha Create endpoint (Criar endpoint).
Depois que o endpoint for criado, escolha o link no AWS Management Console para visualizar os detalhes do endpoint.
A guia Details (Detalhes) do endpoint mostra os nomes de host de DNS que foram gerados durante a criação do Amazon VPC endpoint.
Você pode usar o endpoint padrão (rds-data.) 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.region.amazonaws.com
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 RDS.
Chamar a API de dados do RDS
Com a API de dados do RDS (API de dados) habilitada no cluster de banco de dados do Aurora, é possível executar declaraçõ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
nota
No momento, a API de dados não é compatível com as matrizes de identificadores únicos universais (UUIDs).
A API de dados oferece as operações a seguir para executar declarações SQL.
|
Operação da API de dados |
AWS CLI command |
Descrição |
|---|---|---|
|
Executa uma instrução SQL em um banco de dados. |
||
|
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 |
|---|---|---|
|
Inicia uma transação SQL. |
||
|
Encerra uma transação SQL e confirma as alterações. |
||
|
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 |
|---|---|---|---|
|
|
|
Sim |
O nome do recurso da Amazon (ARN) do cluster de banco de dados do Aurora. |
|
|
|
Sim |
O nome ou o ARN do segredo que permite o acesso ao cluster de banco de dados. |
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 |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Outros tipos (incluindo tipos relacionados a data e hora) |
|
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 correspondenteStringé enviado como objeto do tipoDATEpara o banco de dados. O formato aceito éYYYY-MM-DD. -
DECIMAL: o valor de parâmetro correspondenteStringé enviado como objeto do tipoDECIMALpara o banco de dados. -
JSON: o valor de parâmetro correspondenteStringé enviado como objeto do tipoJSONpara o banco de dados. -
TIME: o valor de parâmetro correspondenteStringé enviado como objeto do tipoTIMEpara o banco de dados. O formato aceito éHH:MM:SS[.FFF]. -
TIMESTAMP: o valor de parâmetro correspondenteStringé enviado como objeto do tipoTIMESTAMPpara o banco de dados. O formato aceito éYYYY-MM-DD HH:MM:SS[.FFF]. UUID: o valor de parâmetro correspondenteStringé enviado como objeto do tipoUUIDpara o banco de dados.
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 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.
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.
Tópicos
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
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.
As instruções Data Definition Language (DDL - Linguagem de definição de dados) dentro de uma transação causam um commit implícito. Recomendamos que você execute cada instrução DDL 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 comandobegin-transactionda 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
--databasepode não funcionar quando você executa uma instrução SQL depois de executar--sql "usena solicitação anterior. Recomendamos que você use a opçãodatabase_name;"--databaseem 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 expira. 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 em formato JSON.
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 intomytablevalues (: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 intomytablevalues (: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 expira, 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
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 comandobegin-transactionda 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 intomytablevalues (: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 intomytablevalues (: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 comandobegin-transactionda 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 comandobegin-transactionda 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 RDS por meio de uma aplicação Python
É possível chamar a API de dados do 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)
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.
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']
1nota
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 expira, especifique o parâmetro continueAfterTimeout como true.
Chamar a API de dados do RDS por meio de uma aplicação Java
É possível chamar a API de dados do 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 for Java.
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.
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<Field> 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 expira, especifique 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);
}
}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
É 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:
<dependency> <groupId>software.amazon.rdsdata</groupId> <artifactId>rds-data-api-client-library-java</artifactId> <version>2.0.0</version> </dependency>
Para a versão 1.x, que é compatível com o AWS SDK 1.x, use o seguinte:
<dependency> <groupId>software.amazon.rdsdata</groupId> <artifactId>rds-data-api-client-library-java</artifactId> <version>1.0.8</version> </dependency>
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<Account> 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 em formato JSON.
Processar resultados de consulta em 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.
Tópicos
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 |
|---|---|
|
|
Número por padrão. String se a opção |
|
|
Número |
|
|
String por padrão. Número se a opção |
|
|
String |
|
|
Booleano |
|
|
String na codificação base64. |
|
|
String |
|
|
Array |
|
|
|
|
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áusulasLIMITeOFFSET.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<List<Record>>() { }); }
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.
<script> const result = JSON.parse(response.formattedRecords); document.getElementById("display").innerHTML = result[0].id; </script>
Solução de problemas da API de dados do 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 RDS (API de dados).
Tópicos
Transação <transaction_ID> 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. 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
CommitTransactionouRollbackTransaction. -
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 RDS.
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 ExecuteStatement com a cláusula LIMIT na sua consulta.
Para obter mais informações sobre a cláusula LIMIT, consulte SELECT Syntax
HttpEndpoint não está habilitado para o cluster <cluster_ID>
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. Por exemplo, para o Aurora MySQL, só é possível usar a API de dados com o Aurora Serverless v1. 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.
-
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 RDS.
-
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.
