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.

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, AWS AppSync e AWS Cloud9.

É possível habilitar a API de dados ao criar o cluster de banco de dados do Aurora. Também é possível modificar a configuração posteriormente. Para ter 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 ter mais informações, consulte Como usar o editor de consultas do Aurora.

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.

Se forem necessários módulos criptográficos validados pelo FIPS 140-2 ao acessar a API de dados por meio de uma interface de linha de comandos ou uma API, use um endpoint do FIPS. Para ter mais informações sobre endpoints do FIPS disponíveis, consulte Federal Information Processing Standard (FIPS) 140-2.

Limitações com a API de dados do RDS

A API de dados do RDS (API de dados) tem as seguintes limitações:

Comparação da API de dados do RDS com Sem Servidor v2 e provisionado e o Aurora Serverless v1

Os aprimoramentos mais recentes da API de dados do RDS a tornam disponível para clusters que usam versões recentes dos mecanismos do PostgreSQL ou do MySQL. Esses clusters podem ser configurados para usar o Aurora Serverless v2 ou classes de instância provisionadas, como db.r6g ou db.r6i.

A tabela a seguir descreve as diferenças entre a API de dados do RDS (API de dados) com o Aurora Serverless v2, os clusters de banco de dados provisionados e os clusters de banco de dados do Aurora Serverless v1. Os clusters de banco de dados do Aurora Serverless v1 usam o modo de mecanismo serverless. Os clusters de banco de dados provisionados usam o modo de mecanismo provisioned. Um cluster de banco de dados Aurora Serverless v2 também usa o modo de mecanismo provisioned e contém uma ou mais instâncias de banco de dados Aurora Serverless v2 com a classe de instância db.serverless.

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:

É 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:

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.

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

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.

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.

Habilitar ou desabilitar a API de dados (Aurora Serverless v2 e provisionado)

Use os procedimentos a seguir para habilitar ou desabilitar a API de dados em bancos de dados do Aurora Serverless v2 e provisionados. Para habilitar ou desabilitar a API de dados em bancos de dados do Aurora Serverless v1, use os procedimentos em Habilitar ou desabilitar a API de dados (somente o Aurora Serverless v1).

Habilitar ou desabilitar a API de dados (somente o Aurora Serverless v1)

Use os procedimentos a seguir para habilitar ou desabilitar a API de dados em bancos de dados do Aurora Serverless v1. Para habilitar ou desabilitar a API de dados em bancos de dados do Aurora Serverless v2 e provisionados, use os procedimentos em Habilitar ou desabilitar a API de dados (Aurora Serverless v2 e provisionado).

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.

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.region.amazonaws.com) ou um dos endpoints específicos da VPC para chamar a API de dados dentro da Amazon VPC. O endpoint padrão da API de dados roteia automaticamente para o Amazon VPC endpoint. Esse roteamento ocorre porque o nome de host DNS privado foi habilitado quando o Amazon VPC endpoint foi criado.

Ao usar um endpoint da Amazon VPC em uma chamada da API de dados, todo tráfego entre a aplicação e a API de dados permanece nas Amazon VPCs que as contêm. Você pode usar um Amazon VPC endpoint para qualquer tipo de chamada da API de dados. Para ter informações sobre como chamar a API de dados, consulte Chamar a API de dados do 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.

Referência das operações de API de dados

A API de dados oferece as operações a seguir para executar declarações SQL.

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.

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.

A API de dados do RDS é compatível com os seguintes tipos de dados para o Aurora MySQL:

A API de dados do RDS é compatível com os seguintes tipos escalares do Aurora PostgreSQL:

A API de dados do RDS é compatível com os seguintes tipos de matriz do Aurora PostgreSQL:

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.

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:

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.

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.

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.

Além das opções comuns, especifique as opções a seguir:

O cluster de banco de dados retorna uma resposta para a chamada.

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.

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
}

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.

Além das opções comuns, especifique as opções a seguir:

O cluster de banco de dados retorna uma resposta para a chamada.

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\"}}]]"

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:

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.

Além das opções comuns, especifique a opção a seguir:

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.

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.

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

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.

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);
  }
}

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.

O exemplo a seguir executa uma operação de inserção em lote.

package com.amazonaws.rdsdata.examples;

import com.amazonaws.services.rdsdata.AWSRDSData;
import com.amazonaws.services.rdsdata.AWSRDSDataClient;
import com.amazonaws.services.rdsdata.model.BatchExecuteStatementRequest;
import com.amazonaws.services.rdsdata.model.Field;
import com.amazonaws.services.rdsdata.model.SqlParameter;

import java.util.Arrays;

public class BatchExecuteExample {
  public static final String RESOURCE_ARN = "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster";
  public static final String SECRET_ARN = "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret";

  public static void main(String[] args) {
      AWSRDSData rdsData = AWSRDSDataClient.builder().build();

    BatchExecuteStatementRequest request = new BatchExecuteStatementRequest()
            .withDatabase("test")
            .withResourceArn(RESOURCE_ARN)
            .withSecretArn(SECRET_ARN)
            .withSql("INSERT INTO test_table2 VALUES (:string, :number)")
            .withParameterSets(Arrays.asList(
                    Arrays.asList(
                            new SqlParameter().withName("string").withValue(new Field().withStringValue("Hello")),
                            new SqlParameter().withName("number").withValue(new Field().withLongValue(1L))
                    ),
                    Arrays.asList(
                            new SqlParameter().withName("string").withValue(new Field().withStringValue("World")),
                            new SqlParameter().withName("number").withValue(new Field().withLongValue(2L))
                    )
            ));

    rdsData.batchExecuteStatement(request);
  }
}

Controlar o comportamento de tempo limite da API de dados

Todas as chamadas para a API de dados são síncronas. Suponha que você realize uma operação da API de dados que execute uma instrução SQL, como INSERT ou CREATE TABLE. Se a chamada da API de dados for retornada com êxito, o processamento de SQL será concluído quando a chamada for retornada.

Por padrão, a API de dados cancelará uma operação e retornará um erro de tempo limite se o processamento da operação não for concluído em 45 segundos. Nesse caso, os dados não são inseridos, a tabela não é criada e assim por diante.

É possível usar a API de dados para realizar operações de longa duração que não podem ser concluídas em 45 segundos. Se você espera que uma operação, como uma operação INSERT em massa ou uma operação de DDL em uma tabela grande, leve mais de 45 segundos, especifique o parâmetro continueAfterTimeout para a operação ExecuteStatement. A aplicação ainda recebe o erro de tempo limite. No entanto, a operação continua em execução e não é cancelada. Para ver um exemplo, consulte Executar uma transação SQL.

Se o SDK da AWS da sua linguagem de programação tiver um período de tempo limite próprio para chamadas de API ou conexões de soquete HTTP, todos esses períodos de tempo limite deverão ser superiores a 45 segundos. Para alguns SDKs, o período de tempo limite é inferior a 45 segundos por padrão. Recomendamos definir qualquer período de tempo limite específico do SDK ou do cliente para pelo menos um minuto. Isso evita a possibilidade de a aplicação receber um erro de tempo limite e garante que a operação da API de dados seja concluída com êxito. Dessa forma, você pode ter certeza sobre se deve tentar novamente a operação ou não.

Por exemplo, suponha que o SDK retorne um erro de tempo limite para a aplicação, mas a operação da API de dados ainda seja concluída dentro do respectivo intervalo de tempo limite. Nesse caso, repetir a operação pode inserir dados duplicados ou produzir resultados incorretos. O SDK pode repetir a operação automaticamente, originando dados incorretos sem nenhuma ação da aplicação.

O intervalo de tempo limite é especialmente importante para o SDK para Java 2. Nesse SDK, o tempo limite da chamada de API e o tempo limite do soquete HTTP são de 30 segundos por padrão. Veja um exemplo de como configurar o tempo limite para um valor mais alto:

public RdsDataClient createRdsDataClient() {
    return RdsDataClient.builder()
        .region(Region.US_EAST_1) // Change this to your desired Region
        .overrideConfiguration(createOverrideConfiguration())
        .httpClientBuilder(createHttpClientBuilder())
        .credentialsProvider(defaultCredentialsProvider()) // Change this to your desired credentials provider
        .build();
}

private static ClientOverrideConfiguration createOverrideConfiguration() {
    return ClientOverrideConfiguration.builder()
        .apiCallTimeout(Duration.ofSeconds(60))
        .build();
}
    
private HttpClientBuilder createHttpClientBuilder() {
    return ApacheHttpClient.builder() // Change this to your desired HttpClient
        .socketTimeout(Duration.ofSeconds(60));
}

Veja um exemplo equivalente usando o cliente de dados assíncrono:

public static RdsDataAsyncClient createRdsDataAsyncClient() {
    return RdsDataAsyncClient.builder()
        .region(Region.US_EAST_1) // Change this to your desired Region
        .overrideConfiguration(createOverrideConfiguration())
        .credentialsProvider(defaultCredentialsProvider())  // Change this to your desired credentials provider
        .build();
}

private static ClientOverrideConfiguration createOverrideConfiguration() {
    return ClientOverrideConfiguration.builder()
        .apiCallAttemptTimeout(Duration.ofSeconds(60))
        .build();
}

private HttpClientBuilder createHttpClientBuilder() {
    return NettyNioAsyncHttpClient.builder() // Change this to your desired AsyncHttpClient
        .readTimeout(Duration.ofSeconds(60));
}

Usar a biblioteca do cliente Java para a API de dados do RDS

É possível baixar e usar uma biblioteca do cliente Java para a API de dados do RDS (API de dados). Essa biblioteca do cliente Java fornece uma forma alternativa de usar a API de dados. Usando essa biblioteca, é possível associar as classes no lado do cliente a solicitações e respostas da API de dados. Esse suporte ao mapeamento pode facilitar a integração com alguns tipos específicos de Java, como Date, Time e BigDecimal.

Baixar a biblioteca cliente Java para API de dados

A biblioteca de cliente Java da API de dados é de código aberto no GitHub no seguinte local:

https://github.com/awslabs/rds-data-api-client-library-java

É 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);

Processar resultados de consulta da API de dados do RDS no formato JSON

Ao chamar a operação ExecuteStatement, você pode optar por ter os resultados da consulta retornados como uma string no formato JSON. Dessa forma, é possível usar os recursos de análise JSON da linguagem de programação para interpretar e reformatar o conjunto de resultados. Isso pode ajudar a evitar a necessidade de escrever código adicional para percorrer o conjunto de resultados e interpretar cada valor de coluna.

Para solicitar o conjunto de resultados no formato JSON, transmita o parâmetro formatRecordsAs opcional com um valor de JSON. O conjunto de resultados formatado em JSON é retornado no campo formattedRecords da estrutura ExecuteStatementResponse.

A ação BatchExecuteStatement não retorna um conjunto de resultados. Dessa forma, a opção JSON não se aplica a essa ação.

Para personalizar as chaves na estrutura de hash JSON, defina aliases de coluna no conjunto de resultados. Você pode fazer isso usando a cláusula AS na lista de colunas da consulta SQL.

É possível usar o recurso JSON para tornar o conjunto de resultados mais fácil de ler e mapear o respectivo conteúdo para frameworks específicos de linguagem. Como o volume do conjunto de resultados com codificação ASCII é maior do que a representação padrão, talvez você escolha a representação padrão para consultas que retornem números de linhas ou valores de coluna grandes que consomem mais memória do que o disponível para a aplicação.

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.

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:

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

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:

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