As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Compreender os conceitos de consultas agendadas

Antes de criar consultas agendadas, entenda esses conceitos-chave que afetam a forma como suas consultas são executadas e onde os resultados são entregues.

Separação de funções do IAM

As consultas agendadas exigem duas funções separadas do IAM: uma para executar consultas e outra para entregar resultados aos barramentos de eventos do Amazon S3 ou da Amazon. EventBridge Entender por que essa separação existe ajuda você a configurar as permissões corretamente e a usar os benefícios operacionais e de segurança que ela oferece.

A arquitetura de duas funções divide as responsabilidades entre acesso e entrega de dados. A função de execução da consulta acessa seus dados de log e executa consultas, enquanto a função de entrega de destino grava os resultados no destino escolhido. Essa separação segue o princípio do menor privilégio: cada função tem somente as permissões necessárias para sua função específica.

Essa separação oferece benefícios práticos para suas operações. Do ponto de vista da segurança, se você precisar alterar onde os resultados são entregues, modifique apenas a função de entrega de destino sem alterar as permissões de execução da consulta. Para fins de conformidade e auditoria, você pode monitorar claramente qual função acessa dados de log confidenciais e qual função grava em sistemas externos. Isso facilita a demonstração de que sua infraestrutura de análise de registros segue as melhores práticas de segurança.

Uso entre regiões e entre contas

Uma consulta agendada é criada em uma região específica e executada nessa região. No entanto, você pode consultar grupos de registros e fornecer resultados em todas as regiões e contas. Você precisa configurar uma ou mais AWS contas como contas de monitoramento e vinculá-las a várias contas de origem. Uma conta de monitoramento é uma AWS conta central que pode visualizar e interagir com os dados de observabilidade gerados pelas contas de origem. Uma conta de origem é uma AWS conta individual que gera dados de observabilidade para os recursos que residem nela. As contas de origem compartilham os dados de observabilidade com a conta de monitoramento. Assim, você pode configurar consultas agendadas da conta de monitoramento usando os grupos de registros de todas as contas vinculadas.

Abordagem alternativa: use a centralização de CloudWatch registros para replicar dados de registros de várias contas e regiões em uma conta de monitoramento central. Isso permite criar consultas agendadas em uma única região que acessa todos os seus registros centralizados, evitando consultas entre regiões e simplificando o gerenciamento de permissões do IAM.

Expressões de programação e tratamento de fuso horário

O cronograma que você define determina quando sua consulta é executada e com que frequência ela é executada. A escolha da expressão de agendamento correta afeta quando você recebe os resultados e a quantidade de dados que você consulta. Compreender os tipos de expressão ajuda você a escolher entre simplicidade e precisão.

As expressões Cron fornecem controle preciso sobre o tempo, permitindo que você especifique horários, dias da semana ou dias do mês exatos. Use expressões cron quando precisar que as consultas sejam executadas em horários comerciais específicos ou estejam alinhadas aos cronogramas operacionais. No console, você também pode agendar consultas usando opções fáceis de calendário.

Todas as consultas agendadas são executadas em UTC, independentemente do fuso horário local ou da localização AWS dos recursos. Isso é particularmente importante quando você agenda consultas para o horário comercial ou análises urgentes. Por exemplo, se sua empresa opera no Horário do Leste dos EUA e você quer um relatório diário às 9h ET, você precisa contabilizar a diferença UTC (14:00 UTC durante o horário de verão, 13:00 UTC caso contrário). Planeje suas expressões de agendamento com o UTC em mente para garantir que as consultas sejam executadas nos horários pretendidos.

Escolhendo um idioma de consulta

As consultas agendadas oferecem suporte a três linguagens de consulta diferentes, e sua escolha afeta a forma como você escreve as consultas e a facilidade com que sua equipe pode mantê-las. O idioma certo depende dos seus requisitos de análise e das habilidades existentes da sua equipe.

Se você está filtrando e agregando principalmente dados de registro, a linguagem de consulta do CloudWatch Logs Insights oferece a sintaxe mais direta. Para transformações de dados complexas em que você precisa remodelar ou enriquecer dados por meio de várias etapas, a abordagem de pipeline do PPL facilita o acompanhamento da lógica. Quando você precisa realizar uniões ou agregações complexas semelhantes às operações de banco de dados, o SQL fornece uma sintaxe familiar que equipes experientes em bancos de dados podem adotar rapidamente.

Seleção de destinos e casos de uso

O local onde você envia os resultados da consulta determina o que você pode fazer com eles. Essa escolha molda todo o seu fluxo de trabalho posterior, esteja você criando análises de longo prazo, acionando respostas automatizadas ou ambas. Compreender os pontos fortes de cada tipo de destino ajuda você a projetar a arquitetura certa para seu caso de uso.

Os destinos do Amazon S3 são otimizados para armazenamento e processamento em lote. Quando você precisa manter os resultados das consultas por meses ou anos, analisar tendências ao longo do tempo ou inserir dados em plataformas de análise, o Amazon S3 fornece armazenamento econômico com retenção ilimitada. EventBridge os destinos são otimizados para automação em tempo real. Quando os resultados da consulta devem acionar ações imediatas, como enviar alertas, iniciar fluxos de trabalho ou atualizar sistemas, EventBridge fornece resultados como eventos aos quais seus aplicativos podem responder instantaneamente. Por padrão, todos os eventos de conclusão da consulta são enviados automaticamente como eventos para o barramento de eventos padrão, permitindo a integração com sistemas de processamento downstream, funções Lambda ou outras arquiteturas orientadas a eventos. Os resultados só são publicados nos destinos quando a consulta é executada com sucesso.

Formato e estrutura do resultado da consulta

Para destinos do Amazon S3 - os resultados da consulta são entregues no formato JSON com a mesma estrutura da resposta da GetQueryResults API. Para a Amazon, EventBridge entender o formato dos resultados de consultas programadas ajuda você a projetar fluxos de trabalho de processamento e integração posteriores.

Os resultados da consulta são entregues no formato JSON com a seguinte estrutura:

{
    "version": "0",
    "id": "be72061b-eca2-e068-a7e1-83e01d6fe807",
    "detail-type": "Scheduled Query Completed",
    "source": "aws.logs",
    "account": "123456789012",
    "time": "2025-11-18T11:31:48Z",
    "region": "us-east-1",
    "resources": [
        "arn:aws:logs:us-east-1:123456789012:scheduled-query:477b4380-b098-474e-9c5e-e10a8cc2e6e7"
    ],
    "detail": {
        "queryId": "2038fd57-ab4f-4018-bb2f-61d363f4a004",
        "queryString": "fields @timestamp, @message, @logStream, @log\n| sort @timestamp desc\n| limit 10000",
        "logGroupIdentifiers": [
            "/aws/lambda/my-function"
        ],
        "status": "Complete",
        "startTime": 1763465460,
        "statistics": {
            "recordsMatched": 0,
            "recordsScanned": 0,
            "estimatedRecordsSkipped": 0,
            "bytesScanned": 0,
            "estimatedBytesSkipped": 0,
            "logGroupsScanned": 1
        }
    }
}

Os principais elementos incluem: