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` ou `batch-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 \\"FROM\\"\\n 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. + Tanto as operações `execute-statement` quanto `batch-execute-statement` são compatíveis com instruções SQL com parâmetros. Ao usar `batch-execute-statement`, os parâmetros são compartilhados entre todas as instruções SQL no lote. Cada instrução SQL pode referenciar um subconjunto dos parâmetros fornecidos, mas todo parâmetro deve ser utilizado por pelo menos uma instrução SQL. ## 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": {{}} } ```