Uso de la API de datos para Aurora Serverless v1 - Amazon Aurora

Uso de la API de datos para Aurora Serverless v1

Al utilizar la API de datos para Aurora Serverless v1, puede trabajar con una interfaz de servicios web para su clúster de Aurora Serverless v1 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.

Todas las llamadas a la API de datos son síncronas. De forma predeterminada, una llamada se agota si no ha terminado de procesar en 45 segundos. Sin embargo, puede continuar ejecutando una instrucción SQL si el tiempo de espera de la llamada se agota mediante el parámetro continueAfterTimeout. Para ver un ejemplo, consulte Ejecución de una transacción SQL.

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.

También puede usar la API de datos para integrar Aurora Serverless v1 con otras aplicaciones de AWS como AWS Lambda, AWS AppSync, y AWS Cloud9. La API 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 Serverless v1. También puede modificar la configuración más adelante. Para obtener más información, consulte Habilitar la API de datos.

Después de habilitar la API de datos, también puede utilizar el editor de consultas para Aurora Serverless v1. Para obtener más información, consulte Uso del editor de consultas para Aurora Serverless v1 .

nota

La API de datos y el editor de consultas no son compatibles con Aurora Serverless v2.

Disponibilidad de API de datos

La API de datos se puede habilitar para clústeres de Aurora Serverless v1 base de datos utilizando solo versiones Aurora MySQL y Aurora PostgreSQL específicas. Para obtener más información, consulte API de datos para Aurora Serverless v1.

En la siguiente tabla se muestran las regiones de AWS donde la API de datos está disponible actualmente para Aurora Serverless v1. Utilice el protocolo HTTPS para acceder a la API de datos de estas regiones.

Región Enlace
Este de EE. UU. (Ohio) rds-data.us-east-2.amazonaws.com
Este de EE. UU. (Norte de Virginia) rds-data.us-east-1.amazonaws.com
Oeste de EE. UU. (Norte de California) rds-data.us-west-1.amazonaws.com
Oeste de EE. UU. (Oregón) rds-data.us-west-2.amazonaws.com
Asia-Pacífico (Bombay) rds-data.ap-south-1.amazonaws.com
Asia-Pacífico (Seúl) rds-data.ap-northeast-2.amazonaws.com
Asia-Pacífico (Singapur) rds-data.ap-southeast-1.amazonaws.com
Asia Pacific (Sydney) rds-data.ap-southeast-2.amazonaws.com
Asia Pacific (Tokyo) rds-data.ap-northeast-1.amazonaws.com
Canadá (centro) rds-data.ca-central-1.amazonaws.com
Europe (Frankfurt) rds-data.eu-central-1.amazonaws.com
Europe (Ireland) rds-data.eu-west-1.amazonaws.com
Europe (London) rds-data.eu-west-2.amazonaws.com
Europe (Paris) rds-data.eu-west-3.amazonaws.com

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 enlace de FIPS disponibles, consulte Estándar de procesamiento de la información federal (FIPS) 140-2.

Autorización de acceso a la API de datos

Los usuarios solo pueden invocar operaciones de la 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 de RDS.

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

  • environment:production

  • environment:development

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:

  • aws:TagKeys

  • aws:ResourceTag/${TagKey}

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.

nota

Tanto la API de datos como AWS Secrets Manager autorizan usuarios. Si no tiene permisos para todas las acciones definidas en una política, obtendrá un error AccessDeniedException.

Almacenamiento de credenciales de base de datos en AWS Secrets Manager

Al llamar a la API de datos, puede transferir las credenciales del clúster de base de datos de Aurora Serverless v1 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 almacenar las credenciales de clúster de base de datos en un secreto

  1. Utilice Secrets Manager para crear un secreto que contenga credenciales para el clúster de base de datos de Aurora.

    Para obtener instrucciones, consulte Creación de un secreto básico en la Guía del usuario de AWS Secrets Manager.

  2. Utilice la consola de Secrets Manager para ver los detalles del secreto que ha creado, o ejecute el comando aws secretsmanager describe-secret de la AWS CLI.

    Anote el nombre y el ARN del secreto. Puede utilizarlos en llamadas a la API de datos.

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

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

nota

En la actualidad no se puede utilizar la API de datos con instancias de base de datos Aurora Serverless v2.

Puede habilitar la API de datos con la consola de RDS cuando cree o modifique un clúster de base de datos de Aurora Serverless v1. Cuando cree un clúster de base de datos de Aurora Serverless v1, debe habilitar la API de datos en la sección Connectivity (Conectividad) de la consola de RDS. Cuando modifique un clúster de base de datos de Aurora Serverless v1, debe habilitar la API de datos en la sección Network & Security (Red y seguridad) de la consola de RDS.

En la siguiente captura de pantalla se muestra la Data API (API de datos) cuando se modifica un clúster de base de datos de Aurora Serverless v1.


                            Habilitación de la API de datos para un clúster de base de datos de Aurora Serverless v1 mediante la consola

Para obtener instrucciones, consulte Creación de un clúster de bases de datos de Aurora Serverless v1 y Modificación de un clúster de bases de datos de Aurora Serverless v1.

Cuando crea o modifica un clúster de base de datos de Aurora Serverless v1 mediante la ejecución de los comandos de la CLI de AWS, la API de datos se habilita cuando especifica el valor --enable-http-endpoint.

También puede especificar el valor --enable-http-endpoint con los siguientes comandos de la CLI de AWS:

En el siguiente ejemplo se modifica el valor sample-cluster para habilitar la API de datos.

Para Linux, macOS o Unix:

aws rds modify-db-cluster \ --db-cluster-identifier sample-cluster \ --enable-http-endpoint

Para Windows:

aws rds modify-db-cluster ^ --db-cluster-identifier sample-cluster ^ --enable-http-endpoint

Cuando crea o modifica un clúster de base de datos de Aurora Serverless v1 mediante las operaciones de la API de Amazon RDS, puede habilitar la API de datos al establecer el valor EnableHttpEndpoint en true.

También puede configurar el valor EnableHttpEndpoint con las siguientes operaciones de la API:

Para crear un punto de enlace de la Amazon VPC para la API de datos (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 con los puntos de enlace de la Amazon VPC. El uso de un punto de enlace de la Amazon VPC 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 enlace de la Amazon VPC, 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.

Para crear un punto de enlace de la Amazon VPC para la API de datos

  1. Inicie sesión en la AWS Management Console y abra la consola de Amazon VPC en https://console.aws.amazon.com/vpc/.

  2. Elija Endpoints (Puntos de enlace) y, a continuación, elija Create Endpoint (Crear punto de enlace).

  3. En la página Create Endpoint (Crear punto de conexión), en Service category (Categoría de servicio), elija AWS services (Servicios de AWS). En Service Name (Nombre del servicio), elija rds-data.

    
                            Creación de un punto de enlace de la Amazon VPC para la API de datos
  4. Para VPC, elija la VPC en la que crear el punto de enlace.

    Elija la VPC que contiene la aplicación que realiza llamadas a la API de datos.

  5. En Subnets (Subredes), elija la subred para cada zona de disponibilidad (AZ) utilizada por el servicio de AWS que ejecuta la aplicación.

    
                            Elección de subredes para el punto de enlace de la Amazon VPC

    Para crear un punto de enlace de la Amazon VPC, especifique el rango de direcciones IP privadas en el que se podrá acceder al punto de enlace. Para ello, elija la subred para cada zona de disponibilidad. Al hacerlo, se restringe el punto de enlace de la VPC al rango de direcciones IP privadas específico de cada zona de disponibilidad y también se crea un punto de enlace de la Amazon VPC en cada zona de disponibilidad.

  6. En Enable Private DNS Name (Habilitar nombre de DNS privado), seleccione Enable for this endpoint (Habilitar para este punto de enlace).

    
                            Habilitar el nombre de DNS para el punto de enlace de la Amazon VPC

    El DNS privado resuelve el nombre de host de DNS de la API de datos estándar (https://rds-data.region.amazonaws.com) en las direcciones IP privadas asociadas con el nombre de host de DNS específico del punto de enlace de la Amazon VPC. Como resultado, puede acceder al punto de enlace de la VPC de la API de datos utilizando los SDK de AWS CLI o la AWS sin realizar ningún cambio de código o configuración para actualizar la URL del punto de enlace de la API de datos.

  7. En Security group (Grupo de seguridad), elija los grupos de seguridad que deban asociarse al punto de enlace de la Amazon VPC.

    Elija el grupo de seguridad que permita el acceso al servicio de AWS que ejecuta la aplicación. Por ejemplo, si una instancia Amazon EC2 está ejecutando la aplicación, elija el grupo de seguridad que permita el acceso a la instancia Amazon EC2. El grupo de seguridad le permite controlar el tráfico al punto de enlace de la Amazon VPC desde los recursos de la VPC.

  8. En Policy (Política), elija Full Access (Acceso total) para permitir que cualquier persona dentro de la Amazon VPC acceda a la API de datos a través de este punto de enlace. O bien, elija Custom (Personalizado) para especificar una política que limite el acceso.

    Si eligeCustom (Personalizado), introduzca la política en la herramienta de creación de políticas.

  9. Elija Create endpoint.

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


                    Enlace a los detalles del punto de enlace de la Amazon VPC

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.


                    Enlace a los detalles del 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 enlace de la Amazon VPC 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.

Llamadas a la API de datos

Con la API de datos habilitada en el clúster de base de datos de Aurora Serverless v1, puede ejecutar sentencias 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.

nota

Actualmente, la API de datos no admite matrices de identificadores únicos universales (UUID).

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

Operación de la API

AWS CLI command

Descripción

ExecuteStatement

aws rds-data execute-statement

Ejecuta una instrucción SQL en una base de datos.

BatchExecuteStatement

aws rds-data batch-execute-statement

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

BeginTransaction

aws rds-data begin-transaction

Inicia una transacción SQL.

CommitTransaction

aws rds-data commit-transaction

Finaliza una transacción SQL y confirma los cambios.

RollbackTransaction

aws rds-data rollback-transaction

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

El nombre del recurso de Amazon (ARN) del clúster de base de datos de Aurora Serverless v1.

secretArn

--secret-arn

Nombre o ARN del secreto que permite el acceso al clúster de base de datos.

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

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 con la AWS CLI

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

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

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.

Las sentencias de lenguaje de definición de datos (DDL) dentro de una transacción causan una confirmación implícita. Recomendamos que ejecute cada instrucción DDL 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.

  • --continue-after-timeout | --no-continue-after-timeout (opcional): valor que indica si se seguirá o no ejecutando la instrucción después de que se agote el tiempo de la llamada. 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 en formato JSON.

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.

El número máximo de solicitudes por segundo es 1000.

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 se agote el tiempo de una llamada, 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 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.

El número máximo de solicitudes por segundo es 1000.

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

Puede llamar a la 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 Serverless v1. 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.

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 se agote el tiempo de una llamada, establezca el parámetro continueAfterTimeout en true.

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

Puede llamar a la 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 Serverless v1. 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.

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 se agote el tiempo de una llamada, establezca 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); } }

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

Puede descargar y utilizar una biblioteca de cliente de Java para la 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);
nota

La función mapToList convierte un conjunto de resultados SQL en una lista de objetos definida por el usuario. No se admite el uso de la instrucción .withFormatRecordsAs(RecordsFormatType.JSON) en una llamada de ExecuteStatement a la biblioteca cliente Java, porque tiene el mismo propósito. Para obtener más información, consulte Procesamiento de resultados de consultas en formato JSON .

Procesamiento de resultados de consultas 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 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.

Tipo de datos JDBC

Tipos de datos de JSON

INTEGER, TINYINT, SMALLINT, BIGINT

Número de forma predeterminada. Cadena si la opción LongReturnType está configurada en STRING.

FLOAT, REAL, DOUBLE

Número

DECIMAL

Cadena de forma predeterminada. Número si la opción DecimalReturnType está configurada en DOUBLE_OR_LONG.

STRING

Cadena

BOOLEAN, BIT

Booleano

BLOB, BINARY, VARBINARY, LONGVARBINARY

Cadena en codificación base64.

CLOB

Cadena

ARRAY

Matriz

NULL

null

Otros tipos (incluidos los tipos relacionados con la fecha y hora)

Cadena

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

  • Reducir el número de filas en el conjunto de resultados. Para ello, añada una cláusula LIMIT. Puede dividir un conjunto de resultados grande en varios más pequeños enviando varias consultas con cláusulas LIMIT y OFFSET.

    Si el conjunto de resultados incluye filas filtradas por lógica de aplicación, puede eliminarlas del conjunto de resultados añadiendo más condiciones en la cláusula WHERE.

  • Reducir el número de columnas en el conjunto de resultados. Para ello, retire elementos de la lista de selección de la consulta.

  • Acortar las etiquetas de columna utilizando alias de columna en la consulta. El nombre de cada columna se repite en la cadena JSON para cada fila del conjunto de resultados. Así, un resultado de consulta con nombres de columna largos y muchas filas podría superar el límite de tamaño. En particular, utilice alias de columna para expresiones complicadas para evitar que se repita toda la expresión en la cadena JSON.

  • Aunque con SQL puede utilizar alias de columna para producir un conjunto de resultados que tenga más de una columna con el mismo nombre, no puede haber nombres de claves duplicados en JSON. La API de datos de RDS devuelve un error si solicita el conjunto de resultados en formato JSON y hay más de una columna con el mismo nombre. Así pues, asegúrese de que todas las etiquetas de columna tengan nombres únicos.

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

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

Use las siguientes secciones, tituladas con mensajes de error comunes, para ayudar a solucionar problemas que tenga con la 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:

  • La transacción puede haber caducado.

    Asegúrese también de que cada llamada transaccional se realice antes de que transcurran tres minutos con respecto al uso anterior.

    También es posible que el ID de transacción especificado no se creara con una llamada a BeginTransaction. Asegúrese de que su llamada tenga un ID de transacción válido.

  • Una llamada anterior dio lugar a la finalización de la transacción.

    La transacción ya la ha finalizado su CommitTransaction o la llamada a RollbackTransaction.

  • La transacción se ha anulado debido a un error de una llamada anterior.

    Comprueba si sus llamadas anteriores han arrojado excepciones.

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

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

Compruebe las siguientes posibles causas de este problema:

  • La API de datos no está habilitada para el clúster de base de datos de Aurora Serverless v1. Para utilizar la API de datos con un clúster de base de datos de Aurora Serverless v1, la API de datos debe estar habilitada para el clúster de base de datos. Para obtener más información sobre la habilitación de la API de datos, consulte Habilitar la API de datos.

  • Se cambió el nombre del clúster de base de datos después de que la API de datos se habilitara para él. En ese caso, desactive la API de datos de ese clúster y vuelva a habilitarla.

  • El ARN que ha especificado no coincide exactamente con el ARN del clúster. Compruebe que el ARN devuelto de otro origen o creado por lógica de programa coincida exactamente con el ARN del clúster. Por ejemplo, asegúrese de que el ARN que utiliza tenga la mayúscula o minúscula correcta para todos los caracteres alfabéticos.

Si la API de datos no se ha habilitado para el clúster de base de datos, habilítela. Asegúrese de que sea un clúster Aurora Serverless v1. En la actualidad no se puede utilizar la API de datos con Aurora Serverless v2.

Si se cambió el nombre del clúster de base de datos después de que se habilitara la API de datos para el clúster de base de datos, deshabilite la API de datos y, a continuación, habilítela de nuevo.

Para obtener más información sobre la habilitación de la API de datos, consulte Habilitar la API de datos.