Configurar uma fila de mensagens mortas para um agendamento

O Amazon EventBridge Scheduler oferece suporte a filas de mensagens não entregues (DLQ) usando o Amazon Simple Queue Service. Quando um agendamento falha em invocar seu alvo, o EventBridge Scheduler entrega uma carga JSON contendo detalhes da invocação e qualquer resposta recebida do alvo para uma fila padrão do Amazon SQS que você especificar.

O tópico a seguir se refere a esse JSON como um evento de letra morta. Um evento sem saída permite que você solucione problemas com sua agenda ou metas. Se você configurar uma política de repetição para sua agenda, o EventBridge Scheduler entregará o evento de letra morta que ele tem, esgotando o número máximo de novas tentativas que você definiu.

Os tópicos a seguir descrevem como você pode configurar uma fila do Amazon SQS como DLQ para seu agendamento, configurar as permissões que o EventBridge Scheduler precisa para entregar mensagens ao Amazon SQS e receber eventos de carta morta do DLQ.

Criar uma fila do Amazon SQS

Antes de configurar uma DLQ para seu agendamento, você deve criar uma fila padrão do Amazon SQS. Para obter instruções sobre criar uma fila utilizando o Amazon SQS, consulte o tópico sobre como Criar uma fila do Amazon SQS, no Guia do desenvolvedor do Amazon Simple Queue Service.

nota

O EventBridge Scheduler não suporta o uso de uma fila FIFO como DLQ da sua agenda.

Use o comando AWS CLI a seguir da CLI do para criar uma fila padrão.

$ aws sqs create-queue --queue-name queue-name

Se o for bem-sucedido, você verá QueueURL no resultado.

{
    "QueueUrl": "https://sqs.us-west-2.amazonaws.com/123456789012/scheduler-dlq-test"
}

Depois de criar a fila, anote o ARN da fila. Você precisará do ARN ao especificar um DLQ para seu agendamento do EventBridge Scheduler. Você pode encontrar o ARN da fila no console do Amazon SQS ou usando o comando get-queue-attributes AWS CLI.

$ aws sqs get-queue-attributes --queue-url your-dlq-url --attribute-names QueueArn

Se for bem-sucedido, você verá o ARN da fila na saída.

{
    "Attributes": {
        "QueueArn": "arn:aws:sqs:us-west-2:123456789012:scheduler-dlq-test"
    }
}

Na próxima seção, você adicionará as permissões necessárias à sua função de execução do cronograma para permitir que o EventBridge Scheduler entregue eventos sem saída para o Amazon SQS.

Configure as permissões da função de execução

Para permitir que o EventBridge Scheduler entregue eventos com data limite para o Amazon SQS, sua função de execução do cronograma precisa da seguinte política de permissão. Para obter mais informações sobre como anexar uma nova política de permissão à sua função de execução do cronograma, consulte Configurando a função de execução.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Action": [
                "sqs:SendMessage"
            ],
            "Effect": "Allow",
            "Resource": "*"
        }
    ]
}

nota

Sua função de execução do cronograma pode já ter as permissões necessárias anexadas se você usar o EventBridge Scheduler para invocar um alvo de API do Amazon SQS.

Na próxima seção, você usará o console do EventBridge Scheduler e especificará uma DLQ para sua agenda.

Especificar uma fila de mensagens mortas

Para especificar uma DLQ, use o console do EventBridge Scheduler ou o AWS CLI para atualizar uma agenda existente ou criar uma nova.

Console

Para especificar uma DLQ usando o console

1. Faça login no AWS Management Console e, em seguida, escolha o link a seguir para abrir a seção EventBridge Scheduler do console EventBridge: https://console.aws.amazon.com/scheduler/home

2. No console do EventBridge Scheduler, crie um novo agendamento ou escolha um agendamento existente na sua lista de agendamentos para edição.

3. Na página Configurações, para a fila de mensagens não entregues (DLQ), faça o seguinte:

   • Escolha Selecionar uma fila do Amazon SQS em minha conta de AWS como DLQ e, em seguida, escolha o ARN da fila para seu DLQ na lista suspensa.

   • Escolha Especificar uma fila do Amazon SQS em outras contas de AWS como DLQ e, em seguida, insira o ARN da fila para sua DLQ. Se você escolher uma fila em outra conta de AWS, o console do EventBridge Scheduler não poderá exibir os ARNs da fila em uma lista suspensa.

4. Revise suas seleções e escolha Criar agenda ou Salvar agenda para concluir a configuração de uma DLQ.

5. (Opcional) Para ver os detalhes do DLQ de um cronograma, escolha o nome do agendamento na lista e, em seguida, escolha a guia fila de mensagens não entregues na página de detalhes do cronograma.

AWS CLI

Para atualizar um agendamento existente, utilizando o AWS CLI

• Use o comando update-schedule para atualizar sua agenda. Especifique a fila do Amazon SQS que você criou anteriormente como DLQ. Especifique o ARN da função do IAM ao qual você anexou as permissões necessárias do Amazon SQS como função de execução. Substitua todos os outros valores de espaço reservado por suas informações.

  $ aws scheduler update-schedule --name existing-schedule \
      --schedule-expression 'rate(5 minutes)' \
      --target '{"DeadLetterConfig": {"Arn": "DLQ_ARN"}, "RoleArn": "ROLE_ARN", "Arn":"QUEUE_ARN", "Input": "Hello world!" }' \
      --flexible-time-window '{ "Mode": "OFF"}'

Para criar uma novo agendamento com um DLQ usando o AWS CLI

• Para criar um agendamento, use o comando create-schedule. Substitua todos os valores de espaço reservado por suas informações.

  $ aws scheduler create-schedule --name new-schedule \
      --schedule-expression 'rate(5 minutes)' \
      --target '{"DeadLetterConfig": {"Arn": "DLQ_ARN"}, "RoleArn": "ROLE_ARN", "Arn":"QUEUE_ARN", "Input": "Hello world!" }' \
      --flexible-time-window '{ "Mode": "OFF"}'

Na próxima seção, você usará o AWS CLI para receber um evento de mensagens não entregues do DLQ.

Recuperar o evento de mensagens mortas

Use o comando receive-message, conforme mostrado a seguir, para recuperar um evento de letra morta do DLQ. Você pode definir o número de mensagens a serem recuperadas usando o atributo --max-number-of-messages.

$ aws sqs receive-message --queue-url your-dlq-url --attribute-names All --message-attribute-names All --max-number-of-messages 1

Se for bem-sucedido, você verá uma saída semelhante à seguinte.

{
    "Messages": [
        {
            "MessageId": "2aeg3510-fe3a-4f5a-ab6a-6906560eaf7e",
            "ReceiptHandle": "AQEBkNKTdOMrWgHKPoITRBwrPoK3eCSZIcZwVqCY0BZ+FfTcORFpopJbtCqj36VbBTlHreM8+qM/m5jcwqSlAlGmIJO/hYmMgn/+dwIty9izE7HnpvRhhEyHxbeTZ5V05RbeasYaBdNyi9WLcnAHviDh6MebLXXNWoFyYNsxdwJuG0f/w3htX6r3dxpXvvFNPGoQb8ihY37+u0gtsbuIwhLtUSmE8rbldEEwiUfi3IJ1zEZpUS77n/k1GWrMrnYg0Gx/BuaLzOrFi2F738XI/Hnh45uv3ca6OYwS1ojPQ1LtX2URg1haV5884FYlaRvY8jRlpCZabTkYRTZKSXG5KNgYZnHpmsspii6JNkjitYVFKPo0H91w5zkHlSx3REAuWk7m3r7PmOMvTNPMhctbD3CkTw==",
            "MD5OfBody": "07adc3fc889d6107d8bb8fda42fe0573",
            "Body": "{\"MessageBody\":\"Hello, world!",\"QueueUrl\":\"https://sqs.us-west-2.amazonaws.com/123456789012/does-not-exist\"}",
            "Attributes": {
                "SenderId": "AROA2DZE3W4CTL5ZR7EIN:ff00212d8c453aaaae644bc6846d4723",
                "ApproximateFirstReceiveTimestamp": "1652499058144",
                "ApproximateReceiveCount": "2",
                "SentTimestamp": "1652490733042"
            },
            "MD5OfMessageAttributes": "f72c1d78100860e00403d849831d4895",
            "MessageAttributes": {
                "ERROR_CODE": {
                    "StringValue": "AWS.SimpleQueueService.NonExistentQueue",
                    "DataType": "String"
                },
                "ERROR_MESSAGE": {
                    "StringValue": "The specified queue does not exist for this wsdl version.",
                    "DataType": "String"
                },
                "EXECUTION_ID": {
                    "StringValue": "ad06616e51cdf74a",
                    "DataType": "String"
                },
                "EXHAUSTED_RETRY_CONDITION": {
                    "StringValue": "MaximumEventAgeInSeconds",
                    "DataType": "String"
                }
                "IS_PAYLOAD_TRUNCATED": {
                    "StringValue": "false",
                    "DataType": "String"
                },
                "RETRY_ATTEMPTS": {
                    "StringValue": "0",
                    "DataType": "String"
                },
                "SCHEDULED_TIME": {
                    "StringValue": "2022-05-14T01:12:00Z",
                    "DataType": "String"
                },
                "SCHEDULE_ARN": {
                    "StringValue": "arn:aws:scheduler:us-west-2:123456789012:schedule/DLQ-test",
                    "DataType": "String"
                },
                "TARGET_ARN": {
                    "StringValue": "arn:aws:scheduler:::aws-sdk:sqs:sendMessage",
                    "DataType": "String"
                }
            }
        }
    ]
}

Observe os atributos a seguir no evento de carta morta para ajudá-lo a identificar e solucionar possíveis motivos pelos quais a inovação do alvo falhou.

• ERROR_CODE — Contém o código de erro que o EventBridge Scheduler recebe da API de serviço do alvo. No exemplo anterior, o código de erro retornado pelo Amazon SQS é AWS.SimpleQueueService.NonExistentQueue. Se o agendamento falhar ao invocar um alvo devido a um problema com o EventBridge Scheduler, você verá o seguinte código de erro em vez disso: AWS.Scheduler.InternalServerError.

• ERROR_MESSAGE — Contém o código de erro que o EventBridge Scheduler recebe da API de serviço do alvo. No exemplo anterior, a mensagem de erro retornada pelo Amazon SQS é The specified queue does not exist for this wsdl version. Se o agendamento falhar devido a um problema com o EventBridge Scheduler, você verá a seguinte mensagem de erro em vez disso: Unexpected error occurred while processing the request.

• TARGET_ARN — O ARN do alvo que sua agenda invoca, no seguinte formato de ARN de serviço: arn:aws:scheduler:::aws-sdk:service:apiAction.

• EXHAUSTED_RETRY_CONDITION — Indica por que o evento foi entregue ao DLQ. Esse atributo estará presente se o erro da API-alvo for um erro que pode ser repetido e não permanente. O atributo pode conter os valores MaximumRetryAttempts se o EventBridge Scheduler o tiver enviado para a DLQ depois de exceder o máximo de tentativas que você configurou para o agendamento ou MaximumEventAgeInSeconds, se o evento for maior que a idade máxima que você configurou no agendamento e ainda não está sendo entregue.

No exemplo anterior, podemos determinar, com base no código de erro e na mensagem de erro, que a fila de alvo que especificamos para o agendamento não existe.