故障診斷 S3 批次操作 - Amazon Simple Storage Service
NoSuchJobExceptionInvalidManifestContent

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

故障診斷 S3 批次操作

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

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

有兩種主要類型的失敗會導致批次操作錯誤：

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

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

NoSuchJobException

類型：API 失敗

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

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

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

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

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

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

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

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

  1. No such job

  2. The specified job does not exist

防止 NoSuchJobException API 故障的最佳實務

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

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

  3. 設定監控 – 建立 CloudWatch 警示，以在 90 天過期前追蹤任務完成。如需詳細資訊，請參閱《Amazon CloudWatch 使用者指南》中的使用 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、CompletingFailed、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 格式。任務 IDs通常包含 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 批次操作請求因許可不足、不支援的操作或政策限制而遭到封鎖時，就會AccessDeniedException發生 。這是批次操作中最常見的錯誤之一。它有下列常見原因：

  1. 缺少 IAM 許可 – IAM 身分缺少批次操作 APIs 的必要許可。

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

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

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

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

  6. 以資源為基礎的政策限制 – 儲存貯體政策或物件 ACLs會封鎖操作。

  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. 監控許可變更 – 針對可能影響批次操作的 IAM 政策修改設定 CloudTrail 提醒。

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

  7. 使用常見許可範本 - 使用許可範例和 polcy 範本：

    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. 檢閱儲存貯體政策是否有可能拒絕操作的 polcies。

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

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

    3. 如果使用 VPC 端點，請確認 VPC 端點政策允許批次操作。

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

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

SlowDownError

類型：API 失敗

當您的帳戶超過 S3 Batch Operations APIs的請求率限制時，就會發生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 SDKs 包含速率限制錯誤的內建重試邏輯。設定它們，如下所示：

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

  2. AWS 適用於 Python 的 SDK (Boto3) – 在用戶端組態中設定重試模式和最大嘗試次數。

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

  4. AWS 適用於 JavaScript 的 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 標記non-UTF-8 字元。

  3. 物件金鑰問題 – 無效的字元、不正確的 URL 編碼或金鑰超過長度限制。

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

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

  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. 無效的版本 IDs – 確保版本 IDs 的英數字串格式正確。如果不需要，請移除版本 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. 如果資訊清單中存在物件範例，請使用下列命令 cehck。

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

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

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