Uso de la API de datos de RDS
Al utilizar la API de datos de RDS (API de datos), puede trabajar con una interfaz de servicios web para su clúster de base de datos. La API de datos no requiere una conexión persistente al clúster de base de datos. En su lugar, proporciona un punto de enlace HTTP seguro e integración con los AWS SDK. Puede usar el punto de enlace para ejecutar instrucciones SQL sin administrar conexiones.
Los usuarios no necesitan transferir credenciales con llamadas a la API de datos, porque la API de datos utiliza credenciales de base de datos almacenadas en AWS Secrets Manager. Para almacenar credenciales en Secrets Manager, se debe conceder a los usuarios los permisos adecuados para usar Secrets Manager y también la API de datos. Para obtener más información acerca de la autorización de usuarios, consulte Autorización de acceso a la API de datos de RDS.
También puede usar la API de datos para integrar Amazon Aurora con otras aplicaciones de AWS como AWS Lambda, AWS AppSync y AWS Cloud9. La API de datos proporciona una forma más segura de usar AWS Lambda. Le habilita para que obtenga acceso a su clúster de base de datos sin tener que configurar una función Lambda para obtener acceso a recursos de una Virtual Private Cloud (VPC). Para obtener más información, consulte AWS Lambda
Puede habilitar la API de datos al crear el clúster de Aurora DB. También puede modificar la configuración más adelante. Para obtener más información, consulte Habilitar la API de datos de RDS.
Después de habilitar la API de datos, también puede utilizar el editor de consultas para ejecutar consultas ad hoc sin configurar una herramienta de consulta para acceder a Aurora en una VPC. Para obtener más información, consulte Uso del editor de consultas de Aurora.
Temas
- Disponibilidad en regiones y versiones
- Limitaciones de la API de datos de RDS
- Comparación de la API de datos de RDS con Aurora sin servidor v2 y aprovisionada, y Aurora Serverless v1
- Autorización de acceso a la API de datos de RDS
- Habilitar la API de datos de RDS
- Creación de un punto de conexión de VPC para la API de datos de RDS (AWS PrivateLink)
- Llamadas a la API de datos de RDS
- Usar la biblioteca de cliente de Java para la API de datos de RDS
- Procesamiento de resultados de consultas de API de datos de RDS en formato JSON
- Solución de problemas de la API de datos de RDS
- Registro de llamadas a la API de datos de RDS con AWS CloudTrail
Disponibilidad en regiones y versiones
Para obtener información sobre las regiones y versiones de motores disponibles para la API de datos, consulte las siguientes secciones.
Tipo de clúster | Disponibilidad en regiones y versiones |
---|---|
Aurora PostgreSQL aprovisionada y sin servidor v2 |
API de datos con Aurora PostgreSQL sin servidor v2 y aprovisionada |
Aurora PostgreSQL sin servidor v1 |
|
Aurora MySQL sin servidor v1 |
nota
Actualmente, la API de datos no está disponible para clústeres aprovisionados o de base de datos Aurora Serverless v2 que utilicen el motor de MySQL.
Si necesita módulos criptográficos validados por FIPS 140-2 al acceder a los datos de la API a través de una interfaz de línea de comandos o una API, utilice un punto de enlace de FIPS. Para obtener más información sobre los puntos de conexión de FIPS disponibles, consulte Estándar de procesamiento de la información federal (FIPS) 140-2
Limitaciones de la API de datos de RDS
La API de datos de RDS (API de datos) tiene las siguientes limitaciones:
Solo puede ejecutar consultas de la API de datos en instancias de escritura de un clúster de base de datos. Sin embargo, las instancias de escritura pueden aceptar consultas de escritura y lectura.
Con las bases de datos globales de Aurora, puede habilitar la API de datos en los clústeres de bases de datos principales y secundarios. Sin embargo, hasta que un clúster secundario pase a ser el principal, no tendrá ninguna instancia de escritura. Por lo tanto, las consultas de la API de datos que se envían a la secundaria fallan. Cuando una instancia de escritura secundaria promocionada esté disponible, las consultas de la API de datos en esa instancia de base de datos deberían realizarse correctamente.
Información de rendimiento no admite la monitorización de las consultas a la base de datos que realice mediante la API de datos.
La API de datos no es compatible con las clases de instancias de base de datos T.
Para clústeres de base de datos de Aurora Serverless v2 y aprovisionados que utilizan el motor de PostgreSQL, la API de datos de RDS no admite algunos tipos de datos. Para obtener una lista de los tipos admitidos, consulte Comparación de la API de datos de RDS con Aurora sin servidor v2 y aprovisionada, y Aurora Serverless v1.
Para bases de datos de Aurora PostgreSQL versión 14 y posteriores, la API de datos solo admite
scram-sha-256
para el cifrado de contraseñas.-
El límite de tamaño de respuesta es de 1 MiB. Si la llamada devuelve más de 1 MiB de datos de respuesta, se terminará la llamada.
-
Para Aurora Serverless v1, el número máximo de solicitudes por segundo es 1000. Para el resto de bases de datos compatibles, no hay límite.
-
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. Asegúrese de que cada fila de un conjunto de resultados sea de 64 KB o menos.
Comparación de la API de datos de RDS con Aurora sin servidor v2 y aprovisionada, y Aurora Serverless v1
En la siguiente tabla se describen las diferencias entre la API de datos de RDS (API de datos) con los clústeres de base de datos de Aurora PostgreSQL sin servidor v2 y aprovisionados, y con los clústeres de bases de datos de Aurora Serverless v1. Aurora Serverless v1 Los clústeres de bases de datos utilizan el modo de motor serverless
. Los clústeres de bases de datos aprovisionados utilizan el modo de motor provisioned
. Un clúster de base de datos Aurora Serverless v2 también utiliza el modo de motor provisioned
y contiene una o más instancias de base de datos Aurora Serverless v2 con la clase de instancia db.serverless
.
Diferencia | Aurora PostgreSQL sin servidor v2 y aprovisionada | Aurora Serverless v1 |
---|---|---|
Número máximo de solicitudes por segundo | Sin límite | 1 000 |
Habilitar o deshabilitar la API de datos en una base de datos existente mediante la API de RDS o AWS CLI |
|
|
Eventos de CloudTrail | Los eventos de las llamadas a la API de datos son eventos de datos. De forma predeterminada, estos eventos se excluyen automáticamente de un registro. Para obtener más información, consulte Inclusión de eventos de la API de datos en un seguimiento de AWS CloudTrail. | Los eventos de las llamadas a la API de datos son eventos de administración. De forma predeterminada, estos eventos se incluyen automáticamente de un registro. Para obtener más información, consulte Excluir eventos de la API de datos de un seguimiento de AWS CloudTrail (solo Aurora Serverless v1). |
Compatibilidad con instrucciones múltiples | Las instrucciones múltiples no son compatibles. En este caso, la API de datos arroja ValidationException: Multistatements aren't
supported . |
Para Aurora PostgreSQL, las instrucciones múltiples devuelven solo la primera respuesta a la consulta. Aurora MySQL no admite las instrucciones múltiples. |
BatchExecuteStatement | El objeto de campos generado en el resultado de la actualización está vacío. | El objeto de campos generado en el resultado de la actualización incluye los valores insertados. |
ExecuteSQL | No compatible | Obsoleto |
ExecuteStatement |
La API de datos no admite algunos tipos de datos, como los geométricos y los monetarios. En este caso, la API de datos arroja Se admiten solamente los siguientes tipos:
Se admiten solamente los siguientes tipos de matrices:
|
ExecuteStatement admite la recuperación de columnas de matrices multidimensionales y todos los tipos de datos avanzados. |
Autorización de acceso a la API de datos de RDS
Los usuarios solo pueden invocar operaciones de la API de datos de RDS (API de datos) si están autorizados a hacerlo. Puede conceder a un usuario permiso para utilizar la API de datos asociando una política de AWS Identity and Access Management (IAM) que defina sus privilegios. También puede asociar la política a un rol si utiliza roles de IAM. Una política administrada por AWS, AmazonRDSDataFullAccess
, incluye permisos para la API de datos.
La política AmazonRDSDataFullAccess
también incluye permisos para que el usuario obtenga el valor de un secreto de AWS Secrets Manager. Los usuarios deben usar Secrets Manager para almacenar secretos que pueden usar en sus llamadas a la API de datos. El uso de secretos significa que los usuarios no tienen que incluir credenciales de base de datos para los recursos a los que se dirigen en sus llamadas a la API de datos. La API de datos llama de forma transparente a Secrets Manager, lo que permite (o deniega) la solicitud del secreto del usuario. Para obtener información acerca de cómo configurar secretos para utilizarlos con la API de datos, consulte Almacenamiento de credenciales de base de datos en AWS Secrets Manager.
La política AmazonRDSDataFullAccess
proporciona acceso completo (a través de la API de datos) a los recursos. Puede restringir el ámbito definiendo sus propias políticas que especifiquen el nombre de recurso de Amazon (ARN) de un recurso.
Por ejemplo, la siguiente política muestra un ejemplo de los permisos mínimos necesarios para que un usuario acceda a la API de datos para el clúster de base de datos identificado por su ARN. La política incluye los permisos necesarios para acceder a Secrets Manager y obtener autorización a la instancia de base de datos para el usuario.
{ "Version": "2012-10-17", "Statement": [ { "Sid": "SecretsManagerDbCredentialsAccess", "Effect": "Allow", "Action": [ "secretsmanager:GetSecretValue" ], "Resource": "
arn:aws:secretsmanager:*:*:secret:rds-db-credentials/*
" }, { "Sid": "RDSDataServiceAccess", "Effect": "Allow", "Action": [ "rds-data:BatchExecuteStatement", "rds-data:BeginTransaction", "rds-data:CommitTransaction", "rds-data:ExecuteStatement", "rds-data:RollbackTransaction" ], "Resource": "arn:aws:rds:us-east-2:111122223333:cluster:prod
" } ] }
Le recomendamos que utilice un ARN específico para el elemento «Recursos» en sus declaraciones de política (como se muestra en el ejemplo) en lugar de un comodín (*).
Trabajo con autorización basada en etiquetas
La API de datos de RDS (API de datos) y Secrets Manager admiten autorización basada en etiquetas. Las etiquetas son pares clave-valor que etiquetan un recurso, como un clúster RDS, con un valor de cadena adicional, por ejemplo:
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 de RDS (API de datos), puede transferir las credenciales del clúster de base de datos de Aurora mediante un secreto en Secrets Manager. Para pasar credenciales mediante este método, especifique el nombre del secreto o el Nombre de recurso de Amazon (ARN) del secreto.
Para almacenar las credenciales de clúster de base de datos en un secreto
-
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.
-
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 de RDS
Para utilizar la API de datos de RDS (API de datos), habilítela para su clúster de base de datos de Aurora. Puede habilitar la API de datos cuando cree o modifique el clúster de base de datos.
nota
Para Aurora PostgreSQL, la API de datos es compatible con las bases de datos de Aurora Serverless v2, Aurora Serverless v1 y las aprovisionadas. Para Aurora MySQL, la API de datos solo se admite con bases de datos Aurora Serverless v1.
Temas
Habilitación de la API de datos de RDS al crear una base de datos
Al crear una base de datos compatible con la API de datos de RDS (API de datos), puede habilitar esta característica. Los siguientes procedimientos describen el proceso al utilizar la AWS Management Console, la AWS CLI o la API de RDS.
Para habilitar la API de datos al crear un clúster de base de datos, seleccione la casilla Habilitar la API de datos de RDS en la sección Conectividad de la página Crear base de datos, como se muestra en la siguiente captura de pantalla.
![La sección Conectividad de la página Crear base de datos, con la casilla Habilitar la API de datos de RDS seleccionada.](images/data-api-enable-on-create.png)
Para obtener instrucciones sobre cómo crear un clúster de base de datos de Aurora que pueda usar la API de datos de RDS, consulte lo siguiente:
Para clústeres de Aurora PostgreSQL sin servidor v2 y aprovisionados: Creación de un clúster de base de datos de Amazon Aurora
Para Aurora Serverless v1: Creación de un clúster de bases de datos de Aurora Serverless v1
Para habilitar la API de datos mientras crea un clúster de base de datos de Aurora, ejecute el comando de la AWS CLI create-db-cluster con la opción --enable-http-endpoint
.
En el ejemplo siguiente se crea un clúster de base de datos de Aurora PostgreSQL con la API de datos habilitada.
Para Linux, macOS o Unix:
aws rds create-db-cluster \ --db-cluster-identifier
my_pg_cluster
\ --engine aurora-postgresql \ --enable-http-endpoint
En Windows:
aws rds create-db-cluster ^ --db-cluster-identifier
my_pg_cluster
^ --engine aurora-postgresql ^ --enable-http-endpoint
Para habilitar la API de datos al crear un clúster de base de datos de Aurora, utilice la operación CreateDBCluster con el valor del parámetro EnableHttpEndpoint
establecido en true
.
Habilitación de la API de datos de RDS en una base de datos existente
Puede modificar un clúster de base de datos que admita la API de datos de RDS (API de datos) para activar o desactivar esta característica.
Temas
Habilitación o deshabilitación de la API de datos (Aurora PostgreSQL sin servidor v2 y aprovisionada)
Utilice los siguientes procedimientos para activar o desactivar la API de datos en Aurora PostgreSQL sin servidor v2 y en las bases de datos aprovisionadas. Para activar o desactivar la API de datos en las bases de datos de Aurora Serverless v1, utilice los procedimientos descritos en Habilitación o deshabilitación de la API de datos (solo Aurora Serverless v1).
Puede habilitar o deshabilitar la API de datos con la consola de RDS para un clúster de base de datos que sea compatible con esta característica. Para ello, abra la página de detalles del clúster de la base de datos en la que desee habilitar o deshabilitar la API de datos y, en la pestaña Conectividad y seguridad, vaya a la sección API de datos de RDS. Esta sección muestra el estado de la API de datos y le permite habilitarla o deshabilitarla.
La siguiente captura de pantalla muestra que la API de datos de RDS no está habilitada.
![La sección API de datos de RDS en la pestaña Conectividad y seguridad de la página de detalles de un clúster de base de datos. El estado de la API de datos aparece como deshabilitado y aparece el botón Habilitar la API de datos de RDS.](images/data-api-enable-from-details.png)
Para habilitar o deshabilitar la API de datos en una base de datos existente, ejecute el comando de la AWS CLI enable-http-endpoint o disable-http-endpoint y especifique el ARN de su clúster de base de datos.
En el ejemplo siguiente se habilita la API de datos.
Para Linux, macOS o Unix:
aws rds enable-http-endpoint \ --resource-arn
cluster_arn
En Windows:
aws rds enable-http-endpoint ^ --resource-arn
cluster_arn
Para habilitar o deshabilitar la API de datos en una base de datos existente, utilice las operaciones EnableHttpEndpoint y DisableHttpEndpoint.
Habilitación o deshabilitación de la API de datos (solo Aurora Serverless v1)
Para habilitar o deshabilitar la API de datos en las bases de datos de Aurora Serverless v1 existentes. Para habilitar o deshabilitar la API de datos en Aurora PostgreSQL sin servidor v2 y en las bases de datos aprovisionadas, use los procedimientos de Habilitación o deshabilitación de la API de datos (Aurora PostgreSQL sin servidor v2 y aprovisionada).
Cuando cree o modifique un clúster de base de datos de Aurora Serverless v1, debe habilitar la API de datos en la sección Conectividad de la consola de RDS.
En la siguiente captura de pantalla se muestra la API de datos cuando se modifica un clúster de base de datos de Aurora.
![En la sección Conectividad de la página Modificar el clúster de base de datos, está seleccionada la casilla de verificación API de datos.](images/data-api-modify-serverlessv1.png)
Para obtener instrucciones sobre cómo modificar un clúster de base de datos de Aurora Serverless v1, consulte Modificación de un clúster de bases de datos de Aurora Serverless v1.
Para habilitar o deshabilitar la API de datos, ejecute el comando de la AWS CLI modify-db-cluster con --enable-http-endpoint
o --no-enable-http-endpoint
, según corresponda.
En el ejemplo siguiente se habilita la API de datos en sample-cluster
.
Para Linux, macOS o Unix:
aws rds modify-db-cluster \ --db-cluster-identifier sample-cluster \ --enable-http-endpoint
En Windows:
aws rds modify-db-cluster ^ --db-cluster-identifier sample-cluster ^ --enable-http-endpoint
Para habilitar la API de datos, utilice la operación ModifyDBCluster y establezca el valor de EnableHttpEndpoint
en true
o false
, según corresponda.
Creación de un punto de conexión de VPC para la API de datos de RDS (AWS PrivateLink)
La Amazon VPC le permite lanzar recursos de AWS, como clústeres de bases de datos y aplicaciones de Aurora, en una Virtual Private Cloud (VPC). AWS PrivateLink proporciona conectividad privada entre las VPC y los servicios de AWS con alta seguridad en la red de Amazon. Con AWS PrivateLink, puede crear puntos de enlace de la Amazon VPC que le permiten conectarse a servicios a través de diferentes cuentas y VPC basados en Amazon VPC. Para obtener más información acerca de AWS PrivateLink, consulte Servicios de punto de enlace de la VPC (AWS PrivateLink) en la guía del usuario de Amazon Virtual Private Cloud.
Puede llamar a la API de datos de RDS (API de datos) con los puntos de conexión de la Amazon VPC. El uso de un punto de conexión de VPC de Amazon mantiene el tráfico entre las aplicaciones de su Amazon VPC y la API de datos en la red de AWS, sin usar direcciones IP públicas. Los puntos de enlace de la Amazon VPC pueden ayudarle a cumplir los requisitos reglamentarios y de conformidad relacionados con la limitación de la conectividad a internet público. Por ejemplo, si utiliza un punto de conexión de VPC de Amazon, puede mantener el tráfico entre una aplicación que se ejecuta en una instancia Amazon EC2 y la API de datos en las VPC donde se contienen.
Después de crear el punto de enlace de la Amazon VPC, puede comenzar a usarlo sin realizar ningún cambio de código o configuración en la aplicación.
Para crear un punto de conexión de VPC de Amazon para la API de datos
Inicie sesión en la AWS Management Console y abra la consola de Amazon VPC en https://console.aws.amazon.com/vpc/
. -
Elija Endpoints (Puntos de enlace) y, a continuación, elija Create Endpoint (Crear punto de enlace).
-
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.
-
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.
-
En Subnets (Subredes), elija la subred para cada zona de disponibilidad (AZ) utilizada por el servicio de AWS que ejecuta la aplicación.
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.
-
En Enable Private DNS Name (Habilitar nombre de DNS privado), seleccione Enable for this endpoint (Habilitar para este punto de enlace).
El DNS privado resuelve el nombre de host de DNS de la API de datos estándar (
https://rds-data.
) 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 conexión 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 conexión de la API de datos.region
.amazonaws.com -
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.
-
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.
-
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](images/data-api-vpc-endpoint-link-to-details.png)
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](images/data-api-vpc-endpoint-dns-names.png)
Puede utilizar el punto de enlace estándar (rds-data.
) 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.region
.amazonaws.com
Cuando utiliza un punto de conexión de VPC de Amazon en una llamada a la API de datos, todo el tráfico entre la aplicación y la API de datos permanece en las Amazon VPC donde se contienen. Puede usar un punto de enlace de la Amazon VPC para cualquier tipo de llamada a la API de datos. Para obtener más información sobre la llamada a la API de datos, consulte Llamadas a la API de datos de RDS.
Llamadas a la API de datos de RDS
Con la API de datos de RDS (API de datos) habilitada en el clúster de base de datos de Aurora, puede ejecutar instrucciones SQL en el clúster de base de datos de Aurora mediante la API de datos o la AWS CLI. La API de los datos es compatible con los idiomas de programación compatibles con AWS SDK. Para obtener más información, consulte Herramientas para crear en AWS
Temas
Referencia de las operaciones de la API de datos
La API de datos proporciona las operaciones siguientes para realizar instrucciones SQL.
Operación de la API |
AWS CLI command |
Descripción |
---|---|---|
Ejecuta una instrucción SQL en una base de datos. |
||
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 |
---|---|---|
Inicia una transacción SQL. |
||
Finaliza una transacción SQL y confirma los cambios. |
||
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 |
---|---|---|---|
|
|
Sí |
El nombre de recurso de Amazon (ARN) del clúster de base de datos de Aurora. |
|
|
Sí |
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 |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
Otros tipos (incluidos los tipos relacionados con la fecha y hora) |
|
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ámetroString
correspondiente se envía como un objeto de tipoDATE
a la base de datos. El formato aceptado esYYYY-MM-DD
. -
DECIMAL
–: el valor del parámetroString
correspondiente se envía como un objeto de tipoDECIMAL
a la base de datos. -
JSON
–: el valor del parámetroString
correspondiente se envía como un objeto de tipoJSON
a la base de datos. -
TIME
–: el valor del parámetroString
correspondiente se envía como un objeto de tipoTIME
a la base de datos. El formato aceptado esHH:MM:SS[.FFF]
. -
TIMESTAMP
–: el valor del parámetroString
correspondiente se envía como un objeto de tipoTIMESTAMP
a la base de datos. El formato aceptado esYYYY-MM-DD HH:MM:SS[.FFF]
. -
UUID
–: el valor del parámetroString
correspondiente se envía como un objeto de tipoUUID
a la base de datos.nota
Actualmente, la API de datos no admite matrices de identificadores únicos universales (UUID).
nota
Para Amazon Aurora PostgreSQL, la API de datos siempre devuelve el tipo de datos de Aurora PostgreSQL TIMESTAMPTZ
en la zona horaria UTC.
Llamadas a la API de datos de RDS con la AWS CLI
Puede llamar a la API de datos de RDS (API de datos) mediante la AWS CLI.
En los siguientes ejemplos se utiliza la AWS CLI para la API de datos. Para obtener más información, consulte la referencia de AWS CLI de la API de datos.
En cada ejemplo, sustituya el nombre de recurso de Amazon (ARN) del clúster de base de datos por el ARN de su clúster de base de datos de Aurora. Reemplace también el ARN del secreto por el ARN del secreto de Secrets Manager que permite obtener acceso al clúster de base de datos.
nota
La AWS CLI puede dar formato a las respuestas de JSON.
Temas
Inicio de una transacción SQL
Puede iniciar una transacción SQL ejecutando el comando de la CLI aws rds-data
begin-transaction
. La llamada devuelve un identificador de transacción.
importante
Dentro de la API de datos, el tiempo de la transacción se agota si no hay llamadas que usen su ID de transacción en un periodo de tres minutos. Si una transacción agota su tiempo antes de que se confirme, la API de datos se revertirá automáticamente.
Las instrucciones de lenguaje de definición de datos (DDL) de MySQL dentro de una transacción causan una confirmación implícita. Recomendamos que ejecute cada instrucción DDL de MySQL en un comando execute-statement
independiente con la opción --continue-after-timeout
.
Además de las opciones comunes, especifique la opción --database
, que proporciona el nombre de la base de datos.
Por ejemplo, el comando de la CLI siguiente inicia una transacción SQL.
Para Linux, macOS o Unix:
aws rds-data begin-transaction --resource-arn "
arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster
" \ --database "mydb
" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret
"
En Windows:
aws rds-data begin-transaction --resource-arn "
arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster
" ^ --database "mydb
" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret
"
A continuación se muestra un ejemplo de respuesta.
{
"transactionId": "ABC1234567890xyz
"
}
Ejecución de una instrucción SQL
Puede ejecutar una instrucción SQL usando el comando de la CLI aws rds-data execute-statement
.
Puede ejecutar la instrucción SQL en una transacción especificando el identificador de transacción con la opción --transaction-id
. Puede iniciar una transacción ejecutando el comando de la CLI aws rds-data begin-transaction
. Puede finalizar y confirmar una transacción ejecutando el comando de la CLI aws rds-data
commit-transaction
.
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 comandobegin-transaction
de la CLI. Especifique el ID de la transacción en la que desea incluir la instrucción SQL. -
--parameters
(opcional): parámetros de la instrucción SQL. -
--include-result-metadata | --no-include-result-metadata
(opcional): valor que indica si deben incluirse o no metadatos en los resultados. El valor predeterminado es--no-include-result-metadata
. -
--database
(opcional): el nombre de la base de datos.Es posible que la opción
--database
no funcione al ejecutar una instrucción SQL después de ejecutar--sql "use
en la solicitud anterior. Le recomendamos que utilice la opcióndatabase_name
;"--database
en lugar de ejecutar instrucciones--sql "use
.database_name
;" -
--continue-after-timeout | --no-continue-after-timeout
(opcional): un valor que indica si se seguirá o no ejecutando la instrucción después de que la llamada supere el intervalo de tiempo de espera de la API de datos de 45 segundos. El valor predeterminado es--no-continue-after-timeout
.Para las instrucciones en lenguaje de definición de datos (DDL), recomendamos seguir ejecutando la instrucción después de que se agote el tiempo de la llamada, a fin de evitar errores y la posibilidad de que las estructuras de datos se dañen.
-
--format-records-as "JSON"|"NONE"
: valor opcional que especifica si se debe dar formato al conjunto de resultados como cadena JSON. El valor predeterminado es"NONE"
. Para obtener información sobre el procesamiento de conjuntos de resultados JSON, consulte Procesamiento de resultados de consultas de API de datos de RDS 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.
Para Aurora Serverless v1, el número máximo de solicitudes por segundo es 1000. Para el resto de bases de datos compatibles, no hay límite.
Por ejemplo, el siguiente comando de la CLI ejecuta una única instrucción SQL y omite los metadatos en los resultados (valor predeterminado).
Para Linux, macOS o Unix:
aws rds-data execute-statement --resource-arn "
arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster
" \ --database "mydb
" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret
" \ --sql "select * from mytable
"
En Windows:
aws rds-data execute-statement --resource-arn "
arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster
" ^ --database "mydb
" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret
" ^ --sql "select * from mytable
"
A continuación se muestra un ejemplo de respuesta.
{
"numberOfRecordsUpdated": 0,
"records": [
[
{
"longValue": 1
},
{
"stringValue": "ValueOne
"
}
],
[
{
"longValue": 2
},
{
"stringValue": "ValueTwo
"
}
],
[
{
"longValue": 3
},
{
"stringValue": "ValueThree
"
}
]
]
}
El siguiente comando de la CLI ejecuta una única instrucción SQL en una transacción mediante la opción --transaction-id
.
Para Linux, macOS o Unix:
aws rds-data execute-statement --resource-arn "
arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster
" \ --database "mydb
" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret
" \ --sql "update mytable set quantity=5 where id=201
" --transaction-id "ABC1234567890xyz
"
En Windows:
aws rds-data execute-statement --resource-arn "
arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster
" ^ --database "mydb
" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret
" ^ --sql "update mytable set quantity=5 where id=201
" --transaction-id "ABC1234567890xyz
"
A continuación se muestra un ejemplo de respuesta.
{
"numberOfRecordsUpdated": 1
}
El siguiente comando de la CLI ejecuta una única instrucción SQL con parámetros.
Para Linux, macOS o Unix:
aws rds-data execute-statement --resource-arn "
arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster
" \ --database "mydb
" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret
" \ --sql "insert intomytable
values (:id
,:val
)" --parameters "[{\"name\": \"id
\", \"value\": {\"longValue\":1
}},{\"name\": \"val
\", \"value\": {\"stringValue\": \"value1
\"}}]"
En Windows:
aws rds-data execute-statement --resource-arn "
arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster
" ^ --database "mydb
" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret
" ^ --sql "insert intomytable
values (:id
,:val
)" --parameters "[{\"name\": \"id
\", \"value\": {\"longValue\":1
}},{\"name\": \"val
\", \"value\": {\"stringValue\": \"value1
\"}}]"
A continuación se muestra un ejemplo de respuesta.
{
"numberOfRecordsUpdated": 1
}
El siguiente comando de la CLI ejecuta una instrucción SQL de lenguaje de definición de datos (DDL). La instrucción DDL cambia el nombre de la columna job
por la columna role
.
importante
Para las instrucciones DDL, recomendamos seguir ejecutando la instrucción después de que se agote el tiempo de la llamada. Cuando se termina una instrucción DDL antes de que acabe de ejecutarse, pueden generarse errores y es posible que las estructuras de datos se dañen. Para seguir ejecutando una instrucción después de que una llamada supere el intervalo de tiempo de espera de la API de datos de RDS de 45 segundos, especifique la opción --continue-after-timeout
.
Para Linux, macOS o Unix:
aws rds-data execute-statement --resource-arn "
arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster
" \ --database "mydb
" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret
" \ --sql "alter table mytable change column job role varchar(100)
" --continue-after-timeout
En Windows:
aws rds-data execute-statement --resource-arn "
arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster
" ^ --database "mydb
" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret
" ^ --sql "alter table mytable change column job role varchar(100)
" --continue-after-timeout
A continuación se muestra un ejemplo de respuesta.
{
"generatedFields": [],
"numberOfRecordsUpdated": 0
}
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
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 comandobegin-transaction
de la CLI. Especifique el ID de la transacción en la que desea incluir la instrucción SQL. -
--parameter-set
(opcional): los conjuntos de parámetros para la operación por lotes. -
--database
(opcional): el nombre de la base de datos.
El clúster de base de datos devuelve una respuesta a la llamada.
nota
No existe un límite máximo fijo en el número de conjuntos de parámetros. Sin embargo, el tamaño máximo de la solicitud HTTP enviada a través de la API de datos es de 4 MiB. Si la solicitud supera este límite, la API de datos devuelve un error y no procesa la solicitud. Este límite de 4 MiB incluye el tamaño de los encabezados HTTP y la notación JSON en la solicitud. Por lo tanto, el número de conjuntos de parámetros que puede incluir depende de una combinación de factores, como el tamaño de la sentencia SQL y el tamaño de cada conjunto de parámetros.
El límite de tamaño de respuesta es de 1 MiB. Si la llamada devuelve más de 1 MiB de datos de respuesta, se terminará la llamada.
Para Aurora Serverless v1, el número máximo de solicitudes por segundo es 1000. Para el resto de bases de datos compatibles, no hay límite.
Por ejemplo, el siguiente comando de la CLI ejecuta una instrucción SQL por lotes en una matriz de datos con un conjunto de parámetros.
Para Linux, macOS o Unix:
aws rds-data batch-execute-statement --resource-arn "
arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster
" \ --database "mydb
" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret
" \ --sql "insert intomytable
values (:id
,:val
)" \ --parameter-sets "[[{\"name\": \"id
\", \"value\": {\"longValue\":1
}},{\"name\": \"val
\", \"value\": {\"stringValue\": \"ValueOne
\"}}], [{\"name\": \"id
\", \"value\": {\"longValue\":2
}},{\"name\": \"val
\", \"value\": {\"stringValue\": \"ValueTwo
\"}}], [{\"name\": \"id
\", \"value\": {\"longValue\":3
}},{\"name\": \"val
\", \"value\": {\"stringValue\": \"ValueThree
\"}}]]"
En Windows:
aws rds-data batch-execute-statement --resource-arn "
arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster
" ^ --database "mydb
" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret
" ^ --sql "insert intomytable
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 comandobegin-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
"
En Windows:
aws rds-data commit-transaction --resource-arn "
arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster
" ^ --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret
" ^ --transaction-id "ABC1234567890xyz
"
A continuación se muestra un ejemplo de respuesta.
{
"transactionStatus": "Transaction Committed"
}
Restauración de una transacción SQL
Con el comando aws rds-data rollback-transaction
de la CLI, puede revertir una transacción SQL que inició con aws rds-data
begin-transaction
. Si revierte una transacción, cancelará sus cambios.
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 comandobegin-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
"
En Windows:
aws rds-data rollback-transaction --resource-arn "
arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster
" ^ --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret
" ^ --transaction-id "ABC1234567890xyz
"
A continuación se muestra un ejemplo de respuesta.
{
"transactionStatus": "Rollback Complete"
}
Llamadas a la API de datos de RDS desde una aplicación Python
Puede llamar a la API de datos de RDS (API de datos) desde una aplicación Python.
En los ejemplos siguientes se usa el AWS SDK para Python (Boto). Para obtener más información acerca de Boto, consulte la documentación de AWS SDK para Python (Boto 3)
En cada ejemplo, sustituya el nombre de recurso de Amazon (ARN) del clúster de base de datos por el ARN de su clúster de base de datos de Aurora. Reemplace también el ARN del secreto por el ARN del secreto de Secrets Manager que permite obtener acceso al clúster de base de datos.
Temas
Ejecución de una consulta SQL
Puede ejecutar una instrucción SELECT
y recopilar los resultados con una aplicación Python.
En el ejemplo siguiente, se ejecuta una consulta SQL.
import boto3
rdsData = boto3.client('rds-data')
cluster_arn = 'arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster
'
secret_arn = 'arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret
'
response1 = rdsData.execute_statement(
resourceArn = cluster_arn,
secretArn = secret_arn,
database = 'mydb
',
sql = 'select * from employees limit 3
')
print (response1['records'])
[
[
{
'longValue': 1
},
{
'stringValue': 'ROSALEZ'
},
{
'stringValue': 'ALEJANDRO'
},
{
'stringValue': '2016-02-15 04:34:33.0'
}
],
[
{
'longValue': 1
},
{
'stringValue': 'DOE'
},
{
'stringValue': 'JANE'
},
{
'stringValue': '2014-05-09 04:34:33.0'
}
],
[
{
'longValue': 1
},
{
'stringValue': 'STILES'
},
{
'stringValue': 'JOHN'
},
{
'stringValue': '2017-09-20 04:34:33.0'
}
]
]
Ejecución de una instrucción SQL DML
Puede ejecutar una instrucción de lenguaje de manipulación de datos (DML) para insertar, actualizar o eliminar datos en su base de datos. También puede utilizar parámetros en instrucciones DML.
importante
Si una llamada no forma parte de una transacción porque no incluye el parámetro transactionID
, los cambios que se generen a partir de la llamada se confirmarán automáticamente.
En el ejemplo siguiente se ejecuta una instrucción SQL de inserción y se utilizan parámetros.
import boto3
cluster_arn = 'arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster
'
secret_arn = 'arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret
'
rdsData = boto3.client('rds-data')
param1 = {'name':'firstname', 'value':{'stringValue': 'JACKSON
'}}
param2 = {'name':'lastname', 'value':{'stringValue': 'MATEO
'}}
paramSet = [param1, param2]
response2 = rdsData.execute_statement(resourceArn=cluster_arn,
secretArn=secret_arn,
database='mydb
',
sql='insert into employees(first_name, last_name) VALUES(:firstname, :lastname)
',
parameters = paramSet)
print (response2["numberOfRecordsUpdated"])
Ejecución de una transacción SQL
Puede iniciar una transacción SQL, ejecutar una o varias instrucciones SQL y luego confirmar los cambios con una aplicación Python.
importante
El tiempo de la transacción se agota si no hay llamadas que usen su ID de transacción en un período de tres minutos. Si una transacción agota su tiempo antes de que se confirme, se revertirá automáticamente.
Si no especifica un ID de transacción, los cambios que se generen a partir de la llamada se confirmarán automáticamente.
En el ejemplo siguiente se ejecuta una transacción SQL que inserta una fila en una tabla.
import boto3
rdsData = boto3.client('rds-data')
cluster_arn = 'arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster
'
secret_arn = 'arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret
'
tr = rdsData.begin_transaction(
resourceArn = cluster_arn,
secretArn = secret_arn,
database = 'mydb
')
response3 = rdsData.execute_statement(
resourceArn = cluster_arn,
secretArn = secret_arn,
database = 'mydb
',
sql = 'insert into employees(first_name, last_name) values('XIULAN', 'WANG')
',
transactionId = tr['transactionId'])
cr = rdsData.commit_transaction(
resourceArn = cluster_arn,
secretArn = secret_arn,
transactionId = tr['transactionId'])
cr['transactionStatus']
'Transaction Committed'
response3['numberOfRecordsUpdated']
1
nota
Si ejecuta una instrucción de lenguaje de definición de datos (DDL), recomendamos que siga ejecutando la instrucción después de que se agote el tiempo de la llamada. Cuando se termina una instrucción DDL antes de que acabe de ejecutarse, pueden generarse errores y es posible que las estructuras de datos se dañen. Para seguir ejecutando una instrucción después de que una llamada supere el intervalo de tiempo de espera de la API de datos de RDS de 45 segundos, ajuste el parámetro continueAfterTimeout
en true
.
Llamadas a la API de datos de RDS desde una aplicación Java
Puede llamar a la API de datos de RDS (API de datos) desde una aplicación Java.
En los ejemplos siguientes se usa el AWS SDK para Java. Para obtener más información, consulte AWS SDK for Java Developer Guide.
En cada ejemplo, sustituya el nombre de recurso de Amazon (ARN) del clúster de base de datos por el ARN de su clúster de base de datos de Aurora. Reemplace también el ARN del secreto por el ARN del secreto de Secrets Manager que permite obtener acceso al clúster de base de datos.
Temas
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 una llamada supere el intervalo de tiempo de espera de la API de datos de RDS de 45 segundos, ajuste el parámetro continueAfterTimeout
en true
.
Ejecución de una operación SQL por lotes
Puede ejecutar operaciones de inserción y actualización masivas en una matriz de datos, con una aplicación Java. Puede ejecutar una instrucción DML con una matriz de conjuntos de parámetros.
importante
Si no especifica un ID de transacción, los cambios que se generen a partir de la llamada se confirmarán automáticamente.
En el siguiente ejemplo se ejecuta una operación de inserción por lotes.
package com.amazonaws.rdsdata.examples;
import com.amazonaws.services.rdsdata.AWSRDSData;
import com.amazonaws.services.rdsdata.AWSRDSDataClient;
import com.amazonaws.services.rdsdata.model.BatchExecuteStatementRequest;
import com.amazonaws.services.rdsdata.model.Field;
import com.amazonaws.services.rdsdata.model.SqlParameter;
import java.util.Arrays;
public class BatchExecuteExample {
public static final String RESOURCE_ARN = "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster
";
public static final String SECRET_ARN = "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret
";
public static void main(String[] args) {
AWSRDSData rdsData = AWSRDSDataClient.builder().build();
BatchExecuteStatementRequest request = new BatchExecuteStatementRequest()
.withDatabase("test")
.withResourceArn(RESOURCE_ARN)
.withSecretArn(SECRET_ARN)
.withSql("INSERT INTO test_table2 VALUES (:string, :number)")
.withParameterSets(Arrays.asList(
Arrays.asList(
new SqlParameter().withName("string").withValue(new Field().withStringValue("Hello")),
new SqlParameter().withName("number").withValue(new Field().withLongValue(1L))
),
Arrays.asList(
new SqlParameter().withName("string").withValue(new Field().withStringValue("World")),
new SqlParameter().withName("number").withValue(new Field().withLongValue(2L))
)
));
rdsData.batchExecuteStatement(request);
}
}
Control del comportamiento del tiempo de espera de la API de datos
Todas las llamadas a la API de datos son síncronas. Imaginemos que realiza una operación de API de datos que ejecuta una instrucción de SQL como INSERT
oCREATE TABLE
. Si la llamada a la API de datos se devuelve correctamente, el procesamiento de SQL finaliza cuando se devuelve la llamada.
De forma predeterminada, la API de datos cancela una operación y devuelve un error de tiempo de espera si la operación no termina de procesarse en 45 segundos. En ese caso, los datos no se insertan, la tabla no se crea, etc.
Puedes usar la API de datos para realizar operaciones de larga duración que no se puedan completar en 45 segundos. Si espera que una operación, como una operación masiva de INSERT
o DDL en una tabla grande, tarde más de 45 segundos, puede especificar el parámetro continueAfterTimeout
para la operación ExecuteStatement
. La aplicación sigue recibiendo el error de tiempo de espera. Sin embargo, la operación continúa ejecutándose y no se cancela. Para ver un ejemplo, consulte Ejecución de una transacción SQL.
Si el AWS SDK de su lenguaje de programación tiene su propio tiempo de espera para las llamadas a la API o las conexiones de sockets HTTP, asegúrese de que todos esos periodos de tiempo de espera sean superiores a 45 segundos. En algunos SDK, el tiempo de espera es inferior a 45 segundos de forma predeterminada. Recomendamos ajustar cualquier periodo de tiempo de espera específico del SDK o específico del cliente en al menos un minuto. De este modo, se evita la posibilidad de que la aplicación reciba un error de tiempo de espera mientras la operación de la API de datos se complete correctamente. De esta forma, puede estar seguro de si desea volver a intentar la operación o no.
Por ejemplo, supongamos que el SDK devuelve un error de tiempo de espera a su aplicación, pero la operación de la API de datos sigue completándose dentro del intervalo de tiempo de espera de la API de datos. En ese caso, volver a intentar la operación podría insertar datos duplicados o producir resultados incorrectos. Es posible que el SDK vuelva a intentar la operación automáticamente, lo que provoca datos incorrectos sin que la aplicación realice ninguna acción.
El intervalo de tiempo de espera es especialmente importante para el SDK de Java 2. En ese SDK, el tiempo de espera de la llamada a la API y el tiempo de espera del socket HTTP es de 30 segundos de forma predeterminada. En este ejemplo se muestra cómo ajustar esos tiempos de espera en un valor superior:
public RdsDataClient createRdsDataClient() { return RdsDataClient.builder() .region(Region.US_EAST_1) // Change this to your desired Region .overrideConfiguration(createOverrideConfiguration()) .httpClientBuilder(createHttpClientBuilder()) .credentialsProvider(defaultCredentialsProvider()) // Change this to your desired credentials provider .build(); } private static ClientOverrideConfiguration createOverrideConfiguration() { return ClientOverrideConfiguration.builder() .apiCallTimeout(Duration.ofSeconds(60)) .build(); } private HttpClientBuilder createHttpClientBuilder() { return ApacheHttpClient.builder() // Change this to your desired HttpClient .socketTimeout(Duration.ofSeconds(60)); }
A continuación, se muestra un ejemplo equivalente con el cliente de datos asíncrono:
public static RdsDataAsyncClient createRdsDataAsyncClient() { return RdsDataAsyncClient.builder() .region(Region.US_EAST_1) // Change this to your desired Region .overrideConfiguration(createOverrideConfiguration()) .credentialsProvider(defaultCredentialsProvider()) // Change this to your desired credentials provider .build(); } private static ClientOverrideConfiguration createOverrideConfiguration() { return ClientOverrideConfiguration.builder() .apiCallAttemptTimeout(Duration.ofSeconds(60)) .build(); } private HttpClientBuilder createHttpClientBuilder() { return NettyNioAsyncHttpClient.builder() // Change this to your desired AsyncHttpClient .readTimeout(Duration.ofSeconds(60)); }
Usar la biblioteca de cliente de Java para la API de datos de RDS
Puede descargar y utilizar una biblioteca de cliente de Java para la API de datos de RDS (API de datos). La biblioteca de cliente de Java ofrece un método alternativo para utilizar la API de datos. Al utilizar esta biblioteca, puede asignar las clases del lado del cliente a las solicitudes y respuestas de la API de datos. Esta compatibilidad con la asignación puede facilitar la integración con algunos tipos de Java específicos, como Date
, Time
y BigDecimal
.
Descarga de la biblioteca de cliente de Java para la API de datos
La biblioteca de cliente Java para la API de datos es de código abierto en GitHub en la siguiente ubicación:
https://github.com/awslabs/rds-data-api-client-library-java
Puede crear la biblioteca de forma manual a partir de los archivos de origen, pero la práctica recomendada es utilizar la biblioteca mediante la administración de dependencias de Apache Maven. Agregue la siguiente dependencia a su archivo Maven POM.
Para la versión 2.x, compatible con AWS SDK 2.x, utilice lo siguiente:
<dependency> <groupId>software.amazon.rdsdata</groupId> <artifactId>rds-data-api-client-library-java</artifactId> <version>2.0.0</version> </dependency>
Para la versión 1.x, compatible con AWS SDK 1.x, utilice lo siguiente:
<dependency> <groupId>software.amazon.rdsdata</groupId> <artifactId>rds-data-api-client-library-java</artifactId> <version>1.0.8</version> </dependency>
Ejemplos de la biblioteca de cliente de Java
A continuación, puede encontrar algunos ejemplos habituales del uso de la biblioteca de cliente de Java para la API de datos. En estos ejemplos se asume que tiene una tabla accounts
con dos columnas: accountId
y name
. También tiene el siguiente objeto de transferencia de datos (DTO).
public class Account {
int accountId;
String name;
// getters and setters omitted
}
La biblioteca de cliente le permite transferir los DTO como parámetros de entrada. En el siguiente ejemplo se muestra cómo los DTO del cliente se asignan a los conjuntos de parámetros de entrada.
var account1 = new Account(1, "John");
var account2 = new Account(2, "Mary");
client.forSql("INSERT INTO accounts(accountId, name) VALUES(:accountId, :name)")
.withParamSets(account1, account2)
.execute();
En algunos casos, es más fácil trabajar con valores simples como parámetros de entrada. Puede hacerlo mediante la siguiente sintaxis:
client.forSql("INSERT INTO accounts(accountId, name) VALUES(:accountId, :name)")
.withParameter("accountId", 3)
.withParameter("name", "Zhang")
.execute();
A continuación se muestra otro ejemplo que funciona con valores simples como parámetros de entrada.
client.forSql("INSERT INTO accounts(accountId, name) VALUES(?, ?)", 4, "Carlos") .execute();
La biblioteca de cliente proporciona un mapeo automático a los DTO cuando se devuelve un resultado. En los siguientes ejemplos se muestra cómo se asigna el resultado a los DTO.
List<Account> result = client.forSql("SELECT * FROM accounts")
.execute()
.mapToList(Account.class);
Account result = client.forSql("SELECT * FROM accounts WHERE account_id = 1")
.execute()
.mapToSingle(Account.class);
En muchos casos, el conjunto de resultados de la base de datos contiene un solo valor. Para simplificar la recuperación de estos resultados, la biblioteca cliente ofrece la siguiente API:
int numberOfAccounts = client.forSql("SELECT COUNT(*) FROM accounts")
.execute()
.singleValue(Integer.class);
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 de API de datos de RDS en formato JSON.
Procesamiento de resultados de consultas de API de datos de RDS en formato JSON
Cuando se llama a la operación ExecuteStatement
, se puede elegir que los resultados de la consulta se devuelvan como cadena en formato JSON. Esto permite utilizar las capacidades de análisis JSON de su lenguaje de programación para interpretar el conjunto de resultados y volver a darle formato. Hacerlo puede ayudar a evitar escribir código adicional para pasar por el conjunto de resultados e interpretar el valor de cada columna.
Para solicitar el conjunto de resultados en formato JSON, es preciso pasar el parámetro opcional formatRecordsAs
con un valor JSON
. El conjunto de resultados con formato JSON se devuelve en el campo formattedRecords
de la estructura ExecuteStatementResponse
.
La acción BatchExecuteStatement
no devuelve un conjunto de resultados. Por lo tanto, la opción JSON no se aplica a esa acción.
Para personalizar las claves de la estructura hash JSON, defina alias de columna en el conjunto de resultados. Puede hacerlo mediante la cláusula AS
de la lista de columnas de la consulta SQL.
Puede hacer uso de la capacidad JSON para facilitar la lectura del conjunto de resultados y asignar su contenido a marcos específicos de lenguaje. Dado que el volumen del conjunto de resultados codificado en ASCII es mayor que la representación predeterminada, puede elegir la representación predeterminada para consultas que devuelvan un gran número de filas o valores de columna grandes que consuman más memoria de la que está disponible para la aplicación.
Temas
Recuperación de resultados de consultas en formato JSON
Para recibir el conjunto de resultados como una cadena JSON, incluya .withFormatRecordsAs(RecordsFormatType.JSON)
en la llamada a ExecuteStatement
. El valor devuelto vuelve como cadena JSON en el campo formattedRecords
. En este caso, columnMetadata
es null
. Las etiquetas de columna son las claves del objeto que representa cada fila. Estos nombres de columna se repiten para cada fila del conjunto de resultados. Los valores de columna son cadenas entre comillas, valores numéricos o valores especiales que representan true
, false
o null
. Los metadatos de columna, como las restricciones de longitud y el tipo preciso de números y cadenas, no se conservan en la respuesta JSON.
Si omite la llamada .withFormatRecordsAs()
o especifica un parámetro de NONE
, el conjunto de resultados se devuelve en formato binario mediante los campos Records
y columnMetadata
.
Asignación de tipos de datos
Los valores SQL del conjunto de resultados se asignan a un conjunto más pequeño de tipos JSON. Los valores se representan en JSON como cadenas, números y ciertas constantes especiales, como true
, false
y null
. Puede convertir estos valores en variables en su aplicación mediante tipado fuerte o débil según corresponda en el lenguaje de programación.
Tipo de datos JDBC |
Tipos de datos de JSON |
---|---|
|
Número de forma predeterminada. Cadena si la opción |
|
Número |
|
Cadena de forma predeterminada. Número si la opción |
|
Cadena |
|
Booleano |
|
Cadena en codificación base64. |
|
Cadena |
|
Matriz |
|
|
Otros tipos (incluidos los tipos relacionados con la fecha y hora) |
Cadena |
Resolución de problemas
La respuesta JSON se limita a 10 megabytes. Si la respuesta supera este límite, el programa recibe un error BadRequestException
. En este caso, puede resolver el error mediante una de las siguientes técnicas:
-
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áusulasLIMIT
yOFFSET
.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 de RDS
Use las siguientes secciones, tituladas con mensajes de error comunes, para ayudar a solucionar problemas que tenga con la API de datos de RDS (API de datos).
Temas
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 aRollbackTransaction
. -
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 de RDS.
El paquete de la consulta es demasiado grande
En este caso, el conjunto de resultados devuelto para una fila era demasiado grande. El límite de tamaño de la API de datos es 64 KB por fila en el conjunto de resultados devuelto por la base de datos.
Para solventar este problema, asegúrese de que cada fila de un conjunto de resultados sea de 64 KB o menos.
Límite de tamaño superado de respuesta de base de datos
En este caso, el tamaño del conjunto de resultados devuelto por la base de datos era demasiado grande. El límite de la API de datos es 1 MB en el conjunto de resultados devuelto por la base de datos.
Para resolver este problema, asegúrese de que las llamada a la API de datos devuelvan 1 MiB de datos o menos. Si necesita devolver más de 1 MiB, puede usar varias llamadas ExecuteStatement
con la cláusula LIMIT
en la consulta.
Para obtener más información acerca de la cláusula LIMIT
, consulte SELECT Syntax
HttpEndpoint no está habilitado para el clúster <cluster_ID>
Compruebe las siguientes posibles causas de este problema:
-
El clúster de base de datos de Aurora no admite la API de datos. Por ejemplo, para Aurora MySQL, solo puede usar la API de datos con Aurora Serverless v1. Para obtener información sobre los tipos de clústeres de bases de datos compatibles con la API de datos de RDS, consulte Disponibilidad en regiones y versiones.
-
La API de datos no está habilitada para el clúster de base de datos de Aurora. Para utilizar la API de datos con un clúster de base de datos de Aurora, 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 de RDS.
-
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.