對 S3 Batch Operations 進行故障診斷 - Amazon Simple Storage Service
NoSuchJobExceptionInvalidManifestContent

對 S3 Batch Operations 進行故障診斷

Amazon S3 Batch Operations 可讓您對 Amazon S3 物件執行大規模的操作。本指南可協助您針對可能遇到的常見問題進行故障診斷。

若要對 S3 批次複寫問題進行故障診斷，請參閱故障排除複寫。

有兩種主要類型的失敗會導致 Batch Operations 錯誤：

  1. API 失敗 – 請求的 API (例如 CreateJob) 無法執行。

  2. 作業失敗 – 初始 API 請求成功，但作業失敗，例如由於資訊清單或資訊清單中指定物件的權限問題。

NoSuchJobException

類型：API 失敗

當 S3 Batch Operations 找不到指定的任務時，就會發生 NoSuchJobException。此錯誤可能發生在簡單任務過期後的幾個案例中。常見原因包括下列項目。

  1. 任務過期 – 在達到結束狀態 (Complete、Cancelled 或 Failed) 的 90 天後，任務會自動刪除。

  2. 不正確的任務 ID – 用於 DescribeJob 或 UpdateJobStatus 的任務 ID 與 CreateJob 傳回的 ID 不相符。

  3. 區域錯誤 – 嘗試存取與建立任務之不同區域中的任務。

  4. 帳戶錯誤 – 使用來自不同 AWS 帳戶的任務 ID。

  5. 任務 ID 格式錯誤 – 任務 ID 中的錯字、額外的字元或不正確的格式。

  6. 時序問題 – 在建立任務後立即檢查任務狀態，然後再完整註冊任務。

相關的錯誤訊息包括下列項目。

  1. No such job

  2. The specified job does not exist

防止 NoSuchJobException API 失敗的最佳實務

  1. 立即儲存任務 ID – 在進行後續 API 呼叫之前，從 CreateJob 回應儲存任務 ID。

  2. 實作重試邏輯 – 在建立後立即檢查任務狀態時新增指數退避。

  3. 設定監控 – 建立 CloudWatch 警示，以在 90 天過期前追蹤直到任務完成。如需詳細資訊，請參閱《Amazon CloudWatch 使用者指南》中的使用 Amazon CloudWatch 警示。

  4. 使用一致的區域 – 確保所有任務操作都使用與任務建立相同的區域。

  5. 驗證輸入 – 在進行 API 呼叫之前檢查任務 ID 格式。

當任務到期

處於終端狀態的任務，會在 90 天後自動刪除。若要避免遺失任務資訊，請考量下列事項。

  1. 過期前下載完成報告 – 如需擷取和儲存任務結果的指示，請參閱 。

  2. 在您自己的系統中封存任務中繼資料 – 將關鍵任務資訊儲存在資料庫或監控系統中。

  3. 設定 90 天截止日期之前自動通知 – 使用 Amazon EventBridge 建立規則，在任務完成時觸發通知。如需更多詳細資訊，請參閱 Amazon S3 事件通知。

NoSuchJobException對 進行故障診斷

  1. 使用下列命令驗證任務存在於您的帳戶和區域中。

    
aws s3control list-jobs --account-id 111122223333 --region us-east-1

  2. 使用下列命令搜尋所有任務狀態。可能的任務狀態包括 Active、Cancelled、Cancelling、Complete、Completing、Failed、Failing、New、Paused、Pausing、Preparing、Ready 和 Suspended。

    
aws s3control list-jobs --account-id 111122223333 --job-statuses your-job-status

  3. 使用下列命令檢查任務是否存在於您通常建立任務的其他區域中。

    
aws s3control list-jobs --account-id 111122223333 --region job-region-1 aws s3control list-jobs --account-id 111122223333 --region job-region-2

  4. 驗證任務 ID 格式。任務 ID 通常包含 36 個字元，例如 12345678-1234-1234-1234-123456789012。檢查是否有額外的空格、缺少的字元或區分大小寫的問題，並確認您使用的是 CreateJob 命令傳回的完整任務 ID。

  5. 使用下列命令，檢查 CloudTrail 日誌是否有任務建立事件。

    
    aws logs filter-log-events --log-group-name CloudTrail/S3BatchOperations \ --filter-pattern "{ $.eventName = CreateJob }" \ --start-time timestamp

AccessDeniedException

類型：API 失敗

當 S3 Batch Operations 請求因權限不足、不受支援的操作或政策限制而遭到封鎖時，就會發生 AccessDeniedException。這是 Batch Operations 中最常見的錯誤之一。它有下列常見原因：

  1. 缺少 IAM 許可 – IAM 身分缺少 Batch Operations API 的必要權限。

  2. S3 權限不足 – 缺少存取來源或目的地儲存貯體和物件的權限。

  3. 任務執行角色問題 – 任務執行角色缺少執行指定操作的權限。

  4. 不支援的操作 – 嘗試使用目前區域或儲存貯體類型中不支援的操作。

  5. 跨帳戶存取權問題 – 缺少跨帳戶儲存貯體或物件存取的權限。

  6. 資源型政策限制 – 儲存貯體政策或物件 ACL 封鎖操作。

  7. 服務控制政策 (SCP) 限制 – 防止操作的組織層級政策。

相關錯誤訊息：

  1. Access Denied

  2. User: arn:aws:iam::account:user/username is not authorized to perform: s3:operation

  3. Cross-account pass role is not allowed

  4. The bucket policy does not allow the specified operation

防止 AccessDeniedException API 失敗的最佳實務

  1. 使用最低權限原則 – 僅授予特定操作所需的最低權限。

  2. 在大型任務之前測試權限 – 在處理數千個物件之前，執行小型測試任務來驗證權限。

  3. 使用 IAM 政策模擬器 – 使用 IAM 政策模擬器在部署之前測試政策。如需詳細資訊，請參閱《IAM 使用者指南》中的使用 IAM 政策模擬器測試 IAM 政策。

  4. 實作適當的跨帳戶設定 – 檢查您的跨帳戶存取權組態是否有跨帳戶任務組態。如需詳細資訊，請參閱《IAM 使用者指南》中的 IAM 教學課程：使用 IAM 角色跨 AWS 委派存取權。

  5. 監控許可權變更 – 設定可能影響 Batch Operations 的 IAM 政策修改的 CloudTrail 警示。

  6. 文件角色需求 – 維護每個任務類型所需許可權的明確文件。

  7. 使用常見許可權範本 - 使用許可權範例和政策範本：

    1. 授予批次操作的許可

    2. 《IAM 使用者指南》中的 IAM 中的跨帳戶資源。

    3. 《AWS PrivateLink 指南》中的使用端點政策控制對 VPC 端點的存取。

AccessDeniedException 疑難排解

依照下列步驟，有系統地識別和解決許可權問題。

  1. 依區域檢查 S3 批次操作支援的操作 中受支援的操作。確認僅區域和區域端點有提供目錄儲存貯體操作。確認儲存貯體的儲存類別是否支援該操作。

  2. 使用以下命令判斷您是否可以列出任務。

    
 aws s3control list-jobs --account-id 111122223333

  3. 使用下列命令檢查請求身分的 IAM 許可。執行任務的帳戶需要下列許可權：s3:CreateJob、s3:DescribeJob、s3:ListJobs-s3:UpdateJobPriority、s3:UpdateJobStatus-iam:PassRole。

    
aws sts get-caller-identity 111122223333

  4. 使用下列命令檢查角色是否存在，且是否可承擔。

    
aws iam get-role --role-name role-name

  5. 使用下列命令檢閱角色的信任政策。執行任務的角色必須具有下列項目：

    1. 信任關係可讓 batchoperations.s3.amazonaws.com 承擔角色。

    2. 批次操作功能正在執行的操作 (例如用於標記操作的 s3:PutObjectTagging)。

    3. 來源與目的地儲存貯體的存取權。

    4. 讀取資訊清單檔案的許可權。

    5. 寫入完成報告的許可權。

    
aws iam get-role --role-name role-name --query 'Role.AssumeRolePolicyDocument'

  6. 使用下列命令以靜態存取資訊清單和來源儲存貯體。

    
aws s3 ls s3://bucket-name

  7. 測試批次操作功能正在執行的操作。例如，若批次操作在執行標記作業，請在來源儲存貯體中標記範例物件。

  8. 檢閱儲存貯體政策是否有可能拒絕操作的政策。

    1. 如果使用舊版存取控制，請檢查物件 ACL。

    2. 確認沒有服務控制政策 (SCP) 在封鎖操作。

    3. 如果使用 VPC 端點，請確認 VPC 端點政策允許 Batch Operations。

  9. 使用下列命令，以使用 CloudTrail 識別許可權失敗。

    
aws logs filter-log-events --log-group-name CloudTrail/S3BatchOperations \
    --filter-pattern "{ $.errorCode = AccessDenied }" \
    --start-time timestamp

SlowDownError

類型：API 失敗

當您的帳戶超出 S3 Batch Operations API 的請求率限制時，就會發生 SlowDownError 例外狀況。這是一種限流機制，可保護服務不受太多請求的影響。它有下列常見原因：

  1. 高 API 請求頻率 – 在短時間內進行太多 API 呼叫。

  2. 並行任務操作 – 多個應用程式或使用者同時建立/管理任務。

  3. 無速率限制的自動化指令碼 – 未實作適當退避策略的指令碼。

  4. 輪詢任務狀態太頻繁 – 檢查任務狀態的頻率過高。

  5. 高載流量模式 – 在尖峰處理時間期間 API 用量突然暴增。

  6. 區域容量限制 – 超出您區域的分配請求容量。

相關錯誤訊息：

  1. SlowDown

  2. Please reduce your request rate

  3. Request rate exceeded

防止 SlowDownError API 失敗的最佳實務

  1. 實作用戶端速率限制 – 在應用程式中新增 API 呼叫之間的延遲。

  2. 使用指數退避與抖動 – 隨機重試延遲，以避免發生驚群問題。

  3. 設定適當的重試邏輯 – 針對暫時性誤差實作自動重試，並逐漸增加重試延遲。

  4. 使用事件驅動的架構 – 以 EventBridge 通知取代輪詢，以取得作業狀態變更資訊。

  5. 將負載分散到不同時段 – 錯開作業建立和狀態檢查的時段。

  6. 監控和發出速率限制警示 – 設定 CloudWatch 警示，以便在接近限制時進行偵測。

大多數 AWS SDK 都包含用於速率限制錯誤的內建重試邏輯。設定如下：

  1. AWS CLI – 使用 cli-read-timeout 和 cli-connect-timeout 參數。

  2. AWS SDK for Python (Boto3) – 在用戶端組態中設定重試模式和嘗試次數上限。

  3. 適用於 Java 的 AWS SDK – 使用 RetryPolicy 和 ClientConfiguration 設定。

  4. 適用於 JavaScript 的 AWS SDK – 設定 maxRetries 和 retryDelayOptions。

如需有關重試模式和最佳實務的詳細資訊，請參閱《AWS 方案指引指南》中的使用退避模式重試。

SlowDownError 疑難排解

  1. 在您的程式碼中，立即實作指數退避。

    範例 bash 的指數退避範例
    
for attempt in {1..5}; do
    if aws s3control describe-job --account-id 111122223333 --job-id job-id; then 
        break
    else 
        wait_time=$((2**attempt)) echo "Rate limited, waiting ${wait_time} seconds..." sleep $wait_time
        fi
done

  2. 使用 CloudTrail 識別高請求量的來源。

    
aws logs filter-log-events \
    --log-group-name CloudTrail/S3BatchOperations \
    --filter-pattern "{ $.eventName = CreateJob || $.eventName = DescribeJob }" \
    --start-time timestamp \
    --query 'events[*].[eventTime,sourceIPAddress,userIdentity.type,eventName]'

  3. 檢閱輪詢頻率。

    1. 避免每 30 秒檢查一次作用中任務的作業狀態。

    2. 盡可能使用任務完成通知，而不是輪詢。

    3. 在輪詢間隔中實作抖動，以避免出現同步請求。

  4. 最佳化您的 API 使用模式。

    1. 盡可能批次進行多個操作。

    2. 使用 ListJobs 在一次呼叫中取得多個任務的狀態。

    3. 快取任務資訊以減少備援 API 呼叫。

    4. 分散在不同時間建立任務，而不是同時建立多個任務。

  5. 使用 API 呼叫的 CloudWatch 指標監控您的請求模式。

    
   aws logs put-metric-filter \
       --log-group-name CloudTrail/S3BatchOperations \
       --filter-name S3BatchOpsAPICallCount \      
       --filter-pattern "{ $.eventSource = s3.amazonaws.com && $.eventName = CreateJob }" \
       --metric-transformations \        
       metricName=S3BatchOpsAPICalls,metricNamespace=Custom/S3BatchOps,metricValue=1

InvalidManifestContent

類型：任務失敗

當資訊清單檔案格式、內容或結構發生問題，導致 S3 Batch Operations 無法處理任務時，就會發生 InvalidManifestContent 例外狀況。它有下列常見原因：

  1. 格式不符 – 缺少必要欄、不正確的分隔符號或格式不正確的 CSV 結構。

  2. 內容編碼問題 – 字元編碼不正確、BOM 標記或非 UTF-8 字元。

  3. 物件索引鍵問題 – 無效的字元、不正確的 URL 編碼，或索引鍵超出長度限制。

  4. 大小限制 – 資訊清單包含的物件數量超出作業支援的數量。

  5. 版本 ID 格式錯誤 – 版本控制物件的版本 ID 格式不正確或無效。

  6. ETag 格式問題 – 需要 ETag 之操作的 ETags 格式不正確或缺少引號。

  7. 不一致的資料 – 相同資訊清單中混用不同格式，或者欄數不一致。

相關錯誤訊息：

  1. Required fields are missing in the schema: + missingFields

  2. Invalid Manifest Content

  3. The S3 Batch Operations job failed because it contains more keys than the maximum allowed in a single job

  4. Invalid object key format

  5. Manifest file is not properly formatted

  6. Invalid version ID format

  7. ETag format is invalid

可防止 InvalidManifestContent 任務失敗的最佳實務

  1. 上傳前驗證 – 在處理大型資料集之前，使用小型任務測試資訊清單格式。

  2. 使用一致的編碼 – 資訊清單檔案一律使用不含 BOM 的 UTF-8 編碼。

  3. 實作資訊清單產生標準 – 建立用於建立資訊清單的範本和驗證程序。

  4. 正確處理特殊字元 – 包含特殊字元的 URL 編碼物件索引鍵。

  5. 監控物件計數 – 主動追蹤資訊清單大小，並分割大型任務。

  6. 驗證物件存在 – 在資訊清單中包含物件之前，先驗證物件是否存在。

  7. 使用 AWS 工具產生資訊清單 – 利用 AWS CLI s3api list-objects-v2 產生格式正確的物件清單。

常見資訊清單問題與解決方案：

  1. 缺少必要欄 – 確保您的資訊清單包含操作類型的所有必要欄。最常見的遺失欄是儲存貯體和索引鍵。

  2. CSV 格式不正確 – 使用逗號分隔符號，確保所有列的欄數一致，並避免欄位中有嵌入換行符號。

  3. 物件索引鍵中的特殊字元 – URL 編碼物件索引鍵，其中包含空格、Unicode 字元或 XML 特殊字元 (＜、＞、&、"、')。

  4. 大型資訊清單檔案 – 將超出操作限制的資訊清單分割成多個較小的資訊清單，並建立個別任務。

  5. 無效的版本 ID – 確保版本 ID 是格式正確的英數字元字串。如果不需要，請移除版本 ID 欄。

  6. 編碼問題 – 將資訊清單檔案儲存為不含 BOM 的 UTF-8 格式。避免透過可能改變編碼的系統複製資訊清單。

如需詳細的資訊清單格式規格和範例，請參閱下列內容：

  1. 指定資訊清單

  2. S3 批次操作支援的操作

  3. 命名 Amazon S3 物件

InvalidManifestContent 疑難排解

  1. 下載並檢查資訊清單檔案。手動驗證資訊清單符合格式要求：

    1. CSV 格式搭配逗號分隔符號。

    2. 不含 BOM 的 UTF-8 編碼。

    3. 所有資料列的資料行數一致。

    4. 沒有空白行或結尾空格。

    5. 物件索引鍵如果包含特殊字元，則正確編碼 URL。

    使用下列命令下載資訊清單檔案。

    
aws s3 cp s3://amzn-s3-demo-bucket1/manifest-key ./manifest.csv

  2. 檢查操作的必要欄：

    1. 所有操作：Bucket、Key

    2. 複製操作：VersionId (選用)

    3. 還原操作：VersionId (選用)

    4. 取代標籤操作：不需要額外的欄。

    5. 取代 ACL 操作：不需要額外的欄。

    6. 啟動還原：VersionId (選用)

  3. 檢查物件計數限制：

    1. 複製：最多 10 億個物件。

    2. 刪除：最多 10 億個物件。

    3. 還原：最多 10 億個物件。

    4. 標記：最多 10 億個物件。

    5. ACL：最多 10 億個物件。

  4. 從您的原始資訊清單中建立具有幾個物件的測試資訊清單。

  5. 請使用下列命令檢查是否存在資訊清單的物件範例。

    
aws s3 ls s3://amzn-s3-demo-bucket1/object-key

  6. 檢查任務失敗詳細資訊，並檢閱任務描述的失敗原因，和任何特定錯誤詳細資訊。

    
aws s3control describe-job --account-id 111122223333 --job-id job-id