Amazon Redshift dejará de admitir la creación de nuevas UDF de Python a partir del parche 198. Las UDF de Python existentes seguirán funcionando hasta el 30 de junio de 2026. Para obtener más información, consulte la [publicación del blog](https://aws.amazon.com/blogs/big-data/amazon-redshift-python-user-defined-functions-will-reach-end-of-support-after-june-30-2026/).
# 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](https://docs.aws.amazon.com/redshift-data/latest/APIReference/).
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 puede utilizar 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?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) en la *Guía del usuario de AWS Secrets Manager*. También puede utilizar AWS IAM Identity Center para la autorización.
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 AI y AWS Cloud9. Para obtener más información sobre estas aplicaciones, consulte [AWS Lambda](https://aws.amazon.com/lambda/), [Amazon SageMaker AI](https://aws.amazon.com/sagemaker/) y [AWS Cloud9](https://aws.amazon.com/cloud9/).
Para obtener más información sobre la API de datos, consulte [Introducción a la API de datos de Amazon Redshift](https://aws.amazon.com/blogs/big-data/get-started-with-the-amazon-redshift-data-api/) 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:
1. 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](data-api-access.md).
1. Determine si tiene previsto llamar a la API de datos con credenciales de autenticación de Secrets Manager, credenciales temporales o utilizar AWS IAM Identity Center. 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](#data-api-calling-considerations-authentication).
1. 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](data-api-secrets.md).
1. 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](#data-api-calling-considerations).
1. 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](data-api-calling.md).
## 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](https://docs.aws.amazon.com/general/latest/gr/redshift-service.html) 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 500 MB (después de la compresión gzip). Si una llamada devuelve más de 500 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 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`, `GetStatementResultV2` 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](data-api-access.md).
+ 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.
+ Si los clústeres aprovisionados por Amazon Redshift y el grupo de trabajo sin servidor de Redshift están cifrados mediante una clave administrada por el cliente, Redshift crea una concesión que permite a la API de datos de Redshift utilizar la clave para sus operaciones. Para obtener más información, consulte [Uso de AWS KMS con la API de datos de Amazon Redshift](data-api-kms.md).
+ 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](amazon-redshift-limits.md#data-api-quotas-account). 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](https://docs.aws.amazon.com/sdkref/latest/guide/feature-retry-behavior.html) 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](https://docs.aws.amazon.com/step-functions/latest/dg/amazon-states-language-intrinsic-functions.html) 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 IAM Identity Center**
Se puede acceder a la API de datos con un usuario de inicio de sesión único registrado en AWS IAM Identity Center. Para obtener información sobre los pasos para configurar IAM Identity Center, consulte [Uso de la API de datos con propagación de identidad de confianza](data-api-trusted-identity-propagation.md).
**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](data-api-secrets.md).
Con este método, también puede proporcionar un valor de `region` que especifique la Región de AWS donde se encuentran los datos.
**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](data-api-dbgroups.md).
Con este método, también puede proporcionar un valor de `region` que especifique la Región de AWS donde 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 \$1"FROM\$1"\$1n 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](https://docs.aws.amazon.com/redshift/latest/dg/c_Supported_data_types.html) 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](logging-with-cloudtrail.md#data-api-cloudtrail).
El siguiente comando `execute-statement` de la AWS CLI ilustra el parámetro `client-token` opcional para idempotencia.
```
aws redshift-data execute-statement
--secret-arn 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: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/redshift/latest/mgmt/data-api.html) 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 | Retry | 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](https://docs.aws.amazon.com/redshift/latest/APIReference/CommonErrors.html) (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
```
## Obtención de los resultados de las instrucciones de SQL
Se utilizan diferentes operaciones de la API de datos para obtener los resultados de SQL en función de su formato. Al llamar a las operaciones `ExecuteStatement` y `BatchExecuteStatement`, puede especificar si los resultados tienen el formato JSON o CSV. Si no lo especifica, el valor predeterminado es JSON. Para recuperar los resultados de JSON, use la operación `GetStatementResult`. Para recuperar los resultados de CSV, use la operación `GetStatementResultV2`.
Los resultados devueltos en formato JSON son registros que incluyen metadatos sobre cada columna. Cada registro está en formato JSON. Por ejemplo, la respuesta de `GetStatementResult` será similar a la siguiente:
```
{
"ColumnMetadata": [
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "?column?",
"name": "?column?",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "",
"typeName": "int4",
"length": 0
}
],
"NextToken": "",
"Records": [
[
{
"longValue": 1
}
]
],
"TotalNumRows":
}
```
Los resultados devueltos en formato CSV son registros que incluyen metadatos sobre cada columna. Los resultados se devuelven en fragmentos de 1 MB y cada fragmento puede almacenar cualquier número de filas en formato CSV. Cada solicitud devuelve hasta 15 MB de resultados. Si los resultados superan los 15 MB, se devuelve el token de la página siguiente para seguir recuperando los resultados. Por ejemplo, la respuesta de `GetStatementResultV2` será similar a la siguiente:
```
{
"ColumnMetadata": [
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "?column?",
"name": "?column?",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "",
"typeName": "int4",
"length": 0
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "?column?",
"name": "?column?",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "",
"typeName": "int4",
"length": 0
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "?column?",
"name": "?column?",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "",
"typeName": "int4",
"length": 0
}
],
"NextToken": "",
"Records": [
[
{
"CSVRecords":"1,2,3\r\n4,5,6\r\n7,8,9\rn, .... 1MB" // First 1MB Chunk
},
{
"CSVRecords":"1025,1026,1027\r\n1028,1029,1030\r\n....2MB" // Second 1MB chunk
}
...
]
],
"ResultFormat" : "CSV",
"TotalNumRows":
}
```
# Autorización del acceso a la API de datos de Amazon Redshift
Para poder obtener acceso a la API de datos, el usuario debe contar con la autorización respectiva. Puede autorizar a un usuario a obtener acceso a la API de datos si agrega la política administrada, que es una política de AWS Identity and Access Management (IAM) predefinida, a ese usuario. Como práctica recomendada, aconsejamos asociar las políticas de permisos a un rol de IAM y luego asignarlo a los usuarios y grupos según sea necesario. Para obtener más información, consulte [Administración de identidades y accesos en Amazon Redshift](https://docs.aws.amazon.com/redshift/latest/mgmt/redshift-iam-authentication-access-control.html). Para ver los permisos permitidos y denegados por las políticas administradas, consulte la consola de IAM ([https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)).
# Configuración de permisos de IAM
Amazon Redshift proporciona la política administrada `AmazonRedshiftDataFullAccess`. Esta política proporciona acceso pleno a las operaciones de la API de datos de Amazon Redshift. Esta política también permite el acceso limitado a operaciones específicas de la API de Amazon Redshift, AWS Secrets Manager e IAM que se necesitan para autenticar y obtener acceso a un clúster de Amazon Redshift o a un grupo de trabajo de Redshift sin servidor.
También puede crear una política de IAM propia que permita obtener acceso a recursos específicos. Para crear su política, utilice la política `AmazonRedshiftDataFullAccess` como la plantilla de partida. Una vez creada la política, agréguela a todos los usuarios que deban acceder a la API de datos.
Tenga en cuenta los siguientes requisitos de la política de IAM asociada al usuario:
+ Si se utiliza AWS Secrets Manager para la autenticación, confirmar la política permite que se use la acción `secretsmanager:GetSecretValue` para recuperar el secreto etiquetado con la clave `RedshiftDataFullAccess`.
+ Si se utilizan credenciales temporales para autenticar un clúster, confirmar la política permite el uso de la acción `redshift:GetClusterCredentials` en el nombre de usuario de base de datos `redshift_data_api_user` correspondiente a cualquiera de las bases de datos del clúster. Es necesario que este nombre de usuario ya se haya creado en su base de datos.
+ Si utiliza credenciales temporales para autenticarse en un grupo de trabajo sin servidor, confirme que la política permite el uso de la acción `redshift-serverless:GetCredentials` para recuperar el grupo de trabajo etiquetado con la clave `RedshiftDataFullAccess`. El usuario de la base de datos se asigna 1:1 a la identidad de AWS Identity and Access Management (IAM) de origen. Por ejemplo, el usuario sample\$1user se asigna al usuario `IAM:sample_user` de la base de datos y el rol de IAM sample\$1role se asigna a `IAMR:sample_role`. Para obtener más información acerca de las identidades de IAM, consulte [Identidades (usuarios, grupos de usuarios y roles)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id.html) en la Guía del usuario de IAM.
+ La acción de IAM `redshift-data:GetStatementResult` permite el acceso a las operaciones `GetStatementResult` y `GetStatementResultV2` de la API.
En los siguientes enlaces, encontrará más información sobre AWS Identity and Access Management en la *Guía del usuario de IAM*.
+ Para obtener más información sobre cómo crear roles de IAM, consulte [Creación de roles de IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create.html).
+ Para obtener más información sobre cómo crear una política de IAM, consulte [Creación de políticas de IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html).
+ Para obtener información sobre cómo agregar una política de IAM a un usuario, consulte [Adición y eliminación de permisos de identidad de IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html).
## Ejecución de una consulta en un clúster que es propiedad de otra cuenta
Para ejecutar una consulta en un clúster que es propiedad de otra cuenta, la cuenta propietaria debe proporcionar un rol de IAM que la API de datos pueda asumir en la cuenta que llama. Por ejemplo, supongamos que la cuenta B posee un clúster al que la cuenta A necesita acceder. La cuenta B puede asociar la política administrada de AWS `AmazonRedshiftDataFullAccess` al rol de IAM de la cuenta B. A continuación, la cuenta B se fía de la cuenta A gracias a una política de confianza como la siguiente:``
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": [
"arn:aws:iam::111122223333:role/someRoleA"
]
},
"Action": "sts:AssumeRole"
}
]
}
```
------
Por último, el rol de IAM de la cuenta A debe ser capaz de asumir el rol de IAM de la cuenta B.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": "sts:AssumeRole",
"Resource": "arn:aws:iam::111122223333:role/someRoleB"
}
}
```
------
## Especificación de un rol de IAM que restrinja los recursos a los grupos de trabajo de Redshift sin servidor y a los clústeres de Amazon Redshift en una Cuenta de AWS
Puede especificar los ARN de recursos en la política basada en identidad para controlar el acceso a los grupos de trabajo de Redshift sin servidor y a los clústeres de Amazon Redshift en una Cuenta de AWS. En este ejemplo se muestra cómo podría crear una política que permita el acceso a la API de datos solo para el grupo de trabajo y los clústeres en la Cuenta de AWS especificada.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"redshift-data:CancelStatement",
"redshift-data:DescribeStatement",
"redshift-data:GetStatementResult",
"redshift-data:ListStatements"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": "redshift-data:*",
"Resource": [
"arn:aws:redshift:us-east-1:111122223333:workgroup/*",
"arn:aws:redshift:us-east-1:111122223333:cluster:*"
]
}
]
}
```
------
## Configuración de una política de IAM que restrinja el acceso a la información de la instrucción SQL solo al propietario de la instrucción
De forma predeterminada, la API de datos de Amazon Redshift trata el rol de IAM utilizado al llamar a `ExecuteStatement` y `BatchExecuteStatement` como el propietario de la instrucción SQL. Cualquier persona a la que se le permita asumir el rol puede acceder a la información sobre la instrucción SQL, incluidos los resultados. Para restringir el acceso a la información de una instrucción SQL a una sesión de rol de IAM con un propietario concreto, agregue una condición `redshift-data:statement-owner-iam-userid: "${aws:userid}"`. La siguiente política de IAM restringe el acceso.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"redshift-data:CancelStatement",
"redshift-data:DescribeStatement",
"redshift-data:GetStatementResult",
"redshift-data:ListStatements"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"redshift-data:statement-owner-iam-userid": "${aws:userid}"
}
}
}
]
}
```
------
Puede utilizar la condición `statement-owner-iam-userid` con `CancelStatement`, `DescribeStatement`, `GetStatementResult` y `ListStatements`. Para obtener más información, consulte [Acciones definidas por la API de datos de Amazon Redshift](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonredshiftdataapi.html#amazonredshiftdataapi-redshift-data_statement-owner-iam-userid).
## Configuración de una política de IAM que restrinja el acceso a los resultados de SQL solo al propietario de la sesión
De forma predeterminada, la API de datos de Amazon Redshift trata el rol de IAM utilizado al llamar a `ExecuteStatement` y `BatchExecuteStatement` como el propietario de la sesión de base de datos que ejecuta la instrucción SQL. Cualquier usuario al que se le permita asumir el rol puede enviar consultas a la sesión de base de datos. Para restringir el acceso de sesión a una sesión de rol de IAM con un propietario concreto, agregue una condición ` redshift-data:session-owner-iam-userid: "${aws:userid}"`. La siguiente política de IAM restringe el acceso.
La siguiente política de IAM permite que solo el propietario de la sesión obtenga los resultados de las instrucciones. La condición `session-owner-iam-userid` se usa para limitar el acceso a los recursos al `userid` especificado.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"redshift-data:ExecuteStatement",
"redshift-data:BatchExecuteStatement"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"redshift-data:session-owner-iam-userid": "${aws:userid}"
}
}
}
]
}
```
------
Puede utilizar la condición `session-owner-iam-userid` con `ExecuteStatement` y `BatchExecuteStatement`. Para obtener más información, consulte [Acciones definidas por la API de datos de Amazon Redshift](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonredshiftdataapi.html#amazonredshiftdataapi-redshift-data_statement-owner-iam-userid).
# Almacenamiento de credenciales de base de datos en AWS Secrets Manager
Al llamar a la API de datos, puede transmitir las credenciales del clúster o grupo de trabajo sin servidor con un secreto en AWS 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 credenciales con Secrets Manager, se necesita contar con el permiso de la política administrada `SecretManagerReadWrite`. Para obtener más información sobre los permisos mínimos, consulte [Creación y administración de secretos con AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/managing-secrets.html) en la *Guía del usuario de AWS Secrets Manager*.
**Si desea almacenar las credenciales en un secreto para un clúster de Amazon Redshift**
1. Utilice la consola de AWS Secrets Manager para crear un secreto que contenga credenciales para el clúster:
+ Cuando elija **Store a new secret** (Almacenar un secreto nuevo), elija **Credentials for Redshift cluster** (Credenciales para clúster de Redshift).
+ Almacene sus valores para **User name** (Nombre de usuario) que es el usuario de la base de datos, **Password** (Contraseña) y **DB cluster **(Clúster de base de datos) que es el identificador del clúster, en su secreto.
+ Etiquete el secreto con la clave `RedshiftDataFullAccess`. La política administrada de AWS `AmazonRedshiftDataFullAccess` solo permite la acción `secretsmanager:GetSecretValue` para los secretos etiquetados con la clave `RedshiftDataFullAccess`.
Para obtener instrucciones, consulte [Creación de un secreto básico](https://docs.aws.amazon.com/secretsmanager/latest/userguide/manage_create-basic-secret.html) en la *Guía del usuario de AWS Secrets Manager*.
1. Utilice la consola de AWS Secrets Manager para ver los detalles del secreto que ha creado, o ejecute el comando de la `aws secretsmanager describe-secret` AWS CLI.
Anote el nombre y el ARN del secreto. Puede utilizarlos en las llamadas a la API de datos.
**Para almacenar las credenciales en un secreto para un grupo de trabajo sin servidor**
1. Utilice los comandos de la AWS CLI de AWS Secrets Manager para almacenar un secreto que contenga credenciales para el grupo de trabajo sin servidor:
+ Cree su secreto en un archivo, por ejemplo, un archivo JSON llamado `mycreds.json`. Proporcione los valores de **User name** (Nombre de usuario) (usuario de base de datos) y **Password** (Contraseña) en el archivo.
```
{
"username": "myusername",
"password": "mypassword"
}
```
+ Almacene los valores en el secreto y etiquete el secreto con la clave `RedshiftDataFullAccess`.
```
aws secretsmanager create-secret --name MyRedshiftSecret --tags Key="RedshiftDataFullAccess",Value="serverless" --secret-string file://mycreds.json
```
El ejemplo siguiente muestra el código resultante.
```
{
"ARN": "arn:aws:secretsmanager:region:accountId:secret:MyRedshiftSecret-mvLHxf",
"Name": "MyRedshiftSecret",
"VersionId": "a1603925-e8ea-4739-9ae9-e509eEXAMPLE"
}
```
Para obtener más información, consulte [Creación de un secreto básico con AWS CLI](https://docs.aws.amazon.com/secretsmanager/latest/userguide/manage_create-basic-secret.html#proc-create-api) en la *Guía del usuario de AWS Secrets Manager*.
1. Utilice la consola de AWS Secrets Manager para ver los detalles del secreto que ha creado, o ejecute el comando de la `aws secretsmanager describe-secret` AWS CLI.
Anote el nombre y el ARN del secreto. Puede utilizarlos en las llamadas a la API de datos.
# Creación de un punto de enlace de la VPC de Amazon VPC (AWS PrivateLink) para la API de datos
Amazon Virtual Private Cloud (Amazon VPC) le permite lanzar recursos de AWS, como clústeres y aplicaciones de Amazon Redshift, en una nube virtual privada (VPC). AWS PrivateLink proporciona conectividad segura y privada entre las nubes virtuales privadas (VPC) y los servicios de AWS a través de la red de Amazon. Con AWS PrivateLink, puede crear puntos de enlace de la VPC que puede utilizar para conectarse a servicios a través de diferentes cuentas y VPC basadas en Amazon VPC. Para obtener más información acerca de AWS PrivateLink, consulte [Servicios de punto de enlace de la VPC (AWS PrivateLink)](https://docs.aws.amazon.com/vpc/latest/userguide/endpoint-service.html) en la *guía del usuario de Amazon Virtual Private Cloud*.
Puede llamar a la API de datos con los puntos de enlace de la Amazon VPC. El uso de un punto de enlace de la Amazon VPC mantiene el tráfico entre las aplicaciones de su Amazon VPC y la API de datos en la red de AWS, sin usar direcciones IP públicas. Los puntos de enlace de la Amazon VPC pueden ayudarle a cumplir los requisitos reglamentarios y de conformidad relacionados con la limitación de la conectividad a internet público. Por ejemplo, si utiliza un punto de enlace de la Amazon VPC, puede mantener el tráfico entre una aplicación que se ejecuta en una instancia Amazon EC2 y la API de datos en las VPC donde se contienen.
Después de crear el punto de enlace de la Amazon VPC, puede comenzar a usarlo sin realizar ningún cambio de código o configuración en la aplicación.
**Para crear un punto de enlace de la Amazon VPC para la API de datos**
1. Inicie sesión en la Consola de administración de AWS y abra la consola de Amazon VPC en [https://console.aws.amazon.com/vpc/](https://console.aws.amazon.com/vpc/).
1. Elija **Endpoints (Puntos de enlace)** y, a continuación, elija **Create Endpoint (Crear punto de enlace)**.
1. En la página **Crear punto de conexión**, en **Categoría de servicio**, elija **Servicios de AWS**. En **Service Name** (Nombre del servicio), elija **redshift-data** (`com.amazonaws.region.redshift-data`).
1. 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.
1. 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 VPC de Amazon VPC, especifique el rango de direcciones IP privadas con las que se puede 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.
1. 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://redshift-data.region.amazonaws.com`) en las direcciones IP privadas asociadas con el nombre de host de DNS específico del punto de enlace de la Amazon VPC. Como resultado, puede acceder al punto de enlace de la VPC de la API de datos utilizando los SDK de AWS CLI o la AWS sin realizar ningún cambio de código o configuración para actualizar la URL del punto de enlace de la API de datos.
1. 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.
1. Elija **Create endpoint** (Crear punto de enlace).
Una vez creado el punto de enlace, elija el vínculo en la Consola de administración de AWS para ver los detalles del punto de enlace.
La ficha **Details** (Detalles) del punto de enlace muestra los nombres de host de DNS que se generaron al crear el punto de enlace de la Amazon VPC.
Puede utilizar el punto de enlace estándar (`redshift-data.region.amazonaws.com`) o uno de los puntos de enlace específicos de la VPC para llamar a la API de datos dentro de la Amazon VPC. El punto de enlace de la API de datos estándar se dirige automáticamente al punto de enlace de la Amazon VPC. Este enrutamiento se produce porque cuando se creó el punto de enlace de la Amazon VPC se habilitó el nombre de host de DNS privado.
Cuando utiliza un punto de enlace de la Amazon VPC en una llamada a la API de datos, todo el tráfico entre la aplicación y la API de datos permanece en las Amazon VPC donde se contienen. Puede usar un punto de enlace de la Amazon VPC para cualquier tipo de llamada a la API de datos. Para obtener más información sobre la llamada a la API de datos, consulte [Consideraciones que deben tenerse en cuenta al llamar a la API de datos de Amazon Redshift](data-api.md#data-api-calling-considerations).
# Unión a grupos de bases de datos al conectarse a un clúster
Los grupos de bases de datos son colecciones de usuarios de bases de datos. Se pueden conceder privilegios de base de datos a los grupos. Un administrador puede configurar un rol de IAM para que estos grupos de bases de datos se tengan en cuenta cuando su código SQL se ejecute con la API de datos. Para obtener más información sobre los grupos de bases de datos, consulte [Grupos](https://docs.aws.amazon.com/redshift/latest/dg/r_Groups.html) en la *Guía para desarrolladores de bases de datos de Amazon Redshift*.
Puede configurar el rol de IAM del intermediario de la API de datos para que el usuario de base de datos especificado en la llamada se una a los grupos de bases de datos cuando la API de datos se conecte a un clúster. Esta capacidad solo se admite cuando se conecta a clústeres aprovisionados. No es compatible cuando se conecta a grupos de trabajo de Redshift sin servidor. El rol de IAM del intermediario de la API de datos también debe permitir la acción `redshift:JoinGroup`.
Agregue etiquetas a los roles de IAM para configurarlo. El administrador del rol de IAM del intermediario agrega etiquetas con la clave `RedshiftDbGroups` y un valor de clave de una lista de grupos de bases de datos. El valor es una lista de nombres de grupos de bases de datos separados por dos puntos (:) hasta una longitud total de 256 caracteres. Los grupos de bases de datos deben estar previamente definidos en la base de datos conectada. Si algún grupo especificado no se encuentra en la base de datos, se omite. Por ejemplo, para los grupos de bases de datos `accounting` y `retail`, la clave-valor es `accounting:retail`. El par clave-valor de etiqueta `{"Key":"RedshiftDbGroups","Value":"accounting:retail"}` lo utiliza la API de datos para determinar qué grupos de base de datos están asociados al usuario de base de datos proporcionado en la llamada a la API de datos.
**Unión a grupos de bases de datos**
1. Inicie sesión en Consola de administración de AWS y abra la consola IAM en [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).
1. En el panel de navegación de la consola, elija **Roles** (Roles) y, a continuación, elija el nombre de la entidad que desea editar.
1. Elija la pestaña **Etiquetas** y, a continuación, **Administrar etiquetas**.
1. Elija **Agregar etiqueta** y, a continuación, agregue la clave **RedshiftDbGroups** y un valor que sea una *lista de grupos de bases de datos separados por dos puntos*.
1. Seleccione **Save changes (Guardar cambios)**.
Ahora, cuando una entidad principal de IAM (con este rol de IAM asociado) llama a la API de datos, el usuario de base de datos especificado se une a los grupos de base de datos indicados en el rol de IAM.
Para obtener más información sobre cómo adjuntar una etiqueta a una entidad principal, incluidos los roles de IAM y los usuarios de IAM, consulte [Etiquetado de recursos de IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_tags.html) en la *Guía del usuario de IAM*.
# Uso de la API de datos con propagación de identidad de confianza
Como administrador de cuentas de Amazon Redshift, puede integrar el clúster o grupo de trabajo de Amazon Redshift con AWS IAM Identity Center, lo que ayuda a administrar el acceso del personal a Amazon Redshift con inicio de sesión único. Para obtener más información, consulte [Configuración de la integración de AWS IAM Identity Center con Amazon Redshift](redshift-iam-access-control-idp-connect-console.md). La API de datos de Amazon Redshift admite la propagación de identidades de usuario de IAM Identity Center a un clúster o grupo de trabajo de Amazon Redshift, y a otros servicios, como AWS Lake Formation, en la cadena. Puede configurar y consultar mediante la API de datos si sigue los pasos de [Acceso a los servicios de AWS mediante programación con la propagación de identidad de confianza](https://aws.amazon.com/blogs//security/access-aws-services-programmatically-using-trusted-identity-propagation/).
Cuando llama a la API de datos con una identidad de usuario de IAM Identity Center desde una sesión de rol de IAM con identidad mejorada, solo puede acceder a la instrucción resultante y al resultado de la instrucción con el mismo usuario de IAM Identity Center. Por ejemplo, el siguiente comando de la AWS CLI llama a la operación `execute-statement` para ejecutar un comando SQL con propagación de identidad de confianza.
```
aws redshift-data execute-statement
--sql "select current_user;"
--cluster-id mycluster
--database dev
```
El siguiente comando de la AWS CLI llama a la operación `batch-execute-statement` para ejecutar dos comandos SQL.
```
aws redshift-data batch-execute-statement
--sqls "select current_user;" "select current_date;"
--cluster-id mycluster
--database dev
```
Para acceder a las instrucciones con `cancel-statement`, `describe-statement`, `get-statement-result` y `get-statement-result-v2` enviadas por sesiones de rol de IAM con identidad mejorada, el usuario de IAM Identity Center y el rol de IAM deben coincidir con las credenciales utilizadas para ejecutar `execute-statment` o `batch-execute-statement`. Por ejemplo, el siguiente comando de la AWS CLI obtiene los resultados de una instrucción SQL.
```
aws redshift-data get-statement-result
--id a1b2c3d4-5678-90ab-cdef-EXAMPLE11111
```
Para enumerar instrucciones, se debe proporcionar un parámetro `cluster-identifier` o `workgroup-name` a fin de garantizar que el usuario de IAM Identity Center solo tenga acceso a las aplicaciones de Amazon Redshift IAM Identity Center a las que está asignado. Por ejemplo, el siguiente comando de la AWS CLI enumera instrucciones para un clúster específico.
```
aws redshift-data list-statements
--cluster-identifier mycluster
```
También puede invocar las operaciones de la API de datos que acceden a objetos de base de datos en un clúster o grupo de trabajo mediante la propagación de identidad de confianza. Esto incluye las operaciones `list-databases`, `list-schemas`, `list-tables` y `describe-table`.
Las llamadas a la API realizadas por el usuario de IAM Identity Center pueden rastrearse en AWS CloudTrail. En la sección `onBehalfOf` del evento de CloudTrail se muestra el ID de usuario de IAM Identity Center y el ARN del almacén de identidades. En el siguiente ejemplo se muestra un fragmento de un evento de CloudTrail que muestra la sección `onBehalfOf` con el ID de usuario de IAM Identity Center de `a1b2c3d4-5678-90ab-cdef-EXAMPLE11111` y el ARN del almacén de identidades de `arn:aws:identitystore::123456789012:identitystore/d-9067bc44d2`.
```
{
"eventVersion":"1.10",
"userIdentity":{
"type":"AssumedRole",
...
},
"onBehalfOf":{
"userId":"a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"identityStoreArn":"arn:aws:identitystore::123456789012:identitystore/d-9067bc44d2"
}
},
"eventTime":"2025-01-13T04:46:27Z",
"eventSource":"redshift-data.amazonaws.com",
"eventName":"ExecuteStatement",
"awsRegion":"us-east-1"
}
```
Puede ejecutar el siguiente comando SQL para comprobar la consulta enviada por el usuario de IAM Identity Center. En este ejemplo, el correo electrónico registrado en Identity Center es `username@example.com`.
```
SELECT
h.query_id,
h.database_name,
h.status,
h.query_text,
u.usename,
h.start_time,
h.end_time
FROM
sys_query_history h
LEFT JOIN
pg_user u
ON
h.user_id = u.usesysid
where u.usename='awsidc:username@example.com'
ORDER BY
h.start_time DESC;
```
# Llamadas a la API de datos
Se puede llamar a la API de datos o a la AWS CLI a fin de ejecutar instrucciones SQL en el clúster o grupo de trabajo sin servidor. Las operaciones principales para ejecutar instrucciones SQL son [https://docs.aws.amazon.com/redshift-data/latest/APIReference/API_ExecuteStatement.html](https://docs.aws.amazon.com/redshift-data/latest/APIReference/API_ExecuteStatement.html) y [https://docs.aws.amazon.com/redshift-data/latest/APIReference/API_BatchExecuteStatement.html](https://docs.aws.amazon.com/redshift-data/latest/APIReference/API_BatchExecuteStatement.html) en la *Referencia de API de datos de Amazon Redshift*. La API de datos admite los lenguajes de programación compatibles con el AWS SDK. Para obtener más información sobre estos, consulte [Herramientas para crear en AWS](https://aws.amazon.com/tools/).
Para ver ejemplos de código de llamadas a la API de datos, consulte la [Introducción a la API de datos de Redshift](https://github.com/aws-samples/getting-started-with-amazon-redshift-data-api#getting-started-with-redshift-data-api) en *GitHub*. Este repositorio contiene ejemplos de uso de AWS Lambda para acceder a los datos de Amazon Redshift desde Amazon EC2, AWS Glue Data Catalog y Amazon SageMaker Runtime. Los lenguajes de programación de ejemplo incluyen Python, Go, Java y Javascript.
Puede llamar a la API de datos utilizando la AWS CLI.
En los siguientes ejemplos, se utiliza la AWS CLI para llamar a la API de datos. Para ejecutar los ejemplos, edite los valores de los parámetros para que se ajusten a su entorno. En muchos de los ejemplos se proporciona un `cluster-identifier` que se ejecuta en un clúster. Cuando se ejecuta en un grupo de trabajo sin servidor, se debe proporcionar un `workgroup-name` en su lugar. En estos ejemplos, se demuestran algunas de las operaciones de la API de datos. Para obtener más información, consulte *Referencia de comandos de la AWS CLI*.
Los comandos que figuran en los siguientes ejemplos se han dividido y se han formateado para facilitar su lectura. No todos los parámetros y respuestas se muestran en todos los ejemplos. Para ver la definición de la API de la sintaxis completa de la solicitud, los parámetros de la solicitud, la sintaxis de respuesta y los elementos de respuesta, consulte la [Referencia de la API de datos de Amazon Redshift](https://docs.aws.amazon.com/redshift-data/latest/APIReference/).
# Transferencia de instrucciones SQL a un almacenamiento de datos de Amazon Redshift
Los ejemplos de esta página describen diferentes formas de transferir una instrucción SQL al almacenamiento de datos
## Ejecución de una instrucción SQL
Para ejecutar una instrucción SQL, utilice el comando AWS CLI de la `aws redshift-data execute-statement`.
El siguiente comando de la AWS CLI ejecuta una instrucción SQL en un clúster y devuelve un identificador que permite obtener los resultados. En este ejemplo, se utiliza el método de autenticación de AWS Secrets Manager.
```
aws redshift-data execute-statement
--secret-arn arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn
--cluster-identifier mycluster-test
--sql "select * from stl_query limit 1"
--database dev
```
A continuación se muestra un ejemplo de respuesta.
```
{
"ClusterIdentifier": "mycluster-test",
"CreatedAt": 1598323175.823,
"Database": "dev",
"Id": "c016234e-5c6c-4bc5-bb16-2c5b8ff61814",
"SecretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn"
}
```
El siguiente comando de la AWS CLI ejecuta una instrucción SQL en un clúster y devuelve un identificador que permite obtener los resultados. En este ejemplo, se utiliza el método de autenticación de credenciales temporales.
```
aws redshift-data execute-statement
--db-user myuser
--cluster-identifier mycluster-test
--database dev
--sql "select * from stl_query limit 1"
```
A continuación se muestra un ejemplo de respuesta.
```
{
"ClusterIdentifier": "mycluster-test",
"CreatedAt": 1598306924.632,
"Database": "dev",
"DbUser": "myuser",
"Id": "d9b6c0c9-0747-4bf4-b142-e8883122f766"
}
```
El siguiente comando de la AWS CLI ejecuta una instrucción SQL en un grupo de trabajo sin servidor y devuelve un identificador que permite obtener los resultados. En este ejemplo, se utiliza el método de autenticación de credenciales temporales.
```
aws redshift-data execute-statement
--database dev
--workgroup-name myworkgroup
--sql "select 1;"
```
A continuación se muestra un ejemplo de respuesta.
```
{
"CreatedAt": "2022-02-11T06:25:28.748000+00:00",
"Database": "dev",
"DbUser": "IAMR:RoleName",
"Id": "89dd91f5-2d43-43d3-8461-f33aa093c41e",
"WorkgroupName": "myworkgroup"
}
```
El siguiente comando de la AWS CLI ejecuta una instrucción SQL en un clúster y devuelve un identificador que permite obtener los resultados. En este ejemplo se utiliza el método de autenticación de AWS Secrets Manager y un token de idempotencia.
```
aws redshift-data execute-statement
--secret-arn 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
```
A continuación se muestra un ejemplo de respuesta.
```
{
"ClusterIdentifier": "mycluster-test",
"CreatedAt": 1598323175.823,
"Database": "dev",
"Id": "c016234e-5c6c-4bc5-bb16-2c5b8ff61814",
"SecretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn"
}
```
## Ejecución de una instrucción SQL con parámetros
Para ejecutar una instrucción SQL, utilice el comando AWS CLI de la `aws redshift-data execute-statement`.
El siguiente comando de la AWS CLI ejecuta una instrucción SQL en un clúster y devuelve un identificador que permite obtener los resultados. En este ejemplo, se utiliza el método de autenticación de AWS Secrets Manager. El texto SQL tiene el parámetro con nombre `distance`. En este caso, la distancia utilizada en el predicado es `5`. En una instrucción SELECT, los parámetros con nombre de los nombres de columna solo se pueden usar en el predicado. Los valores de los parámetros con nombre para la instrucción SQL se especifican en la opción `parameters`.
```
aws redshift-data execute-statement
--secret-arn arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn
--cluster-identifier mycluster-test
--sql "SELECT ratecode FROM demo_table WHERE trip_distance > :distance"
--parameters "[{\"name\": \"distance\", \"value\": \"5\"}]"
--database dev
```
A continuación se muestra un ejemplo de respuesta.
```
{
"ClusterIdentifier": "mycluster-test",
"CreatedAt": 1598323175.823,
"Database": "dev",
"Id": "c016234e-5c6c-4bc5-bb16-2c5b8ff61814",
"SecretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn"
}
```
En el siguiente ejemplo, se utiliza la tabla `EVENT` de la base de datos de muestra. Para obtener más información, consulte [Tabla EVENT](https://docs.aws.amazon.com/redshift/latest/dg/r_eventtable.html) en la *Guía para desarrolladores de bases de datos de Amazon Redshift.*.
Si aún no dispone de una tabla `EVENT` en la base de datos, puede crear una con la API de datos de la siguiente manera:
```
aws redshift-data execute-statement
--database dev
--cluster-id mycluster-test
--db-user awsuser
--sql "create table event( eventid integer not null distkey,
venueid smallint not null,
catid smallint not null,
dateid smallint not null sortkey,
eventname varchar(200),
starttime timestamp)"
```
El siguiente comando inserta una fila en la tabla `EVENT`.
```
aws redshift-data execute-statement
--database dev
--cluster-id mycluster-test
--db-user awsuser
--sql "insert into event values(:eventid, :venueid::smallint, :catid, :dateid, :eventname, :starttime)"
--parameters "[{\"name\": \"eventid\", \"value\": \"1\"}, {\"name\": \"venueid\", \"value\": \"1\"},
{\"name\": \"catid\", \"value\": \"1\"},
{\"name\": \"dateid\", \"value\": \"1\"},
{\"name\": \"eventname\", \"value\": \"event 1\"},
{\"name\": \"starttime\", \"value\": \"2022-02-22\"}]"
```
El siguiente comando inserta una segunda fila en la tabla `EVENT`. Este ejemplo hace lo siguiente:
+ El parámetro con nombre `id` se utiliza cuatro veces en el texto SQL.
+ La conversión del tipo implícita se aplica automáticamente cuando se inserta un parámetro `starttime`.
+ La columna `venueid` se convierte en un tipo de datos SMALLINT.
+ Las cadenas de caracteres que representan el tipo de datos DATE se convierten de forma implícita en el tipo de datos TIMESTAMP.
+ Los comentarios se pueden emplear en el texto SQL.
```
aws redshift-data execute-statement
--database dev
--cluster-id mycluster-test
--db-user awsuser
--sql "insert into event values(:id, :id::smallint, :id, :id, :eventname, :starttime) /*this is comment, and it won't apply parameterization for :id, :eventname or :starttime here*/"
--parameters "[{\"name\": \"eventname\", \"value\": \"event 2\"},
{\"name\": \"starttime\", \"value\": \"2022-02-22\"},
{\"name\": \"id\", \"value\": \"2\"}]"
```
A continuación, se muestran las dos filas que se han insertado:
```
eventid | venueid | catid | dateid | eventname | starttime
---------+---------+-------+--------+-----------+---------------------
1 | 1 | 1 | 1 | event 1 | 2022-02-22 00:00:00
2 | 2 | 2 | 2 | event 2 | 2022-02-22 00:00:00
```
El siguiente comando utiliza un parámetro con nombre en una cláusula WHERE que permite recuperar la fila donde `eventid` es `1`.
```
aws redshift-data execute-statement
--database dev
--cluster-id mycluster-test
--db-user awsuser
--sql "select * from event where eventid=:id"
--parameters "[{\"name\": \"id\", \"value\": \"1\"}]"
```
Ejecute el siguiente comando para obtener los resultados SQL de la instrucción SQL precedente:
```
aws redshift-data get-statement-result --id 7529ad05-b905-4d71-9ec6-8b333836eb5a
```
Proporciona los siguientes resultados:
```
{
"Records": [
[
{
"longValue": 1
},
{
"longValue": 1
},
{
"longValue": 1
},
{
"longValue": 1
},
{
"stringValue": "event 1"
},
{
"stringValue": "2022-02-22 00:00:00.0"
}
]
],
"ColumnMetadata": [
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "eventid",
"length": 0,
"name": "eventid",
"nullable": 0,
"precision": 10,
"scale": 0,
"schemaName": "public",
"tableName": "event",
"typeName": "int4"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "venueid",
"length": 0,
"name": "venueid",
"nullable": 0,
"precision": 5,
"scale": 0,
"schemaName": "public",
"tableName": "event",
"typeName": "int2"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "catid",
"length": 0,
"name": "catid",
"nullable": 0,
"precision": 5,
"scale": 0,
"schemaName": "public",
"tableName": "event",
"typeName": "int2"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "dateid",
"length": 0,
"name": "dateid",
"nullable": 0,
"precision": 5,
"scale": 0,
"schemaName": "public",
"tableName": "event",
"typeName": "int2"
},
{
"isCaseSensitive": true,
"isCurrency": false,
"isSigned": false,
"label": "eventname",
"length": 0,
"name": "eventname",
"nullable": 1,
"precision": 200,
"scale": 0,
"schemaName": "public",
"tableName": "event",
"typeName": "varchar"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"label": "starttime",
"length": 0,
"name": "starttime",
"nullable": 1,
"precision": 29,
"scale": 6,
"schemaName": "public",
"tableName": "event",
"typeName": "timestamp"
}
],
"TotalNumRows": 1
}
```
## Ejecución de varias instrucciones SQL
Para ejecutar varias instrucciones SQL con un solo comando, utilice el comando `aws redshift-data batch-execute-statement` de la AWS CLI.
El siguiente comando de la AWS CLI ejecuta tres instrucciones SQL en un clúster y devuelve un identificador que permite obtener los resultados. En este ejemplo, se utiliza el método de autenticación de credenciales temporales.
```
aws redshift-data batch-execute-statement
--db-user myuser
--cluster-identifier mycluster-test
--database dev
--sqls "set timezone to BST" "select * from mytable" "select * from another_table"
```
A continuación se muestra un ejemplo de respuesta.
```
{
"ClusterIdentifier": "mycluster-test",
"CreatedAt": 1598306924.632,
"Database": "dev",
"DbUser": "myuser",
"Id": "d9b6c0c9-0747-4bf4-b142-e8883122f766"
}
```
# Muestra de metadatos sobre las instrucciones SQL
Para enumerar los metadatos relativos a las instrucciones SQL, utilice el comando `aws redshift-data list-statements` de la AWS CLI. La autorización para ejecutar este comando se basa en los permisos de IAM de la persona que llama.
El siguiente comando de la AWS CLI enumera las instrucciones SQL que se ejecutaron.
```
aws redshift-data list-statements
--status ALL
```
A continuación se muestra un ejemplo de respuesta.
```
{
"Statements": [
{
"CreatedAt": 1598306924.632,
"Id": "d9b6c0c9-0747-4bf4-b142-e8883122f766",
"QueryString": "select * from stl_query limit 1",
"Status": "FINISHED",
"UpdatedAt": 1598306926.667
},
{
"CreatedAt": 1598311717.437,
"Id": "e0ebd578-58b3-46cc-8e52-8163fd7e01aa",
"QueryString": "select * from stl_query limit 1",
"Status": "FAILED",
"UpdatedAt": 1598311719.008
},
{
"CreatedAt": 1598313683.65,
"Id": "c361d4f7-8c53-4343-8c45-6b2b1166330c",
"QueryString": "select * from stl_query limit 1",
"Status": "ABORTED",
"UpdatedAt": 1598313685.495
},
{
"CreatedAt": 1598306653.333,
"Id": "a512b7bd-98c7-45d5-985b-a715f3cfde7f",
"QueryString": "select 1",
"Status": "FINISHED",
"UpdatedAt": 1598306653.992
}
]
}
```
# Descripción de metadatos sobre una instrucción SQL
Para obtener descripciones de los metadatos de una instrucción SQL, utilice el comando `aws redshift-data describe-statement` de la AWS CLI. La autorización para ejecutar este comando se basa en los permisos de IAM de la persona que llama.
El siguiente comando de la AWS CLI describe una instrucción SQL.
```
aws redshift-data describe-statement
--id d9b6c0c9-0747-4bf4-b142-e8883122f766
```
A continuación se muestra un ejemplo de respuesta.
```
{
"ClusterIdentifier": "mycluster-test",
"CreatedAt": 1598306924.632,
"Duration": 1095981511,
"Id": "d9b6c0c9-0747-4bf4-b142-e8883122f766",
"QueryString": "select * from stl_query limit 1",
"RedshiftPid": 20859,
"RedshiftQueryId": 48879,
"ResultRows": 1,
"ResultSize": 4489,
"Status": "FINISHED",
"UpdatedAt": 1598306926.667
}
```
A continuación, se muestra un ejemplo de una respuesta `describe-statement` que surge después de ejecutar un comando `batch-execute-statement` con varias instrucciones SQL.
```
{
"ClusterIdentifier": "mayo",
"CreatedAt": 1623979777.126,
"Duration": 6591877,
"HasResultSet": true,
"Id": "b2906c76-fa6e-4cdf-8c5f-4de1ff9b7652",
"RedshiftPid": 31459,
"RedshiftQueryId": 0,
"ResultRows": 2,
"ResultSize": 22,
"Status": "FINISHED",
"SubStatements": [
{
"CreatedAt": 1623979777.274,
"Duration": 3396637,
"HasResultSet": true,
"Id": "b2906c76-fa6e-4cdf-8c5f-4de1ff9b7652:1",
"QueryString": "select 1;",
"RedshiftQueryId": -1,
"ResultRows": 1,
"ResultSize": 11,
"Status": "FINISHED",
"UpdatedAt": 1623979777.903
},
{
"CreatedAt": 1623979777.274,
"Duration": 3195240,
"HasResultSet": true,
"Id": "b2906c76-fa6e-4cdf-8c5f-4de1ff9b7652:2",
"QueryString": "select 2;",
"RedshiftQueryId": -1,
"ResultRows": 1,
"ResultSize": 11,
"Status": "FINISHED",
"UpdatedAt": 1623979778.076
}
],
"UpdatedAt": 1623979778.183
}
```
# Obtención de los resultados de una instrucción SQL
Para obtener el resultado de una instrucción de SQL que ya se ejecutó, utilice el comando `redshift-data get-statement-result` o `redshift-data get-statement-result-v2` de la AWS CLI. Los resultados de `get-statement-result` están en formato JSON. Los resultados de `get-statement-result-v2` están en formato CSV. Puede proporcionar un `Id` que reciba en respuesta a `execute-statement` o `batch-execute-statement`. El valor `Id` para una instrucción SQL ejecutada por `batch-execute-statement` se puede recuperar en el resultado de `describe-statement` y lleva como sufijo dos puntos y un número de secuencia, como `b2906c76-fa6e-4cdf-8c5f-4de1ff9b7652:2`. Si ejecuta varias instrucciones SQL con `batch-execute-statement`, cada una de ellas tiene un valor `Id` como se muestra en `describe-statement`. La autorización para ejecutar este comando se basa en los permisos de IAM de la persona que llama.
La siguiente instrucción devuelve el resultado de una instrucción de SQL que se ejecuta mediante `execute-statement` que hace que `ResultFormat` utilice `JSON` de manera predeterminada. Para recuperar los resultados, llame a la operación `get-statement-result`.
```
aws redshift-data get-statement-result
--id d9b6c0c9-0747-4bf4-b142-e8883122f766
```
La siguiente instrucción devuelve el resultado de la segunda instrucción SQL que se ejecuta mediante `batch-execute-statement`.
```
aws redshift-data get-statement-result
--id b2906c76-fa6e-4cdf-8c5f-4de1ff9b7652:2
```
A continuación, se muestra un ejemplo de una respuesta a una llamada a `get-statement-result` en la que se devuelve el resultado de SQL en formato JSON en la clave `Records` de la respuesta.
```
{
"ColumnMetadata": [
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "userid",
"length": 0,
"name": "userid",
"nullable": 0,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "stll_query",
"typeName": "int4"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "query",
"length": 0,
"name": "query",
"nullable": 0,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "stll_query",
"typeName": "int4"
},
{
"isCaseSensitive": true,
"isCurrency": false,
"isSigned": false,
"label": "label",
"length": 0,
"name": "label",
"nullable": 0,
"precision": 320,
"scale": 0,
"schemaName": "",
"tableName": "stll_query",
"typeName": "bpchar"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "xid",
"length": 0,
"name": "xid",
"nullable": 0,
"precision": 19,
"scale": 0,
"schemaName": "",
"tableName": "stll_query",
"typeName": "int8"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "pid",
"length": 0,
"name": "pid",
"nullable": 0,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "stll_query",
"typeName": "int4"
},
{
"isCaseSensitive": true,
"isCurrency": false,
"isSigned": false,
"label": "database",
"length": 0,
"name": "database",
"nullable": 0,
"precision": 32,
"scale": 0,
"schemaName": "",
"tableName": "stll_query",
"typeName": "bpchar"
},
{
"isCaseSensitive": true,
"isCurrency": false,
"isSigned": false,
"label": "querytxt",
"length": 0,
"name": "querytxt",
"nullable": 0,
"precision": 4000,
"scale": 0,
"schemaName": "",
"tableName": "stll_query",
"typeName": "bpchar"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"label": "starttime",
"length": 0,
"name": "starttime",
"nullable": 0,
"precision": 29,
"scale": 6,
"schemaName": "",
"tableName": "stll_query",
"typeName": "timestamp"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"label": "endtime",
"length": 0,
"name": "endtime",
"nullable": 0,
"precision": 29,
"scale": 6,
"schemaName": "",
"tableName": "stll_query",
"type": 93,
"typeName": "timestamp"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "aborted",
"length": 0,
"name": "aborted",
"nullable": 0,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "stll_query",
"typeName": "int4"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "insert_pristine",
"length": 0,
"name": "insert_pristine",
"nullable": 0,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "stll_query",
"typeName": "int4"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "concurrency_scaling_status",
"length": 0,
"name": "concurrency_scaling_status",
"nullable": 0,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "stll_query",
"typeName": "int4"
}
],
"Records": [
[
{
"longValue": 1
},
{
"longValue": 3
},
{
"stringValue": "health"
},
{
"longValue": 1023
},
{
"longValue": 15279
},
{
"stringValue": "dev"
},
{
"stringValue": "select system_status from stv_gui_status;"
},
{
"stringValue": "2020-08-21 17:33:51.88712"
},
{
"stringValue": "2020-08-21 17:33:52.974306"
},
{
"longValue": 0
},
{
"longValue": 0
},
{
"longValue": 6
}
]
],
"TotalNumRows": 1
}
```
En el siguiente ejemplo, se muestra una instrucción de SQL ejecutada por `execute-statement` para devolver resultados en formato JSON. La tabla `testingtable` tiene tres columnas de enteros (col1, col2, col3) y hay tres filas con valores (1, 2, 3), (4, 5, 6) y (7, 8, 9).
```
aws redshift-data execute-statement
--database dev
--sql "SELECT col1, col2, col3 FROM testingtable"
--cluster-id mycluster-test
--result-format JSON
```
```
{
"ClusterIdentifier": "mycluster-test",
"CreatedAt": "2024-04-02T16:45:25.144000+00:00",
"Database": "dev",
"DbUser": "IAMR:Administrator",
"Id": "d468d942-6df9-4f85-8ae3-bac01a61aec3"
}
```
A continuación, se muestra un ejemplo de una respuesta a una llamada a `get-statement-result` en la que se devuelve el resultado de SQL en formato JSON en la clave `Records` de la respuesta.
```
aws redshift-data get-statement-result
--id d468d942-6df9-4f85-8ae3-bac01a61aec3
```
```
{
"Records": [
[
{
"longValue": 1
},
{
"longValue": 2
},
{
"longValue": 3
}
],
[
{
"longValue": 4
},
{
"longValue": 5
},
{
"longValue": 6
}
],
[
{
"longValue": 7
},
{
"longValue": 8
},
{
"longValue": 9
}
]
],
"ColumnMetadata": [
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "col1",
"name": "col1",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "public",
"tableName": "testingtable",
"typeName": "int4",
"length": 0
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "col2",
"name": "col2",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "public",
"tableName": "testingtable",
"typeName": "int4",
"length": 0
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "col3",
"name": "col3",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "public",
"tableName": "testingtable",
"typeName": "int4",
"length": 0
}
],
"TotalNumRows": 3
}
```
En el siguiente ejemplo, se muestra una instrucción de SQL ejecutada por `execute-statement` para devolver resultados en formato CSV. La tabla `testingtable` tiene tres columnas de enteros (col1, col2, col3) y hay tres filas con valores (1, 2, 3), (4, 5, 6) y (7, 8, 9).
```
aws redshift-data execute-statement
--database dev
--sql "SELECT col1, col2, col3 FROM testingtable"
--cluster-id mycluster-test
--result-format CSV
```
```
{
"ClusterIdentifier": "mycluster-test",
"CreatedAt": "2024-04-02T16:45:25.144000+00:00",
"Database": "dev",
"DbUser": "IAMR:Administrator",
"Id": "d468d942-6df9-4f85-8ae3-bac01a61aec3"
}
```
A continuación, se muestra un ejemplo de una respuesta a una llamada a `get-statement-result-v2` en la que se devuelve el resultado de SQL en formato CSV en la clave `Records` de la respuesta. Las filas están separadas por un retorno de carro y una línea nueva (\$1r\$1n). La primera fila devuelta en `Records` son los encabezados de columna. Los resultados en formato CSV se devuelven en fragmentos de 1 MB y cada fragmento puede almacenar cualquier número de filas de hasta 1 MB.
```
aws redshift-data get-statement-result-v2
--id d468d942-6df9-4f85-8ae3-bac01a61aec3
```
```
{
"Records": [
{
"CSVRecords": "col1,col2,col3\r\n1,2,3\r\n4,5,6\r\n7,8,9\r\n"
}
],
"ColumnMetadata": [
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "col1",
"name": "col1",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "public",
"tableName": "testingtable",
"typeName": "int4",
"length": 0
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "col2",
"name": "col2",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "public",
"tableName": "testingtable",
"typeName": "int4",
"length": 0
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "col3",
"name": "col3",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "public",
"tableName": "testingtable",
"typeName": "int4",
"length": 0
}
],
"TotalNumRows": 3,
"ResultFormat": "csv"
}
```
# Descripción de una tabla
Para obtener los metadatos que describen una tabla, utilice el comando `aws redshift-data describe-table` de la AWS CLI.
El siguiente comando de la AWS CLI ejecuta una instrucción SQL en un clúster y devuelve los metadatos que describen una tabla. En este ejemplo, se utiliza el método de autenticación de AWS Secrets Manager.
```
aws redshift-data describe-table
--cluster-identifier mycluster-test
--database dev
--schema information_schema
--table sql_features
--secret-arn arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn
```
A continuación se muestra un ejemplo de respuesta.
```
{
"ColumnList": [
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"length": 2147483647,
"name": "feature_id",
"nullable": 1,
"precision": 2147483647,
"scale": 0,
"schemaName": "information_schema",
"tableName": "sql_features",
"typeName": "character_data"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"length": 2147483647,
"name": "feature_name",
"nullable": 1,
"precision": 2147483647,
"scale": 0,
"schemaName": "information_schema",
"tableName": "sql_features",
"typeName": "character_data"
}
]
}
```
El siguiente comando de la AWS CLI ejecuta una instrucción SQL en un clúster que describe una tabla. En este ejemplo, se utiliza el método de autenticación de credenciales temporales.
```
aws redshift-data describe-table
--db-user myuser
--cluster-identifier mycluster-test
--database dev
--schema information_schema
--table sql_features
```
A continuación se muestra un ejemplo de respuesta.
```
{
"ColumnList": [
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"length": 2147483647,
"name": "feature_id",
"nullable": 1,
"precision": 2147483647,
"scale": 0,
"schemaName": "information_schema",
"tableName": "sql_features",
"typeName": "character_data"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"length": 2147483647,
"name": "feature_name",
"nullable": 1,
"precision": 2147483647,
"scale": 0,
"schemaName": "information_schema",
"tableName": "sql_features",
"typeName": "character_data"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"length": 2147483647,
"name": "sub_feature_id",
"nullable": 1,
"precision": 2147483647,
"scale": 0,
"schemaName": "information_schema",
"tableName": "sql_features",
"typeName": "character_data"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"length": 2147483647,
"name": "sub_feature_name",
"nullable": 1,
"precision": 2147483647,
"scale": 0,
"schemaName": "information_schema",
"tableName": "sql_features",
"typeName": "character_data"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"length": 2147483647,
"name": "is_supported",
"nullable": 1,
"precision": 2147483647,
"scale": 0,
"schemaName": "information_schema",
"tableName": "sql_features",
"typeName": "character_data"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"length": 2147483647,
"name": "is_verified_by",
"nullable": 1,
"precision": 2147483647,
"scale": 0,
"schemaName": "information_schema",
"tableName": "sql_features",
"typeName": "character_data"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"length": 2147483647,
"name": "comments",
"nullable": 1,
"precision": 2147483647,
"scale": 0,
"schemaName": "information_schema",
"tableName": "sql_features",
"typeName": "character_data"
}
]
}
```
# Enumeración de las bases de datos de un clúster
Para enumerar las bases de datos de un clúster, utilice el comando `aws redshift-data list-databases` de la AWS CLI.
El siguiente comando de la AWS CLI ejecuta una instrucción SQL en un clúster para mostrar bases de datos. En este ejemplo, se utiliza el método de autenticación de AWS Secrets Manager.
```
aws redshift-data list-databases
--secret-arn arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn
--cluster-identifier mycluster-test
--database dev
```
A continuación se muestra un ejemplo de respuesta.
```
{
"Databases": [
"dev"
]
}
```
El siguiente comando de la AWS CLI ejecuta una instrucción SQL en un clúster para mostrar bases de datos. En este ejemplo, se utiliza el método de autenticación de credenciales temporales.
```
aws redshift-data list-databases
--db-user myuser
--cluster-identifier mycluster-test
--database dev
```
A continuación se muestra un ejemplo de respuesta.
```
{
"Databases": [
"dev"
]
}
```
# Enumeración de los esquemas de una base de datos
Para enumerar los esquemas de una base de datos, utilice el comando `aws redshift-data list-schemas` de la AWS CLI.
El siguiente comando de la AWS CLI ejecuta una instrucción SQL en un clúster para mostrar esquemas en una base de datos. En este ejemplo, se utiliza el método de autenticación de AWS Secrets Manager.
```
aws redshift-data list-schemas
--secret-arn arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn
--cluster-identifier mycluster-test
--database dev
```
A continuación se muestra un ejemplo de respuesta.
```
{
"Schemas": [
"information_schema",
"pg_catalog",
"pg_internal",
"public"
]
}
```
El siguiente comando de la AWS CLI ejecuta una instrucción SQL en un clúster para mostrar esquemas en una base de datos. En este ejemplo, se utiliza el método de autenticación de credenciales temporales.
```
aws redshift-data list-schemas
--db-user mysuser
--cluster-identifier mycluster-test
--database dev
```
A continuación se muestra un ejemplo de respuesta.
```
{
"Schemas": [
"information_schema",
"pg_catalog",
"pg_internal",
"public"
]
}
```
# Enumeración de tablas de una base de datos
Para enumerar las tablas de una base de datos, utilice el comando `aws redshift-data list-tables` de la AWS CLI.
El siguiente comando de la AWS CLI ejecuta una instrucción SQL en un clúster para mostrar tablas en una base de datos. En este ejemplo, se utiliza el método de autenticación de AWS Secrets Manager.
```
aws redshift-data list-tables
--secret-arn arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn
--cluster-identifier mycluster-test
--database dev
--schema information_schema
```
A continuación se muestra un ejemplo de respuesta.
```
{
"Tables": [
{
"name": "sql_features",
"schema": "information_schema",
"type": "SYSTEM TABLE"
},
{
"name": "sql_implementation_info",
"schema": "information_schema",
"type": "SYSTEM TABLE"
}
}
```
El siguiente comando de la AWS CLI ejecuta una instrucción SQL en un clúster para mostrar tablas en una base de datos. En este ejemplo, se utiliza el método de autenticación de credenciales temporales.
```
aws redshift-data list-tables
--db-user myuser
--cluster-identifier mycluster-test
--database dev
--schema information_schema
```
A continuación se muestra un ejemplo de respuesta.
```
{
"Tables": [
{
"name": "sql_features",
"schema": "information_schema",
"type": "SYSTEM TABLE"
},
{
"name": "sql_implementation_info",
"schema": "information_schema",
"type": "SYSTEM TABLE"
}
]
}
```
# Solución de problemas de la API de datos de Amazon Redshift
Use las siguientes secciones, tituladas con mensajes de error comunes, para ayudar a solucionar problemas que tenga con la API de datos.
**Topics**
+ [El paquete de la consulta es demasiado grande](#data-api-troubleshooting-packet-too-large)
+ [Límite de tamaño superado de respuesta de base de datos](#data-api-troubleshooting-response-size-too-large)
## El paquete de la consulta es demasiado grande
Si aparece un error que indica que el paquete de una consulta es demasiado grande, por lo general, el conjunto de resultados que se obtiene para una fila también es 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
Si aparece un error que indica que la respuesta de la base de datos ha superado el límite de tamaño, por lo general, esto significa que 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 500 MB en el conjunto de resultados devuelto por la base de datos.
Para resolver este problema, asegúrese de que las llamadas a la API de datos devuelvan 500 MB o menos. Si necesita devolver más de 500 MB, puede ejecutar varias llamadas de instrucción con la cláusula `LIMIT` en la consulta.
# Programación de operaciones de la API de datos de Amazon Redshift con Amazon EventBridge
Puede crear reglas que coincidan con los eventos seleccionados y que los dirijan a los destinos para realizar alguna acción. También puede utilizar reglas para realizar acciones en una programación predeterminada. Para más información, consulte la [Guía del usuario de Amazon EventBridge](https://docs.aws.amazon.com/eventbridge/latest/userguide/).
Para programar operaciones de la API de datos con EventBridge, el rol de IAM asociado debe confiar en la entidad principal de CloudWatch Events (events.amazonaws.com). Este rol debería tener el equivalente a la política administrada `AmazonEventBridgeFullAccess` adjunta. Además, debería contar con los permisos de la política `AmazonRedshiftDataFullAccess` que administra la API de datos. Puede crear un rol de IAM con estos permisos en la consola de IAM. Al crear un rol en la consola de IAM, elija la entidad de confianza del servicio de AWS para CloudWatch Events. Especifique el rol de IAM en el valor JSON `RoleArn` del destino de EventBridge. Para obtener más información sobre cómo crear un rol de IAM, consulte [Creación de un rol para un servicio de AWS (consola)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html#roles-creatingrole-service-console) en la *Guía del usuario de IAM*.
La regla `name` que cree en Amazon EventBridge debe coincidir con el `StatementName` en los `RedshiftDataParameters`.
En los siguientes ejemplos, se muestran las variaciones de la creación de reglas de EventBridge con una o varias instrucciones SQL y con un clúster de Amazon Redshift o un grupo de trabajo de Amazon Redshift sin servidor como almacenamiento de datos.
## Llamada con una sola instrucción SQL y un clúster
En el siguiente ejemplo, se utiliza la AWS CLI a fin de crear una regla de EventBridge que se use para ejecutar una instrucción SQL en un clúster de Amazon Redshift.
```
aws events put-rule
--name test-redshift-cluster-data
--schedule-expression "rate(1 minute)"
```
A continuación, se crea un objetivo de EventBridge para que se ejecute en la programación especificada en la regla.
```
aws events put-targets
--cli-input-json file://data.json
```
El archivo data.json de entrada es así. La clave JSON `Sql` indica que hay una sola instrucción SQL. El valor JSON `Arn` contiene un identificador de clúster. El valor JSON `RoleArn` contiene el rol de IAM que se utiliza para ejecutar el código SQL, tal como se describió anteriormente.
```
{
"Rule": "test-redshift-cluster-data",
"EventBusName": "default",
"Targets": [
{
"Id": "2",
"Arn": "arn:aws:redshift:us-east-1:123456789012:cluster:mycluster",
"RoleArn": "arn:aws:iam::123456789012:role/Administrator",
"RedshiftDataParameters": {
"Database": "dev",
"DbUser": "root",
"Sql": "select 1;",
"StatementName": "test-redshift-cluster-data",
"WithEvent": true
}
}
]
}
```
## Llamada con una sola instrucción SQL y un grupo de trabajo
En el siguiente ejemplo, se utiliza la AWS CLI a fin de crear una regla de EventBridge que se use para ejecutar una instrucción SQL en un grupo de trabajo de Amazon Redshift sin servidor.
```
aws events put-rule
--name test-redshift-serverless-workgroup-data
--schedule-expression "rate(1 minute)"
```
A continuación, se crea un objetivo de EventBridge para que se ejecute en la programación especificada en la regla.
```
aws events put-targets
--cli-input-json file://data.json
```
El archivo data.json de entrada es así. La clave JSON `Sql` indica que hay una sola instrucción SQL. El valor JSON `Arn` contiene un nombre de grupo de trabajo. El valor JSON `RoleArn` contiene el rol de IAM que se utiliza para ejecutar el código SQL, tal como se describió anteriormente.
```
{
"Rule": "test-redshift-serverless-workgroup-data",
"EventBusName": "default",
"Targets": [
{
"Id": "2",
"Arn": "arn:aws:redshift-serverless:us-east-1:123456789012:workgroup/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"RoleArn": "arn:aws:iam::123456789012:role/Administrator",
"RedshiftDataParameters": {
"Database": "dev",
"Sql": "select 1;",
"StatementName": "test-redshift-serverless-workgroup-data",
"WithEvent": true
}
}
]
}
```
## Llamada con varias instrucciones SQL y un clúster
En el siguiente ejemplo, se utiliza la AWS CLI a fin de crear una regla de EventBridge que se use para ejecutar varias instrucciones SQL en un clúster de Amazon Redshift.
```
aws events put-rule
--name test-redshift-cluster-data
--schedule-expression "rate(1 minute)"
```
A continuación, se crea un objetivo de EventBridge para que se ejecute en la programación especificada en la regla.
```
aws events put-targets
--cli-input-json file://data.json
```
El archivo data.json de entrada es así. La clave JSON `Sqls` indica que hay varias instrucciones SQL. El valor JSON `Arn` contiene un identificador de clúster. El valor JSON `RoleArn` contiene el rol de IAM que se utiliza para ejecutar el código SQL, tal como se describió anteriormente.
```
{
"Rule": "test-redshift-cluster-data",
"EventBusName": "default",
"Targets": [
{
"Id": "2",
"Arn": "arn:aws:redshift:us-east-1:123456789012:cluster:mycluster",
"RoleArn": "arn:aws:iam::123456789012:role/Administrator",
"RedshiftDataParameters": {
"Database": "dev",
"Sqls": ["select 1;", "select 2;", "select 3;"],
"StatementName": "test-redshift-cluster-data",
"WithEvent": true
}
}
]
}
```
## Llamada con varias instrucciones SQL y un grupo de trabajo
En el siguiente ejemplo, se utiliza la AWS CLI a fin de crear una regla de EventBridge que se use para ejecutar varias instrucciones SQL en un grupo de trabajo de Amazon Redshift sin servidor.
```
aws events put-rule
--name test-redshift-serverless-workgroup-data
--schedule-expression "rate(1 minute)"
```
A continuación, se crea un objetivo de EventBridge para que se ejecute en la programación especificada en la regla.
```
aws events put-targets
--cli-input-json file://data.json
```
El archivo data.json de entrada es así. La clave JSON `Sqls` indica que hay varias instrucciones SQL. El valor JSON `Arn` contiene un nombre de grupo de trabajo. El valor JSON `RoleArn` contiene el rol de IAM que se utiliza para ejecutar el código SQL, tal como se describió anteriormente.
```
{
"Rule": "test-redshift-serverless-workgroup-data",
"EventBusName": "default",
"Targets": [
{
"Id": "2",
"Arn": "arn:aws:redshift-serverless:us-east-1:123456789012:workgroup/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"RoleArn": "arn:aws:iam::123456789012:role/Administrator",
"RedshiftDataParameters": {
"Database": "dev",
"Sqls": ["select 1;", "select 2;", "select 3;"],
"StatementName": "test-redshift-serverless-workgroup-data",
"WithEvent": true
}
}
]
}
```
# Monitoreo de la API de datos
El monitoreo es una parte importante del mantenimiento de la fiabilidad, la disponibilidad y el rendimiento de la API de datos y de sus otras soluciones de AWS. AWS proporciona las siguientes herramientas de monitoreo para vigilar la API de datos, informar cuando algo va mal y realizar acciones de manera automática cuando sea necesario:
+ Amazon EventBridge puede utilizarse para automatizar los servicios de AWS y responder automáticamente a eventos del sistema, como problemas de disponibilidad de las aplicaciones o cambios en los recursos. Los eventos de los servicios de AWS se envían a EventBridge casi en tiempo real. Puede crear reglas sencillas para indicar qué eventos le resultan de interés, así como qué acciones automatizadas se van a realizar cuando un evento cumple una de las reglas. Para obtener más información, consulte la [Guía del usuario de Amazon EventBridge](https://docs.aws.amazon.com/eventbridge/latest/userguide/).
+ AWS CloudTrail captura llamadas a la API y eventos relacionados efectuados por su cuenta de AWS o en su nombre, y entrega los archivos de registro al bucket de Amazon S3 que se haya especificado. También puede identificar qué usuarios y cuentas llamaron a AWS, la dirección IP de origen de las llamadas y el momento en que se hicieron. Para obtener más información sobre cómo Amazon Redshift se integra con AWS CloudTrail, consulte [Registro con CloudTrail](https://docs.aws.amazon.com/redshift/latest/mgmt/logging-with-cloudtrail.html). Para obtener más información acerca de CloudTrail, consulte la [Guía del usuario de AWS CloudTrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/).
**Topics**
+ [Monitoreo de eventos para la API de datos de Amazon Redshift en Amazon EventBridge](data-api-monitoring-events.md)
# Monitoreo de eventos para la API de datos de Amazon Redshift en Amazon EventBridge
Puede monitorear los eventos de la API de datos en EventBridge, lo que envía un flujo de datos en tiempo real desde sus propias aplicaciones, aplicaciones de software como servicio (SaaS) y servicios de AWS. EventBridge dirige esos datos a los objetivos, como AWS Lambda y Amazon SNS. Estos eventos son los mismos que los que aparecen en CloudWatch Events, lo que proporciona un flujo de eventos del sistema casi en tiempo real que describen los cambios en los recursos de AWS. Los eventos se envían a la cuenta donde se encuentra la base de datos de Amazon Redshift. Por ejemplo, si se asume un rol en otra cuenta, los eventos se envían a esa cuenta. Para obtener más información, consulte los [Eventos de Amazon EventBridge](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-events.html) en la *Guía del usuario de Amazon EventBridge*.
Los eventos de la API de datos se envían cada vez que la operación `ExecuteStatement` o `BatchExecuteStatement` de la API establece la opción `WithEvent` como `true`. El campo `state` del evento contiene uno de los siguientes valores.
+ ABORTED: el usuario ha detenido la ejecución de la consulta.
+ FAILED: se produce un error en la ejecución de la consulta.
+ FINISHED: se completó la ejecución de la consulta.
Los eventos se entregan de forma garantizada. Para obtener más información, consulte [Eventos de servicios de AWS](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-service-event.html) en la *Guía del usuario de Amazon EventBridge*.
## Ejemplo de evento terminado de la API de datos
En el siguiente ejemplo, se muestra un evento de la API de datos en el momento en que la operación `ExecuteStatement` de la API se completa. En este ejemplo, una instrucción denominada `test.testtable` completó la ejecución.
```
{
"version": "0",
"id": "18e7079c-dd4b-dd64-caf9-e2a31640dab0",
"detail-type": "Redshift Data Statement Status Change",
"source": "aws.redshift-data",
"account": "123456789012",
"time": "2020-10-01T21:14:26Z",
"region": "us-east-1",
"resources": [
"arn:aws:redshift:us-east-1:123456789012:cluster:redshift-cluster-1"
],
"detail": {
"principal": "arn:aws:iam::123456789012:user/myuser",
"statementName": "test.testtable",
"statementId": "dd2e1ec9-2ee3-49a0-819f-905fa7d75a4a",
"redshiftQueryId": -1,
"state": "FINISHED",
"rows": 1,
"expireAt": 1601673265
}
}
```
# Uso de AWS KMS con la API de datos de Amazon Redshift
Al cifrar el clúster de Amazon Redshift o el grupo de trabajo sin servidor de Redshift con una clave administrada por el cliente, la API de datos de Amazon Redshift utiliza esa misma clave administrada por el cliente para almacenar y cifrar las consultas y los resultados.
La API de datos cifra los datos de forma predeterminada para proteger la información confidencial, como el texto y los resultados de las consultas. Utiliza claves de cifrado de AWS KMS que son propiedad de AWS para esta protección.
El cifrado predeterminado de los datos en reposo reduce la sobrecarga operativa y la complejidad al proteger la información confidencial. Este enfoque lo ayuda a crear aplicaciones seguras que cumplen con los estrictos requisitos normativos y de conformidad del cifrado.
## Uso de concesiones en AWS KMS
La API de datos requiere una concesión para utilizar la clave administrada por el cliente.
Cuando llama a `ExecuteStatement` o `BatchExecuteStatement` en contra de un clúster cifrado con una clave administrada por el cliente, Amazon Redshift crea una concesión en su nombre mediante el envío de una solicitud [https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html) a AWS KMS. AWS KMS usa concesiones para otorgar a la API de datos acceso a una clave de KMS en la cuenta.
La API de datos necesita la concesión para utilizar la clave administrada por el cliente para las siguientes operaciones:
+ Envíe solicitudes de [https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html) a AWS KMS para cifrar los metadatos de las consultas con la clave administrada por el cliente.
+ Envíe solicitudes de [https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) a AWS KMS para generar claves de datos cifradas por la clave administrada por el cliente.
+ Envíe solicitudes de [https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) a AWS KMS para descifrar las claves de datos cifradas, para que puedan cifrarse los datos.
Puede revocar el acceso a la concesión o eliminar el acceso de Amazon Redshift a la clave administrada por el cliente en cualquier momento. Si lo hace, la API de datos ya no puede acceder a datos cifrados por la clave administrada por el cliente, lo que afecta a las operaciones que dependan de esos datos. Por ejemplo, si intenta recuperar los resultados de una consulta o realizar un seguimiento del estado de la consulta después de revocar la concesión, la API de datos devuelve una `AccessDeniedException`.
## Políticas de claves para la clave administrada por el cliente
Las políticas de clave controlan el acceso a la clave administrada por el cliente. Cada clave administrada por el cliente debe tener exactamente una política de clave, que contiene instrucciones que determinan quién puede usar la clave y cómo puede utilizarla. Cuando crea la clave administrada por el cliente, puede especificar una política de clave. Para más información, consulte las [claves administradas por el cliente](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#customer-mgn-key) en la *Guía para desarrolladores de AWS Key Management Service*.
Para utilizar las claves administradas por el cliente con la API de datos, primero debe permitir el acceso a Amazon Redshift. Las operaciones de la API siguientes se deben permitir en la política de claves:
+ `kms:CreateGrant`: agrega una concesión a una clave administrada por el cliente. Concede acceso de control a una clave de AWS KMS especificada, lo que permite acceder a las operaciones de concesión que Amazon Redshift necesita. Para obtener más información, consulte [Uso de concesiones en AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/grants.html#terms-grant-operations).
A continuación, se muestra una política de claves de ejemplo:
```
"Statement":[
{
"Sid":"Allow access to principals authorized to use Amazon Redshift",
"Effect":"Allow",
"Principal":{
"AWS":"*"
},
"Action":[
"kms:DescribeKey",
"kms:CreateGrant"
],
"Resource":"*",
"Condition":{
"StringEquals":{
"kms:ViaService":"redshift.amazonaws.com",
"kms:CallerAccount":"111122223333"
}
}
},
{
"Sid":"AllowKeyAdministratorsAccess",
"Effect":"Allow",
"Principal":{
"AWS":"arn:aws:iam::111122223333:role/ExampleAdminRole"
},
"Action":"kms:*",
"Resource":"*"
},
{
"Sid":"AllowKeyUseForExampleRole",
"Effect":"Allow",
"Principal":{
"AWS":"arn:aws:iam::111122223333:role/ExampleUserRole"
},
"Action":[
"kms:Encrypt",
"kms:Decrypt",
"kms:ReEncrypt*",
"kms:GenerateDataKey*",
"kms:DescribeKey"
],
"Resource":"*"
}
]
```
## Contexto de cifrado de API de datos
Un contexto de cifrado es un conjunto de pares de valor de clave opcional que contiene información contextual adicional sobre los datos. AWS KMS utiliza el contexto de cifrado como datos autenticados adicionales para permitir el cifrado autenticado. Cuando se incluye un contexto de cifrado en una solicitud para cifrar datos, AWS KMS vincula el contexto de cifrado a los datos cifrados. Para descifrar los datos, debe incluir el mismo contexto de cifrado en la solicitud.
La API de datos utiliza los mismos tres pares clave-valor del contexto de cifrado en todas las operaciones criptográficas de AWS KMS de los clústeres aprovisionados:
+ `aws:redshift:arn`: el nombre de recurso de Amazon (ARN) del clúster
+ `aws:redshift:createtime`: la marca temporal en que solicitó la creación de un clúster
+ `serviceName` – `RedshiftDataAPI`
```
"EncryptionContextSubset": {
"aws:redshift:arn": "arn:aws:redshift:us-east-1:123456789012:cluster:redshift-cluster",
"aws:redshift:createtime": "20250815T0000Z",
"serviceName": "RedshiftDataAPI",
}
```
La API de datos utiliza dos pares clave-valor del contexto de cifrado en todas las operaciones criptográficas de AWS KMS de los grupos de trabajo sin servidor:
+ `aws:redshift-serverless:arn`: el nombre de recurso de Amazon (ARN) del espacio de nombres
+ `serviceName`: RedshiftDataAPI
```
"EncryptionContextSubset": {
"aws:redshift-serverless:arn": "arn:aws:redshift-serverless:us-east-1:123456789012:namespace:12345678-1234-1234-1234-123456789012",
"serviceName": "RedshiftDataAPI"
}
```
Para obtener más información sobre el cifrado, consulte [Introducción a los detalles criptográficos de AWS KMS](https://docs.aws.amazon.com/kms/latest/cryptographic-details/intro.html). Para obtener más información sobre Amazon Redshift y la integración de AWS KMS, consulte [Cómo Amazon Redshift utiliza AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/services-redshift.html).