Disponibilidade de região e versão Autorizar acesso Habilitar a API de dados Criar um Amazon VPC endpoint Chamar a API de dados Usar a biblioteca de cliente Java Processar resultados de consulta em formato JSON Solução de problemas da API de dados

Usar a API de dados do Aurora Serverless v1

Usando a API de dados para Aurora Serverless v1, você pode trabalhar com uma interface de serviços web para seu cluster de banco de dados de Aurora Serverless v1. 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 passar 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.

Também é possível usar a API de dados para integrar o Aurora Serverless v1 a outras aplicações da AWS, como o AWS Lambda, o AWS AppSync e o AWS Cloud9. A API também fornece 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, AWS AppSync e AWS Cloud9.

É possível habilitar a API de dados ao criar o cluster do Aurora Serverless v1. Também é possível modificar a configuração posteriormente. Para obter mais informações, consulte Habilitar a API de dados.

Depois de habilitar a API de dados, também é possível usar o editor de consultas do Aurora Serverless v1. Para obter mais informações, consulte Usar o editor de consultas do Aurora Serverless v1.

nota

A API de dados e o editor de consultas não são compatíveis com o Aurora Serverless v2.

Tópicos

Disponibilidade de região e versão
Autorizar acesso à API de dados
Habilitar a API de dados
Como criar um endpoint da Amazon VPC para a API de dados (AWS PrivateLink)
Chamar a API de dados
Usar a biblioteca de cliente Java para a API de dados
Processar resultados de consulta em formato JSON
Solução de problemas da API de dados
Registrar em log chamadas da API Data com o AWS CloudTrail

Disponibilidade de região e versão

A API de dados só está disponível para clusters de banco de dados do Aurora Serverless v1 que usam versões específicas do Aurora MySQL e Aurora PostgreSQL, e em Regiões da AWS específicas. Para mais informações, consulte API de dados para Aurora Serverless v1.

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 comando ou uma API, use um endpoint do FIPS. Para obter mais informações sobre endpoints do FIPS, consulte Federal Information Processing Standard (FIPS) 140-2.

Autorizar acesso à API de dados

Os usuários poderão invocar operações da 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 define seus 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 do RDS.

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 segredos que podem usar nas chamadas para a API de dados. O uso de segredos significa que 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, o que permite (ou nega) a solicitação do usuário para o segredo. Para obter 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 fornece 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 e o Secrets Manager têm suporte à 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.) É 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 para o serviço. A API de dados primeiro verifica se o ARN de cluster passado 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: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.

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, passe credenciais para o cluster de banco de dados do Aurora Serverless v1 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-secret da AWS CLI.

Anote o nome e o ARN do segredo. Use-os 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

Para usar a API de dados, habilite-a para o cluster de banco de dados do Aurora Serverless v1. É possível habilitar a API de dados ao criar ou modificar o cluster de banco de dados.

nota

No momento, não é possível usar a API de dados com instâncias de banco de dados do Aurora Serverless v2

Habilite a API de dados usando o console do RDS ao criar ou modificar um cluster de banco de dados do Aurora Serverless v1. Ao criar um cluster de banco de dados do Aurora Serverless v1, habilite a API de dados na seção Connectivity (Conectividade) do console do RDS. Ao modificar um cluster de banco de dados do Aurora Serverless v1, habilite a API de dados na seção Network & Security (Rede e segurança) no console do RDS.

A captura de tela a seguir mostra a Data API (API de dados) ao modificar um cluster de banco de dados do Aurora Serverless v1.

Habilitar a API de dados para um cluster de banco de dados do Aurora Serverless v1 com o console

Para obter instruções, consulte Criar um cluster de banco de dados do Aurora Serverless v1 e Modificar um cluster de banco de dados do Aurora Serverless v1.

Ao criar ou modificar um cluster de banco de dados do Aurora Serverless v1 usando comandos da CLI da AWS, a API de dados será habilitada quando você especificar --enable-http-endpoint.

Também é possível especificar o --enable-http-endpoint usando os seguintes comandos da AWSCLI:

O exemplo a seguir modifica o sample-cluster para habilitar a API de dados.

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

Ao criar ou modificar um cluster de banco de dados do Aurora Serverless v1 usando operações de API do Amazon RDS, habilite a API de dados configurando o valor EnableHttpEndpoint como true.

É possível definir o valor EnableHttpEndpoint usando as seguintes operações da API:

Como criar um endpoint da Amazon VPC para a API de dados (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.

Você pode chamar a API de dados com endpoints da Amazon VPC. O uso de um endpoint da Amazon VPC mantém o tráfego entre aplicações em sua Amazon VPC e a API de dados na 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, você pode 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 API 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 Amazon VPC endpoint para a API de dados

Faça login no AWS Management Console e abra o console da 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.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 endpoint da API de dados usando a AWS CLI ou os SDKs da AWS sem fazer alterações no código ou na configuração para atualizar o URL do endpoint da API de dados.
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.

Link para os detalhes do Amazon VPC 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.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.

Quando você usa um Amazon VPC endpoint em uma chamada da API de dados, todo tráfego entre sua aplicação e a API de dados permanece nas Amazon VPCs que o contêm. Você pode usar um Amazon VPC endpoint para qualquer tipo de chamada da API de dados. Para obter informações sobre como chamar a API de dados, consulte Chamar a API de dados.

Chamar a API de dados

Com a API de dados ativada em seu cluster de banco de dados do Aurora Serverless v1, você pode executar instruções SQL no cluster de bancos de dados Aurora usando a API de dados ou a AWS CLI. A API de dados oferece suporte a linguagens de programação aceitas pelos AWS SDKs. Para obter mais informações, consulte o tópico sobre Ferramentas para criar na AWS.

nota

No momento, a API de dados não oferece suporte às matrizes de identificadores únicos universais (UUIDs).

A API de dados fornece as operações a seguir para executar instruções SQL.

Operação da API de dados	AWS CLI command	Descrição
`ExecuteStatement`	`aws rds-data execute-statement`	Executa uma instrução SQL em um banco de dados.
`BatchExecuteStatement`	`aws rds-data batch-execute-statement`	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. A API de dados fornece as operações a seguir para oferecer suporte a transações.

Operação da API de dados	AWS CLI command	Descrição
`BeginTransaction`	`aws rds-data begin-transaction`	Inicia uma transação SQL.
`CommitTransaction`	`aws rds-data commit-transaction`	Encerra uma transação SQL e confirma as alterações.
`RollbackTransaction`	`aws rds-data rollback-transaction`	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 de recurso da Amazon (ARN) do cluster de banco de dados do Aurora Serverless v1.
`secretArn`	`--secret-arn`	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
`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.

Certos tipos, como DECIMAL e TIME, exigem uma dica para que a API de dados passe valores String para o 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

Para o Amazon Aurora PostgreSQL, a API de dados sempre retorna o tipo de dados TIMESTAMPTZ do Aurora PostgreSQL no fuso horário UTC.

Chamar a API de dados com a AWS CLI

Você pode chamar a 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 de recurso da Amazon (ARN) do cluster de banco de dados pelo ARN do cluster de banco de dados do Aurora Serverless v1. 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
Executar uma instrução SQL
Executar uma instrução SQL em lote em uma matriz de dados
Confirmar uma transação SQL
Reverter uma transação SQL

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 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.
--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.

O número máximo de solicitações por segundo é de 1.000.

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 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 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.

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 retornará 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.

O número máximo de solicitações por segundo é de 1.000.

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 a partir de uma aplicação Python

Você pode chamar a API de dados a partir 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 de recurso da Amazon (ARN) do cluster de banco de dados pelo ARN do cluster de banco de dados do Aurora Serverless v1. Além disso, substitua o ARN do segredo pelo ARN do segredo no Secrets Manager que concede acesso ao cluster de banco de dados.

Tópicos

Executar uma consulta SQL
Executar uma instrução SQL DML
Executar uma transação SQL

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 expira, especifique o parâmetro continueAfterTimeout como true.

Chamar a API de dados a partir de uma aplicação Java

Você pode chamar a API de dados a partir 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.

Tópicos

Executar uma consulta SQL
Executar uma transação SQL
Executar uma operação SQL em lote

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

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 de cliente Java para a API de dados

É possível baixar e usar a biblioteca de cliente Java para a API de dados. Essa biblioteca de cliente Java fornece uma forma alternativa de usar a API de dados. Usando essa biblioteca, é possível mapear as classes no lado do cliente para 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
Mapeamento de tipo de dados
Solução de problemas
Exemplos

Recuperar resultados de consulta no formato JSON

Para receber o conjunto de resultados como uma string JSON, inclua .withFormatRecordsAs(RecordsFormatType.JSON) na chamada ao 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`	Booliano
`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<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

Use as seções a seguir, intituladas com mensagens de erro comuns, para ajudar na solução de problemas com a Data API.

Tópicos

Transação <transaction_ID> não encontrada
O pacote para consulta é muito grande
A resposta do banco de dados excedeu o limite de tamanho
HttpEndpoint não está habilitado para o cluster <cluster_ID>

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 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.

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, certifique-se de que as chamadas para a API de dados retornem 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 na documentação do MySQL.

HttpEndpoint não está habilitado para o cluster <cluster_ID>

Verifique as possíveis causas a seguir para esse problema:

A API de dados não está habilitada para o cluster de banco de dados do Aurora Serverless v1. Para usar a API de dados com um cluster de banco de dados do Aurora Serverless v1, a API de dados deve estar habilitada para o cluster de banco de dados. Para obter informações sobre como habilitar a API de dados, consulte Habilitar a API de dados.
O cluster de banco de dados foi renomeado depois de a API de dados ter sido 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.

Se a API de dados não tiver sido habilitada para o cluster de banco de dados, habilite-a. Verifique se é um cluster do Aurora Serverless v1. No momento, não é possível usar a API de dados com o Aurora Serverless v2

Se o cluster de banco de dados foi renomeado depois de a API de dados ter sido habilitada para o cluster de banco de dados, desabilite a API de dados e habilite-a novamente.

Para obter informações sobre como habilitar a API de dados, consulte Habilitar a API de dados.

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Versões de mecanismos de banco de dados do Aurora Serverless v1 e do Aurora

Registrar em log chamadas da API Data com o AWS CloudTrail