Uso de la API de datos Consideraciones que deben tenerse en cuenta al llamar a la API de datos Ejecución de instrucciones SQL con un token de idempotencia Ejecución de instrucciones SQL con reutilización de sesión

Uso de la API de datos de Amazon Redshift

La API de datos de Amazon Redshift simplifica el acceso al almacenamiento de datos de Amazon Redshift al eliminar la necesidad de administrar controladores de bases de datos, conexiones, configuraciones de red, almacenamiento de datos en búfer, credenciales y mucho más. Puede ejecutar instrucciones SQL mediante las operaciones de la API de datos con el AWS SDK. Para obtener más información sobre las operaciones de la API de datos, consulte Referencia de la API de datos de Amazon Redshift.

La API de datos no requiere una conexión persistente a la 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. Las llamadas a la API de datos son asíncronas. La API de datos utiliza las credenciales almacenadas en AWS Secrets Manager o las credenciales temporales de la base de datos. No es necesario transmitir contraseñas en las llamadas a la API con ninguno de los dos métodos de autorización. Para obtener más información sobre AWS Secrets Manager, consulte ¿Qué es AWS Secrets Manager? en la Guía del usuario de AWS Secrets Manager.

Con la API de datos, puede obtener acceso mediante programación a los datos de Amazon Redshift con aplicaciones basadas en servicios web, entre ellas, AWS Lambda, cuadernos de Amazon SageMaker y AWS Cloud9. Para obtener más información sobre estas aplicaciones, consulte AWS Lambda, Amazon SageMaker y AWS Cloud9.

Para obtener más información sobre la API de datos, consulte Introducción a la API de datos de Amazon Redshift en el blog de macrodatos de AWS.

Uso de la API de datos de Amazon Redshift

Antes de utilizar la API de datos de Amazon Redshift, consulte los siguientes pasos:

Determine si usted, como persona que llama a la API de datos, cuenta con la autorización necesaria. Para obtener más información acerca de la autorización, consulte Autorización del acceso a la API de datos de Amazon Redshift.
Determine si tiene previsto llamar a la API de datos con credenciales de autenticación de Secrets Manager, o bien, con credenciales temporales. Para obtener más información, consulte Elección de las credenciales de autenticación de base de datos al llamar a la API de datos de Amazon Redshift.
Configure un secreto si utiliza Secrets Manager para las credenciales de autenticación. Para obtener más información, consulte Almacenamiento de credenciales de base de datos en AWS Secrets Manager.
Revise las consideraciones y las limitaciones que intervienen al llamar a la API de datos. Para obtener más información, consulte Consideraciones que deben tenerse en cuenta al llamar a la API de datos de Amazon Redshift.
Llame a la API de datos desde la AWS Command Line Interface (AWS CLI), desde su propio código o mediante el editor de consultas de la consola de Amazon Redshift. Si desea ver algunos ejemplos de llamadas desde la AWS CLI, consulte Llamadas a la API de datos.

Consideraciones que deben tenerse en cuenta al llamar a la API de datos de Amazon Redshift

Cuando llame a la API de datos, tenga en cuenta los siguientes aspectos:

La API de datos de Amazon Redshift puede acceder a las bases de datos de los clústeres aprovisionados de Amazon Redshift y de los grupos de trabajo de Redshift sin servidor. Para obtener una lista de Regiones de AWS en las que está disponible la API de datos de Redshift, consulte los puntos de conexión enumerados para la API de datos de Redshift en la Referencia general de Amazon Web Services.
La duración máxima de una consulta es de 24 horas.
La cantidad máxima de consultas activas (consultas STARTED y SUBMITTED) por clúster de Amazon Redshift es de 500.
El tamaño máximo del resultado de la consulta es 100 MB (después de la compresión gzip). Si una llamada devuelve más de 100 MB de datos como respuesta, se terminará la llamada.
El tiempo máximo de retención de los resultados de la consulta es de 24 horas.
El tamaño máximo de las instrucciones de la consulta es de 100 KB.
La API de datos está disponible para consultar clústeres de uno o más nodos con los siguientes tipos de nodos:
- dc2.large
- dc2.8xlarge
- ra3.large
- ra3.xlplus
- ra3.4xlarge
- ra3.16xlarge
El clúster debe estar en una nube virtual privada (VPC) basada en el servicio Amazon VPC.
De manera predeterminada, los usuarios que tengan el mismo rol de IAM o permisos de IAM que el ejecutor de una operación ExecuteStatement o BatchExecuteStatement de la API pueden actuar en la misma instrucción con las operaciones CancelStatement, DescribeStatement, GetStatementResult y ListStatements de la API. Para actuar sobre la misma instrucción SQL de otro usuario, el usuario debe poder asumir el rol de IAM del usuario que ejecutó la instrucción SQL. Para obtener más información sobre cómo asumir un rol, consulte Autorización del acceso a la API de datos de Amazon Redshift.
Las instrucciones SQL del parámetro Sqls de la operación de la API BatchExecuteStatement se ejecutan como una sola transacción. Se ejecutan en serie en el orden de la matriz. Las instrucciones SQL posteriores no se inician hasta que se completa la instrucción anterior de la matriz. Si alguna instrucción SQL falla, dado que se ejecuta como una sola transacción, se deshace todo el trabajo.
El tiempo máximo de retención de un token de cliente utilizado en una operación de API ExecuteStatement o BatchExecuteStatement es de 8 horas.
Cada API de la API de datos de Redshift tiene una cuota de transacciones por segundo antes de limitar las solicitudes. Para conocer la cuota, consulte Cuotas para la API de datos de Amazon Redshift. Si la tasa de solicitudes supera la cuota, se devuelve una ThrottlingException con el código de estado HTTP 400. Para responder a la limitación, utilice una estrategia de reintentos tal como se describe en el apartado Comportamiento de los reintentos de la Guía de referencia de los SDK y las herramientas de AWS. Esta estrategia se implementa automáticamente para los errores de limitación en algunos SDK de AWS.
nota
De forma predeterminada, los reintentos no están habilitados en AWS Step Functions. Si necesita llamar a una API de datos de Redshift en una máquina de estados de Step Functions, incluya el parámetro de idempotencia ClientToken en la llamada a la API de datos de Redshift. El valor de ClientToken debe persistir entre los reintentos. En el siguiente fragmento de ejemplo de una solicitud a la API ExecuteStatement, la expresión States.ArrayGetItem(States.StringSplit($$.Execution.Id, ':'), 7) utiliza una función intrínseca para extraer la parte del UUID de $$.Execution.Id, que es única para cada ejecución de la máquina de estado. Para obtener más información, consulte Funciones intrínsecas en la Guía para desarrolladores de AWS Step Functions.
```
{
  "Database": "dev",
  "Sql": "select 1;",
  "ClusterIdentifier": "MyCluster",
  "ClientToken.$": "States.ArrayGetItem(States.StringSplit($$.Execution.Id, ':'), 7)"
}
```

Elección de las credenciales de autenticación de base de datos al llamar a la API de datos de Amazon Redshift

Cuando se llama a la API de datos, se utiliza uno de los siguientes métodos de autenticación en determinadas operaciones de la API. Para cada método, se requiere una combinación diferente de parámetros.

AWS Secrets Manager

Con este método, proporcione el secret-arn de un secreto almacenado en AWS Secrets Manager que tenga username y password. El secreto especificado contiene las credenciales para conectarse a la database que se indique. Cuando se conecta a un clúster, también proporciona el nombre de la base de datos. Si proporciona un identificador de clúster (dbClusterIdentifier), debe coincidir con el identificador de clúster almacenado en el secreto. Cuando se conecta a un grupo de trabajo sin servidor, también proporciona el nombre de la base de datos. Para obtener más información, consulte Almacenamiento de credenciales de base de datos en AWS Secrets Manager.

Credenciales temporales

Con este método, elija una de las siguientes opciones:

Al conectarse a un grupo de trabajo sin servidor, se especifica el nombre del grupo de trabajo y de la base de datos. El nombre de usuario de base de datos se deriva de la identidad de IAM. Por ejemplo, arn:iam::123456789012:user:foo tiene el nombre de usuario de base de datos IAM:foo. Además, se requiere permiso para llamar a la operación redshift-serverless:GetCredentials.
Al conectarse a un clúster como una identidad de IAM, especifique el identificador de clúster y el nombre de la base de datos. El nombre de usuario de base de datos se deriva de la identidad de IAM. Por ejemplo, arn:iam::123456789012:user:foo tiene el nombre de usuario de base de datos IAM:foo. Además, se requiere permiso para llamar a la operación redshift:GetClusterCredentialsWithIAM.
Al conectarse a un clúster como un usuario de base de datos, especifique el identificador de clúster, el nombre de la base de datos y el nombre de usuario de base de datos. Además, se requiere permiso para llamar a la operación redshift:GetClusterCredentials. Para obtener información sobre cómo unir grupos de bases de datos al conectarse con este método, consulte Unión a grupos de bases de datos al conectarse a un clúster.

Con estos métodos, también puede proporcionar un valor de region que especifica la Región de AWS en la que se encuentran los datos.

Asignación de tipos de datos JDBC al llamar a la API de datos de Amazon Redshift

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, SMALLINT, BIGINT`	`LONG`
`FLOAT, REAL, DOUBLE`	`DOUBLE`
`DECIMAL`	`STRING`
`BOOLEAN, BIT`	`BOOLEAN`
`BLOB, BINARY, LONGVARBINARY`	`BLOB`
`VARBINARY`	`STRING`
`CLOB`	`STRING`
Otros tipos (incluidos los tipos relacionados con la fecha y hora)	`STRING`

Los valores de las cadenas se transmiten a la base de datos de Amazon Redshift y se convierten implícitamente en un tipo de datos de la base de datos.

nota

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

Ejecución de instrucciones SQL con parámetros cuando se llama a la API de datos de Amazon Redshift

Puede controlar el texto SQL enviado al motor de base de datos llamando a la operación de la API de datos con los parámetros relativos a partes de la instrucción SQL. Los parámetros con nombre proporcionan una manera flexible de transmitir parámetros sin codificarlos de forma rígida en el texto SQL. Sirven para que vuelva a utilizar el texto SQL y evite los problemas de inyección SQL.

En el siguiente ejemplo, se muestran los parámetros con nombre de un campo parameters de un comando execute-statement de la AWS CLI.


--parameters "[{\"name\": \"id\", \"value\": \"1\"},{\"name\": \"address\", \"value\": \"Seattle\"}]"

A la hora de utilizar parámetros con nombre, tenga en cuenta lo siguiente:

Los parámetros con nombre solo se pueden usar para reemplazar valores en las instrucciones SQL.
- Puede reemplazar los valores en una instrucción INSERT, por ejemplo, INSERT INTO mytable VALUES(:val1).
  
  Los parámetros con nombre pueden estar dispuestos en cualquier orden y se pueden utilizar parámetros más de una vez en el texto SQL. En la opción de parámetros que se muestra en un ejemplo anterior, los valores 1 y Seattle se insertan en las columnas de tabla id y address. En el texto SQL, se especifican los parámetros con nombre de la siguiente manera:
```
--sql "insert into mytable values (:id, :address)"
```
- Puede reemplazar los valores en una cláusula de condiciones, como WHERE attr >= :val1, WHERE attr BETWEEN :val1 AND :val2 y HAVING COUNT(attr) > :val.
- No puede reemplazar los nombres de columna en una instrucción SQL, como SELECT column-name, ORDER BY column-name o GROUP BY column-name.
  
  Por ejemplo, la siguiente instrucción SELECT tiene un error de sintaxis no válida.
```
--sql "SELECT :colname, FROM event" --parameters "[{\"name\": \"colname\", \"value\": \"eventname\"}]"
```
  Si describe (operación describe-statement) la instrucción con el error de sintaxis, la QueryString que se devuelve no sustituye el nombre de columna por el parámetro ("QueryString": "SELECT :colname, FROM event") y se notifica un error (ERROR: error de sintaxis en o cerca de \"FROM\"\n Posición: 12).
- No puede reemplazar los nombres de columna en una función de agregación, como COUNT(column-name), AVG(column-name) o SUM(column-name).
- No puede reemplazar los nombres de columna en una cláusula JOIN.
Cuando se ejecuta SQL, los datos se convierten de forma implícita en un tipo de datos. Para obtener más información acerca de la conversión de tipos de datos, consulte Tipos de datos en la Guía para desarrolladores de bases de datos de Amazon Redshift.
No se puede establecer un valor en NULL. La API de datos lo interpreta como la cadena literal NULL. En el siguiente ejemplo, se reemplaza id con la cadena literal null. No con el valor NULL de SQL.
```
--parameters "[{\"name\": \"id\", \"value\": \"null\"}]"
```
No se puede establecer un valor de longitud cero. Se produce un error en la instrucción SQL de la API de datos. En el siguiente ejemplo, se intenta establecer id con un valor de longitud cero y se produce un error en la instrucción SQL.
```
--parameters "[{\"name\": \"id\", \"value\": \"\"}]"
```
No se puede establecer un nombre de tabla en la instrucción SQL con un parámetro. La API de datos cumple la regla de JDBC PreparedStatement.
La salida de la operación describe-statement devuelve los parámetros de consulta de una instrucción SQL.
Solo la operación execute-statement admite instrucciones SQL con parámetros.

Ejecución de instrucciones SQL con un token de idempotencia cuando se llama a la API de datos de Amazon Redshift

Cuando realiza una solicitud de API de mutación, la solicitud suele devolver un resultado antes de que se hayan completado los flujos de trabajo asíncronos de la operación. También es posible que se agote el tiempo de espera de las operaciones o que surjan otros problemas con el servidor antes de que finalicen, aunque la solicitud ya haya devuelto un resultado. Esto podría dificultar la determinación de si la solicitud se ha realizado correctamente o no, y podría dar lugar a múltiples reintentos para garantizar que la operación se completa correctamente. No obstante, si la solicitud original y los reintentos posteriores se realizan correctamente, la operación se completa varias veces. Esto significa que podría actualizar más recursos de los previstos.

La idempotencia garantiza que una solicitud a la API no se complete más de una vez. Con una solicitud idempotente, si la solicitud original se completa correctamente, cualquier reintento posterior también se completa correctamente sin realizar ninguna otra acción. Las operaciones ExecuteStatement y BatchExecuteStatement de la API de datos tienen un parámetro idempotente ClientToken opcional. ClientToken caduca a las 8 horas.

importante

Si llama a las operaciones ExecuteStatement y BatchExecuteStatement desde un SDK de AWS, este genera automáticamente un token de cliente para utilizarlo en el reintento. En este caso, no recomendamos utilizar el parámetro client-token con las operaciones ExecuteStatement y BatchExecuteStatement. Consulte el registro de CloudTrail para ver ClientToken. Para ver un ejemplo de registro de CloudTrail, consulte Ejemplo de la API de datos de Amazon Redshift.

El siguiente comando execute-statement de la AWS CLI ilustra el parámetro client-token opcional para idempotencia.



aws redshift-data execute-statement 
    --region us-west-2 
    --secret arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn 
    --cluster-identifier mycluster-test 
    --sql "select * from stl_query limit 1" 
    --database dev 
    --client-token b855dced-259b-444c-bc7b-d3e8e33f94g1

En la siguiente tabla se muestran algunas respuestas comunes que puede obtener para solicitudes de API idempotentes y se ofrecen recomendaciones de reintento.

Respuesta	Recomendación	Comentarios
200 (OK)	No reintentar	La solicitud original se ha completado correctamente. Cualquier reintento posterior se devuelve correctamente.
Códigos de respuesta de la serie 400	No reintentar	Hay un problema con la solicitud, uno de los siguientes: Incluye un parámetro o una combinación de parámetros que no es válida. Utiliza una acción o un recurso para el que no tiene permisos. Utiliza un recurso que está en proceso de cambiar de estado. Si la solicitud implica un recurso que está en proceso de cambiar de estado, el reintento de la solicitud podría realizarse correctamente.
Códigos de respuesta de la serie 500	Reintentar	El error se debe a un problema en el servidor de AWS y suele ser transitorio. Repita la solicitud con una estrategia de retardo adecuada.

Respuesta

Recomendación

Comentarios

200 (OK)

No reintentar

La solicitud original se ha completado correctamente. Cualquier reintento posterior se devuelve correctamente.

Códigos de respuesta de la serie 400

No reintentar

Hay un problema con la solicitud, uno de los siguientes:

Incluye un parámetro o una combinación de parámetros que no es válida.
Utiliza una acción o un recurso para el que no tiene permisos.
Utiliza un recurso que está en proceso de cambiar de estado.

Si la solicitud implica un recurso que está en proceso de cambiar de estado, el reintento de la solicitud podría realizarse correctamente.

Códigos de respuesta de la serie 500

Reintentar

El error se debe a un problema en el servidor de AWS y suele ser transitorio. Repita la solicitud con una estrategia de retardo adecuada.

Para obtener información sobre los códigos de respuesta de Amazon Redshift, consulte Common Errors (Errores comunes) en Amazon Redshift API Reference (Referencia de la API de Amazon Redshift).

Ejecución de instrucciones SQL con reutilización de sesión cuando se llama a la API de datos de Amazon Redshift

Al realizar una solicitud a la API para ejecutar una instrucción SQL, la sesión en la que se ejecuta el código SQL suele terminar cuando finaliza dicho código SQL. Para mantener la sesión activa durante un número de segundos específico, las operaciones ExecuteStatement y BatchExecuteStatement de la API de datos tienen un parámetro SessionKeepAliveSeconds opcional. Un campo de respuesta SessionId contiene la identidad de la sesión, que luego se puede utilizar en las operaciones ExecuteStatement y BatchExecuteStatement posteriores. En las llamadas posteriores, puede especificar otro valor de SessionKeepAliveSeconds para cambiar el tiempo de espera de inactividad. Si no cambia el valor de SessionKeepAliveSeconds, se mantiene la configuración de tiempo de espera de inactividad inicial. Tenga en cuenta lo siguiente al usar la reutilización de sesión:

El valor máximo de SessionKeepAliveSeconds es de 24 horas.
La sesión puede durar 24 horas como máximo. Transcurridas 24 horas, la sesión se cierra de un modo forzado y finalizan las consultas en curso.
El número máximo de sesiones por clúster de Amazon Redshift o grupo de trabajo de Amazon Redshift sin servidor es de 500.
Solo puede ejecutar una consulta cada vez en una sesión. Debe esperar a que finalice la consulta para ejecutar la siguiente consulta en la misma sesión. Es decir, no puede ejecutar consultas en paralelo en una sesión indicada.
La API de datos no puede poner en cola las consultas de una sesión determinada.

Para recuperar el valor de SessionId que utilizan las llamadas a las operaciones ExecuteStatement y BatchExecuteStatement, llame a las operaciones DescribeStatement y ListStatements.

En el siguiente ejemplo, se muestra el uso de los parámetros SessionKeepAliveSeconds y SessionId para mantener una sesión activa y reutilizada. En primer lugar, llame al comando execute-statement de la AWS CLI con el parámetro opcional session-keep-alive-seconds establecido a 2.



aws redshift-data execute-statement 
    --session-keep-alive-seconds 2 
    --sql "select 1" 
    --database dev 
    --workgroup-name mywg

La respuesta contiene el identificador de sesión.


{
    "WorkgroupName": "mywg",
    "CreatedAt": 1703022996.436,
    "Database": "dev",
    "DbUser": "awsuser",
    "Id": "07c5ffea-76d6-4786-b62c-4fe3ef529680",
    "SessionId": "5a254dc6-4fc2-4203-87a8-551155432ee4"
}

A continuación, llame al comando execute-statement de la AWS CLI con el valor de SessionId devuelto en la primera llamada. Y, si lo desea, especifique el parámetro session-keep-alive-seconds establecido a 10 para cambiar el valor del tiempo de espera de inactividad.



aws redshift-data execute-statement 
    --sql "select 1" 
    --session-id 5a254dc6-4fc2-4203-87a8-551155432ee4
    --session-keep-alive-seconds 10

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

Solución de problemas de conexión en Amazon Redshift

Autorización del acceso