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

Uso de la API de datos para Aurora Serverless

Al utilizar la API de datos para Aurora Serverless, puede trabajar con una interfaz de servicios web para su clúster de Aurora Serverless 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 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. 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. Para obtener más información, consulte Uso del editor de consultas para Aurora Serverless.

Disponibilidad de API de datos

La API de datos se puede habilitar para clústeres de Aurora Serverless 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.

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

Región Enlace
US East (Ohio) rds-data.us-east-2.amazonaws.com
EE.UU. Este (Norte de Virginia) rds-data.us-east-1.amazonaws.com
EE.UU. Oeste (Norte de California) rds-data.us-west-1.amazonaws.com
US West (Oregon) rds-data.us-west-2.amazonaws.com
Asia Pacific (Mumbai) rds-data.ap-south-1.amazonaws.com
Asia Pacific (Seoul) 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
Canada (Central) 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 acerca de 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 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. Puede habilitar la API de datos cuando cree o modifique el clúster de base de datos.

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. Cuando cree un clúster de base de datos de Aurora Serverless, 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, 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.


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

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

Cuando crea o modifica un clúster de base de datos de Aurora Serverless 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 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, 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.

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

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. 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. 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 POM de Maven:

<dependency> <groupId>software.amazon.rdsdata</groupId> <artifactId>rds-data-api-client-library-java</artifactId> <version>1.0.7</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);

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 casi siempre es uno de los siguientes:

  • El ID de transacción especificado no se creó con una llamada BeginTransaction.

  • El ID de transacción especificado ha caducado.

    Una transacción caduca si ninguna llamada utiliza el ID de transacción en un plazo de tres minutos.

Para resolver el problema, asegúrese de que su llamada tenga un ID de transacción válido. Asegúrese también de que cada transacción se realice antes de que transcurran tres minutos con respecto a la última.

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>

La causa de este problema casi siempre es uno de los siguientes:

  • La API de datos no está habilitada para el clúster de base de datos de Aurora Serverless. Para utilizar la API de datos con un clúster de base de datos de Aurora Serverless, la API de datos debe estar habilitada para el clúster de base 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.

Si la API de datos no se ha habilitado para el clúster de base de datos, habilítela.

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.