Definir permissões para programar uma consulta Autenticar uma consulta programada Configurar permissões para consultar o histórico de consultas programadas Monitoramento da consulta programada Solução de problemas de programação de uma consulta Encontrar detalhes sobre consultas programadas com o AWS CloudShell Vídeo de demonstração

Programar uma consulta com o editor de consultas v2

É possível criar uma programação para executar uma instrução SQL com o Editor de Consultas v2 do Amazon Redshift. Crie uma programação para executar sua instrução SQL nos intervalos de tempo que correspondam às suas necessidades de negócios. Na hora da execução da consulta programada, a consulta é iniciada pelo Amazon EventBridge e usa a API de dados do Amazon Redshift.

Como criar uma programação a fim de executar uma instrução SQL

Na visualização do Editor, selecione Programar para criar uma programação para executar uma instrução SQL.
Quando você define a programação, fornece as informações a seguir.
- Um perfil do IAM que assume as permissões necessárias para executar a consulta. Esse perfil do IAM também está associado ao cluster ou grupo de trabalho.
- Os valores de autenticação para AWS Secrets Manager ou credenciais temporárias para autorizar o acesso ao cluster ou grupo de trabalho. Esses métodos de autenticação são compatíveis com a API de dados. Para ter mais informações, consulte Autenticar uma consulta programada.
- O cluster ou grupo de trabalho em que o banco de dados reside.
- O nome do banco de dados que contém os dados a serem consultados.
- O nome da consulta programada e sua descrição. O editor de consultas v2 usa “QS2-” como prefixo do nome da consulta programada que você fornece. O editor de consultas v1 prefixa os nomes das consultas programadas com “QS-”.
- A instrução SQL a ser executada de acordo com a programação.
- A frequência de programação e opções de repetição ou um valor formatado cron que define a programação. Para obter mais informações, consulte Expressões Cron, no Guia do usuário do Amazon CloudWatch Events.
- Opcionalmente, você pode ativar as notificações comuns do Amazon SNS para monitorar a consulta programada. Talvez seja necessário confirmar o endereço de e-mail fornecido para a notificação do Amazon SNS. Verifique se recebeu um e-mail com um link para confirmar o endereço de e-mail da notificação do Amazon SNS. Para obter mais informações, consulte Notificações de e-mail no Guia do desenvolvedor do Amazon Simple Notification Service. Se a consulta estiver sendo executada, mas você não vir mensagens publicadas no tópico do SNS, consulte Minha regra é executada, mas eu não vejo nenhuma mensagem publicada no meu tópico do Amazon SNS no Guia do usuário do Amazon EventBridge.
Escolha Programar consulta para salvar e ativar a programação e adicionar a programação à lista de consultas na visualização Consultas programadas.

As visualização de de Consultas programadas lista todas as consultas programadas para os clusters e grupos de trabalho. Com essa visualização, é possível exibir detalhes da consulta de programação, ativar ou desativar a programação, editar a programação e excluir a consulta programada. Ao visualizar os detalhes da consulta, você também pode ver o histórico de execução da consulta com a programação.

nota

A execução de uma consulta programada só está disponível na lista Histórico de programação por 24 horas. As consultas executadas de acordo com uma programação não aparecem na visualização Histórico de consultas do editor de consultas v2.

Configurar permissões para programar uma consulta

Para programar consultas, o usuário do AWS Identity and Access Management (IAM) que define a programação e o perfil do IAM associado à programação devem ser configurados com as permissões do IAM para usar o Amazon EventBridge e a API de dados do Amazon Redshift. Para receber e-mails de consultas programadas, a notificação do Amazon SNS que você especificar opcionalmente também deverá ser configurada.

A seguir, descrevemos as tarefas para usar políticas gerenciadas da AWS para fornecer permissão, mas, dependendo do ambiente, talvez você queira reduzir as permissões concedidas.

Para o usuário do IAM conectado ao editor de consultas v2, edite o usuário do IAM que usa o console do IAM (https://console.aws.amazon.com/iam/).

Além das permissões para executar as operações do Amazon Redshift e do editor de consultas v2, anexe as políticas gerenciadas AmazonEventBridgeFullAccess e AmazonRedshiftDataFullAccess da AWS a um usuário do IAM.
Uma alternativa é atribuir as permissões a um perfil e designá-lo ao usuário.

Anexe uma política com a permissão sts:AssumeRole ao ARN do recurso do perfil do IAM que você especificou ao definir a consulta agendada. Para obter mais informações sobre como assumir perfis, consulte Concessão de permissões a um usuário para alternar funções no Guia do usuário do IAM.

O exemplo a seguir mostra uma política de permissão que assume o perfil do IAM myRedshiftRole na conta 123456789012. O perfil do IAM myRedshiftRole também é o perfil anexado ao cluster ou grupo de trabalho em que a consulta programada é executada.
```
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AssumeIAMRole",
            "Effect": "Allow",
            "Action": "sts:AssumeRole",
            "Resource": [
                "arn:aws:iam::123456789012:role/myRedshiftRole"
            ]
        }
    ]
}
```
Atualize a política de confiança do perfil do IAM usado para programar a consulta a fim de permitir que o usuário do IAM a assuma.
```
{
            "Sid": "AssumeRole",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::123456789012:user/myIAMusername"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}
```

Para o perfil do IAM que você especifica para permitir a execução da consulta programada, edite o perfil do IAM usando o console do IAM (https://console.aws.amazon.com/iam/).

Anexe as políticas gerenciadas AmazonRedshiftDataFullAccess e AmazonEventBridgeFullAccess da AWS ao perfil do IAM. A política gerenciada AmazonRedshiftDataFullAccess só concede a permissão redshift-serverless:GetCredentials para grupos de trabalho do Redshift sem servidor marcados com a chave RedshiftDataFullAccess.

Autenticar uma consulta programada

Ao programar uma consulta, você usa um dos métodos de autenticação a seguir quando o SQL é executado. Cada método requer uma combinação diferente de entrada no editor de consultas v2. Esses métodos de autenticação são compatíveis com a API de dados, que é usada para executar as instruções SQL.

O usuário ou perfil do banco de dados usado para executar a consulta deve ter os privilégios de banco de dados necessários. Por exemplo, para conceder privilégios IAMR:MyRedshiftQEv2Scheduler à tabela mytable, execute o comando SQL a seguir.


GRANT all ON TABLE mytable TO "IAMR:MyRedshiftQEv2Scheduler";

Para ver a lista de usuários do banco de dados no cluster ou grupo de trabalho, consulte a visualização do sistema PG_USER_INFO.

nota

Todos os grupos de trabalho do Redshift sem servidor para o qual você programa consultas devem ser marcados com a chave RedshiftDataFullAccess. Para ter mais informações, consulte Autorizar acesso à API de dados do Amazon Redshift.

Como alternativa à marcação do grupo de trabalho, você pode adicionar uma política em linha ao perfil do IAM (especificado com a programação) que permite redshift-serverless:GetCredentials. Por exemplo:


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "UseTemporaryCredentialsForAllServerlessWorkgroups",
            "Effect": "Allow",
            "Action": "redshift-serverless:GetCredentials",
            "Resource": [
                "arn:aws:redshift-serverless:*:*:workgroup/*"
            ]
        }
    ]
}

AWS Secrets Manager

Com este método, forneça um valor secreto para secret-arn que é armazenado no AWS Secrets Manager. Este segredo contém credenciais para se conectar ao seu banco de dados. Talvez você tenha criado um segredo com as credenciais adequadas quando criou o cluster ou o grupo de trabalho. O segredo deve ser marcado com a chave RedshiftDataFullAccess. Se a chave da tag ainda não estiver presente, use o console AWS Secrets Manager para adicioná-la. Para obter informações sobre como criar um segredo, consulte Criar um segredo para credenciais de conexão de banco de dados.

Para obter mais informações sobre as permissões mínimas, consulte Criação e gerenciamento de segredos com o AWS Secrets Manager no Manual do usuário do AWS Secrets Manager.

Credenciais temporárias

Com esse método, forneça o Nome do banco de dados e os valores do Usuário do banco de dados ao se conectar a um banco de dados em um cluster. Você só precisa fornecer o Nome do banco de dados ao se conectar a um banco de dados em um grupo de trabalho.

Ao se conectar a um cluster, a política AmazonRedshiftDataFullAccess concede ao usuário do banco de dados chamado redshift_data_api_user permissão para redshift:GetClusterCredentials. Se você quiser usar um usuário de banco de dados diferente para executar a instrução SQL, adicione uma política ao perfil do IAM anexado ao cluster para permitir redshift:GetClusterCredentials. O exemplo a seguir permite usuários do banco de dados awsuser e myuser.


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "UseTemporaryCredentialsForAllDbUsers",
            "Effect": "Allow",
            "Action": "redshift:GetClusterCredentials",
            "Resource": [
                "arn:aws:redshift:*:*:dbuser:*/awsuser",
                "arn:aws:redshift:*:*:dbuser:*/myuser"
            ]
        }
    ]
}

Configurar permissões para consultar o histórico de consultas programadas

Para permitir que os usuários visualizem o histórico de consultas programadas, edite o perfil do IAM Relações de confiança (especificado com a programação) para adicionar permissões.

Veja a seguir um exemplo de política de confiança em um perfil do IAM que permite ao usuário do IAM myIAMusername ver o histórico de consultas programadas. Em vez de conceder a um usuário do IAM a permissão sts:AssumeRole, é possível optar por atribuir essa permissão a um perfil do IAM.



{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": [
                    "redshift.amazonaws.com",
                    "redshift-serverless.amazonaws.com"
                ]
            },
            "Action": "sts:AssumeRole"
        },
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "events.amazonaws.com"
            },
            "Action": "sts:AssumeRole"
        },
        {
            "Sid": "AssumeRole",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::123456789012:user/myIAMusername"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

Monitoramento da consulta programada

Para o tópico do Amazon SNS que você especifica para enviar notificações por e-mail, crie o tópico do Amazon SNS usando o editor de consultas v2. Para isso, você deve acessar a seção Notificações do SNS, Ativar o monitoramento e criar o tópico com Criar tópico do SNS. O editor de consultas v2 cria o tópico do Amazon SNS e adiciona uma entidade principal de serviço à política de acesso do Amazon EventBridge. Veja a seguir uma Política de acesso de exemplo que é criada no tópico do Amazon SNS. No exemplo, são usados a Região da AWS us-west-2, a Conta da AWS 123456789012 e o tópico do Amazon SNS select-version-pdx-testunload.


{
  "Version": "2008-10-17",
  "Id": "__default_policy_ID",
  "Statement": [
    {
      "Sid": "Allow_Publish_Events",
      "Effect": "Allow",
      "Principal": {
        "Service": "events.amazonaws.com"
      },
      "Action": "sns:Publish",
      "Resource": "arn:aws:sns:us-west-2:123456789012:select-version-pdx-testunload"
    }
  ]
}

Quando a consulta programada é executada, o Amazon SNS envia e-mails de notificação da AWS. O exemplo a seguir mostra um e-mail enviado para myemail@example.com referente à consulta programada QS2-may25a executada na Região da AWS eu-north-1 na Conta da AWS 123.456.789.012 usando o tópico de notificação do Amazon SNS may25a-SNS.


{"version":"0","id":"8e4323ec-5258-7138-181b-91290e30ff9b","detail-type":"Scheduled Event","source":"aws.events","account":"123456789012","time":"2023-05-25T15:22:00Z",
                    "region":"eu-north-1","resources":["arn:aws:events:eu-north-1:123456789012:rule/QS2-may25a"],"detail":{}}

--
If you wish to stop receiving notifications from this topic, please click or visit the link below to unsubscribe:
https://sns.eu-north-1.amazonaws.com/unsubscribe.html?SubscriptionArn=arn:aws:sns:eu-north-1:123456789012:may25a-SNS:0c1a3d05-39c2-4507-bc3d-47250513d7b0&Endpoint=myemail@example.com

Please do not reply directly to this email. If you have any questions or comments regarding this email, please contact us at https://aws.amazon.com/support

Solução de problemas da configuração de programação de uma consulta

Considere o seguinte se você tiver problemas ao programar uma consulta:

As consultas não são executadas

Verifique se o perfil do IAM usado na programação tem permissão para obter as credenciais temporárias do cluster. A permissão para clusters provisionados é redshift:GetClusterCredentialsWithIAM. A permissão para grupos de trabalho do Redshift sem servidor é redshift-serverless:GetCredentials.

O histórico de programação não é exibido

O usuário do IAM ou o perfil do IAM usado para fazer login no console da AWS não foi adicionado à política de confiança do perfil do IAM usado para programar a consulta.

Ao usar o AWS Secrets Manager para a consulta agendada para se conectar, confirme se o segredo está marcado com a chave RedshiftDataFullAccess.

Se a consulta agendada estiver usando uma conexão do AWS Secrets Manager, o perfil do IAM usado para agendar a consulta deverá ter o valor equivalente à política gerenciada SecretsManagerReadWrite anexada ao perfil.

O status do histórico de consultas é Failed

Exiba a visualização do sistema SYS_QUERY_HISTORY para obter detalhes sobre por que a consulta falhou. Um problema comum é que o usuário ou o perfil do banco de dados que foi usado para executar a consulta pode não ter o privilégio necessário para executar o SQL. Para ter mais informações, consulte Autenticar uma consulta programada.

O SQL a seguir consulta a visualização SYS_QUERY_HISTORY para retornar consultas com falha.


SELECT user_id, query_id, transaction_id, session_id, database_name, query_type, status, error_message, query_text 
FROM sys_query_history
WHERE status = 'failed';

Para descobrir detalhes de uma consulta programada com falha específica, consulte Encontrar detalhes sobre consultas programadas com o AWS CloudShell.

Encontrar detalhes sobre consultas programadas com o AWS CloudShell

É possível usar o AWS CloudShell para descobrir detalhes sobre uma consulta programada. Você deve ter as permissões adequadas para executar os comandos da AWS CLI mostrados no procedimento a seguir.

Para visualizar os resultados de uma consulta programada

No console do AWS, abra o prompt de comando do AWS CloudShell. Para obter mais informações sobre o AWS CloudShell, consulte O que é o AWS CloudShell no Guia do usuário do AWS CloudShell.

Assuma o perfil do IAM da consulta programada. Para assumir o perfil, encontre o perfil do IAM associado à consulta programada no editor de consultas v2 e use-o no comando da AWS CLI no AWS CloudShell. Por exemplo, para o perfil scheduler, insira um comando AWS STS para assumir o perfil usado pela consulta programada.


aws sts assume-role —role-arn "arn:aws:iam::123456789012:role/scheduler" —role-session-name "scheduler-test"

As credenciais retornadas são semelhantes às seguintes:


"Credentials": {
"AccessKeyId": "AKIAIOSFODNN7EXAMPLE",
"SecretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
"SessionToken": "je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY...",        
"Expiration": "2023-08-18T18:19:44+00:00"
},
"AssumedRoleUser": {
"AssumedRoleId": "AROA35B2NH6WBTP7ONL4E:scheduler-test",
"Arn": "arn:aws:sts::123456789012:assumed-role/scheduler/scheduler-test"
}
}

Crie variáveis de ambiente na AWS CLI usando as credenciais exibidas ao assumir o perfil do IAM. É necessário usar esses tokens antes do respectivo prazo de validade. Por exemplo, insira o seguinte no AWS CloudShell.
```
export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
export AWS_SESSION_TOKEN=je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY...
```

Para ver o erro de uma consulta com falha, execute o comando da AWS CLI para descrever uma instrução. O ID da instrução SQL é do ID mostrado na seção Histórico de programação de uma consulta programada no editor de consultas v2.


aws redshift-data describe-statement —id 130d2620-05d2-439c-b7cf-815d9767f513

Neste exemplo, o SQL programado select * from users limit 100 resulta em um erro de SQL segundo o qual a tabela users não existe.


{
"CreatedAt": "2023-08-18T17:39:15.563000+00:00",
"Duration": -1,
"Error": "ERROR: relation \"users\" does not exist",
"HasResultSet": false,
"Id": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"QueryString": "select * from users limit 100\n—RequestID=a1b2c3d4-5678-90ab-cdef-EXAMPLE22222; TraceID=1-633c5642-4039308d03f3a0ba53dbdf6f",
"RedshiftPid": 1073766651,
"RedshiftQueryId": 0,
"ResultRows": -1,
"ResultSize": -1,
"Status": "FAILED",
"UpdatedAt": "2023-08-18T17:39:16.116000+00:00",
"WorkgroupName": "default"
}

Demonstração do agendamento de uma consulta

Para ver uma demonstração de como agendar uma consulta, assista ao vídeo a seguir.

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

Trabalho com unidades de compartilhamento de dados

Visualizar resultados