Trabalhar com a API de dados Considerações ao chamar a API de dados Executar instruções SQL com um token de idempotência Executar instruções SQL com reutilização de sessão

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.

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 usa 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? no Manual do usuário do AWS Secrets Manager.

Com a API de dados, é possível acessar programaticamente dados do Amazon Redshift com aplicações baseadas em serviços da web, incluindo o AWS Lambda, cadernos do Amazon SageMaker e o AWS Cloud9. Para obter mais informações sobre essas aplicações, consulte AWS Lambda, Amazon SageMaker, e AWS Cloud9.

Para saber mais sobre a API de dados, consulte 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:

Determine se você, como autor da chamada da API de dados, está autorizado. Para obter mais informações sobre a autorização, consulte Autorizar acesso à API de dados do Amazon Redshift.
Determine se você planeja chamar a API de dados com credenciais de autenticação do Secrets Manager ou credenciais temporárias. Para ter mais informações, consulte Escolher credenciais de autenticação de banco de dados ao chamar a API de dados do Amazon Redshift.
Configure um segredo se você usar o Secrets Manager para credenciais de autenticação. Para ter mais informações, consulte Armazenar credenciais de banco de dados no AWS Secrets Manager.
Revise as considerações e limitações ao chamar a API de dados. Para ter mais informações, consulte Considerações ao chamar a API de dados do Amazon Redshift.
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, consulteChamar a API de dados.

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 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 é 100 MB (após a compactação gzip). Se uma chamada retornar mais de 100 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 ou permissões do IAM que o executor de uma operação da API ExecuteStatement ou BatchExecuteStatement podem atuar na mesma instrução com as operações da API CancelStatement, DescribeStatement, GetStatementResult 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.
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.
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. 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 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 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.

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 ter mais informações, consulte Armazenar credenciais de banco de dados no AWS Secrets Manager.

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.

Com esses métodos, você também pode fornecer um valor de region que especifica a Região da AWS em que 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 \"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 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.

O comando execute-statement da AWS CLI a seguir ilustra o parâmetro client-token opcional para idempotência.



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

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: Ela inclui um parâmetro ou uma combinação de parâmetros que não é válido. Ela usa uma ação ou um recurso para o qual você não tem permissões. Ela usa um recurso que está em processo de mudança de estado. 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.

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:

Ela inclui um parâmetro ou uma combinação de parâmetros que não é válido.
Ela usa uma ação ou um recurso para o qual você não tem permissões.
Ela usa um recurso que está em processo de mudança de estado.

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 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

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Solução de problemas de conexão no Amazon Redshift

Autorizar acesso