本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 對 S3 Batch Operations 進行故障診斷
Amazon S3 Batch Operations 可讓您對 Amazon S3 物件執行大規模的操作。本指南可協助您針對可能遇到的常見問題進行故障診斷。
若要對 S3 批次複寫問題進行故障診斷，請參閱[故障排除複寫](replication-troubleshoot.md)。
有兩種主要類型的失敗會導致 Batch Operations 錯誤：
1. **API 失敗** – 請求的 API (例如 `CreateJob`) 無法執行。
1. **作業失敗** – 初始 API 請求成功，但作業失敗，例如由於資訊清單或資訊清單中指定物件的權限問題。
## NoSuchJobException
**類型**：API 失敗
當 S3 Batch Operations 找不到指定的任務時，就會發生 `NoSuchJobException`。此錯誤可能發生在簡單任務過期後的幾個案例中。常見原因包括下列項目。
1. **任務過期** – 在達到結束狀態 (`Complete`、`Cancelled` 或 `Failed`) 的 90 天後，任務會自動刪除。
1. **不正確的任務 ID** – 用於 `DescribeJob` 或 `UpdateJobStatus` 的任務 ID 與 `CreateJob` 傳回的 ID 不相符。
1. **區域錯誤** – 嘗試存取與建立任務之不同區域中的任務。
1. **錯誤帳戶** – 使用來自不同 AWS 帳戶的任務 ID。
1. **任務 ID 格式錯誤** – 任務 ID 中的錯字、額外的字元或不正確的格式。
1. **時序問題** – 在建立任務後立即檢查任務狀態，然後再完整註冊任務。
相關的錯誤訊息包括下列項目。
1. `No such job`
1. `The specified job does not exist`
### 防止 `NoSuchJobException` API 失敗的最佳實務
1. **立即儲存任務 ID** – 在進行後續 API 呼叫之前，從 `CreateJob` 回應儲存任務 ID。
1. **實作重試邏輯** – 在建立後立即檢查任務狀態時新增指數退避。
1. **設定監控** – 建立 CloudWatch 警示，以在 90 天過期前追蹤直到任務完成。如需詳細資訊，請參閱《Amazon CloudWatch 使用者指南》中的[使用 Amazon CloudWatch 警示](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html)。
1. **使用一致的區域** – 確保所有任務操作都使用與任務建立相同的區域。
1. **驗證輸入** – 在進行 API 呼叫之前檢查任務 ID 格式。
### 當任務到期
處於終端狀態的任務，會在 90 天後自動刪除。若要避免遺失任務資訊，請考量下列事項。
1. **過期前下載完成報告** – 如需擷取和儲存任務結果的指示，請參閱 [完成報告](batch-ops-job-status.md#batch-ops-completion-report)。
1. 在**您自己的系統中封存任務中繼資料** – 將關鍵任務資訊儲存在資料庫或監控系統中。
1. **設定 90 天截止日期之前自動通知** – 使用 Amazon EventBridge 建立規則，在任務完成時觸發通知。如需詳細資訊，請參閱[Amazon S3 事件通知](EventNotifications.md)。
### 對 `NoSuchJobException` 進行故障診斷
1. 使用下列命令驗證任務存在於您的帳戶和區域中。
```
aws s3control list-jobs --account-id {{111122223333}} --region {{us-east-1}}
```
1. 使用下列命令搜尋所有任務狀態。可能的任務狀態包括 `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}}
```
1. 使用下列命令檢查任務是否存在於您通常建立任務的其他區域中。
```
aws s3control list-jobs --account-id {{111122223333}} --region {{job-region-1}} aws s3control list-jobs --account-id {{111122223333}} --region {{job-region-2}}
```
1. 驗證任務 ID 格式。任務 ID 通常包含 36 個字元，例如 `12345678-1234-1234-1234-123456789012`。檢查是否有額外的空格、缺少的字元或區分大小寫的問題，並確認您使用的是 `CreateJob` 命令傳回的完整任務 ID。
1. 使用下列命令，檢查 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 的必要權限。
1. **S3 權限不足** – 缺少存取來源或目的地儲存貯體和物件的權限。
1. **任務執行角色問題** – 任務執行角色缺少執行指定操作的權限。
1. **不支援的操作** – 嘗試使用目前區域或儲存貯體類型中不支援的操作。
1. **跨帳戶存取權問題** – 缺少跨帳戶儲存貯體或物件存取的權限。
1. **資源型政策限制** – 儲存貯體政策或物件 ACL 封鎖操作。
1. **服務控制政策 (SCP) 限制** – 防止操作的組織層級政策。
相關錯誤訊息：
1. `Access Denied`
1. `User: arn:aws:iam::account:user/username is not authorized to perform: s3:operation`
1. `Cross-account pass role is not allowed`
1. `The bucket policy does not allow the specified operation`
#### 防止 AccessDeniedException API 失敗的最佳實務
1. **使用最低權限原則** – 僅授予特定操作所需的最低權限。
1. **在大型任務之前測試權限** – 在處理數千個物件之前，執行小型測試任務來驗證權限。
1. **使用 IAM 政策模擬器** – 使用 IAM 政策模擬器在部署之前測試政策。如需詳細資訊，請參閱《IAM 使用者指南》中的[使用 IAM 政策模擬器測試 IAM 政策](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_testing-policies.html)。
1. **實作適當的跨帳戶設定** – 檢查您的跨帳戶存取權組態是否有跨帳戶任務組態。如需詳細資訊，請參閱《[IAM 使用者指南》中的 IAM 教學課程：使用 IAM 角色委派跨 AWS 帳戶的存取權](https://docs.aws.amazon.com/IAM/latest/UserGuide/tutorial_cross-account-with-roles.html)。
1. **監控許可權變更** – 設定可能影響 Batch Operations 的 IAM 政策修改的 CloudTrail 警示。
1. **文件角色需求** – 維護每個任務類型所需許可權的明確文件。
1. **使用常見許可範本** - 使用許可範例和政策範本：
1. [授予批次操作的許可](batch-ops-iam-role-policies.md)
1. 《IAM 使用者指南》中的 [IAM 中的跨帳戶資源](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies-cross-account-resource-access.html)。
1. 《 AWS PrivateLink 指南》中的[使用端點政策控制對 VPC 端點的存取](https://docs.aws.amazon.com/vpc/latest/privatelink/vpc-endpoints-access.html)。
#### AccessDeniedException 疑難排解
依照下列步驟，有系統地識別和解決許可權問題。
1. 依區域檢查 [S3 批次操作支援的操作](batch-ops-operations.md) 中受支援的操作。確認僅區域和區域端點有提供目錄儲存貯體操作。確認儲存貯體的儲存類別是否支援該操作。
1. 使用以下命令判斷您是否可以列出任務。
```
aws s3control list-jobs --account-id {{111122223333}}
```
1. 使用下列命令檢查請求身分的 IAM 許可。執行任務的帳戶需要下列許可：`s3:CreateJob`、`s3:DescribeJob`、`s3:ListJobs`、`s3:UpdateJobStatus`、 `s3:UpdateJobPriority`和 `iam:PassRole`。
```
aws sts get-caller-identity {{111122223333}}
```
1. 使用下列命令檢查角色是否存在，且是否可承擔。
```
aws iam get-role --role-name {{role-name}}
```
1. 使用下列命令檢閱角色的信任政策。執行任務的角色必須具有下列項目：
1. 信任關係可讓 `batchoperations.s3.amazonaws.com` 承擔角色。
1. 批次操作功能正在執行的操作 (例如用於標記操作的 `s3:PutObjectTagging`)。
1. 來源與目的地儲存貯體的存取權。
1. 讀取資訊清單檔案的許可權。
1. 寫入完成報告的許可權。
```
aws iam get-role --role-name {{role-name}} --query 'Role.AssumeRolePolicyDocument'
```
1. 使用下列命令來測試資訊清單和來源儲存貯體的存取。
```
aws s3 ls s3://{{amzn-s3-demo-bucket}}
```
1. 測試批次操作功能正在執行的操作。例如，若批次操作在執行標記作業，請在來源儲存貯體中標記範例物件。
1. 檢閱儲存貯體政策是否有可能拒絕操作的政策。
1. 如果使用舊版存取控制，請檢查物件 ACL。
1. 確認沒有服務控制政策 (SCP) 在封鎖操作。
1. 如果使用 VPC 端點，請確認 VPC 端點政策允許 Batch Operations。
1. 使用下列命令，以使用 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 呼叫。
1. **並行任務操作** – 多個應用程式或使用者同時建立/管理任務。
1. **無速率限制的自動化指令碼** – 未實作適當退避策略的指令碼。
1. **輪詢任務狀態太頻繁** – 檢查任務狀態的頻率過高。
1. **高載流量模式** – 在尖峰處理時間期間 API 用量突然暴增。
1. **區域容量限制** – 超出您區域的分配請求容量。
相關錯誤訊息：
1. `SlowDown`
1. `Please reduce your request rate`
1. `Request rate exceeded`
#### 防止 SlowDownError API 失敗的最佳實務
1. **實作用戶端速率限制** – 在應用程式中新增 API 呼叫之間的延遲。
1. **使用指數退避與抖動** – 隨機重試延遲，以避免發生驚群問題。
1. **設定適當的重試邏輯** – 針對暫時性誤差實作自動重試，並逐漸增加重試延遲。
1. **使用事件驅動的架構** – 以 EventBridge 通知取代輪詢，以取得作業狀態變更資訊。
1. **將負載分散到不同時段** – 錯開作業建立和狀態檢查的時段。
1. **監控和發出速率限制警示** – 設定 CloudWatch 警示，以便在接近限制時進行偵測。
AWS SDKs 包含速率限制錯誤的內建重試邏輯。設定如下：
1. **AWS CLI** – 使用 `cli-read-timeout` 和 `cli-connect-timeout` 參數。
1. **AWS 適用於 Python 的 SDK (Boto3)** – 在用戶端組態中設定重試模式和最大嘗試次數。
1. **AWS 適用於 Java 的 SDK** – 使用 `RetryPolicy` 和 `ClientConfiguration`設定。
1. **AWS 適用於 JavaScript 的 SDK** – 設定 `maxRetries`和 `retryDelayOptions`。
如需重試模式和最佳實務的詳細資訊，請參閱 AWS 方案指引指南中的[使用退避模式重試](https://docs.aws.amazon.com/prescriptive-guidance/latest/cloud-design-patterns/retry-backoff.html)。
#### SlowDownError 疑難排解
1. 在您的程式碼中，立即實作指數退避。
**Example 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
```
1. 使用 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]'
```
1. 檢閱輪詢頻率。
1. 避免每 30 秒檢查一次作用中任務的作業狀態。
1. 盡可能使用任務完成通知，而不是輪詢。
1. 在輪詢間隔中實作抖動，以避免出現同步請求。
1. 最佳化您的 API 使用模式。
1. 盡可能批次進行多個操作。
1. 使用 `ListJobs` 在一次呼叫中取得多個任務的狀態。
1. 快取任務資訊以減少備援 API 呼叫。
1. 分散在不同時間建立任務，而不是同時建立多個任務。
1. 使用 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 結構。
1. **內容編碼問題** – 字元編碼不正確、BOM 標記或非 UTF-8 字元。
1. **物件索引鍵問題** – 無效的字元、不正確的 URL 編碼，或索引鍵超出長度限制。
1. **大小限制** – 資訊清單包含的物件數量超出作業支援的數量。
1. **版本 ID 格式錯誤** – 版本控制物件的版本 ID 格式不正確或無效。
1. **ETag 格式問題** – 需要 ETag 之操作的 ETags 格式不正確或缺少引號。
1. **不一致的資料** – 相同資訊清單中混用不同格式，或者欄數不一致。
相關錯誤訊息：
1. `Required fields are missing in the schema: + missingFields`
1. `Invalid Manifest Content`
1. `The S3 Batch Operations job failed because it contains more keys than the maximum allowed in a single job`
1. `Invalid object key format`
1. `Manifest file is not properly formatted`
1. `Invalid version ID format`
1. `ETag format is invalid`
### 可防止 InvalidManifestContent 任務失敗的最佳實務
1. **上傳前驗證** – 在處理大型資料集之前，使用小型任務測試資訊清單格式。
1. **使用一致的編碼** – 資訊清單檔案一律使用不含 BOM 的 UTF-8 編碼。
1. **實作資訊清單產生標準** – 建立用於建立資訊清單的範本和驗證程序。
1. **正確處理特殊字元** – 包含特殊字元的 URL 編碼物件索引鍵。
1. **監控物件計數** – 主動追蹤資訊清單大小，並分割大型任務。
1. **驗證物件存在** – 在資訊清單中包含物件之前，先驗證物件是否存在。
1. **使用 AWS 工具產生資訊清單** – 利用 AWS CLI `s3api list-objects-v2` 產生格式正確的物件清單。
常見資訊清單問題與解決方案：
1. **缺少必要欄** – 確保您的資訊清單包含操作類型的所有必要欄。最常見的遺失欄是儲存貯體和索引鍵。
1. **CSV 格式不正確** – 使用逗號分隔符號，確保所有列的欄數一致，並避免欄位中有嵌入換行符號。
1. **物件索引鍵中的特殊字元** – URL 編碼物件索引鍵，其中包含空格、Unicode 字元或 XML 特殊字元 (＜、＞、&、"、')。
1. **大型資訊清單檔案** – 將超出操作限制的資訊清單分割成多個較小的資訊清單，並建立個別任務。
1. **無效的版本 ID** – 確保版本 ID 是格式正確的英數字元字串。如果不需要，請移除版本 ID 欄。
1. **編碼問題** – 將資訊清單檔案儲存為不含 BOM 的 UTF-8 格式。避免透過可能改變編碼的系統複製資訊清單。
如需詳細的資訊清單格式規格和範例，請參閱下列內容：
1. [指定資訊清單](batch-ops-create-job.md#specify-batchjob-manifest)
1. [S3 批次操作支援的操作](batch-ops-operations.md)
1. [命名 Amazon S3 物件](object-keys.md)
### InvalidManifestContent 疑難排解
1. 下載並檢查資訊清單檔案。手動驗證資訊清單符合格式要求：
1. CSV 格式搭配逗號分隔符號。
1. 不含 BOM 的 UTF-8 編碼。
1. 所有資料列的資料行數一致。
1. 沒有空白行或結尾空格。
1. 物件索引鍵如果包含特殊字元，則正確編碼 URL。
使用下列命令下載資訊清單檔案。
```
aws s3 cp s3://{{amzn-s3-demo-bucket1}}/{{manifest-key}} {{./manifest.csv}}
```
1. 檢查操作的必要欄：
1. 所有操作：`Bucket`、`Key`
1. 複製操作：`VersionId` (選用)
1. 還原操作：`VersionId` (選用)
1. 取代標籤操作：不需要額外的欄。
1. 取代 ACL 操作：不需要額外的欄。
1. 啟動還原：`VersionId` (選用)
1. 檢查物件計數限制：
1. 複製：最多 10 億個物件。
1. 刪除：最多 10 億個物件。
1. 還原：最多 10 億個物件。
1. 標記：最多 10 億個物件。
1. ACL：最多 10 億個物件。
1. 使用原始資訊清單中的幾個物件建立測試資訊清單。
1. 使用下列命令來檢查資訊清單中的物件範例是否存在。
```
aws s3 ls s3://{{amzn-s3-demo-bucket1}}/{{object-key}}
```
1. 檢查任務失敗詳細資訊，並檢閱任務描述的失敗原因，和任何特定錯誤詳細資訊。
```
aws s3control describe-job --account-id {{111122223333}} --job-id {{job-id}}
```