O Amazon Redshift não permitirá mais a criação de UDFs do Python a partir do Patch 198. As UDFs do Python existentes continuarão a funcionar normalmente até 30 de junho de 2026. Para ter mais informações, consulte a [publicação de blog ](https://aws.amazon.com/blogs/big-data/amazon-redshift-python-user-defined-functions-will-reach-end-of-support-after-june-30-2026/).
# Usar a API de dados Amazon Redshift
A API de dados do Amazon Redshift simplifica o acesso ao data warehouse do Amazon Redshift, eliminando a necessidade de gerenciar drivers de banco de dados, conexões, configurações de rede, buffer de dados, credenciais e muito mais. É possível executar instruções SQL usando as operações da API de dados com o AWS SDK. Consulte mais informações sobre as operações da API de dados na [Referência da API de dados do Amazon Redshift](https://docs.aws.amazon.com/redshift-data/latest/APIReference/).
A API de dados não requer uma conexão persistente com o banco de dados. Em vez disso, ela oferece um endpoint HTTP seguro e uma integração com SDKs da AWS. Você pode usar o endpoint para executar instruções SQL sem gerenciar conexões. Chamadas para a API de dados são assíncronas. A API de dados pode usar as credenciais armazenadas no AWS Secrets Manager ou credenciais temporárias do banco de dados. Você não precisa passar senhas nas chamadas de API com nenhum dos métodos de autorização. Para obter informações sobre o AWS Secrets Manager, consulte [O que é AWS Secrets Manager?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) no *Manual do usuário do AWS Secrets Manager*. Também é possível usar o Centro de Identidade do AWS IAM para autorização.
Com a API de dados, você pode acessar programaticamente os dados do Amazon Redshift com aplicações baseadas em serviços da web, incluindo o AWS Lambda, cadernos do Amazon SageMaker AI e o AWS Cloud9. Para obter mais informações sobre essas aplicações, consulte [AWS Lambda](https://aws.amazon.com/lambda/), [Amazon SageMaker AI](https://aws.amazon.com/sagemaker/) e [AWS Cloud9](https://aws.amazon.com/cloud9/).
Para saber mais sobre a API de dados, consulte [Get started with the Amazon Redshift Data API](https://aws.amazon.com/blogs/big-data/get-started-with-the-amazon-redshift-data-api/) no *Blog de big data da AWS*.
## Trabalhar com a API de dados do Amazon Redshift
Antes de usar a API de dados do Amazon Redshift, revise as seguintes etapas:
1. Determine se você, como autor da chamada da API de dados, está autorizado. Para obter mais informações sobre a autorização da , consulte [Autorizar acesso à API de dados do Amazon Redshift](data-api-access.md).
1. Determine se você planeja chamar a API de dados com credenciais de autenticação do Secrets Manager, credenciais temporárias ou usar o Centro de Identidade do AWS IAM. Para obter mais informações, consulte [Escolher credenciais de autenticação de banco de dados ao chamar a API de dados do Amazon Redshift](#data-api-calling-considerations-authentication).
1. Configure um segredo se você usar o Secrets Manager para credenciais de autenticação. Para obter mais informações, consulte [Armazenar credenciais de banco de dados no AWS Secrets Manager](data-api-secrets.md).
1. Revise as considerações e limitações ao chamar a API de dados. Para obter mais informações, consulte [Considerações ao chamar a API de dados do Amazon Redshift](#data-api-calling-considerations).
1. Ligue para a API de dados a partir da AWS Command Line Interface(AWS CLI), a partir de seu próprio código ou usando o editor de consulta no console do Amazon Redshift. Para obter exemplos de chamadas a partir da AWS CLI, consulte[Chamar a API de dados](data-api-calling.md).
## Considerações ao chamar a API de dados do Amazon Redshift
Considere o seguinte ao chamar a API de dados:
+ A API de dados do Amazon Redshift pode acessar bancos de dados em clusters provisionados do Amazon Redshift e grupos de trabalho do Redshift sem servidor. Para obter uma lista de Regiões da AWS onde a API de dados do Redshift está disponível, consulte os endpoints listados para a [API de dados do Redshift](https://docs.aws.amazon.com/general/latest/gr/redshift-service.html) na *Referência geral da Amazon Web Services*.
+ A duração máxima de uma consulta é de 24 horas.
+ O número máximo de consultas ativas (`STARTED` e `SUBMITTED`) por cluster do Amazon Redshift é 500.
+ O tamanho máximo do resultado da consulta é 500 MB (após a compactação gzip). Se uma chamada retornar mais de 500 MB de dados de resposta, a chamada será encerrada.
+ O tempo máximo de retenção para resultados da consulta é de 24 horas.
+ O tamanho máximo da instrução de consulta é de 100 KB.
+ A API de dados está disponível para consultar clusters de nó único e de vários nós dos seguintes tipos de nó:
+ dc2.large
+ dc2.8xlarge
+ ra3.large
+ ra3.xlplus
+ ra3.4xlarge
+ ra3.16xlarge
+ O cluster deve estar em uma Virtual Private Cloud (VPC) baseada no serviço Amazon VPC.
+ Por padrão, os usuários com o mesmo perfil do IAM que o executor de uma operação de API `ExecuteStatement` ou `BatchExecuteStatement` podem agir em relação à mesma instrução com as operações de API `CancelStatement`, `DescribeStatement`, `GetStatementResult`, `GetStatementResultV2` e `ListStatements`. Para agir na mesma instrução SQL de outro usuário, o usuário deve ser capaz de assumir o perfil do IAM do usuário que executou a instrução SQL. Para obter mais informações sobre como assumir uma função, consulte [Autorizar acesso à API de dados do Amazon Redshift](data-api-access.md).
+ As instruções SQL no parâmetro `Sqls` da operação da API `BatchExecuteStatement` são executadas como uma única transação. Eles são executados em série na ordem da matriz. As instruções SQL subsequentes não são iniciadas enquanto a instrução anterior na matriz não for concluída. Se alguma instrução SQL falhar, como ela é executada como uma transação, todo o trabalho será revertido.
+ O tempo máximo de retenção de um token de cliente usado na operação de API `ExecuteStatement` ou `BatchExecuteStatement` é de 8 horas.
+ Se os clusters provisionados pelo Amazon Redshift e o grupo de trabalho Redshift sem servidor forem criptografados usando uma chave gerenciada pelo cliente, o Redshift criará uma concessão que permite que a API de dados do Redshift use a chave em suas operações. Para obter mais informações, consulte [Usar o AWS KMS com a API de dados do Amazon Redshift](data-api-kms.md).
+ Cada API na API do Redshift Data tem uma cota de transações por segundo antes do controle de utilização das solicitações. Para a cota, consulte [Cotas da API de dados do Amazon Redshift](amazon-redshift-limits.md#data-api-quotas-account). Se a taxa de solicitação exceder a cota, um `ThrottlingException` com o código de status HTTP: 400 será retornado. Para responder ao controle de utilização, use uma estratégia de repetição conforme descrito em [Comportamento de nova tentativa](https://docs.aws.amazon.com/sdkref/latest/guide/feature-retry-behavior.html) no *Guia de referência de SDKs e ferramentas da AWS*. Essa estratégia é implementada automaticamente para erros no controle de utilização em alguns SDKs da AWS.
**nota**
Por padrão, no AWS Step Functions, as novas tentativas não permanecem habilitadas. Se você precisar chamar uma API do Redshift Data em uma máquina de estado Step Functions, inclua o parâmetro de idempotência `ClientToken` na chamada de API do Redshift Data. O valor de `ClientToken` precisa persistir entre as novas tentativas. No trecho de exemplo a seguir de uma solicitação para a API `ExecuteStatement`, a expressão `States.ArrayGetItem(States.StringSplit($$.Execution.Id, ':'), 7)` usa uma função intrínseca para extrair a parte UUID de `$$.Execution.Id`, que é exclusiva de cada execução da máquina de estado. Para obter mais informações, consulte [Intrinsic functions](https://docs.aws.amazon.com/step-functions/latest/dg/amazon-states-language-intrinsic-functions.html) no *Guia de desenvolvedor do AWS Step Functions*.
```
{
"Database": "dev",
"Sql": "select 1;",
"ClusterIdentifier": "MyCluster",
"ClientToken.$": "States.ArrayGetItem(States.StringSplit($$.Execution.Id, ':'), 7)"
}
```
## Escolher credenciais de autenticação de banco de dados ao chamar a API de dados do Amazon Redshift
Quando você chama a API de dados, você usa um dos métodos de autenticação a seguir para algumas operações de API. Cada método requer uma combinação diferente de parâmetros.
**Centro de Identidade do AWS IAM**
A API de dados pode ser acessada com um usuário de autenticação única registrado no Centro de Identidade do AWS IAM. Para ter informações sobre as etapas para configurar o Centro de Identidade do IAM, consulte [Usar a API de dados com propagação de identidade confiável](data-api-trusted-identity-propagation.md).
**AWS Secrets Manager**
Com esse método, forneça o `secret-arn` de um segredo armazenado no AWS Secrets Manager que tenha `username` e `password`. O segredo especificado contém credenciais para se conectar ao `database` que você especificar. Quando está se conectando a um cluster, você também fornece o nome do banco de dados. Se você fornecer um identificador do cluster (`dbClusterIdentifier`), ele deverá corresponder ao identificar de cluster armazenado no segredo. Ao se conectar a um grupo de trabalho com a tecnologia sem servidor, você também fornece o nome do banco de dados. Para obter mais informações, consulte [Armazenar credenciais de banco de dados no AWS Secrets Manager](data-api-secrets.md).
Com esse método, também é possível fornecer um valor `region` que especifica a Região da AWS onde os dados estão localizados.
**Credenciais temporárias**
Com esse método, escolha uma das seguintes opções:
+ Ao se conectar a um grupo de trabalho com tecnologia sem servidor, especifique o nome do grupo de trabalho e o nome do banco de dados. O nome de usuário do banco de dados é derivado da identidade do IAM. Por exemplo, `arn:iam::123456789012:user:foo` tem o nome de usuário de banco de dados `IAM:foo`. Além disso, é necessário ter uma permissão para chamar a operação `redshift-serverless:GetCredentials`.
+ Ao se conectar a um cluster como uma identidade do IAM, especifique o identificador do cluster e o nome do banco de dados. O nome de usuário do banco de dados é derivado da identidade do IAM. Por exemplo, `arn:iam::123456789012:user:foo` tem o nome de usuário de banco de dados `IAM:foo`. Além disso, é necessário ter uma permissão para chamar a operação `redshift:GetClusterCredentialsWithIAM`.
+ Ao se conectar a um cluster como um usuário do banco de dados, especifique o identificador do cluster, o nome do banco de dados e o nome de usuário do banco de dados. Além disso, é necessário ter uma permissão para chamar a operação `redshift:GetClusterCredentials`. Para obter informações sobre como ingressar em grupos de banco de dados ao se conectar com esse método, consulte [Unir grupos de banco de dados ao se conectar a um cluster](data-api-dbgroups.md).
Com esse método, também é possível fornecer um valor `region` que especifica a Região da AWS onde os dados estão localizados.
## Mapear tipos de dados JDBC ao chamar a API de dados do Amazon Redshift
A tabela a seguir mapeia tipos de dados Java Database Connectivity (JDBC) para os tipos de dados especificados nas chamadas da API Data.
****
| Tipo de dados JDBC | Tipo de dados da API de dados |
| --- | --- |
| `INTEGER, SMALLINT, BIGINT` | `LONG` |
| `FLOAT, REAL, DOUBLE` | `DOUBLE` |
| `DECIMAL` | `STRING` |
| `BOOLEAN, BIT` | `BOOLEAN` |
| `BLOB, BINARY, LONGVARBINARY` | `BLOB` |
| `VARBINARY` | `STRING` |
| `CLOB` | `STRING` |
| Outros tipos (incluindo tipos relacionados a data e hora) | `STRING` |
Os valores de string são passados ao banco de dados do Amazon Redshift e convertidos implicitamente em um tipo de dados de banco de dados.
**nota**
Atualmente, a API de dados não oferece suporte a arrays de identificadores exclusivos universais (UUIDs).
## Executar instruções SQL com parâmetros ao chamar a API de dados do Amazon Redshift
Você pode controlar o texto SQL submetido ao mecanismo de banco de dados chamando a operação API de dados usando parâmetros para partes da instrução SQL. Parâmetros nomeados fornecem uma maneira flexível de transmitir parâmetros sem codificá-los no texto SQL. Eles ajudam você a reutilizar o texto SQL e evitar problemas de injeção SQL.
O exemplo a seguir mostra os parâmetros nomeados de um campo `parameters` de um comando `execute-statement` da AWS CLI.
```
--parameters "[{\"name\": \"id\", \"value\": \"1\"},{\"name\": \"address\", \"value\": \"Seattle\"}]"
```
Considere o seguinte ao usar parâmetros nomeados:
+ Parâmetros nomeados só podem ser usados para substituir valores em instruções SQL.
+ Você pode substituir os valores em uma instrução INSERT, como `INSERT INTO mytable VALUES(:val1)`.
Os parâmetros nomeados podem estar em qualquer ordem e os parâmetros podem ser usados mais de uma vez no texto SQL. Na opção de parâmetros mostrada em um exemplo anterior, os valores `1` e `Seattle` são inseridos nas colunas da tabela `id` e `address`. No texto SQL, você especifica os parâmetros nomeados da seguinte forma:
```
--sql "insert into mytable values (:id, :address)"
```
+ Você pode substituir os valores em uma cláusula de condições, como `WHERE attr >= :val1`, `WHERE attr BETWEEN :val1 AND :val2` e `HAVING COUNT(attr) > :val`.
+ Você não pode substituir nomes de colunas em uma instrução SQL, como `SELECT column-name`, `ORDER BY column-name` ou `GROUP BY column-name`.
Por exemplo, a instrução SELECT a seguir falha com sintaxe inválida.
```
--sql "SELECT :colname, FROM event" --parameters "[{\"name\": \"colname\", \"value\": \"eventname\"}]"
```
Se você descrever (operação `describe-statement`) a instrução com o erro de sintaxe, a `QueryString` retornada não substituirá o nome da coluna pelo parâmetro (`"QueryString": "SELECT :colname, FROM event"`) e um erro será relatado (ERRO: erro de sintaxe em ou próximo a \$1"FROM\$1"\$1n Posição: 12).
+ Não é possível substituir nomes de colunas em uma função agregada, como `COUNT(column-name)`, `AVG(column-name)` ou `SUM(column-name)`.
+ Não é possível substituir nomes de colunas em uma cláusula JOIN.
+ Quando o SQL é executado, os dados são implicitamente convertidos em um tipo de dados. Para obter mais informações sobre a conversão do tipo de dados do, consulte [Tipos de dados](https://docs.aws.amazon.com/redshift/latest/dg/c_Supported_data_types.html) no *Guia do desenvolvedor de banco de dados do Amazon Redshift*.
+ Não é possível definir um valor como NULL. A API de dados a interpreta como a string literal `NULL`. O exemplo a seguir substitui `id` com a string literal `null`. Não o valor NULL SQL.
```
--parameters "[{\"name\": \"id\", \"value\": \"null\"}]"
```
+ Não é possível definir um valor de comprimento zero. Falha na instrução SQL da API de dados. O exemplo a seguir tenta definir `id` com um valor de comprimento zero e resulta em uma falha da instrução SQL.
```
--parameters "[{\"name\": \"id\", \"value\": \"\"}]"
```
+ Você não pode definir um nome de tabela na instrução SQL com um parâmetro. A API de dados segue a regra do JDBC `PreparedStatement`.
+ A saída da operação `describe-statement` retorna os parâmetros de consulta de uma instrução SQL.
+ Somente a operação `execute-statement` suporta instruções SQL com parâmetros.
## Executar instruções SQL com um token de idempotência ao chamar a API de dados do Amazon Redshift
Quando você faz uma solicitação de API de mutação, a solicitação normalmente retorna um resultado antes da conclusão dos fluxos de trabalho assíncronos da operação. As operações também podem expirar ou encontrar outros problemas no servidor antes de serem concluídas, mesmo que a solicitação já tenha retornado um resultado. Isso pode dificultar na hora de determinar se a solicitação foi bem-sucedida ou não, e pode levar a várias novas tentativas para garantir que a operação seja concluída com êxito. No entanto, se a solicitação original e as tentativas subsequentes forem bem-sucedidas, a operação será concluída várias vezes. Isso significa que você pode atualizar mais recursos do que pretendia.
A *idempotência* garante que uma solicitação de API seja concluída no máximo uma vez. Com uma solicitação idempotente, se a solicitação original for concluída com êxito, todas as novas tentativas subsequentes serão concluídas com êxito sem realizar nenhuma ação. As operações `ExecuteStatement` e `BatchExecuteStatement` da API de dados têm um parâmetro idempotente `ClientToken` opcional. O `ClientToken` expira após 8 horas.
**Importante**
Se você chamar as operações `ExecuteStatement` e `BatchExecuteStatement` usando um AWS SDK, um token de cliente será gerado automaticamente para ser usado em uma nova tentativa. Nesse caso, não recomendamos usar o parâmetro `client-token` com as operações `ExecuteStatement` e `BatchExecuteStatement`. Veja o log do CloudTrail para ver o `ClientToken`. Para obter um exemplo de log do CloudTrail, consulte [Exemplos de API de dados do Amazon Redshift](logging-with-cloudtrail.md#data-api-cloudtrail).
O comando `execute-statement` da AWS CLI a seguir ilustra o parâmetro `client-token` opcional para idempotência.
```
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 tabela a seguir mostra algumas respostas comuns que você pode obter para solicitações de API idempotentes e fornece recomendações para novas tentativas.
| Resposta | Recomendação | Comentários |
| --- | --- | --- |
| 200 (OK) | Não repetir | A solicitação original foi concluída com êxito. Qualquer repetição subsequente é retornada com êxito. |
| Códigos de resposta da série 400 | Não repetir | Há um dos seguintes problemas com a solicitação: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/redshift/latest/mgmt/data-api.html) Se a solicitação envolver um recurso em processo de mudança de estado, a repetição da solicitação poderá ser bem-sucedida. |
| Códigos de resposta da série 500 | Tentar novamente | O erro é causado por um problema no servidor da AWS e geralmente é transitório. Repita a solicitação com uma estratégia de recuo apropriada. |
Para obter informações sobre os códigos de resposta do Amazon Redshift, consulte [Erros comuns](https://docs.aws.amazon.com/redshift/latest/APIReference/CommonErrors.html) na *Referência de API do Amazon Redshift*.
## Executar instruções SQL com reutilização de sessão ao chamar a API de dados do Amazon Redshift
Quando você faz uma solicitação de API para executar uma instrução SQL, a sessão em que o SQL é executado geralmente é encerrada quando o SQL é concluído. Para manter a sessão ativa durante determinado número de segundos, as operações `ExecuteStatement` e `BatchExecuteStatement` da API de dados têm um parâmetro `SessionKeepAliveSeconds` opcional. Um campo de resposta `SessionId` contém a identidade da sessão, que pode ser usada nas operações `BatchExecuteStatement` e `ExecuteStatement` subsequentes. Nas chamadas subsequentes, você pode especificar outra `SessionKeepAliveSeconds` para alterar o tempo limite de inatividade. Se `SessionKeepAliveSeconds` não for alterada, a configuração inicial de tempo limite de inatividade permanecerá. Considere o seguinte ao usar a reutilização de sessão:
+ O valor máximo de `SessionKeepAliveSeconds` é 24 horas.
+ A sessão pode durar no máximo 24 horas. Após 24 horas, a sessão é encerrada à força e as consultas em andamento são encerradas.
+ O número máximo de sessões por cluster do Amazon Redshift ou grupo de trabalho do Redshift sem servidor é 500.
+ Você só pode executar uma consulta por vez em uma sessão. É necessário esperar a conclusão da consulta para executar a próxima consulta na mesma sessão. Ou seja, não é possível executar consultas paralelamente em uma sessão fornecida.
+ A API de dados não pode colocar consultas em fila para determinada sessão.
Para recuperar o `SessionId` que é usado por chamadas às operações `ExecuteStatement` e `BatchExecuteStatement`, chame as operações `DescribeStatement` e `ListStatements`.
O exemplo a seguir demonstra o uso dos parâmetros `SessionId` e `SessionKeepAliveSeconds` para manter uma sessão ativa e reutilizada. Primeiro, chame o comando `execute-statement` da AWS CLI com o parâmetro opcional `session-keep-alive-seconds` definido como `2`.
```
aws redshift-data execute-statement
--session-keep-alive-seconds 2
--sql "select 1"
--database dev
--workgroup-name mywg
```
A resposta contém o identificador da sessão.
```
{
"WorkgroupName": "mywg",
"CreatedAt": 1703022996.436,
"Database": "dev",
"DbUser": "awsuser",
"Id": "07c5ffea-76d6-4786-b62c-4fe3ef529680",
"SessionId": "5a254dc6-4fc2-4203-87a8-551155432ee4"
}
```
Em seguida, chame o comando `execute-statement` da AWS CLI com o `SessionId` apresentado na primeira chamada. E, opcionalmente, especifique o parâmetro `session-keep-alive-seconds` definido como `10` para alterar o valor do tempo limite de inatividade.
```
aws redshift-data execute-statement
--sql "select 1"
--session-id 5a254dc6-4fc2-4203-87a8-551155432ee4
--session-keep-alive-seconds 10
```
## Buscar os resultados de instruções SQL
Você usa diferentes operações da API de dados para buscar resultados SQL, dependendo do formato do resultado. Ao chamar as operações `ExecuteStatement` e `BatchExecuteStatement`, você pode especificar se os resultados serão formatados como JSON ou CSV. Se você não especificar, o padrão será JSON. Para obter resultados JSON, use a operação `GetStatementResult`. Para obter resultados CSV, use a operação `GetStatementResultV2`.
Os resultados gerados no formato JSON são registros que incluem metadados sobre cada coluna. Cada registro está no formato JSON. Por exemplo, a resposta de `GetStatementResult` é semelhante a esta:
```
{
"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":
}
```
Os resultados gerados no formato CSV são registros que incluem metadados sobre cada coluna. Os resultados são gerados em blocos de 1 MB, em que cada bloco pode armazenar qualquer número de linhas no formato CSV. Cada solicitação gera até 15 MB de resultados. Se os resultados tiverem mais de 15 MB, um token de próxima página será exibido para continuar a recuperar os resultados. Por exemplo, a resposta de `GetStatementResultV2` é semelhante a esta:
```
{
"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":
}
```
# Autorizar acesso à API de dados do Amazon Redshift
Para acessar a API de dados, um usuário deve ser autorizado. Você pode autorizar um usuário a acessar a API de dados adicionando uma política gerenciada, que é uma política do AWS Identity and Access Management (IAM) predefinida para esse usuário. Como prática recomendada, anexe políticas de permissões a um perfil do IAM e, depois, atribua-as a usuários e grupos, conforme necessário. Para obter mais informações, consulte [Gerenciamento de identidade e acesso no Amazon Redshift](https://docs.aws.amazon.com/redshift/latest/mgmt/redshift-iam-authentication-access-control.html). Para ver as permissões permitidas e negadas pelas políticas gerenciadas, consulte o console do IAM ([https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)).
# Configurar permissões do IAM
O Amazon Redshift fornece a política gerenciada `AmazonRedshiftDataFullAccess`. Esta política fornece acesso total às operações da API de dados do Amazon Redshift. Esta política também permite acesso com escopo específico ao Amazon Redshift, ao AWS Secrets Manager e às operações de API do IAM necessárias para autenticar e acessar um cluster do Amazon Redshift ou um grupo de trabalho do Redshift sem servidor.
Você também pode criar sua própria política do IAM que permite acesso a recursos específicos. Para criar sua política, use a política `AmazonRedshiftDataFullAccess` como seu modelo inicial. Depois de criar sua política, adicione-a a cada usuário que requer acesso à API de dados.
Considere os seguintes requisitos da política do IAM associada ao usuário:
+ Se você usar o AWS Secrets Manager para autenticar, confirme se a política permite o uso da ação `secretsmanager:GetSecretValue` para recuperar o segredo marcado com a chave `RedshiftDataFullAccess`.
+ Se você usar credenciais temporárias a fim de autenticar em um cluster, confirme se a política permitirá o uso da ação `redshift:GetClusterCredentials` para o nome do usuário do banco de dados `redshift_data_api_user` a qualquer banco de dados no cluster. Esse nome de usuário já deve ter sido criado no banco de dados.
+ Se você usar credenciais temporárias para autenticar em um grupo de trabalho com a tecnologia sem servidor, confirme se a política permite o uso da ação `redshift-serverless:GetCredentials` para recuperar o grupo de trabalho marcado com a chave `RedshiftDataFullAccess`. O usuário do banco de dados é mapeado 1:1 para a identidade de origem do AWS Identity and Access Management (IAM). Por exemplo, o usuário usuário\$1amostra é mapeado para o usuário do banco de dados `IAM:sample_user` e o perfil do IAM perfil\$1amostra é mapeado para `IAMR:sample_role`. Para obter mais informações sobre as identidades do IAM, consulte [Identidades do IAM (usuários, grupos de usuários e perfis)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id.html) no Guia do usuário do IAM.
+ A ação `redshift-data:GetStatementResult` do IAM permite acesso às operações de API `GetStatementResult` e `GetStatementResultV2`.
Os links a seguir fornecem informações adicionais sobre o AWS Identity and Access Management no *Manual do usuário do IAM*.
+ Para obter informações sobre como criar funções de IAM, consulte [Criar funções do IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create.html).
+ Para obter informações sobre como criar uma política do IAM, consulte [Criar políticas do IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html).
+ Para obter informações sobre como adicionar uma política do IAM a um usuário, consulte [Adicionando e removendo permissões de identidade do IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html).
## Executar uma consulta em um cluster pertencente a outra conta
Para executar uma consulta em um cluster que pertence a outra conta, a conta proprietária deve fornecer uma função do IAM que a API de dados pode assumir na conta de chamada. Por exemplo, suponha que a Conta B possui um cluster que a Conta A precisa acessar. A conta B pode anexar a política `AmazonRedshiftDataFullAccess` gerenciada pela AWS ao perfil do IAM da conta B. Em seguida, a Conta B confia na Conta A utilizando uma política fidedigna como a seguinte: :``
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": [
"arn:aws:iam::111122223333:role/someRoleA"
]
},
"Action": "sts:AssumeRole"
}
]
}
```
------
Finalmente, a função do IAM da conta A precisa ser capaz de assumir a função do IAM da conta B.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": "sts:AssumeRole",
"Resource": "arn:aws:iam::111122223333:role/someRoleB"
}
}
```
------
## Especificar um perfil do IAM que restrinja recursos aos grupos de trabalho do Redshift sem servidor e aos clusters do Amazon Redshift em uma Conta da AWS
É possível especificar ARNs de recursos em sua política baseada em identidade para controlar o acesso aos grupos de trabalho do Redshift sem servidor e clusters do Amazon Redshift em uma Conta da AWS. Este exemplo mostra como você pode criar uma política que permita acesso à API de dados somente ao grupo de trabalho e aos clusters na Conta da 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:*"
]
}
]
}
```
------
## Configurar uma política do IAM que permita que somente o proprietário da instrução tenha acesso às informações da instrução SQL
Por padrão, a API de dados do Amazon Redshift trata o perfil do IAM usado ao chamar `ExecuteStatement` e `BatchExecuteStatement` como proprietário da instrução SQL. Qualquer pessoa autorizada a assumir o perfil pode acessar informações da instrução SQL, bem como os respectivos resultados. Para restringir o acesso às informações da instrução SQL a uma sessão do perfil do IAM com um proprietário específico, adicione uma condição `redshift-data:statement-owner-iam-userid: "${aws:userid}"`. A política do IAM a seguir restringe o acesso.
------
#### [ 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}"
}
}
}
]
}
```
------
É possível usar a condição `statement-owner-iam-userid` com `CancelStatement`, `DescribeStatement`, `GetStatementResult` e `ListStatements`. Para obter mais informações, consulte [Actions defined by Amazon Redshift Data API](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonredshiftdataapi.html#amazonredshiftdataapi-redshift-data_statement-owner-iam-userid).
## Configurar uma política do IAM que permita que somente o proprietário da sessão tenha acesso aos resultados SQL
Por padrão, a API de dados do Amazon Redshift trata o perfil do IAM usado ao chamar `ExecuteStatement` e `BatchExecuteStatement` como o proprietário da instrução SQL que executa a instrução SQL. Qualquer pessoa autorizada a assumir o perfil pode enviar consultas à sessão do banco de dados. Para restringir o acesso a uma sessão do perfil do IAM com um proprietário específico, adicione a condição ` redshift-data:session-owner-iam-userid: "${aws:userid}"`. A política do IAM a seguir restringe o acesso.
A política do IAM a seguir permite que somente o proprietário da sessão obtenha os resultados da instrução. A condição `session-owner-iam-userid` é usada para permitir o acesso a recursos somente ao `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}"
}
}
}
]
}
```
------
É possível usar a condição `session-owner-iam-userid` com `ExecuteStatement` e `BatchExecuteStatement`. Para obter mais informações, consulte [Actions defined by Amazon Redshift Data API](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonredshiftdataapi.html#amazonredshiftdataapi-redshift-data_statement-owner-iam-userid).
# Armazenar credenciais de banco de dados no AWS Secrets Manager
Ao chamar a API de dados, você pode passar credenciais para o cluster ou um grupo de trabalho com a tecnologia sem servidor usando um segredo no AWS Secrets Manager. Para passar credenciais dessa maneira, especifique o nome do segredo ou o nome de recurso da Amazon (ARN) do segredo.
Para armazenar credenciais com o Secrets Manager, você precisa da permissão de política gerenciada `SecretManagerReadWrite`. Para obter mais informações sobre as permissões mínimas, consulte [Criar e gerenciar segredos com o AWSSecrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/managing-secrets.html) no *Manual do usuário do AWS Secrets Manager*.
**Para armazenar suas credenciais em um segredo para um cluster do Amazon Redshift**
1. Use o console do AWS Secrets Manager a fim de criar um segredo que contenha credenciais para o cluster:
+ Quando você escolher **Armazenar um novo segredo**, escolha **Credenciais do cluster Redshift**.
+ Armazene seus valores para **Nome de usuário** (usuário do banco de dados), **Senha** e**Cluster de banco de dados** (identificador de cluster) em seu segredo.
+ Etiquete o segredo com a chave `RedshiftDataFullAccess`. A política `AmazonRedshiftDataFullAccess` gerenciada pela AWS permite apenas a ação `secretsmanager:GetSecretValue` para segredos marcados com a chave `RedshiftDataFullAccess`.
Para obter instruções, consulte [Criar um segredo básico](https://docs.aws.amazon.com/secretsmanager/latest/userguide/manage_create-basic-secret.html) no *Manual do usuário do AWS Secrets Manager*.
1. Use o console do AWS Secrets Manager para visualizar os detalhes do segredo criado ou execute o comando `aws secretsmanager describe-secret` da AWS CLI.
Anote o nome e o ARN do segredo. Você pode usá-los em chamadas para a API de dados.
**Para armazenar suas credenciais em um segredo para um grupo de trabalho com a tecnologia sem servidor**
1. Use os comandos da AWS CLI do AWS Secrets Manager para armazenar um segredo que contenha as credenciais para o grupo de trabalho com a tecnologia sem servidor:
+ Crie o segredo em um arquivo, por exemplo, um arquivo JSON denominado `mycreds.json`. Forneça os valores para **User name** (Nome de usuário) (usuário do banco de dados) e **Password** (Senha) no arquivo.
```
{
"username": "myusername",
"password": "mypassword"
}
```
+ Armazene seus valores no segredo e marque-o com a chave `RedshiftDataFullAccess`.
```
aws secretsmanager create-secret --name MyRedshiftSecret --tags Key="RedshiftDataFullAccess",Value="serverless" --secret-string file://mycreds.json
```
A seguir, é mostrada a saída.
```
{
"ARN": "arn:aws:secretsmanager:region:accountId:secret:MyRedshiftSecret-mvLHxf",
"Name": "MyRedshiftSecret",
"VersionId": "a1603925-e8ea-4739-9ae9-e509eEXAMPLE"
}
```
Para obter mais informações, consulte [Criar um segredo básico com a AWS CLI](https://docs.aws.amazon.com/secretsmanager/latest/userguide/manage_create-basic-secret.html#proc-create-api) no *Guia do usuário do AWS Secrets Manager*.
1. Use o console do AWS Secrets Manager para visualizar os detalhes do segredo criado ou execute o comando `aws secretsmanager describe-secret` da AWS CLI.
Anote o nome e o ARN do segredo. Você pode usá-los em chamadas para a API de dados.
# Criar um endpoint da Amazon VPC (AWS PrivateLink) para a API de dados
O Amazon Virtual Private Cloud (Amazon VPC) permite que você inicie recursos da AWS, como clusters e aplicações do Amazon Redshift, em uma nuvem privada virtual (VPC). O AWS PrivateLink fornece conectividade privada entre nuvens privadas virtuais (VPCs) e serviços da AWS com segurança na rede Amazon. Usando AWS PrivateLink, você pode criar endpoints da VPC, que você pode usar para se conectar a serviços em diferentes contas e VPCs com base no Amazon VPC. Para obter mais informações sobre AWS PrivateLink, consulte [Serviços de endpoint da VPC (AWS PrivateLink)](https://docs.aws.amazon.com/vpc/latest/userguide/endpoint-service.html) no *Manual do usuário do Amazon Virtual Private Cloud*.
Você pode chamar a API de dados com endpoints da Amazon VPC. O uso de um endpoint da Amazon VPC mantém o tráfego entre aplicações em sua Amazon VPC e a API de dados na AWS sem usar endereços IP públicos. Os endpoints do Amazon VPC podem ajudá-lo a atender aos requisitos normativos e de compatibilidade relacionados à limitação da conectividade pública com a Internet. Por exemplo, ao usar um endpoint da Amazon VPC, você pode manter o tráfego entre uma aplicação em execução em uma instância do Amazon EC2 e a API de dados nas VPCs que API contêm.
Depois de criar o Amazon VPC endpoint, você pode começar a usá-lo sem fazer alterações no código ou na configuração de sua aplicação.
**Como criar um Amazon VPC endpoint para a API de dados**
1. Faça login no Console de gerenciamento da AWS e abra o console da Amazon VPC em [https://console.aws.amazon.com/vpc/](https://console.aws.amazon.com/vpc/).
1. Escolha **Endpoints** e **Create Endpoint (Criar endpoint)**.
1. Na página **Criar endpoint**, para a **Categoria de serviço**, escolha **Serviços da AWS**. Para o **Nome do serviço**, escolha **redshift-data** (`com.amazonaws.region.redshift-data`).
1. Em **VPC**, escolha a VPC na qual criar o endpoint.
Escolha a VPC que contém a aplicação que faz chamadas da API de dados.
1. Em **Sub-redes**, escolha a sub-rede de cada zona de disponibilidade (AZ) usada pelo serviço da AWS que está executando a aplicação.
Para criar um endpoint do Amazon VPC, especifique o intervalo de endereços IP privados no qual o endpoint está acessível. Para fazer isso, escolha a sub-rede de cada zona de disponibilidade. Isso restringe o VPC endpoint ao intervalo de endereços IP privados específico para cada zona de disponibilidade e também cria um Amazon VPC endpoint em cada zona de disponibilidade.
1. Em **Enable DNS Name (Habilitar nome DNS)**, selecione **Enable for this endpoint (Habilitar para este endpoint)**.
O DNS privado resolve o nome de host DNS da API de dados padrão (`https://redshift-data.region.amazonaws.com`) para os endereços IP privados associados ao nome de host DNS específico a seu Amazon VPC endpoint. Como resultado, é possível acessar o endpoint da VPC endpoint da API de dados usando a AWS CLI ou os SDKs da AWS sem fazer alterações no código ou na configuração para atualizar o URL do endpoint da API de dados.
1. Em **Security group (Grupo de segurança)**, escolha um grupo de segurança para associar ao Amazon VPC endpoint.
Escolha o grupo de segurança que permite o acesso ao serviço da AWS que está executando sua aplicação. Por exemplo, se uma instância do Amazon EC2 estiver executando sua aplicação, escolha o grupo de segurança que permite o acesso à instância do Amazon EC2. O grupo de segurança permite que você controle o tráfego para o Amazon VPC endpoint nos recursos em sua VPC.
1. Escolha **Create endpoint (Criar endpoint)**.
Depois que o endpoint for criado, escolha o link no Console de gerenciamento da AWS para visualizar os detalhes do endpoint.
A guia **Details (Detalhes)** do endpoint mostra os nomes de host de DNS que foram gerados durante a criação do Amazon VPC endpoint.
Você pode usar o endpoint padrão (`redshift-data.region.amazonaws.com`) ou um dos endpoints específicos da VPC para chamar a API de dados dentro da Amazon VPC. O endpoint padrão da API de dados roteia automaticamente para o Amazon VPC endpoint. Esse roteamento ocorre porque o nome de host DNS privado foi habilitado quando o Amazon VPC endpoint foi criado.
Quando você usa um Amazon VPC endpoint em uma chamada da API de dados, todo tráfego entre sua aplicação e a API de dados permanece nas Amazon VPCs que o contêm. Você pode usar um Amazon VPC endpoint para qualquer tipo de chamada da API de dados. Para obter informações sobre como chamar a API de dados, consulte [Considerações ao chamar a API de dados do Amazon Redshift](data-api.md#data-api-calling-considerations).
# Unir grupos de banco de dados ao se conectar a um cluster
Grupos de banco de dados são coleções de usuários do banco de dados. Os privilégios do banco de dados podem ser concedidos a grupos. Um administrador pode configurar um perfil do IAM de forma que esses grupos de banco de dados sejam levados em consideração quando o SQL for executado com a API de dados. Para obter informações sobre grupos de banco de dados, consulte [Grupos](https://docs.aws.amazon.com/redshift/latest/dg/r_Groups.html) no *Guia do desenvolvedor de banco de dados do Amazon Redshift*.
É possível configurar o perfil do IAM de um chamador da API de dados para que o usuário do banco de dados especificado na chamada se junte a grupos de banco de dados quando a API de dados se conectar a um cluster. Esse recurso só é compatível com a conexão com clusters provisionados. Não é compatível com a conexão com grupos de trabalho do Redshift sem servidor. O perfil do IAM do chamador da API de dados também deve permitir a ação `redshift:JoinGroup`.
Configure isso adicionando tags aos perfis do IAM. O administrador do perfil do IAM do chamador adiciona tags com a chave `RedshiftDbGroups` e um valor de chave de uma lista de grupos de banco de dados. O valor é uma lista de nomes separados por dois-pontos (:) de grupos de banco de dados com uma extensão total de até 256 caracteres. Os grupos do banco de dados devem ser definidos previamente no banco de dados conectado. Se algum grupo especificado não for encontrado no banco de dados, ele será ignorado. Por exemplo, para grupos de banco de dados `accounting` e `retail`, o valor da chave é `accounting:retail`. O par chave-valor da tag `{"Key":"RedshiftDbGroups","Value":"accounting:retail"}` é usado pela API de dados para determinar quais grupos de banco de dados estão associados ao usuário do banco de dados fornecido na chamada para a API de dados.
**Como unir grupos de banco de dados**
1. Faça login no Console de gerenciamento da AWS e abra o console do IAM em [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).
1. No painel de navegação do console, escolha **Roles (Funções)** e, em seguida, escolha o nome da função que deseja editar.
1. Escolha a guia **Tags** e **Gerenciar tags**.
1. Escolha **Adicionar tag** e adicione a chave **RedshiftDbGroups** e um valor que é uma lista de *database-groups-colon-separated*.
1. Escolha **Salvar alterações**.
Agora, quando uma entidade principal do IAM (com esse perfil do IAM anexado) chama a API de dados, o usuário do banco de dados especificado se junta aos grupos de banco de dados especificados no perfil do IAM.
Para obter mais informações sobre como anexar uma etiqueta a uma entidade principal, inclusive funções do IAM e usuários do IAM, consulte [Recursos de etiquetas do IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_tags.html) no *Guia do usuário do IAM*.
# Usar a API de dados com propagação de identidade confiável
Como administrador de contas do Amazon Redshift, você pode integrar o cluster ou o grupo de trabalho do Amazon Redshift ao Centro de Identidade do AWS IAM, o que ajuda a gerenciar o acesso do quadro de funcionários ao Amazon Redshift com autenticação única. Para obter mais informações, consulte [Configuração da integração do Centro de Identidade do AWS IAM com o Amazon Redshift](redshift-iam-access-control-idp-connect-console.md). A API de dados do Amazon Redshift comporta a propagação de identidades de usuário do Centro de Identidade do IAM para um cluster ou um grupo de trabalho do Amazon Redshift e para outros serviços, como o AWS Lake Formation, ao longo da cadeia. É possível configurar e consultar usando a API de dados seguindo as etapas em [Access AWS services programmatically using trusted identity propagation](https://aws.amazon.com/blogs//security/access-aws-services-programmatically-using-trusted-identity-propagation/).
Ao chamar a API de dados usando uma identidade de usuário do Centro de Identidade do IAM por meio de uma sessão de perfil do IAM com identidade aprimorada, você só pode acessar a declaração e o respectivo resultado usando o mesmo usuário do Centro de Identidade do IAM. Por exemplo, o comando AWS CLI a seguir chama a operação `execute-statement` para executar um comando SQL com propagação de identidade confiável.
```
aws redshift-data execute-statement
--sql "select current_user;"
--cluster-id mycluster
--database dev
```
O comando AWS CLI a seguir chama a operação `batch-execute-statement` para executar dois comandos SQL.
```
aws redshift-data batch-execute-statement
--sqls "select current_user;" "select current_date;"
--cluster-id mycluster
--database dev
```
Para acessar declarações com `cancel-statement`, `describe-statement`, `get-statement-result` e `get-statement-result-v2` enviadas por sessões de perfil do IAM com identidade aprimorada, o usuário do Centro de Identidade do IAM e o perfil do IAM devem corresponder às credenciais usadas para executar `execute-statment` ou `batch-execute-statement`. Por exemplo, o comando AWS CLI a seguir exibe os resultados de uma declaração SQL.
```
aws redshift-data get-statement-result
--id a1b2c3d4-5678-90ab-cdef-EXAMPLE11111
```
Para listar declarações, um parâmetro `cluster-identifier` ou `workgroup-name` deve ser fornecido para garantir que o usuário do Centro de Identidade do IAM tenha acesso somente às aplicações do Centro de Identidade do IAM do Amazon Redshift às quais ele está atribuído. Por exemplo, o comando AWS CLI a seguir lista as declarações para um cluster específico.
```
aws redshift-data list-statements
--cluster-identifier mycluster
```
Também é possível invocar as operações da API de dados que acessam objetos de banco de dados em um cluster ou um grupo de trabalho usando propagação de identidade confiável. Isso inclui as operações `list-databases`, `list-schemas`, `list-tables` e `describe-table`.
As chamadas de API feitas pelo usuário do Centro de Identidade do IAM podem ser rastreadas no AWS CloudTrail. Uma seção `onBehalfOf` do evento do CloudTrail mostra o ID de usuário do Centro de Identidade do IAM e o ARN do armazenamento de identidades. O exemplo a seguir mostra um trecho de um evento do CloudTrail que exibe a seção `onBehalfOf` com o ID de usuário `a1b2c3d4-5678-90ab-cdef-EXAMPLE11111` do Centro de Identidade do IAM e o ARN `arn:aws:identitystore::123456789012:identitystore/d-9067bc44d2` do armazenamento de identidades.
```
{
"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"
}
```
É possível executar o comando SQL a seguir para conferir a consulta enviada pelo usuário do Centro de Identidade do IAM. Neste exemplo, o e-mail registrado no Centro de Identidade é `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;
```
# Chamar a API de dados
Você pode chamar a API de dados ou a AWS CLI para executar instruções SQL no cluster ou no grupo de trabalho com a tecnologia sem servidor. As principais operações para executar instruções SQL são [https://docs.aws.amazon.com/redshift-data/latest/APIReference/API_ExecuteStatement.html](https://docs.aws.amazon.com/redshift-data/latest/APIReference/API_ExecuteStatement.html) e [https://docs.aws.amazon.com/redshift-data/latest/APIReference/API_BatchExecuteStatement.html](https://docs.aws.amazon.com/redshift-data/latest/APIReference/API_BatchExecuteStatement.html) na *Referência da API de dados do Amazon Redshift*. A API de dados oferece suporte a linguagens de programação aceitas pelos AWS SDKs. Para obter mais informações, consulte [Ferramentas para construir na AWS](https://aws.amazon.com/tools/).
Para ver exemplos de código de chamada da API Data, consulte [Conceitos básicos da API Data do Redshift](https://github.com/aws-samples/getting-started-with-amazon-redshift-data-api#getting-started-with-redshift-data-api) no *GitHub*. Esse repositório tem exemplos de uso do AWS Lambda para acessar dados do Amazon Redshift pelo Amazon EC2, do AWS Glue Data Catalog e do Amazon SageMaker Runtime. Entre os exemplos de linguagens de programação estão: Python, Go, Java e Javascript.
Você pode chamar a API de dados usando a AWS CLI.
Os exemplos a seguir usam a AWS CLI para chamar a API de dados. Para executar os exemplos, edite os valores de parâmetro para corresponder ao seu ambiente. Em muitos dos exemplos, um `cluster-identifier` é fornecido para ser executado em um cluster. Ao executar em um grupo de trabalho com a tecnologia sem servidor, você fornece um `workgroup-name`. Estes exemplos demonstram algumas das operações da API de dados. Para obter mais informações, consulte a *Referência de comandos da AWS CLI*.
Os comandos nos exemplos a seguir foram divididos e formatados para facilitar a leitura. Nem todos os parâmetros e respostas são mostrados em todos os exemplos. Para obter a definição de API da sintaxe completa da solicitação, parâmetros da solicitação, sintaxe da resposta e elementos da resposta, consulte a [Referência de API de dados do Amazon Redshift](https://docs.aws.amazon.com/redshift-data/latest/APIReference/).
# Passar instruções SQL para um data warehouse do Amazon Redshift
Os exemplos nesta página mostram maneiras diferentes de passar uma instrução SQL para o data warehouse.
## Executar uma instrução SQL
Para executar uma instrução SQL, use o comando `aws redshift-data execute-statement` da AWS CLI.
O comando a seguir da AWS CLI executa uma instrução SQL em um cluster e retorna um identificador para obter os resultados. Este exemplo usa o método de autenticação 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
```
Este é um exemplo da resposta.
```
{
"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"
}
```
O comando a seguir da AWS CLI executa uma instrução SQL em um cluster e retorna um identificador para obter os resultados. Este exemplo usa o método de autenticação de credenciais temporárias.
```
aws redshift-data execute-statement
--db-user myuser
--cluster-identifier mycluster-test
--database dev
--sql "select * from stl_query limit 1"
```
Este é um exemplo da resposta.
```
{
"ClusterIdentifier": "mycluster-test",
"CreatedAt": 1598306924.632,
"Database": "dev",
"DbUser": "myuser",
"Id": "d9b6c0c9-0747-4bf4-b142-e8883122f766"
}
```
O comando a seguir da AWS CLI executa uma instrução SQL em um grupo de trabalho com a tecnologia sem servidor e retorna um identificador para obter os resultados. Este exemplo usa o método de autenticação de credenciais temporárias.
```
aws redshift-data execute-statement
--database dev
--workgroup-name myworkgroup
--sql "select 1;"
```
Este é um exemplo da resposta.
```
{
"CreatedAt": "2022-02-11T06:25:28.748000+00:00",
"Database": "dev",
"DbUser": "IAMR:RoleName",
"Id": "89dd91f5-2d43-43d3-8461-f33aa093c41e",
"WorkgroupName": "myworkgroup"
}
```
O comando a seguir da AWS CLI executa uma instrução SQL em um cluster e retorna um identificador para obter os resultados. Este exemplo usa o método de autenticação AWS Secrets Manager e um token de idempotência.
```
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
```
Este é um exemplo da resposta.
```
{
"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"
}
```
## Executar uma instrução SQL com parâmetros
Para executar uma instrução SQL, use o comando `aws redshift-data execute-statement` da AWS CLI.
O comando a seguir da AWS CLI executa uma instrução SQL em um cluster e retorna um identificador para obter os resultados. Este exemplo usa o método de autenticação AWS Secrets Manager. O texto SQL tem o parâmetro nomeado `distance`. Nesse caso, a distância usada no predicado é `5`. Em uma instrução SELECT, os parâmetros nomeados para nomes de colunas só podem ser usados no predicado. Valores para parâmetros nomeados para a instrução SQL são especificados na opção `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
```
Este é um exemplo da resposta.
```
{
"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"
}
```
O exemplo a seguir usa a tabela `EVENT` do banco de dados de amostra. Para obter mais informações, consulte [Tabela EVENT](https://docs.aws.amazon.com/redshift/latest/dg/r_eventtable.html) no *Guia do desenvolvedor de banco de dados do Amazon Redshift*.
Se você ainda não tem a tabela `EVENT` em seu banco de dados, você pode criar uma usando a API de dados da seguinte maneira:
```
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)"
```
O comando a seguir insere uma linha na tabela `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\"}]"
```
O comando a seguir insere uma segunda linha na tabela `EVENT`. Este exemplo demonstra o seguinte:
+ O parâmetro chamado `id` é usado quatro vezes no texto SQL.
+ Conversão de tipo implícita é aplicada automaticamente ao inserir o parâmetro `starttime`.
+ A coluna `venueid` é o tipo de conversão para o tipo de dados SMALLINT.
+ As strings de caracteres que representam o tipo de dados DATE são implicitamente convertidas no tipo de dados TIMESTAMP.
+ Os comentários podem ser usados dentro do 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\"}]"
```
O seguinte mostra as duas linhas inseridas:
```
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
```
O comando a seguir usa um parâmetro nomeado em uma cláusula WHERE para recuperar a linha em que `eventid` é `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\"}]"
```
Execute o seguinte comando para obter os resultados SQL da instrução SQL anterior:
```
aws redshift-data get-statement-result --id 7529ad05-b905-4d71-9ec6-8b333836eb5a
```
Fornece os seguintes 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
}
```
## Executar várias instruções SQL
Para executar várias instruções SQL com um comando, use o comando `aws redshift-data batch-execute-statement` da AWS CLI.
O comando a seguir da AWS CLI executa três instruções SQL em um cluster e retorna um identificador para obter os resultados. Este exemplo usa o método de autenticação de credenciais temporárias.
```
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"
```
Este é um exemplo da resposta.
```
{
"ClusterIdentifier": "mycluster-test",
"CreatedAt": 1598306924.632,
"Database": "dev",
"DbUser": "myuser",
"Id": "d9b6c0c9-0747-4bf4-b142-e8883122f766"
}
```
# Listar metadados sobre instruções SQL
Para listar metadados sobre instruções SQL, use o comando `aws redshift-data list-statements` da AWS CLI. A autorização para executar esse comando é baseada nas permissões do IAM do autor da chamada.
O seguinte comando da AWS CLI lista as instruções SQL que foram executadas.
```
aws redshift-data list-statements
--status ALL
```
Este é um exemplo da resposta.
```
{
"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
}
]
}
```
# Descrever metadados sobre uma instrução SQL
Para obter descrições de metadados para uma instrução SQL, use o comando `aws redshift-data describe-statement` da AWS CLI. A autorização para executar esse comando é baseada nas permissões do IAM do autor da chamada.
O comando da AWS CLI a seguir descreve uma instrução SQL.
```
aws redshift-data describe-statement
--id d9b6c0c9-0747-4bf4-b142-e8883122f766
```
Este é um exemplo da resposta.
```
{
"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
}
```
Veja a seguir um exemplo de uma resposta `describe-statement` após a execução de um `batch-execute-statement` com várias instruções 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
}
```
# Buscar os resultados de uma instrução SQL
Para obter o resultado de uma instrução SQL executada, use o comando `redshift-data get-statement-result` ou `redshift-data get-statement-result-v2` da AWS CLI. Os resultados de `get-statement-result` estão no formato JSON. Os resultados de `get-statement-result-v2` estão no formato CSV. Você pode fornecer um `Id` que você recebe em resposta a `execute-statement` ou `batch-execute-statement`. O valor `Id` para uma instrução SQL executada pelo `batch-execute-statement` pode ser recuperado no resultado de `describe-statement` e recebe o sufixo de dois pontos e número de sequência, como `b2906c76-fa6e-4cdf-8c5f-4de1ff9b7652:2`. Se você executar várias instruções SQL com `batch-execute-statement`, cada instrução SQL tem um `Id` como mostrado na `describe-statement`. A autorização para executar esse comando é baseada nas permissões do IAM do autor da chamada.
A instrução a seguir gera o resultado de uma instrução SQL executada por `execute-statement` que permite que o `ResultFormat` tenha `JSON` como padrão. Para obter os resultados, chame a operação `get-statement-result`.
```
aws redshift-data get-statement-result
--id d9b6c0c9-0747-4bf4-b142-e8883122f766
```
A instrução a seguir retorna o resultado da segunda instrução SQL executada pelo `batch-execute-statement`.
```
aws redshift-data get-statement-result
--id b2906c76-fa6e-4cdf-8c5f-4de1ff9b7652:2
```
Veja a seguir um exemplo de resposta a uma chamada para `get-statement-result`, em que o resultado SQL é gerado no formato JSON na chave `Records` da resposta.
```
{
"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
}
```
O exemplo a seguir mostra uma instrução SQL executada por `execute-statement` para gerar resultados como JSON. A tabela `testingtable` tem três colunas inteiras (col1, col2, col3), e há três linhas com valores (1, 2, 3), (4, 5, 6) e (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"
}
```
Veja a seguir um exemplo de resposta a uma chamada para `get-statement-result`, em que o resultado SQL é gerado no formato JSON na chave `Records` da resposta.
```
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
}
```
O exemplo a seguir mostra uma instrução SQL executada por `execute-statement` para gerar resultados como CSV. A tabela `testingtable` tem três colunas inteiras (col1, col2, col3), e há três linhas com valores (1, 2, 3), (4, 5, 6) e (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"
}
```
Veja a seguir um exemplo de resposta a uma chamada para `get-statement-result-v2`, em que o resultado SQL é gerado no formato CSV na chave `Records` da resposta. As linhas são separadas por retorno de carro e nova linha (\$1r\$1n). A primeira linha gerada em `Records` são os títulos das colunas. Os resultados gerados no formato CSV são retornados em 1 MB, em que cada bloco pode armazenar qualquer número de linhas de até 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"
}
```
# Descrever uma tabela
Para obter metadados que descrevem uma tabela, use o comando `aws redshift-data describe-table` da AWS CLI.
O comando a seguir da AWS CLI executa uma instrução SQL em um cluster e retorna metadados que descrevem uma tabela. Este exemplo usa o método de autenticação 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
```
Este é um exemplo da resposta.
```
{
"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"
}
]
}
```
O comando a seguir da AWS CLI executa uma instrução SQL em um cluster que descreve uma tabela. Este exemplo usa o método de autenticação de credenciais temporárias.
```
aws redshift-data describe-table
--db-user myuser
--cluster-identifier mycluster-test
--database dev
--schema information_schema
--table sql_features
```
Este é um exemplo da resposta.
```
{
"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"
}
]
}
```
# Relacionar bancos de dados em um cluster
Para listar os bancos de dados em um cluster, use o comando `aws redshift-data list-databases` da AWS CLI.
O comando a seguir da AWS CLI executa uma instrução SQL em um cluster para listar bancos de dados. Este exemplo usa o método de autenticação 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
```
Este é um exemplo da resposta.
```
{
"Databases": [
"dev"
]
}
```
O comando a seguir da AWS CLI executa uma instrução SQL em um cluster para listar bancos de dados. Este exemplo usa o método de autenticação de credenciais temporárias.
```
aws redshift-data list-databases
--db-user myuser
--cluster-identifier mycluster-test
--database dev
```
Este é um exemplo da resposta.
```
{
"Databases": [
"dev"
]
}
```
# Relacionar esquemas em um banco de dados
Para listar os esquemas em um banco de dados, use o comando `aws redshift-data list-schemas` da AWS CLI.
O comando a seguir da AWS CLI executa uma instrução SQL em um cluster para listar esquemas em um banco de dados. Este exemplo usa o método de autenticação 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
```
Este é um exemplo da resposta.
```
{
"Schemas": [
"information_schema",
"pg_catalog",
"pg_internal",
"public"
]
}
```
O comando a seguir da AWS CLI executa uma instrução SQL em um cluster para listar esquemas em um banco de dados. Este exemplo usa o método de autenticação de credenciais temporárias.
```
aws redshift-data list-schemas
--db-user mysuser
--cluster-identifier mycluster-test
--database dev
```
Este é um exemplo da resposta.
```
{
"Schemas": [
"information_schema",
"pg_catalog",
"pg_internal",
"public"
]
}
```
# Relacionar tabelas em um banco de dados
Para listar as tabelas em um banco de dados, use o comando `aws redshift-data list-tables` da AWS CLI.
O comando a seguir da AWS CLI executa uma instrução SQL em um cluster para listar tabelas em um banco de dados. Este exemplo usa o método de autenticação 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
```
Este é um exemplo da resposta.
```
{
"Tables": [
{
"name": "sql_features",
"schema": "information_schema",
"type": "SYSTEM TABLE"
},
{
"name": "sql_implementation_info",
"schema": "information_schema",
"type": "SYSTEM TABLE"
}
}
```
O comando a seguir da AWS CLI executa uma instrução SQL em um cluster para listar tabelas em um banco de dados. Este exemplo usa o método de autenticação de credenciais temporárias.
```
aws redshift-data list-tables
--db-user myuser
--cluster-identifier mycluster-test
--database dev
--schema information_schema
```
Este é um exemplo da resposta.
```
{
"Tables": [
{
"name": "sql_features",
"schema": "information_schema",
"type": "SYSTEM TABLE"
},
{
"name": "sql_implementation_info",
"schema": "information_schema",
"type": "SYSTEM TABLE"
}
]
}
```
# Solução de problemas da API de dados do Amazon Redshift
Use as seções a seguir, intituladas com mensagens de erro comuns, para ajudar na solução de problemas com a Data API.
**Topics**
+ [O pacote para consulta é muito grande](#data-api-troubleshooting-packet-too-large)
+ [A resposta do banco de dados excedeu o limite de tamanho](#data-api-troubleshooting-response-size-too-large)
## O pacote para consulta é muito grande
Se você vir um erro indicando que o pacote de uma consulta é muito grande, geralmente o conjunto de resultados retornado para uma linha é muito grande. O limite de tamanho da API de dados é de 64 KB por linha no conjunto de resultados obtido pelo banco de dados.
Para resolver esse problema, verifique se cada linha em um conjunto de resultados tem até 64 KB.
## A resposta do banco de dados excedeu o limite de tamanho
Se você vir um erro indicando que a resposta do banco de dados excedeu o limite de tamanho, geralmente o tamanho do conjunto de resultados retornado pelo banco de dados era muito grande. O limite da API de dados é de 500 MB no conjunto de resultados retornado pelo banco de dados.
Para resolver esse problema, certifique-se de que as chamadas para a API de dados retornem 500 MB de dados ou menos. Se você precisar retornar mais de 500 MB, poderá executar várias chamadas de instrução com a cláusula `LIMIT` em sua consulta.
# Programar operações da API de dados do Amazon Redshift com o Amazon EventBridge
Você pode criar regras que estabeleçam correspondência com eventos selecionados e os encaminhem aos destinos para ação. Você também pode usar as regras para executar uma ação em uma programação predeterminada. Para saber mais, consulte o [Guia do Usuário do Amazon EventBridge](https://docs.aws.amazon.com/eventbridge/latest/userguide/).
Para programar operações de API de dados com o EventBridge, a função do IAM associada deve confiar na entidade principal para o CloudWatch Events (events.amazonaws.com). Essa função deve ter o equivalente à política gerenciada `AmazonEventBridgeFullAccess` anexada. Também deve ter política de permissões `AmazonRedshiftDataFullAccess` que são gerenciadas pela API de dados. Você pode criar uma função do IAM com essas permissões no console do IAM. Ao criar uma função no console do IAM, selecione a entidade confiável do para CloudWatch Events do serviço da AWS. Especifique o perfil do IAM no valor `RoleArn` JSON no destino do EventBridge. Para obter mais informações sobre como criar uma função do IAM, consulte [Criando uma função para um serviço da AWS (console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html#roles-creatingrole-service-console) no *Guia do usuário do IAM*.
O `name` da regra que você cria no Amazon EventBridge deve corresponder ao `StatementName` nos `RedshiftDataParameters`.
Os exemplos a seguir mostram variações da criação de regras do EventBridge com uma ou várias instruções SQL e com um cluster do Amazon Redshift ou um grupo de trabalho do Amazon Redshift sem servidor como data warehouse.
## Chamadas com cluster e uma única instrução SQL
O exemplo a seguir usa a AWS CLI para criar uma regra do EventBridge que é usada para executar uma instrução SQL em um cluster do Amazon Redshift.
```
aws events put-rule
--name test-redshift-cluster-data
--schedule-expression "rate(1 minute)"
```
Em seguida, um destino EventBridge é criado para ser executado na programação especificada na regra.
```
aws events put-targets
--cli-input-json file://data.json
```
O arquivo data.json de entrada é o seguinte. A chave JSON `Sql` indica que há uma única instrução SQL. O valor JSON `Arn` contém um identificador de cluster. O valor `RoleArn` JSON contém o perfil do IAM usado para executar o SQL conforme descrito 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
}
}
]
}
```
## Chamadas com grupo de trabalho e uma única instrução SQL
O exemplo a seguir usa a AWS CLI para criar uma regra do EventBridge que é usada para executar uma instrução SQL em um grupo de trabalho do Amazon Redshift sem servidor.
```
aws events put-rule
--name test-redshift-serverless-workgroup-data
--schedule-expression "rate(1 minute)"
```
Em seguida, um destino EventBridge é criado para ser executado na programação especificada na regra.
```
aws events put-targets
--cli-input-json file://data.json
```
O arquivo data.json de entrada é o seguinte. A chave JSON `Sql` indica que há uma única instrução SQL. O valor JSON `Arn` contém um nome de grupo de trabalho. O valor `RoleArn` JSON contém o perfil do IAM usado para executar o SQL conforme descrito 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
}
}
]
}
```
## Chamadas com cluster e várias instruções SQL
O exemplo a seguir usa a AWS CLI para criar uma regra do EventBridge que é usada para executar várias instruções SQL em um cluster do Amazon Redshift.
```
aws events put-rule
--name test-redshift-cluster-data
--schedule-expression "rate(1 minute)"
```
Em seguida, um destino EventBridge é criado para ser executado na programação especificada na regra.
```
aws events put-targets
--cli-input-json file://data.json
```
O arquivo data.json de entrada é o seguinte. A chave JSON `Sqls` indica que há várias instruções SQL. O valor JSON `Arn` contém um identificador de cluster. O valor `RoleArn` JSON contém o perfil do IAM usado para executar o SQL conforme descrito 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
}
}
]
}
```
## Chamadas com grupo de trabalho e várias instruções SQL
O exemplo a seguir usa a AWS CLI para criar uma regra do EventBridge que é usada para executar várias instruções SQL em um grupo de trabalho do Amazon Redshift sem servidor.
```
aws events put-rule
--name test-redshift-serverless-workgroup-data
--schedule-expression "rate(1 minute)"
```
Em seguida, um destino EventBridge é criado para ser executado na programação especificada na regra.
```
aws events put-targets
--cli-input-json file://data.json
```
O arquivo data.json de entrada é o seguinte. A chave JSON `Sqls` indica que há várias instruções SQL. O valor JSON `Arn` contém um nome de grupo de trabalho. O valor `RoleArn` JSON contém o perfil do IAM usado para executar o SQL conforme descrito 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
}
}
]
}
```
# Monitorar a API de dados
O monitoramento é uma parte importante da manutenção da confiabilidade, disponibilidade e performance da API de dados e de suas outras soluções da AWS. A AWS fornece as seguintes ferramentas de monitoramento para observar a API de dados, relatar quando algo está errado e realizar ações automáticas quando apropriado:
+ O Amazon EventBridge pode ser usado para automatizar seus serviços da AWS e responder automaticamente a eventos do sistema, como problemas de disponibilidade de aplicações ou alterações de recursos. Os eventos dos serviços da AWS são entregues ao EventBridge quase em tempo real. Você pode escrever regras simples para determinar quais eventos são do seu interesse, e as ações automatizadas a serem tomadas quando um evento corresponder à regra. Para saber mais, consulte o [Guia do Usuário do Amazon EventBridge](https://docs.aws.amazon.com/eventbridge/latest/userguide/).
+ O AWS CloudTrail captura chamadas de API e eventos relacionados feitos por ou em nome de sua conta da AWS e entrega os arquivos de log a um bucket do Amazon S3 que você especificar. Você pode identificar quais usuários e contas chamaram AWS, o endereço IP de origem de onde as chamadas foram feitas e quando elas ocorreram. Para saber mais sobre como o Amazon Redshift é integrado ao AWS CloudTrail, consulte [“Logging with CloudTrail”](https://docs.aws.amazon.com/redshift/latest/mgmt/logging-with-cloudtrail.html) (Registro em log com o CloudTrail). Para obter mais informações sobre o CloudTrail, consulte o [ Guia do usuário do AWS CloudTrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/).
**Topics**
+ [Monitorar eventos para a API de dados do Amazon Redshift no Amazon EventBridge](data-api-monitoring-events.md)
# Monitorar eventos para a API de dados do Amazon Redshift no Amazon EventBridge
Você pode monitorar eventos de API de dados no EventBridge, que fornece um fluxo de dados em tempo real de suas próprias aplicações, aplicações de software como serviço (SaaS) e serviços da AWS. O EventBridge encaminha esses dados para destinos como AWS Lambda e o Amazon SNS. Esses eventos são iguais aos que aparecem no CloudWatch Events, que oferece um fluxo quase em tempo real de eventos do sistema que descrevem as mudanças nos recursos da AWS. Os eventos são enviados para a conta que contém o banco de dados do Amazon Redshift. Por exemplo, se você assumir uma função em outra conta, os eventos serão enviados para essa conta. Para obter mais informações, consulte [Eventos do Amazon EventBridge](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-events.html) no *Guia do usuário do Amazon EventBridge*.
Os eventos da API Data são enviados quando a operação da API `ExecuteStatement` ou `BatchExecuteStatement` define a opção `WithEvent` como `true`. O campo `state` do evento contém um dos seguintes valores:
+ ABORTED: a execução da consulta foi interrompida pelo usuário.
+ FAILED — Falha na execução da consulta.
+ FINISHED — A consulta terminou de ser executada.
A entrega dos eventos é garantida. Para obter mais informações, consulte [Eventos de produtos da AWS](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-service-event.html) no *Guia do usuário do Amazon EventBridge*.
## Exemplo de evento concluído da API de dados
Os exemplos a seguir mostram um evento para API Data quando a operação da API `ExecuteStatement` termina. Neste exemplo, uma instrução chamada `test.testtable` terminou de ser executada.
```
{
"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
}
}
```
# Usar o AWS KMS com a API de dados do Amazon Redshift
Quando você criptografa o cluster do Amazon Redshift ou grupo de trabalho do Redshift sem servidor com uma chave gerenciada pelo cliente, a API de dados do Amazon Redshift usa essa mesma chave gerenciada pelo cliente para armazenar e criptografar suas consultas e resultados.
A API de dados criptografa seus dados por padrão para proteger informações sensíveis, como texto e resultados da consulta. Ela usa chaves de criptografia do AWS KMS de propriedade da AWS para essa proteção.
A criptografia de dados em repouso padrão reduz os custos operacionais e a complexidade envolvidos na proteção de dados sensíveis. Essa abordagem ajuda a criar aplicações seguras que atendam aos rigorosos requisitos regulatórios e de conformidade de criptografia.
## Usar concessões no AWS KMS
A API de dados requer uma concessão para usar a chave gerenciada pelo cliente.
Quando você chama `ExecuteStatement` ou `BatchExecuteStatement` em um cluster criptografado com uma chave gerenciada pelo cliente, o Amazon Redshift cria uma concessão em seu nome enviando uma solicitação [https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html) ao AWS KMS. O AWS KMS usa concessões para dar acesso à API de dados a uma chave do KMS em sua conta.
A API de dados exige concessões para usar sua chave gerenciada pelo cliente para as seguintes operações:
+ Enviar solicitações [https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html) ao AWS KMS para criptografar os metadados da consulta com sua chave gerenciada pelo cliente.
+ Enviar solicitações [https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) ao AWS KMS para gerar chaves de dados criptografadas pela chave gerenciada pelo cliente.
+ Enviar solicitações [https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) ao AWS KMS para descriptografar as chaves de dados criptografadas para que elas possam ser usadas para criptografar seus dados.
É possível revogar o acesso à concessão, ou remover o acesso do Amazon Redshift à chave gerenciada pelo cliente a qualquer momento. Se você fizer isso, a API de dados não poderá mais acessar dados criptografados pela chave gerenciada pelo cliente, o que afetará as operações que dependem desses dados. Por exemplo, se você tentar recuperar os resultados da consulta ou acompanhar o status da consulta depois de revogar a concessão, a API de dados exibirá uma `AccessDeniedException`.
## Políticas de chave para a chave gerenciada pelo cliente
As políticas de chaves controlam o acesso à chave gerenciada pelo seu cliente. Cada chave gerenciada pelo cliente deve ter exatamente uma política de chaves, que contém declarações que determinam quem pode usar a chave e como pode usá-la. Ao criar a chave gerenciada pelo cliente, é possível especificar uma política de chave. Para saber mais, consulte [Chaves mestras do cliente (CMKs)](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#customer-mgn-key) no *AWS Key Management Service Guia do desenvolvedor*.
Para usar suas chaves gerenciadas pelo cliente com a API de dados, primeiro permita o acesso ao Amazon Redshift. As seguintes operações de API deverão ser permitidas na política de chave:
+ `kms:CreateGrant`: adiciona uma concessão a uma chave gerenciada pelo cliente. Concede controle de acesso a uma chave do AWS KMS especificada, que permite o acesso às operações de concessão exigidas pelo Amazon Redshift. Para obter mais informações, consulte [Usar concessõesAWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/grants.html#terms-grant-operations).
Veja a seguir um exemplo de política de chave.
```
"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 criptografia da API de dados
Um contexto de criptografia é um conjunto opcional de pares de chave-valor que pode conter mais informações contextuais sobre os dados. O AWS KMS usa o contexto de criptografia como dados autenticados adicionais para comportar criptografia autenticada. Quando você inclui um contexto de criptografia em uma solicitação para criptografar dados, o AWS KMS vincula de forma criptográfica o contexto da criptografia aos dados criptografados. Para descriptografar os dados, você inclui o mesmo contexto de criptografia na solicitação.
A API de dados usa os mesmos três pares de chave-valor de contexto de criptografia em todas as operações criptográficas do AWS KMS para clusters provisionados:
+ `aws:redshift:arn`: o nome do recurso da Amazon (ARN) do cluster.
+ `aws:redshift:createtime`: o carimbo de data/hora em que você solicitou a criação do cluster.
+ `serviceName` – `RedshiftDataAPI`
```
"EncryptionContextSubset": {
"aws:redshift:arn": "arn:aws:redshift:us-east-1:123456789012:cluster:redshift-cluster",
"aws:redshift:createtime": "20250815T0000Z",
"serviceName": "RedshiftDataAPI",
}
```
A API de dados usa dois pares de chave-valor de contexto de criptografia em todas as operações criptográficas do AWS KMS para grupos de trabalho sem servidor:
+ `aws:redshift-serverless:arn`: o nome do recurso da Amazon (ARN) do namespace.
+ `serviceName`: RedshiftDataAPI
```
"EncryptionContextSubset": {
"aws:redshift-serverless:arn": "arn:aws:redshift-serverless:us-east-1:123456789012:namespace:12345678-1234-1234-1234-123456789012",
"serviceName": "RedshiftDataAPI"
}
```
Para acessar mais informações sobre criptografia, consulte [Introdução aos detalhes criptográficos do AWS KMS](https://docs.aws.amazon.com/kms/latest/cryptographic-details/intro.html). Para acessar mais informações sobre a integração do Amazon Redshift e do AWS KMS, consulte [Como o Amazon Redshift usa o AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/services-redshift.html).