Amazon SQS キューを作成する実行ロールのアクセス許可を設定するデッドレターキューを指定するデッドレターイベントの取得

スケジュールのデッドレターキューを設定する

Amazon EventBridge スケジューラでは、Amazon Simple Queue Service を使用してデッドレターキュー (DLQ) をサポートしています。スケジュールがターゲットの呼び出しに失敗した場合、EventBridge スケジューラは、呼び出しの詳細とターゲットから受信した応答を含む JSON ペイロードを、指定された Amazon SQS 標準キューに配信します。

次のトピックでは、この JSON をデッドレターイベントと呼んでいます。デッドレターイベントを使用すると、スケジュールやターゲットに関する問題をトラブルシューティングできます。スケジュールに再試行ポリシーを設定すると、EventBridge スケジューラは、設定された最大再試行回数を使い切ったデッドレターイベントを配信します。

以下のトピックでは、Amazon SQS キューをスケジュールの DLQ として設定する方法、EventBridge スケジューラが Amazon SQS にメッセージを配信するために必要な権限を設定する方法、および DLQ からデッドレターイベントを受信する方法について説明します。

Amazon SQS キューを作成する

スケジュールに DLQ を設定する前に、標準の Amazon SQS キューを作成する必要があります。Amazon SQS コンソールを使用してキューを作成する手順については、「Amazon Simple Queue Service デベロッパーガイド」の「Amazon SQS キューの作成」を参照してください。

注記

EventBridge スケジューラは、スケジュールの DLQ として FIFO キューを使用することをサポートしていません。

以下の AWS CLI コマンドを使用して標準キューを作成します。


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

成功すると、出力に QueueURL が表示されます。

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

キューを作成したら、キュー ARN を書き留めておきます。EventBridge スケジューラのスケジュールに DLQ を指定するときに、ARN が必要になります。キュー ARN は Amazon SQS コンソールから、または get-queue-attributesAWS CLI コマンドを使用して確認できます。


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

成功すると、出力にキュー ARN が表示されます。

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

次のセクションでは、スケジュール実行ロールに必要なアクセス権限を追加して、EventBridge スケジューラがデッドレターイベントを Amazon SQS に配信できるようにします。

実行ロールのアクセス許可を設定する

EventBridge スケジューラがデッドレターイベントを Amazon SQS に配信できるようにするには、スケジュール実行ロールに以下のアクセス権限ポリシーが必要です。スケジュール実行ロールに新しいアクセス権限ポリシーをアタッチする方法の詳細については、「実行ロールの設定」を参照してください。


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

注記

EventBridge スケジューラを使用して Amazon SQS API ターゲットを呼び出す場合、スケジュール実行ロールには必要な権限がすでにアタッチされている可能性があります。

次のセクションでは、EventBridge スケジューラのコンソールを使用して、スケジュールの DLQ を指定します。

デッドレターキューを指定する

DLQ を指定するには、EventBridge スケジューラのコンソールまたは AWS CLI を使用して既存のスケジュールを更新するか、新しいスケジュールを作成します。

Console

コンソールを使用して DLQ を指定する方法

AWS Management Console にサインインし、次のリンクを選択して EventBridge コンソールの EventBridge スケジューラのセクションを開きます: https://console.aws.amazon.com/scheduler/home
EventBridge スケジューラのコンソールで、新しいスケジュールを作成するか、スケジュールのリストから既存のスケジュールを選択して編集します。
[設定] ページの [デッドレターキュー (DLQ)] で、次のいずれかを実行します。
- [自分の AWS アカウントの Amazon SQS キューを DLQ として選択] を選択し、ドロップダウンリストから DLQ のキュー ARN を選択します。
- [他の AWS アカウントの Amazon SQS キューを DLQ として指定] を選択し、DLQ のキュー ARN を入力します。別の AWS アカウントのキューを選択した場合、EventBridge スケジューラのコンソールはキュー ARN をドロップダウンリストに表示できません。
選択内容を確認し、[スケジュールを作成] または [スケジュールを保存] を選択して DLQ の設定を完了します。
(オプション) スケジュールの DLQ の詳細を表示するには、一覧からスケジュールの名前を選択し、[スケジュール詳細] ページの [デッドレターキュー] タブを選択します。

AWS CLI

AWS CLI を使用して既存のスケジュールを更新する方法

update-schedule コマンドを使用してスケジュールを更新します。以前に作成した Amazon SQS キューを DLQ として指定します。必要な Amazon SQS アクセス権限をアタッチした IAM ロール ARN を実行ロールとして指定します。他のすべてのプレースホルダー値を、ユーザー自身の情報に置き換えます。
```
$ 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"}'
```

AWS CLI を使用して DLQ を使用して新しいスケジュールを作成する方法

スケジュールを作成するには、create-schedule コマンドを使用します。すべてのプレースホルダー値を、ユーザー自身の情報に置き換えます。


$ 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"}'

次のセクションでは、AWS CLI を使用して DLQ からデッドレターイベントを受信します。

デッドレターイベントの取得

次に示す receive-message コマンドを使用して、DLQ からデッドレターイベントを取得します。--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

成功すると、次のような出力が表示されます。

{
    "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"
                }
            }
        }
    ]
}

デッドレターイベントの以下の属性に注目しておくと、ターゲットの呼び出しが失敗した原因として考えられるものの特定とトラブルシューティングに役立ちます。

ERROR_CODE — EventBridge スケジューラがターゲットのサービス API から受け取るエラーコードが含まれます。前述の例では、Amazon SQS によって返されるエラーコードは AWS.SimpleQueueService.NonExistentQueue です。EventBridge スケジューラの問題によりスケジュールがターゲットの呼び出しに失敗した場合、代わりに次のエラーコードが表示されます: AWS.Scheduler.InternalServerError
ERROR_MESSAGE — EventBridge スケジューラがターゲットのサービス API から受け取るエラーメッセージが含まれます。前述の例では、Amazon SQS によって返されるエラーメッセージは The specified queue does not exist for this wsdl version です。EventBridge スケジューラの問題によりスケジュールが失敗した場合、代わりに次のエラーメッセージが表示されます: Unexpected error occurred while processing the request
TARGET_ARN — スケジュールが呼び出すターゲットの ARN。サービス ARN 形式は次のとおりです: arn:aws:scheduler:::aws-sdk:service:apiAction
EXHAUSTED_RETRY_CONDITION — イベントが DLQ に配信された理由を示します。この属性は、ターゲット API からのエラーが永続的なエラーではなく、再試行可能なエラーである場合に表示されます。この属性には、スケジュールに設定した最大再試行回数を超えた後に EventBridge スケジューラが DLQ に送信した場合は MaximumRetryAttempts の値、またはイベントがスケジュールに設定した最大経過時間よりも古く、依然として配信に失敗している場合は MaximumEventAgeInSeconds の値が含まれる場合があります。

前の例では、エラーコードとエラーメッセージに基づいて、スケジュールに指定したターゲットキューが存在しないと判断できます。

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

柔軟な時間枠の設定

スケジュールの削除