S3 バッチオペレーションのトラブルシューティング - Amazon Simple Storage Service
NoSuchJobExceptionInvalidManifestContent

S3 バッチオペレーションのトラブルシューティング

Amazon S3 バッチオペレーションを使用すると、Amazon S3 のオブジェクトに対して大規模なオペレーションを実行できます。このガイドは、発生する可能性のある一般的な問題のトラブルシューティングに役立ちます。

S3 バッチレプリケーションに関する問題のトラブルシューティングについては、「レプリケーションのトラブルシューティング」を参照してください。

バッチオペレーションエラーが発生する障害には、主に 2 つのタイプがあります。

  1. API の失敗 – リクエストされた API (CreateJob など) の実行に失敗しました。

  2. ジョブの失敗 – 最初の API リクエストは成功しましたが、例えば、マニフェストの問題やマニフェストで指定されたオブジェクトへのアクセス許可が原因でジョブが失敗しました。

NoSuchJobException

タイプ: API の失敗

NoSuchJobException は、S3 バッチオペレーションが指定されたジョブを見つけられない場合に発生します。このエラーは、単純なジョブの有効期限切れ以外にも、いくつかのシナリオで発生する可能性があります。一般的な原因には以下が含まれます。

  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. モニタリングの設定 – 90 日の有効期限が切れる前にジョブの完了を追跡する CloudWatch アラームを作成します。手順については、「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 は通常、12345678-1234-1234-1234-123456789012 のように 36 文字で構成されます。余分なスペース、欠落している文字、大文字と小文字の区別の問題をチェックし、CreateJob コマンドによって返される完全なジョブ ID を使用していることを確認します。

  5. 次のコマンドを使用して、ジョブ作成イベントの CloudTrail ログを確認します。

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

AccessDeniedException

タイプ: API の失敗

AccessDeniedException は、アクセス許可の不足、サポートされていないオペレーション、またはポリシーの制限により S3 バッチオペレーションリクエストがブロックされた場合に発生します。これは、バッチオペレーションで最も一般的なエラーの 1 つです。これには次の一般的な原因があります。

  1. IAM アクセス許可がない – IAM ID にバッチオペレーション 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 ユーザーガイドの「AWS アカウント間の IAM ロールを使用したアクセスの委任」を参照してください。

  5. アクセス許可の変更を監視する – バッチオペレーションに影響を与える可能性のある IAM ポリシーの変更に関する CloudTrail アラートを設定します。

  6. ドキュメントロールの要件 – 各ジョブタイプに必要なアクセス許可の明確なドキュメントを維持します。

  7. 一般的なアクセス許可テンプレートを使用する - アクセス許可の例とポリシーテンプレートを使用します。

    1. バッチオペレーションに対するアクセス許可の付与

    2. IAM ユーザーガイドのIAM のクロスアカウントリソース。

    3. AWS PrivateLink ガイドのエンドポイントポリシーを使用して VPC エンドポイントへのアクセスを制御する。

AccessDeniedException のトラブルシューティング

アクセス許可の問題を特定して解決するには、以下のステップを体系的に実行します。

  1. S3 バッチ操作でサポートされるオペレーション については、リージョンごとにサポートされているオペレーションを確認します。ディレクトリバケットオペレーションがリージョンエンドポイントとゾーンエンドポイントでのみ使用可能であることを確認します。オペレーションがバケットのストレージクラスでサポートされていることを確認します。

  2. 次のコマンドを使用して、ジョブを一覧表示できるかどうかを判断します。

    
 aws s3control list-jobs --account-id 111122223333

  3. 次のコマンドを使用して、リクエスト元の ID の 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 エンドポイントポリシーでバッチオペレーションが許可されていることを確認します。

  9. CloudTrail を使用してアクセス許可の失敗を特定するには、次のコマンドを使用します。

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

SlowDownError

タイプ: API の失敗

この SlowDownError 例外は、アカウントが S3 バッチオペレーション API のリクエストレート制限を超えた場合に発生します。これは、リクエストが多すぎてサービスが過負荷にならないようにするためのスロットリングメカニズムです。これには次の一般的な原因があります。

  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. ジッターでエクスポネンシャルバックオフを使用する – 再試行の遅延をランダム化して、Thundering Herd 問題を回避します。

  3. 適切な再試行ロジックを設定する – 一時的なエラーに対して、遅延を徐々に増やしながら自動的に再試行する機能を実装します。

  4. イベント駆動型アーキテクチャを使用する – ジョブステータスの変更に関して、ポーリングを EventBridge 通知に置き換えます。

  5. 時間の経過とともに負荷を分散する – ジョブの作成とステータスチェックを異なる時間帯で分散させます。

  6. レート制限のモニタリングとアラート – CloudWatch アラームを設定して、制限に近づいていることを検出します。

ほとんどの AWS SDK には、レート制限エラーの再試行ロジックが組み込まれています。次のように設定します。

  1. AWS CLI – cli-read-timeout および cli-connect-timeout パラメータを使用します。

  2. AWS SDK for Python (Boto3) – クライアント設定で再試行モードと最大試行回数を設定します。

  3. AWS SDK for Java – RetryPolicy と ClientConfiguration 設定を使用します。

  4. AWS SDK for JavaScript – maxRetries と retryDelayOptions を設定します。

再試行パターンとベストプラクティスの詳細については、「AWS 規範ガイダンスガイド」の「Retry with backoff pattern」を参照してください。

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 秒に 1 回以上ジョブのステータスをチェックしないようにします。

    2. 可能な場合はポーリングの代わりにジョブ完了通知を使用します。

    3. 同期したリクエストを避けるために、ポーリング間隔にジッターを実装します。

  4. API の使用パターンを最適化します。

    1. 可能な場合は、複数のオペレーションをバッチ処理します。

    2. ListJobs を使用して、1 回の呼び出しで複数のジョブのステータスを取得します。

    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

タイプ: ジョブの失敗

この InvalidManifestContent 例外は、マニフェストファイルの形式、内容、または構造に問題があり、S3 バッチオペレーションがジョブを処理できない場合に発生します。これには次の一般的な原因があります。

  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. オブジェクトキーの特殊文字 – スペース、Unicode 文字、または XML 特殊文字 (<、>、&、"、') を含む URL エンコードオブジェクトキー。

  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