Uso de la API de datos de RDS

Al utilizar la API de datos de RDS (API de datos), puede trabajar con una interfaz de servicios web para su clúster de base de datos. La API de datos no requiere una conexión persistente al clúster de base de datos. En su lugar, proporciona un punto de enlace HTTP seguro e integración con los AWS SDK. Puede usar el punto de enlace para ejecutar instrucciones SQL sin administrar conexiones.

Los usuarios no necesitan transferir credenciales con llamadas a la API de datos, porque la API de datos utiliza credenciales de base de datos almacenadas en AWS Secrets Manager. Para almacenar credenciales en Secrets Manager, se debe conceder a los usuarios los permisos adecuados para usar Secrets Manager y también la API de datos. Para obtener más información acerca de la autorización de usuarios, consulte Autorización de acceso a la API de datos de RDS.

También puede usar la API de datos para integrar Amazon Aurora con otras aplicaciones de AWS como AWS Lambda, AWS AppSync y AWS Cloud9. La API de datos proporciona una forma más segura de usar AWS Lambda. Le habilita para que obtenga acceso a su clúster de base de datos sin tener que configurar una función Lambda para obtener acceso a recursos de una Virtual Private Cloud (VPC). Para obtener más información, consulte AWS Lambda, AWS AppSync y AWS Cloud9.

Puede habilitar la API de datos al crear el clúster de Aurora DB. También puede modificar la configuración más adelante. Para obtener más información, consulte Habilitar la API de datos de RDS.

Después de habilitar la API de datos, también puede utilizar el editor de consultas para ejecutar consultas ad hoc sin configurar una herramienta de consulta para acceder a Aurora en una VPC. Para obtener más información, consulte Uso del editor de consultas de Aurora.

Disponibilidad en regiones y versiones

Para obtener información sobre las regiones y versiones de motores disponibles para la API de datos, consulte las siguientes secciones.

Si necesita módulos criptográficos validados por FIPS 140-2 al acceder a los datos de la API a través de una interfaz de línea de comandos o una API, utilice un punto de enlace de FIPS. Para obtener más información sobre los puntos de conexión de FIPS disponibles, consulte Estándar de procesamiento de la información federal (FIPS) 140-2.

Limitaciones de la API de datos de RDS

La API de datos de RDS (API de datos) tiene las siguientes limitaciones:

Comparación de la API de datos de RDS con Aurora sin servidor v2 y aprovisionada, y Aurora Serverless v1

Las mejoras más recientes de la API de datos de RDS permiten que esté disponible para los clústeres que utilizan versiones recientes de los motores de PostgreSQL o MySQL. Estos clústeres se pueden configurar para el uso de Aurora Serverless v2 o de clases de instancias aprovisionadas, como db.r6g o db.r6i.

En la siguiente tabla se describen las diferencias entre la API de datos de RDS (API de datos) con clústeres de bases de datos de Aurora Serverless v2 y aprovisionados y los clústeres de bases de datos de Aurora Serverless v1. Aurora Serverless v1 Los clústeres de bases de datos utilizan el modo de motor serverless. Los clústeres de bases de datos aprovisionados utilizan el modo de motor provisioned. Un clúster de base de datos de Aurora Serverless v2 también utiliza el modo de motor provisioned y contiene una o más instancias de base de datos de Aurora Serverless v2 con la clase de instancia db.serverless.

Autorización de acceso a la API de datos de RDS

Los usuarios solo pueden invocar operaciones de la API de datos de RDS (API de datos) si están autorizados a hacerlo. Puede conceder a un usuario permiso para utilizar la API de datos asociando una política de AWS Identity and Access Management (IAM) que defina sus privilegios. También puede asociar la política a un rol si utiliza roles de IAM. Una política administrada por AWS, AmazonRDSDataFullAccess, incluye permisos para la API de datos.

La política AmazonRDSDataFullAccess también incluye permisos para que el usuario obtenga el valor de un secreto de AWS Secrets Manager. Los usuarios deben usar Secrets Manager para almacenar secretos que pueden usar en sus llamadas a la API de datos. El uso de secretos significa que los usuarios no tienen que incluir credenciales de base de datos para los recursos a los que se dirigen en sus llamadas a la API de datos. La API de datos llama de forma transparente a Secrets Manager, lo que permite (o deniega) la solicitud del secreto del usuario. Para obtener información acerca de cómo configurar secretos para utilizarlos con la API de datos, consulte Almacenamiento de credenciales de base de datos en AWS Secrets Manager.

La política AmazonRDSDataFullAccess proporciona acceso completo (a través de la API de datos) a los recursos. Puede restringir el ámbito definiendo sus propias políticas que especifiquen el nombre de recurso de Amazon (ARN) de un recurso.

Por ejemplo, la siguiente política muestra un ejemplo de los permisos mínimos necesarios para que un usuario acceda a la API de datos para el clúster de base de datos identificado por su ARN. La política incluye los permisos necesarios para acceder a Secrets Manager y obtener autorización a la instancia de base de datos para el usuario.

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

Le recomendamos que utilice un ARN específico para el elemento «Recursos» en sus declaraciones de política (como se muestra en el ejemplo) en lugar de un comodín (*).

Trabajo con autorización basada en etiquetas

La API de datos de RDS (API de datos) y Secrets Manager admiten autorización basada en etiquetas. Las etiquetas son pares clave-valor que etiquetan un recurso, como un clúster RDS, con un valor de cadena adicional, por ejemplo:

Puede aplicar etiquetas a los recursos para la asignación de costos, soporte de operaciones, control de acceso y muchas otras razones. (Si aún no tiene etiquetas en sus recursos y desea aplicarlas, puede obtener más información en Etiquetado de recursos de Amazon RDS). Puede utilizar las etiquetas en las instrucciones de política para limitar el acceso a los clústeres de RDS que están etiquetados con estas etiquetas. Por ejemplo, un clúster de base de datos de Aurora puede tener etiquetas que identifican su entorno como producción o desarrollo.

En el ejemplo siguiente se muestra cómo se pueden utilizar etiquetas en las instrucciones de política. Esta instrucción requiere que tanto el clúster como el secreto transferido en la solicitud de API de datos tengan una etiqueta environment:production.

Así es como se aplica la política: cuando un usuario realiza una llamada utilizando la API de datos, la solicitud se envía al servicio. La API de datos comprueba primero que el ARN del clúster transferido en la solicitud esté etiquetado con environment:production. A continuación, llama a Secrets Manager para recuperar el valor del secreto del usuario en la solicitud. Secrets Manager también verifica que el secreto del usuario esté etiquetado con environment:production. Si es así, la API de datos utiliza el valor recuperado para la contraseña de base de datos del usuario. Finalmente, si eso también es correcto, la solicitud de la API de datos se invoca correctamente para el usuario.

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

En el ejemplo se muestran acciones independientes para rds-data y secretsmanager para la API de datos y Secrets Manager. Sin embargo, puede combinar acciones y definir condiciones de etiqueta de muchas maneras distintas para admitir casos de uso específicos. Para obtener más información, consulte Uso de políticas basadas en identidad (políticas de IAM) para Secrets Manager.

En el elemento «Condición» de la política, puede elegir claves de etiqueta entre las siguientes:

Para obtener más información sobre las etiquetas de recursos y cómo utilizar aws:TagKeys, consulte Control del acceso a los recursos de AWS mediante etiquetas de recursos.

Almacenamiento de credenciales de base de datos en AWS Secrets Manager

Al llamar a la API de datos de RDS (API de datos), puede transferir las credenciales del clúster de base de datos de Aurora mediante un secreto en Secrets Manager. Para pasar credenciales mediante este método, especifique el nombre del secreto o el Nombre de recurso de Amazon (ARN) del secreto.

Para obtener más información acerca de cómo utilizar Secrets Manager, consulte la Guía del usuario de Secrets Manager de AWS.

Para comprender cómo administra Amazon Aurora Identity and Access Management, consulte Cómo funciona Amazon Aurora con IAM.

Para obtener más información acerca de cómo crear una política de IAM, consulte Creación de políticas de IAM en la Guía del usuario de IAM. Para obtener información sobre cómo añadir una política de IAM a un usuario, consulte Adición y eliminación de permisos de identidad de IAM en la Guía del usuario de IAM.

Habilitar la API de datos de RDS

Para utilizar la API de datos de RDS (API de datos), habilítela para su clúster de base de datos de Aurora. Puede habilitar la API de datos cuando cree o modifique el clúster de base de datos.

Habilitación de la API de datos de RDS al crear una base de datos

Al crear una base de datos compatible con la API de datos de RDS (API de datos), puede habilitar esta característica. Los siguientes procedimientos describen el proceso al utilizar la AWS Management Console, la AWS CLI o la API de RDS.

Habilitación de la API de datos de RDS en una base de datos existente

Puede modificar un clúster de base de datos que admita la API de datos de RDS (API de datos) para activar o desactivar esta característica.

Habilitación o deshabilitación de la API de datos (Aurora Serverless v2 y aprovisionada)

Utilice los siguientes procedimientos para habilitar o deshabilitar la API de datos en las bases de datos de Aurora Serverless v2 y aprovisionadas. Para activar o desactivar la API de datos en las bases de datos de Aurora Serverless v1, utilice los procedimientos descritos en Habilitación o deshabilitación de la API de datos (solo Aurora Serverless v1).

Habilitación o deshabilitación de la API de datos (solo Aurora Serverless v1)

Para habilitar o deshabilitar la API de datos en las bases de datos de Aurora Serverless v1 existentes. Para habilitar o deshabilitar la API de datos en las bases de datos de Aurora Serverless v2 y aprovisionadas, utilice los procedimientos indicados en Habilitación o deshabilitación de la API de datos (Aurora Serverless v2 y aprovisionada).

Creación de un punto de conexión de VPC para la API de datos de RDS (AWS PrivateLink)

La Amazon VPC le permite lanzar recursos de AWS, como clústeres de bases de datos y aplicaciones de Aurora, en una Virtual Private Cloud (VPC). AWS PrivateLink proporciona conectividad privada entre las VPC y los servicios de AWS con alta seguridad en la red de Amazon. Con AWS PrivateLink, puede crear puntos de enlace de la Amazon VPC que le permiten conectarse a servicios a través de diferentes cuentas y VPC basados en Amazon VPC. Para obtener más información acerca de AWS PrivateLink, consulte Servicios de punto de enlace de la VPC (AWS PrivateLink) en la guía del usuario de Amazon Virtual Private Cloud.

Puede llamar a la API de datos de RDS (API de datos) con los puntos de conexión de la Amazon VPC. El uso de un punto de conexión de VPC de Amazon mantiene el tráfico entre las aplicaciones de su Amazon VPC y la API de datos en la red de AWS, sin usar direcciones IP públicas. Los puntos de enlace de la Amazon VPC pueden ayudarle a cumplir los requisitos reglamentarios y de conformidad relacionados con la limitación de la conectividad a internet público. Por ejemplo, si utiliza un punto de conexión de VPC de Amazon, puede mantener el tráfico entre una aplicación que se ejecuta en una instancia Amazon EC2 y la API de datos en las VPC donde se contienen.

Después de crear el punto de enlace de la Amazon VPC, puede comenzar a usarlo sin realizar ningún cambio de código o configuración en la aplicación.

Una vez creado el punto de enlace, elija el vínculo en la AWS Management Console para ver los detalles del punto de enlace.

La ficha Details (Detalles) del punto de enlace muestra los nombres de host de DNS que se generaron al crear el punto de enlace de la Amazon VPC.

Puede utilizar el punto de enlace estándar (rds-data.region.amazonaws.com) o uno de los puntos de enlace específicos de la VPC para llamar a la API de datos dentro de la Amazon VPC. El punto de enlace de la API de datos estándar se dirige automáticamente al punto de enlace de la Amazon VPC. Este enrutamiento se produce porque cuando se creó el punto de enlace de la Amazon VPC se habilitó el nombre de host de DNS privado.

Cuando utiliza un punto de conexión de VPC de Amazon en una llamada a la API de datos, todo el tráfico entre la aplicación y la API de datos permanece en las Amazon VPC donde se contienen. Puede usar un punto de enlace de la Amazon VPC para cualquier tipo de llamada a la API de datos. Para obtener más información sobre la llamada a la API de datos, consulte Llamadas a la API de datos de RDS.

Llamadas a la API de datos de RDS

Con la API de datos de 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.

Referencia de las operaciones de la API de datos

La API de datos proporciona las operaciones siguientes para realizar instrucciones SQL.

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.

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.

La API de datos de RDS admite los tipos de datos siguientes para Aurora MySQL:

La API de datos de RDS admite los siguientes tipos escalares de Aurora PostgreSQL:

La API de datos de RDS admite los siguientes tipos de matriz de Aurora PostgreSQL:

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.

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:

Llamadas a la API de datos de 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.

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.

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.

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"

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

Además de las opciones habituales, especifique las opciones siguientes:

El clúster de base de datos devuelve una respuesta para la llamada.

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"

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

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

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

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

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

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.

Además de las opciones habituales, especifique las opciones siguientes:

El clúster de base de datos devuelve una respuesta a la llamada.

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

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

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:

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"

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

Además de las opciones habituales, especifique la opción siguiente:

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"

En: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 RDS desde una aplicación Python

Puede llamar a la API de datos de 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).

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.

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.

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.

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

Llamadas a la API de datos de RDS desde una aplicación Java

Puede llamar a la API de datos de 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 for Java Developer Guide.

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.

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

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.

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

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.

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

Puedes 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, consulte Ejecución de una transacción SQL.

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

Usar la biblioteca de cliente de Java para la API de datos de RDS

Puede descargar y utilizar una biblioteca de cliente de Java para la API de datos de RDS (API de datos). La biblioteca de cliente de Java ofrece un método alternativo para utilizar la API de datos. Al utilizar esta biblioteca, puede asignar las clases del lado del cliente a las solicitudes y respuestas de la API de datos. Esta compatibilidad con la asignación puede facilitar la integración con algunos tipos de Java específicos, como Date, Time y BigDecimal.

Descarga de la biblioteca de cliente de Java para la API de datos

La biblioteca de cliente Java para la API de datos es de código abierto en GitHub en la siguiente ubicación:

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

Puede crear la biblioteca de forma manual a partir de los archivos de origen, pero la práctica recomendada es utilizar la biblioteca mediante la administración de dependencias de Apache Maven. Agregue la siguiente dependencia a su archivo Maven POM.

Para la versión 2.x, compatible con AWS SDK 2.x, utilice lo siguiente:

<dependency>
   <groupId>software.amazon.rdsdata</groupId>
   <artifactId>rds-data-api-client-library-java</artifactId>
   <version>2.0.0</version>
</dependency>

Para la versión 1.x, compatible con AWS SDK 1.x, utilice lo siguiente:

<dependency>
    <groupId>software.amazon.rdsdata</groupId>
    <artifactId>rds-data-api-client-library-java</artifactId>
    <version>1.0.8</version>
</dependency>

Ejemplos de la biblioteca de cliente de Java

A continuación, puede encontrar algunos ejemplos habituales del uso de la biblioteca de cliente de Java para la API de datos. En estos ejemplos se asume que tiene una tabla accounts con dos columnas: accountId y name. También tiene el siguiente objeto de transferencia de datos (DTO).

public class Account {
    int accountId;
    String name;
    // getters and setters omitted
}

La biblioteca de cliente le permite transferir los DTO como parámetros de entrada. En el siguiente ejemplo se muestra cómo los DTO del cliente se asignan a los 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();

En algunos casos, es más fácil trabajar con valores simples como parámetros de entrada. Puede hacerlo mediante la siguiente sintaxis:

client.forSql("INSERT INTO accounts(accountId, name) VALUES(:accountId, :name)")
         .withParameter("accountId", 3)
         .withParameter("name", "Zhang")
         .execute();

A continuación se muestra otro ejemplo que funciona con valores simples como parámetros de entrada.

client.forSql("INSERT INTO accounts(accountId, name) VALUES(?, ?)", 4, "Carlos")
         .execute();
                

La biblioteca de cliente proporciona un mapeo automático a los DTO cuando se devuelve un resultado. En los siguientes ejemplos se muestra cómo se asigna el resultado a los DTO.

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

En muchos casos, el conjunto de resultados de la base de datos contiene un solo valor. Para simplificar la recuperación de estos resultados, la biblioteca cliente ofrece la siguiente API:

int numberOfAccounts = client.forSql("SELECT COUNT(*) FROM accounts")
          .execute()
          .singleValue(Integer.class);

Procesamiento de resultados de consultas de API de datos de RDS en formato JSON

Cuando se llama a la operación ExecuteStatement, se puede elegir que los resultados de la consulta se devuelvan como cadena en formato JSON. Esto permite utilizar las capacidades de análisis JSON de su lenguaje de programación para interpretar el conjunto de resultados y volver a darle formato. Hacerlo puede ayudar a evitar escribir código adicional para pasar por el conjunto de resultados e interpretar el valor de cada columna.

Para solicitar el conjunto de resultados en formato JSON, es preciso pasar el parámetro opcional formatRecordsAs con un valor JSON. El conjunto de resultados con formato JSON se devuelve en el campo formattedRecords de la estructura ExecuteStatementResponse.

La acción BatchExecuteStatement no devuelve un conjunto de resultados. Por lo tanto, la opción JSON no se aplica a esa acción.

Para personalizar las claves de la estructura hash JSON, defina alias de columna en el conjunto de resultados. Puede hacerlo mediante la cláusula AS de la lista de columnas de la consulta SQL.

Puede hacer uso de la capacidad JSON para facilitar la lectura del conjunto de resultados y asignar su contenido a marcos específicos de lenguaje. Dado que el volumen del conjunto de resultados codificado en ASCII es mayor que la representación predeterminada, puede elegir la representación predeterminada para consultas que devuelvan un gran número de filas o valores de columna grandes que consuman más memoria de la que está disponible para la aplicación.

Recuperación de resultados de consultas en formato JSON

Para recibir el conjunto de resultados como una cadena JSON, incluya .withFormatRecordsAs(RecordsFormatType.JSON) en la llamada a ExecuteStatement. El valor devuelto vuelve como cadena JSON en el campo formattedRecords. En este caso, columnMetadata es null. Las etiquetas de columna son las claves del objeto que representa cada fila. Estos nombres de columna se repiten para cada fila del conjunto de resultados. Los valores de columna son cadenas entre comillas, valores numéricos o valores especiales que representan true, false o null. Los metadatos de columna, como las restricciones de longitud y el tipo preciso de números y cadenas, no se conservan en la respuesta JSON.

Si omite la llamada .withFormatRecordsAs() o especifica un parámetro de NONE, el conjunto de resultados se devuelve en formato binario mediante los campos Records y columnMetadata.

Asignación de tipos de datos

Los valores SQL del conjunto de resultados se asignan a un conjunto más pequeño de tipos JSON. Los valores se representan en JSON como cadenas, números y ciertas constantes especiales, como true, false y null. Puede convertir estos valores en variables en su aplicación mediante tipado fuerte o débil según corresponda en el lenguaje de programación.

Resolución de problemas

La respuesta JSON se limita a 10 megabytes. Si la respuesta supera este límite, el programa recibe un error BadRequestException. En este caso, puede resolver el error mediante una de las siguientes técnicas:

Ejemplos

Los siguientes ejemplos de Java muestran cómo llamar a ExecuteStatement con la respuesta como cadena con formato JSON y, a continuación, interpretar el conjunto de resultados. Sustituya los valores apropiados por los parámetros databaseName, secretStoreArn y clústerArn.

En el siguiente ejemplo de Java se muestra una consulta que devuelve un valor numérico decimal en el conjunto de resultados. Las llamadas assertThat prueban que los campos de la respuesta tengan las propiedades esperadas según las reglas de los conjuntos de resultados JSON.

Este ejemplo funciona con el siguiente esquema y datos de ejemplo:

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

El valor del campo formattedRecords del programa anterior es:

[{"a":10.0}]

Los campos Records y ColumnMetadata de la respuesta son nulos debido a la presencia del conjunto de resultados JSON.

En el siguiente ejemplo de Java se muestra una consulta que devuelve un valor numérico entero en el conjunto de resultados. En el ejemplo se llama a getFormattedRecords para devolver solo la cadena con formato JSON e ignorar los demás campos de respuesta en blanco o nulos. En el ejemplo se deserializa el resultado en una estructura que representa una lista de registros. Cada registro tiene campos cuyos nombres corresponden a los alias de columna del conjunto de resultados. Esta técnica simplifica el código que analiza el conjunto de resultados. La aplicación no tiene que recorrer las filas y las columnas del conjunto de resultados y convertir cada valor al tipo adecuado.

Este ejemplo funciona con el siguiente esquema y datos de ejemplo:

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

El valor del campo formattedRecords del programa anterior es:

[{"a":17}]

Para recuperar la columna a de la fila de resultados 0, la aplicación haría referencia a recordsList.get(0).a.

En cambio, en el siguiente ejemplo de Java se muestra el tipo de código necesario para construir una estructura de datos que contenga el conjunto de resultados cuando no se utilice el formato JSON. En este caso, cada fila del conjunto de resultados contiene campos con información sobre un solo usuario. La creación de una estructura de datos para representar el conjunto de resultados requiere recorrer las filas en bucle. Para cada fila, el código recupera el valor de cada campo, hace la conversión de tipo adecuada y asigna el resultado al campo correspondiente del objeto que representa la fila. A continuación, el código añade el objeto que representa a cada usuario a la estructura de datos que representa todo el conjunto de resultados. Si la consulta se modificó para reordenar, agregar o quitar campos del conjunto de resultados, el código de la aplicación tendría que cambiar también.

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

Los siguientes valores de ejemplo muestran los valores del campo formattedRecords para conjuntos de resultados con diferentes números de columnas, alias de columna y tipos de datos de columnas.

Si el conjunto de resultados incluye varias filas, cada fila se representa como un objeto que es un elemento de matriz. Cada columna del conjunto de resultados se convierte en una clave dentro del objeto. Las claves se repiten para cada fila del conjunto de resultados. Por lo tanto, para los conjuntos de resultados que constan de varias filas y columnas, es posible que deba definir alias de columna cortos para evitar superar el límite de longitud de toda la respuesta.

Este ejemplo funciona con el siguiente esquema y datos de ejemplo:

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

Si una columna del conjunto de resultados se define como expresión, el texto de la expresión se convierte en la clave JSON. Así pues, suele ser conveniente definir un alias de columna descriptivo para cada expresión de la lista de selección de la consulta. Por ejemplo, la siguiente consulta incluye expresiones como llamadas a funciones y operaciones aritméticas en su lista de selección.

select count(*), max(id), 4+7 from sample_names;

Esas expresiones se pasan al conjunto de resultados JSON como claves.

[{"count(*)":5,"max(id)":4,"4+7":11}]

Añadir columnas AS con etiquetas descriptivas simplifica la interpretación de las claves en el conjunto de resultados JSON.

select count(*) as rows, max(id) as largest_id, 4+7 as addition_result from sample_names;

Con la consulta SQL revisada, se utilizan como nombres de clave las etiquetas de columna definidas por las cláusulas AS.

[{"rows":5,"largest_id":4,"addition_result":11}]

El valor de cada par clave-valor de la cadena JSON puede ser una cadena entre comillas. La cadena podría contener caracteres unicode. Si la cadena contiene secuencias de escape o caracteres " o \, esos personajes van precedidos de caracteres de escape de barra invertida. Los siguientes ejemplos de cadenas JSON muestran estas posibilidades. Por ejemplo, el resultado string_with_escape_sequences contiene el valor de retroceso para caracteres especiales, nueva línea, retorno de carro, sangría, salto de página y \.

[{"quoted_string":"hello"}]
[{"unicode_string":"邓不利多"}]
[{"string_with_escape_sequences":"\b \n \r \t \f \\ '"}] 

El valor de cada par clave-valor de la cadena JSON puede también representar un número. El número puede ser un entero, un valor de coma flotante, un valor negativo o un valor representado como notación exponencial. Los siguientes ejemplos de cadenas JSON muestran estas posibilidades.

[{"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}] 

Los valores booleanos y nulos se representan con las palabras clave especiales sin comillas true, false y null. Los siguientes ejemplos de cadenas JSON muestran estas posibilidades.

[{"boolean_value_1":true,"boolean_value_2":false}]
[{"unknown_value":null}] 

Si selecciona un valor de tipo BLOB, el resultado se representa en la cadena JSON como un valor codificado en base64. Para convertir el valor a su representación original, puede utilizar la función de descodificación adecuada en el lenguaje de la aplicación. Por ejemplo, en Java se llama a la función Base64.getDecoder().decode(). El siguiente ejemplo muestra el resultado de seleccionar un valor BLOB de hello world y devuelve el conjunto de resultados como una cadena JSON.

[{"blob_column":"aGVsbG8gd29ybGQ="}]

El siguiente ejemplo de Python muestra cómo acceder a los valores del resultado de una llamada a la función de Python execute_statement. El conjunto de resultados es un valor de cadena en el campo response['formattedRecords']. El código convierte la cadena JSON en una estructura de datos llamando a la función json.loads. A continuación, cada fila del conjunto de resultados es un elemento de lista dentro de la estructura de datos y, dentro de cada fila, puede hacer referencia a cada campo del conjunto de resultados por nombre.

import json

result = json.loads(response['formattedRecords'])
print (result[0]["id"])

En el siguiente ejemplo de JavaScript se muestra cómo acceder a los valores del resultado de una llamada a la función executeStatement de JavaScript. El conjunto de resultados es un valor de cadena en el campo response.formattedRecords. El código convierte la cadena JSON en una estructura de datos llamando a la función JSON.parse. A continuación, cada fila del conjunto de resultados es un elemento de matriz dentro de la estructura de datos y, dentro de cada fila, puede hacer referencia a cada campo del conjunto de resultados por nombre.

<script>
    const result = JSON.parse(response.formattedRecords);
    document.getElementById("display").innerHTML = result[0].id;
</script> 

Solución de problemas de la API de datos de RDS

Use las siguientes secciones, tituladas con mensajes de error comunes, para ayudar a solucionar problemas que tenga con la API de datos de RDS (API de datos).

No se ha encontrado la transacción <transaction_ID>

En este caso, el ID de transacción especificado en la API de datos no se ha podido encontrar. La causa de este problema se anexa al mensaje de error y es uno de los siguientes:

Para obtener más información acerca de la ejecución de transacciones, consulte Llamadas a la API de datos de RDS.

El paquete de la consulta es demasiado grande

En este caso, el conjunto de resultados devuelto para una fila era demasiado grande. El límite de tamaño de la API de datos es 64 KB por fila en el conjunto de resultados devuelto por la base de datos.

Para solventar este problema, asegúrese de que cada fila de un conjunto de resultados sea de 64 KB o menos.

Límite de tamaño superado de respuesta de base de datos

En este caso, el tamaño del conjunto de resultados devuelto por la base de datos era demasiado grande. El límite de la API de datos es 1 MB en el conjunto de resultados devuelto por la base de datos.

Para resolver este problema, asegúrese de que las llamada a la API de datos devuelvan 1 MiB de datos o menos. Si necesita devolver más de 1 MiB, puede usar varias llamadas ExecuteStatement con la cláusula LIMIT en la consulta.

Para obtener más información acerca de la cláusula LIMIT, consulte SELECT Syntax en la documentación de MySQL.

HttpEndpoint no está habilitado para el clúster <clúster_ID>

Compruebe las siguientes posibles causas de este problema: