# Llamadas a la API de datos de Amazon RDS
Con la API de datos de Amazon RDS (API de datos) habilitada en el clúster de base de datos de Aurora, puede ejecutar instrucciones SQL en el clúster de base de datos de Aurora mediante la API de datos o la AWS CLI. La API de los datos es compatible con los idiomas de programación compatibles con AWS SDK. Para obtener más información, consulte [Herramientas para crear en AWS](https://aws.amazon.com/tools/).
**Topics**
+ [Referencia de las operaciones de la API de datos de Amazon RDS](data-api-operations.md)
+ [Llamadas a la API de datos de Amazon RDS con la AWS CLI](data-api.calling.cli.md)
+ [Llamadas a la API de datos de Amazon RDS desde una aplicación Python](data-api.calling.python.md)
+ [Llamadas a la API de datos de Amazon RDS desde una aplicación Java](data-api.calling.java.md)
+ [Control del comportamiento del tiempo de espera de la API de datos](data-api-timeouts.md)
# Referencia de las operaciones de la API de datos de Amazon RDS
La API de datos de Amazon RDS proporciona las operaciones siguientes para realizar instrucciones SQL.
****
| Operación de la API | AWS CLI command | Descripción |
| --- | --- | --- |
| [https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_ExecuteStatement.html](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_ExecuteStatement.html) | [https://docs.aws.amazon.com/cli/latest/reference/rds-data/execute-statement.html](https://docs.aws.amazon.com/cli/latest/reference/rds-data/execute-statement.html) | Ejecuta una instrucción SQL en una base de datos. |
| [https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_BatchExecuteStatement.html](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_BatchExecuteStatement.html) | [https://docs.aws.amazon.com/cli/latest/reference/rds-data/batch-execute-statement.html](https://docs.aws.amazon.com/cli/latest/reference/rds-data/batch-execute-statement.html) | Ejecuta una instrucción SQL por lotes en una matriz de datos para operaciones de inserción y actualización masivas. Puede ejecutar una instrucción de lenguaje de manipulación de datos (DML) con una matriz de conjuntos de parámetros. Una instrucción SQL por lotes puede proporcionar una mejora significativa del rendimiento en comparación con las instrucciones de actualización e inserción individuales. |
Puede utilizar cualquiera de las operaciones para ejecutar sentencias SQL individuales o para ejecutar transacciones. La API de datos proporciona las operaciones siguientes para las transacciones.
****
| Operación de la API | AWS CLI command | Descripción |
| --- | --- | --- |
| [https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_BeginTransaction.html](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_BeginTransaction.html) | [https://docs.aws.amazon.com/cli/latest/reference/rds-data/begin-transaction.html](https://docs.aws.amazon.com/cli/latest/reference/rds-data/begin-transaction.html) | Inicia una transacción SQL. |
| [https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_CommitTransaction.html](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_CommitTransaction.html) | [https://docs.aws.amazon.com/cli/latest/reference/rds-data/commit-transaction.html](https://docs.aws.amazon.com/cli/latest/reference/rds-data/commit-transaction.html) | Finaliza una transacción SQL y confirma los cambios. |
| [https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_RollbackTransaction.html](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_RollbackTransaction.html) | [https://docs.aws.amazon.com/cli/latest/reference/rds-data/rollback-transaction.html](https://docs.aws.amazon.com/cli/latest/reference/rds-data/rollback-transaction.html) | Ejecuta una restauración de una transacción. |
Las operaciones para realizar instrucciones SQL y darle soporte a transacciones tienen los siguientes parámetros de la API de datos y opciones de AWS CLI comunes. Algunas operaciones dan soporte a otros parámetros u opciones.
****
| Parámetro de operación de la API de datos | AWS CLIOpción de comando de la | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `resourceArn` | `--resource-arn` | Sí | El nombre de recurso de Amazon (ARN) del clúster de base de datos de Aurora. El clúster debe estar en la misma Cuenta de AWS que el rol o el usuario de IAM que invoca la API de datos. Para acceder a un clúster en una cuenta diferente, asuma un rol en esa cuenta. |
| `secretArn` | `--secret-arn` | Sí | Nombre o ARN del secreto que permite el acceso al clúster de base de datos. |
La API de datos de RDS admite los tipos de datos siguientes para Aurora MySQL:
+ `TINYINT(1)`, `BOOLEAN`, `BOOL`
+ `TINYINT`
+ `SMALLINT` [`SIGNED` \$1 `UNSIGNED`]
+ `MEDIUMINT` [`SIGNED` \$1 `UNSIGNED`]
+ `INT` [`SIGNED` \$1 `UNSIGNED`]
+ `BIGINT` [`SIGNED` \$1 `UNSIGNED`]
+ `FLOAT`
+ `DOUBLE`
+ `VARCHAR`, `CHAR`, `TEXT`, `ENUM`
+ `VARBINARY`, `BINARY`, `BLOB`
+ `DATE`, `TIME`, `DATETIME`, `TIMESTAMP`
+ `DECIMAL`
+ `JSON`
+ `BIT`, `BIT(N)`
La API de datos de RDS admite los siguientes tipos escalares de Aurora PostgreSQL:
+ `BOOL`
+ `BYTEA`
+ `DATE`
+ `CIDR`
+ `DECIMAL`, `NUMERIC`
+ `ENUM`
+ `FLOAT8`, `DOUBLE PRECISION`
+ `INET`
+ `INT`, `INT4`, `SERIAL`
+ `INT2`, `SMALLINT`, `SMALLSERIAL`
+ `INT8`, `BIGINT`, `BIGSERIAL`
+ `JSONB`, `JSON`
+ `REAL`, `FLOAT`
+ `TEXT`, `CHAR(N)`, `VARCHAR`, `NAME`
+ `TIME`
+ `TIMESTAMP`
+ `UUID`
+ `VECTOR`
La API de datos de RDS admite los siguientes tipos de matriz de Aurora PostgreSQL:
+ `BOOL[]`, `BIT[]`
+ `DATE[]`
+ `DECIMAL[]`, `NUMERIC[]`
+ `FLOAT8[]`, `DOUBLE PRECISION[]`
+ `INT[]`, `INT4[]`
+ `INT2[]`
+ `INT8[]`, `BIGINT[]`
+ `JSON[]`
+ `REAL[]`, `FLOAT[]`
+ `TEXT[]`, `CHAR(N)[]`, `VARCHAR[]`, `NAME[]`
+ `TIME[]`
+ `TIMESTAMP[]`
+ `UUID[]`
Puede usar parámetros en las llamadas a la API de datos para `ExecuteStatement` y `BatchExecuteStatement`, y cuando ejecuta los comandos de la AWS CLI `execute-statement` y `batch-execute-statement`. Para utilizar un parámetro, especifique un par de nombre-valor en el tipo de datos `SqlParameter`. Especifique el valor con el tipo de datos `Field`. En la tabla siguiente se mapean los tipos de datos de Java Database Connectivity (JDBC) con los tipos de datos que especifica en las llamadas a la API de datos.
****
| Tipo de datos JDBC | Tipo de datos de la API de datos |
| --- | --- |
| `INTEGER, TINYINT, SMALLINT, BIGINT` | `LONG` (o `STRING`) |
| `FLOAT, REAL, DOUBLE` | `DOUBLE` |
| `DECIMAL` | `STRING` |
| `BOOLEAN, BIT` | `BOOLEAN` |
| `BLOB, BINARY, LONGVARBINARY, VARBINARY` | `BLOB` |
| `CLOB` | `STRING` |
| Otros tipos (incluidos los tipos relacionados con la fecha y hora) | `STRING` |
**nota**
Puede especificar el tipo de datos `LONG` o `STRING` en la llamada de API de datos para `LONG` los valores devueltos por la base de datos. Le recomendamos que lo haga para evitar perder precisión para números extremadamente grandes, lo que puede suceder cuando trabaja con JavaScript.
Ciertos tipos, como `DECIMAL` y `TIME`, requieren una sugerencia para que la API de datos pase `String` valores a la base de datos como el tipo correcto. Para utilizar una sugerencia, incluya valores para `typeHint` en los tipos de datos `SqlParameter`. Los posibles valores de `typeHint` son:
+ `DATE` –: el valor del parámetro `String` correspondiente se envía como un objeto de tipo `DATE` a la base de datos. El formato aceptado es `YYYY-MM-DD`.
+ `DECIMAL` –: el valor del parámetro `String` correspondiente se envía como un objeto de tipo `DECIMAL` a la base de datos.
+ `JSON` –: el valor del parámetro `String` correspondiente se envía como un objeto de tipo `JSON` a la base de datos.
+ `TIME` –: el valor del parámetro `String` correspondiente se envía como un objeto de tipo `TIME` a la base de datos. El formato aceptado es `HH:MM:SS[.FFF]`.
+ `TIMESTAMP` –: el valor del parámetro `String` correspondiente se envía como un objeto de tipo `TIMESTAMP` a la base de datos. El formato aceptado es `YYYY-MM-DD HH:MM:SS[.FFF]`.
+ `UUID` –: el valor del parámetro `String` correspondiente se envía como un objeto de tipo `UUID` a la base de datos.
**nota**
Actualmente, la API de datos no admite matrices de identificadores únicos universales (UUID).
**nota**
Para Amazon Aurora PostgreSQL, la API de datos siempre devuelve el tipo de datos de Aurora PostgreSQL `TIMESTAMPTZ` en la zona horaria UTC.
# Llamadas a la API de datos de Amazon RDS con la AWS CLI
Puede llamar a la API de datos de RDS (API de datos) mediante la AWS CLI.
En los siguientes ejemplos se utiliza la AWS CLI para la API de datos. Para obtener más información, consulte la [referencia de AWS CLI de la API de datos](https://docs.aws.amazon.com/cli/latest/reference/rds-data/index.html).
En cada ejemplo, sustituya el nombre de recurso de Amazon (ARN) del clúster de base de datos por el ARN de su clúster de base de datos de Aurora. Reemplace también el ARN del secreto por el ARN del secreto de Secrets Manager que permite obtener acceso al clúster de base de datos.
**nota**
La AWS CLI puede dar formato a las respuestas de JSON.
**Topics**
+ [Inicio de una transacción SQL](#data-api.calling.cli.begin-transaction)
+ [Ejecución de una instrucción SQL](#data-api.calling.cli.execute-statement)
+ [Ejecución de una instrucción SQL por lotes en una matriz de datos](#data-api.calling.cli.batch-execute-statement)
+ [Confirmación de una transacción SQL](#data-api.calling.cli.commit-transaction)
+ [Restauración de una transacción SQL](#data-api.calling.cli.rollback-transaction)
## Inicio de una transacción SQL
Puede iniciar una transacción SQL ejecutando el comando de la CLI `aws rds-data begin-transaction`. La llamada devuelve un identificador de transacción.
**importante**
Dentro de la API de datos, el tiempo de la transacción se agota si no hay llamadas que usen su ID de transacción en un periodo de tres minutos. Si una transacción agota su tiempo antes de que se confirme, la API de datos se revertirá automáticamente.
Las instrucciones de lenguaje de definición de datos (DDL) de MySQL dentro de una transacción causan una confirmación implícita. Recomendamos que ejecute cada instrucción DDL de MySQL en un comando `execute-statement` independiente con la opción `--continue-after-timeout`.
Además de las opciones comunes, especifique la opción `--database`, que proporciona el nombre de la base de datos.
Por ejemplo, el comando de la CLI siguiente inicia una transacción SQL.
Para Linux, macOS o 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"
```
A continuación se muestra un ejemplo de respuesta.
```
{
"transactionId": "ABC1234567890xyz"
}
```
## Ejecución de una instrucción SQL
Puede ejecutar una instrucción SQL usando el comando de la CLI `aws rds-data execute-statement`.
Puede ejecutar la instrucción SQL en una transacción especificando el identificador de transacción con la opción `--transaction-id`. Puede iniciar una transacción ejecutando el comando de la CLI `aws rds-data begin-transaction`. Puede finalizar y confirmar una transacción ejecutando el comando de la CLI `aws rds-data commit-transaction`.
**importante**
Si no especifica la opción `--transaction-id`, los cambios que se generan a partir de la llamada se confirman automáticamente.
Además de las opciones habituales, especifique las opciones siguientes:
+ `--sql` (obligatorio): instrucción SQL que debe ejecutarse en el clúster de base de datos.
+ `--transaction-id` (opcional): identificador de una transacción que se inició mediante el comando `begin-transaction` de la CLI. Especifique el ID de la transacción en la que desea incluir la instrucción SQL.
+ `--parameters` (opcional): parámetros de la instrucción SQL.
+ `--include-result-metadata | --no-include-result-metadata` (opcional): valor que indica si deben incluirse o no metadatos en los resultados. El valor predeterminado es `--no-include-result-metadata`.
+ `--database` (opcional): el nombre de la base de datos.
Es posible que la opción `--database` no funcione al ejecutar una instrucción SQL después de ejecutar `--sql "use database_name;"` en la solicitud anterior. Le recomendamos que utilice la opción `--database` en lugar de ejecutar instrucciones `--sql "use database_name;"`.
+ `--continue-after-timeout | --no-continue-after-timeout` (opcional): un valor que indica si se seguirá o no ejecutando la instrucción después de que la llamada supere el intervalo de tiempo de espera de la API de datos de 45 segundos. El valor predeterminado es `--no-continue-after-timeout`.
Para las instrucciones en lenguaje de definición de datos (DDL), recomendamos seguir ejecutando la instrucción después de que se agote el tiempo de la llamada, a fin de evitar errores y la posibilidad de que las estructuras de datos se dañen.
+ `--format-records-as "JSON"|"NONE"`: valor opcional que especifica si se debe dar formato al conjunto de resultados como cadena JSON. El valor predeterminado es `"NONE"`. Para obtener información sobre el procesamiento de conjuntos de resultados JSON, consulte [Procesamiento de resultados de consultas de API de datos de Amazon RDS en formato JSON](data-api-json.md).
El clúster de base de datos devuelve una respuesta para la llamada.
**nota**
El límite de tamaño de respuesta es de 1 MiB. Si la llamada devuelve más de 1 MiB de datos de respuesta, se terminará la llamada.
Para Aurora Serverless v1, el número máximo de solicitudes por segundo es 1000. Para el resto de bases de datos compatibles, no hay límite.
Por ejemplo, el siguiente comando de la CLI ejecuta una única instrucción SQL y omite los metadatos en los resultados (valor predeterminado).
Para Linux, macOS o 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"
```
A continuación se muestra un ejemplo de respuesta.
```
{
"numberOfRecordsUpdated": 0,
"records": [
[
{
"longValue": 1
},
{
"stringValue": "ValueOne"
}
],
[
{
"longValue": 2
},
{
"stringValue": "ValueTwo"
}
],
[
{
"longValue": 3
},
{
"stringValue": "ValueThree"
}
]
]
}
```
El siguiente comando de la CLI ejecuta una única instrucción SQL en una transacción mediante la opción `--transaction-id`.
Para Linux, macOS o 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"
```
A continuación se muestra un ejemplo de respuesta.
```
{
"numberOfRecordsUpdated": 1
}
```
El siguiente comando de la CLI ejecuta una única instrucción SQL con parámetros.
Para Linux, macOS o 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\"}}]"
```
A continuación se muestra un ejemplo de respuesta.
```
{
"numberOfRecordsUpdated": 1
}
```
El siguiente comando de la CLI ejecuta una instrucción SQL de lenguaje de definición de datos (DDL). La instrucción DDL cambia el nombre de la columna `job` por la columna `role`.
**importante**
Para las instrucciones DDL, recomendamos seguir ejecutando la instrucción después de que se agote el tiempo de la llamada. Cuando se termina una instrucción DDL antes de que acabe de ejecutarse, pueden generarse errores y es posible que las estructuras de datos se dañen. Para seguir ejecutando una instrucción después de que una llamada supere el intervalo de tiempo de espera de la API de datos de RDS de 45 segundos, especifique la opción `--continue-after-timeout`.
Para Linux, macOS o 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
```
A continuación se muestra un ejemplo de respuesta.
```
{
"generatedFields": [],
"numberOfRecordsUpdated": 0
}
```
**nota**
Los datos `generatedFields` no se admiten en Aurora PostgreSQL. Para obtener los valores de los campos generados, utilice la cláusula `RETURNING`. Para obtener más información, consulte [Returning Data From Modified Rows](https://www.postgresql.org/docs/10/dml-returning.html) en la documentación de PostgreSQL.
## Ejecución de una instrucción SQL por lotes en una matriz de datos
Puede ejecutar una instrucción SQL por lotes en una matriz de datos ejecutando el comando `aws rds-data batch-execute-statement` de la CLI. Puede utilizar este comando para realizar una operación de actualización o importación masiva.
Puede ejecutar la instrucción SQL en una transacción especificando el identificador de transacción con la opción `--transaction-id`. Puede iniciar una transacción ejecutando el comando de la CLI `aws rds-data begin-transaction`. Puede finalizar y confirmar una transacción mediante el comando `aws rds-data commit-transaction` de la CLI.
**importante**
Si no especifica la opción `--transaction-id`, los cambios que se generan a partir de la llamada se confirman automáticamente.
Además de las opciones habituales, especifique las opciones siguientes:
+ `--sql` (obligatorio): instrucción SQL que debe ejecutarse en el clúster de base de datos.
**sugerencia**
Para las sentencias compatibles con MySQL, no incluya un punto y coma al final del parámetro `--sql`. Un punto y coma final puede causar un error de sintaxis.
+ `--transaction-id` (opcional): identificador de una transacción que se inició mediante el comando `begin-transaction` de la CLI. Especifique el ID de la transacción en la que desea incluir la instrucción SQL.
+ `--parameter-set` (opcional): los conjuntos de parámetros para la operación por lotes.
+ `--database` (opcional): el nombre de la base de datos.
El clúster de base de datos devuelve una respuesta a la llamada.
**nota**
No existe un límite máximo fijo en el número de conjuntos de parámetros. Sin embargo, el tamaño máximo de la solicitud HTTP enviada a través de la API de datos es de 4 MiB. Si la solicitud supera este límite, la API de datos devuelve un error y no procesa la solicitud. Este límite de 4 MiB incluye el tamaño de los encabezados HTTP y la notación JSON en la solicitud. Por lo tanto, el número de conjuntos de parámetros que puede incluir depende de una combinación de factores, como el tamaño de la sentencia SQL y el tamaño de cada conjunto de parámetros.
El límite de tamaño de respuesta es de 1 MiB. Si la llamada devuelve más de 1 MiB de datos de respuesta, se terminará la llamada.
Para Aurora Serverless v1, el número máximo de solicitudes por segundo es 1000. Para el resto de bases de datos compatibles, no hay límite.
Por ejemplo, el siguiente comando de la CLI ejecuta una instrucción SQL por lotes en una matriz de datos con un conjunto de parámetros.
Para Linux, macOS o 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**
No incluya saltos de línea en la opción `--parameter-sets`.
## Confirmación de una transacción SQL
Con el comando `aws rds-data commit-transaction` de la CLI, puede finalizar una transacción SQL que inició con `aws rds-data begin-transaction` y confirmar los cambios.
Además de las opciones habituales, especifique la opción siguiente:
+ `--transaction-id` (obligatorio): identificador de una transacción que se inició ejecutando el comando `begin-transaction` de la CLI. Especifique el ID de la transacción que desea finalizar y confirmar.
Por ejemplo, el siguiente comando de la CLI finaliza una transacción SQL y confirma los cambios.
Para Linux, macOS o 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"
```
A continuación se muestra un ejemplo de respuesta.
```
{
"transactionStatus": "Transaction Committed"
}
```
## Restauración de una transacción SQL
Con el comando `aws rds-data rollback-transaction` de la CLI, puede revertir una transacción SQL que inició con `aws rds-data begin-transaction`. Si revierte una transacción, cancelará sus cambios.
**importante**
Si el ID de la transacción ha vencido, la transacción se revertirá automáticamente. En este caso, un comando `aws rds-data rollback-transaction` que especifique el ID de transacción que ha vencido devolverá un error.
Además de las opciones habituales, especifique la opción siguiente:
+ `--transaction-id` (obligatorio): identificador de una transacción que se inició ejecutando el comando `begin-transaction` de la CLI. Especifique el ID de la transacción que desea revertir.
Por ejemplo, el comando de la AWS CLI siguiente revierte una transacción SQL.
Para Linux, macOS o 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"
```
A continuación se muestra un ejemplo de respuesta.
```
{
"transactionStatus": "Rollback Complete"
}
```
# Llamadas a la API de datos de Amazon RDS desde una aplicación Python
Puede llamar a la API de datos de Amazon RDS (API de datos) desde una aplicación Python.
En los ejemplos siguientes se usa el AWS SDK para Python (Boto). Para obtener más información acerca de Boto, consulte la [documentación de AWS SDK para Python (Boto 3)](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html).
En cada ejemplo, sustituya el nombre de recurso de Amazon (ARN) del clúster de base de datos por el ARN de su clúster de base de datos de Aurora. Reemplace también el ARN del secreto por el ARN del secreto de Secrets Manager que permite obtener acceso al clúster de base de datos.
**Topics**
+ [Ejecución de una consulta SQL](#data-api.calling.python.run-query)
+ [Ejecución de una instrucción SQL DML](#data-api.calling.python.run-inert)
+ [Ejecución de una transacción SQL](#data-api.calling.python.run-transaction)
## Ejecución de una consulta SQL
Puede ejecutar una instrucción `SELECT` y recopilar los resultados con una aplicación Python.
En el ejemplo siguiente, se ejecuta una 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'
}
]
]
```
## Ejecución de una instrucción SQL DML
Puede ejecutar una instrucción de lenguaje de manipulación de datos (DML) para insertar, actualizar o eliminar datos en su base de datos. También puede utilizar parámetros en instrucciones DML.
**importante**
Si una llamada no forma parte de una transacción porque no incluye el parámetro `transactionID`, los cambios que se generen a partir de la llamada se confirmarán automáticamente.
En el ejemplo siguiente se ejecuta una instrucción SQL de inserción y se utilizan 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"])
```
## Ejecución de una transacción SQL
Puede iniciar una transacción SQL, ejecutar una o varias instrucciones SQL y luego confirmar los cambios con una aplicación Python.
**importante**
El tiempo de la transacción se agota si no hay llamadas que usen su ID de transacción en un período de tres minutos. Si una transacción agota su tiempo antes de que se confirme, se revertirá automáticamente.
Si no especifica un ID de transacción, los cambios que se generen a partir de la llamada se confirmarán automáticamente.
En el ejemplo siguiente se ejecuta una transacción SQL que inserta una fila en una tabla.
```
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**
Si ejecuta una instrucción de lenguaje de definición de datos (DDL), recomendamos que siga ejecutando la instrucción después de que se agote el tiempo de la llamada. Cuando se termina una instrucción DDL antes de que acabe de ejecutarse, pueden generarse errores y es posible que las estructuras de datos se dañen. Para seguir ejecutando una instrucción después de que una llamada supere el intervalo de tiempo de espera de la API de datos de RDS de 45 segundos, ajuste el parámetro `continueAfterTimeout` en `true`.
# Llamadas a la API de datos de Amazon RDS desde una aplicación Java
Puede llamar a la API de datos de Amazon RDS (API de datos) desde una aplicación Java.
En los ejemplos siguientes se usa el AWS SDK para Java. Para obtener más información, consulte [AWS SDK para Java Developer Guide](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/welcome.html).
En cada ejemplo, sustituya el nombre de recurso de Amazon (ARN) del clúster de base de datos por el ARN de su clúster de base de datos de Aurora. Reemplace también el ARN del secreto por el ARN del secreto de Secrets Manager que permite obtener acceso al clúster de base de datos.
**Topics**
+ [Ejecución de una consulta SQL](#data-api.calling.java.run-query)
+ [Ejecución de una transacción SQL](#data-api.calling.java.run-transaction)
+ [Ejecución de una operación SQL por lotes](#data-api.calling.java.run-batch)
## Ejecución de una consulta SQL
Puede ejecutar una instrucción `SELECT` y recopilar los resultados con una aplicación Java.
En el ejemplo siguiente, se ejecuta una consulta SQL.
```
package com.amazonaws.rdsdata.examples;
import com.amazonaws.services.rdsdata.AWSRDSData;
import com.amazonaws.services.rdsdata.AWSRDSDataClient;
import com.amazonaws.services.rdsdata.model.ExecuteStatementRequest;
import com.amazonaws.services.rdsdata.model.ExecuteStatementResult;
import com.amazonaws.services.rdsdata.model.Field;
import java.util.List;
public class FetchResultsExample {
public static final String RESOURCE_ARN = "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster";
public static final String SECRET_ARN = "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret";
public static void main(String[] args) {
AWSRDSData rdsData = AWSRDSDataClient.builder().build();
ExecuteStatementRequest request = new ExecuteStatementRequest()
.withResourceArn(RESOURCE_ARN)
.withSecretArn(SECRET_ARN)
.withDatabase("mydb")
.withSql("select * from mytable");
ExecuteStatementResult result = rdsData.executeStatement(request);
for (List fields: result.getRecords()) {
String stringValue = fields.get(0).getStringValue();
long numberValue = fields.get(1).getLongValue();
System.out.println(String.format("Fetched row: string = %s, number = %d", stringValue, numberValue));
}
}
}
```
## Ejecución de una transacción SQL
Puede iniciar una transacción SQL, ejecutar una o varias instrucciones SQL y luego confirmar los cambios con una aplicación Java.
**importante**
El tiempo de la transacción se agota si no hay llamadas que usen su ID de transacción en un período de tres minutos. Si una transacción agota su tiempo antes de que se confirme, se revertirá automáticamente.
Si no especifica un ID de transacción, los cambios que se generen a partir de la llamada se confirmarán automáticamente.
En el ejemplo siguiente, se ejecuta una transacción 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**
Si ejecuta una instrucción de lenguaje de definición de datos (DDL), recomendamos que siga ejecutando la instrucción después de que se agote el tiempo de la llamada. Cuando se termina una instrucción DDL antes de que acabe de ejecutarse, pueden generarse errores y es posible que las estructuras de datos se dañen. Para seguir ejecutando una instrucción después de que una llamada supere el intervalo de tiempo de espera de la API de datos de RDS de 45 segundos, ajuste el parámetro `continueAfterTimeout` en `true`.
## Ejecución de una operación SQL por lotes
Puede ejecutar operaciones de inserción y actualización masivas en una matriz de datos, con una aplicación Java. Puede ejecutar una instrucción DML con una matriz de conjuntos de parámetros.
**importante**
Si no especifica un ID de transacción, los cambios que se generen a partir de la llamada se confirmarán automáticamente.
En el siguiente ejemplo se ejecuta una operación de inserción por lotes.
```
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);
}
}
```
# Control del comportamiento del tiempo de espera de la API de datos
Todas las llamadas a la API de datos son síncronas. Imaginemos que realiza una operación de API de datos que ejecuta una instrucción de SQL como `INSERT` o`CREATE TABLE`. Si la llamada a la API de datos se devuelve correctamente, el procesamiento de SQL finaliza cuando se devuelve la llamada.
De forma predeterminada, la API de datos cancela una operación y devuelve un error de tiempo de espera si la operación no termina de procesarse en 45 segundos. En ese caso, los datos no se insertan, la tabla no se crea, etc.
Puede usar la API de datos para realizar operaciones de larga duración que no se puedan completar en 45 segundos. Si espera que una operación, como una operación masiva de `INSERT` o DDL en una tabla grande, tarde más de 45 segundos, puede especificar el parámetro `continueAfterTimeout` para la operación `ExecuteStatement`. La aplicación sigue recibiendo el error de tiempo de espera. Sin embargo, la operación continúa ejecutándose y no se cancela. Para ver un ejemplo, consulta [Ejecución de una transacción SQL](data-api.calling.java.md#data-api.calling.java.run-transaction).
Si el AWS SDK de su lenguaje de programación tiene su propio tiempo de espera para las llamadas a la API o las conexiones de sockets HTTP, asegúrese de que todos esos periodos de tiempo de espera sean superiores a 45 segundos. En algunos SDK, el tiempo de espera es inferior a 45 segundos de forma predeterminada. Recomendamos ajustar cualquier periodo de tiempo de espera específico del SDK o específico del cliente en al menos un minuto. De este modo, se evita la posibilidad de que la aplicación reciba un error de tiempo de espera mientras la operación de la API de datos se complete correctamente. De esta forma, puede estar seguro de si desea volver a intentar la operación o no.
Por ejemplo, supongamos que el SDK devuelve un error de tiempo de espera a su aplicación, pero la operación de la API de datos sigue completándose dentro del intervalo de tiempo de espera de la API de datos. En ese caso, volver a intentar la operación podría insertar datos duplicados o producir resultados incorrectos. Es posible que el SDK vuelva a intentar la operación automáticamente, lo que provoca datos incorrectos sin que la aplicación realice ninguna acción.
El intervalo de tiempo de espera es especialmente importante para el SDK de Java 2. En ese SDK, el tiempo de espera de la llamada a la API y el tiempo de espera del socket HTTP es de 30 segundos de forma predeterminada. En este ejemplo se muestra cómo ajustar esos tiempos de espera en un valor superior:
```
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));
}
```
A continuación, se muestra un ejemplo equivalente con el cliente de datos así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));
}
```