本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# Amazon EventBridge 管道錯誤處理和故障排除
了解 EventBridge 管道可能遇到的錯誤類型，以及 EventBridge 如何處理這些錯誤，可協助您疑難排解管道的問題。
## 重試行為和錯誤處理
針對來源服務、擴充或目標服務或 EventBridge 的任何可重試 AWS 失敗，EventBridge 管道會自動重試擴充和目標調用。但是，如果擴充或目標客戶實作傳回失敗，則管道輪詢輸送量將逐漸退回。針對幾乎連續的 4xx 錯誤 (例如 IAM 的授權問題或缺少資源)，管道可以自動停用，並在 `StateReason` 中帶有解釋訊息。
## 管道調用錯誤和重試行為
當您調用管道時，可能會發生兩種主要類型的錯誤：*管道內部錯誤*和*客戶調用錯誤*。
### 管內部錯誤
管道內部錯誤是由 EventBridge 管道服務管理的調用方面所造成的錯誤。
這些類型的錯誤可能包括以下問題：
+ 嘗試叫用客戶目標服務時發生 HTTP 連線失敗
+ 管道服務本身的可用性暫時下降。
一般而言，EventBridge 管道會無限次重試內部錯誤，並且只有在來源中的記錄到期時才會停止。
針對具有串流來源的管道，EventBridge Pipes 不會將內部錯誤的重試次數與串流來源的重試政策上指定的最大重試次數計算。針對具有 Amazon SQS 來源的管道，EventBridge 管道不會將內部錯誤的重試次數與 Amazon SQS 來源的最大接收次數計算。
### 客戶調用錯誤
客戶調用錯誤是由用戶管理的配置或代碼引起的錯誤。
這些類型的錯誤可能包括以下問題：
+ 管道的權限不足，無法調用目標。
+ 同步調用的客戶 Lambda、Step Functions、API 目標或 API Gateway 端點中的邏輯錯誤。
針對客戶調用錯誤，EventBridge 管道會執行下列動作：
+ 針對具有串流來源的管道，EventBridge 管道會重試直到管道重試原則上設定的重試次數上限，或直到記錄保留天數上限到期為止 (以先到者為準)。
+ 針對具有 Amazon SQS 來源的管道，EventBridge 管道會重試客戶錯誤，直到來源佇列上的最大接收計數為止。
+ 針對具有 Apache Kafka 或 Amazon MQ 來源的管道，EventBridge 會重試客戶錯誤，因為它會重試內部錯誤。
針對具有計算目標的管道，您必須同步調用管道，以便 EventBridge 管道知道從客戶計算邏輯擲回的任何執行期錯誤，然後重試此類錯誤。管道無法重試從 Step Functions 標準工作流程邏輯擲回的錯誤，因為必須以非同步方式調用此目標。
針對 Amazon SQS 和串流來源，例如 Kinesis 和 DynamoDB，EventBridge 管道支援目標故障的部分批次失敗處理。如需詳細資訊，請參閱[部分批次失敗](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-pipes-batching-concurrency.html#pipes-partial-batch-failure)。
## 使用 maxBatchWindowInSeconds 的 Amazon SQS 來源重試計時
使用 Amazon SQS 佇列做為管道來源時，重試時間行為會因您是否設定 `maxBatchWindowInSeconds` 參數而有所不同：
+ **沒有 maxBatchWindowInSeconds** – SQS 輪詢器會使用佇列的可見性逾時設定進行重試。當處理失敗時，訊息會在可見性逾時持續時間內保持隱藏狀態，之後才可供重試。若要減少重試延遲，請將佇列的可見性逾時設定為適合您使用案例的適當值。
+ **使用 maxBatchWindowInSeconds** – SQS 輪詢器會使用公式動態設定輪詢訊息的可見性逾時：`functionTimeout + maxBatchWindowInSeconds + 30 seconds`。對於 EventBridge 管道，函數逾時為 7 分鐘，導致可見性逾時約為 7.5 分鐘加上您設定`maxBatchWindowInSeconds`的值。當處理失敗時，訊息會在此延長的持續時間內保持隱藏狀態，然後可供重試。
此行為在使用[部分批次回應](eb-pipes-batching-concurrency.md#pipes-partial-batch-failure)時特別相關。如果您需要更快的重試時間，請避免設定 `maxBatchWindowInSeconds` ，而是依賴佇列設定的可見性逾時。
## 管道 DLQ 行為
管道從來源繼承無效字母佇列 (DLQ) 行為：
+ 如果來源 Amazon SQS 佇列具有已設定的 DLQ，則訊息會在指定的嘗試次數後自動傳送至該處。
+ 針對串流來源，例如 DynamoDB 和 Kinesis 串流，您可以為管道和路由事件設定 DLQ。DynamoDB 和 Kinesis 串流來源支援 Amazon SQS 佇列和 Amazon SNS 主題做為 DLQ 目標。
如果您為具有 Kinesis 或 DynamoDB 來源的管路指定 `DeadLetterConfig`，請確定管道上的 `MaximumRecordAgeInSeconds` 屬性小於來源事件的 `MaximumRecordAge` 屬性。`MaximumRecordAgeInSeconds` 控制管道輪詢器何時放棄事件並將其傳遞給 DLQ，並且 `MaximumRecordAge` 控制在源流中可見的消息多長時間才被刪除。因此，請設定 `MaximumRecordAgeInSeconds` 為小於 `MaximumRecordAge` 來源的值，以便在事件傳送至 DLQ 之間有足夠的時間，以及來源自動刪除，以便您判斷事件為何進入 DLQ。
`MaximumRecordAgeInSeconds` 參數獨立於重試行為套用。輪詢串流來源時，如果記錄的存留期超過 `MaximumRecordAgeInSeconds`值，EventBridge 管道將不會處理該記錄，無論是否存在重試情況。這些記錄會直接傳送至 DLQ （如果已設定），無需任何處理嘗試。
針對 Amazon MQ 來源，DLQ 可以直接在訊息代理程式上設定。
EventBridge 管道不支援串流來源的先進先出 (FIFO) DLQ。
EventBridge 管道不支援 Amazon MSK 串流和自我管理的 Apache Kafka 串流來源的 DLQ。
## 管路故障狀態
建立、刪除和更新管道是非同步作業，可能會導致失敗狀態。同樣地，管道可能會因故障而自動停用。在所有情況下，管道 `StateReason` 都會提供協助疑難排解故障的資訊。
以下是 `StateReason` 可能值的清單範例：
+ 找不到串流。若要繼續處理，請刪除並建立新的管道。
+ 管道沒有執行佇列作業所需的權限 (sqs:ReceiveMessage, sqs:DeleteMessage and sqs:GetQueueAttributes)
+ 連線錯誤。您的 VPC 必須能夠連線至管道。您可以透過將 NAT 閘道或 VPC 端點設定為 pipes-data 來提供存取權。如需如何將 NAT 閘道或 VPC 端點設定為 pipes-data，請檢查 AWS 文件。
+ MSK 叢集沒有與其相關聯的安全群組
管道可能會隨著更新而自動停止 `StateReason`。可能的原因包括：
+ 設定為[擴充](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-pipes.html#pipes-enrichment)的 Step Functions 標準工作流程。
+ 設定為要[同步調用](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-pipes.html#pipes-invocation)之目標的「步驟函數」標準工作流程。
## 自訂加密失敗
如果您將來源設定為使用 AWS KMS 自訂加密金鑰 (CMK)，而不是 AWS受管 AWS KMS 金鑰，則必須明確授予管道的執行角色解密許可。若要這麼做，請在自訂 CMK 原則中包含下列額外權限：
```
{
"Sid": "Allow Pipes access",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::01234567890:role/service-role/Amazon_EventBridge_Pipe_DDBStreamSourcePipe_12345678"
},
"Action": "kms:Decrypt",
"Resource": "*"
}
```
將上述角色替換為管道的執行角色。
接著，請確定 KMS 的相同許可已新增至您的管道執行角色。
這適用於具有 CMK AWS KMS 的所有管道來源，包括：
+ Amazon DynamoDB Streams
+ Amazon Kinesis Data Streams
+ Amazon MQ
+ Amazon MSK
+ Amazon SQS