S3 バッチオペレーションジョブの作成 - Amazon Simple Storage Service

S3 バッチオペレーションジョブの作成

S3 バッチオペレーションを使用すると、特定の Amazon S3 オブジェクトのリストに対して大規模なバッチオペレーションを実行できます。AWS マネジメントコンソール、AWS コマンドラインインターフェイス(AWS CLI)、AWS SDK、または REST API を使用して S3 バッチオペレーションジョブを作成できます。

バッチオペレーションの詳細については、「S3 バッチオペレーションの基本」を参照してください。

このセクションでは、S3 バッチオペレーションジョブの作成に必要な情報と Create Job リクエストの結果について説明します。また、バッチオペレーションジョブの作成手順についても説明します。

S3 バッチオペレーションジョブを作成するときに、すべてのタスクまたは失敗したタスクについてのみ完了レポートをリクエストできます。少なくとも 1 つのタスクが正常に呼び出されている限り、S3 バッチオペレーションは、完了、失敗、またはキャンセルされたジョブに関するレポートを生成します。詳細については、「S3 バッチオペレーション完了レポート」を参照してください。

前提条件: バッチオペレーションジョブを作成する前に、関連するアクセス許可が設定されていることを確認します。詳細については、Amazon S3 バッチオペレーションに対するアクセス許可の付与 を参照してください。

バッチオペレーションジョブのリクエストの要素

S3 バッチオペレーションジョブを作成するには、次の情報を指定する必要があります。

オペレーション

S3 バッチオペレーションでマニフェストのオブジェクトに対して実行するオペレーションを指定します。オペレーションのタイプごとに、そのオペレーションに固有のパラメータを受け入れます。これにより、各オブジェクトに対してオペレーションを 1 つずつ実行した場合と同じタスクを実行できます。

マニフェスト

マニフェストは、S3 バッチオペレーションで指定したアクションを実行するすべてのオブジェクトのリストです。マニフェストとして CSV 形式の Amazon S3 インベントリ レポートを使用するか、独自にカスタマイズしたオブジェクトの CSV リストを使用できます。

マニフェスト内のオブジェクトがバージョニング対応のバケット内にある場合は、そのオブジェクトのバージョン ID を指定する必要があります。詳細については、「マニフェストの指定」を参照してください。

優先度

ジョブの優先順位を使用して、自分のアカウントで実行中の他のユーザーに対するこのジョブの相対的な優先順位を示します。番号が大きいほど、優先度が高いことを表します。

ジョブの優先度は、同じアカウントとリージョンの他のジョブに設定された優先度に相対して解釈されます。お客様に合った番号付け体系を選択できます。たとえば、すべての Initiate Restore Object ジョブに 1 の優先順位を、すべての PUT Object Copy ジョブに 2 の優先順位を、すべての Put Object ACL ジョブに 3 の優先順位を付けることができます。

S3 バッチオペレーションは優先順位番号順にジョブを優先しますが、厳密な順序は保証されません。したがって、他のジョブよりも先に開始または終了するようにするために、ジョブの優先順位を使用しないでください。厳密な順序付けする必要がある場合は、1 つのジョブが終了するまで待ってから次のジョブを開始します。

RoleArn

ジョブを実行する AWS Identity and Access Management (IAM) ロールを指定します。使用する IAM ロールには、そのジョブで指定されているオペレーションを実行するための十分なアクセス許可が必要です。たとえば、PUT Object Copy ジョブを実行するには、IAM ロールに、レプリケート元バケットに対する s3:GetObject アクセス許可と、レプリケート先バケットに対する s3:PutObject アクセス許可が必要です。このロールには、マニフェストを読み取り、ジョブ完了レポートを書き込むためのアクセス許可も必要です。

IAM ロールの詳細については、IAM ユーザーガイドの「IAM ロール」を参照してください。

Amazon S3 のアクセス許可の詳細については、「Amazon S3 のアクション」を参照してください。

レポート

S3 バッチオペレーションで完了レポートを生成するかどうかを指定します。ジョブ完了レポートをリクエストする場合、この要素にレポートのパラメータも指定する必要があります。必要な情報には、レポートを保存するバケット、レポートの形式、レポートにすべてのタスクの詳細を含めるか失敗したタスクのみを含めるか、およびオプションのプレフィックス文字列が含まれます。

タグ (オプション)

タグを追加することで、S3 バッチオペレーションジョブへのラベル付けとアクセスの制御を実行できます。タグを使用して、バッチオペレーションジョブの担当者を識別できます。タグをアタッチしてジョブを作成し、後でジョブにタグを追加できます。たとえば、タグ "Department=Finance" を付けてジョブを作成する場合に、IAM ユーザーに CreateJob を呼び出すアクセス許可を付与できます。

詳細については、「タグを使用したアクセスのコントロールとジョブのラベル付け」を参照してください。

説明 (オプション)

ジョブを追跡および監視するために、最大 256 文字の説明を指定することもできます。Amazon S3 では、ジョブに関する情報を返すか、Amazon S3 コンソールにジョブの詳細を表示するたびに、この説明が含まれます。これによって、入力した説明に応じて簡単にジョブを並べ替えたりフィルタリングしたりできます。説明は一意である必要はないので、類似したジョブのグループを追跡するのに役立つように、説明をカテゴリとして使用することができます (「Weekly Log Copy Jobs」など)。

マニフェストの指定

マニフェストは、Amazon S3 でオペレーションを実行するオブジェクトのキーをリストする Amazon S3 のオブジェクトです。ジョブのマニフェストを作成するには、マニフェストオブジェクトキー、ETag、およびオプションでバージョン ID を指定します。マニフェストの内容は URL エンコードされている必要があります。お客様が用意したキーを使用したサーバー側の暗号化 (SSE-C) および AWS Key Management Service のカスタマーマスターキー (CMK) を使用したサーバー側の暗号化 (SSE-KMS) を使用するマニフェストはサポートされていません。マニフェストには、各オブジェクトのバケット名、オブジェクトキー、およびオプションでオブジェクトバージョンを含める必要があります。マニフェストのその他のフィールドは、S3 バッチオペレーションでは使用されません。

以下の 2 つの形式のいずれかを使用して、ジョブ作成リクエストでマニフェストを指定できます。

  • Amazon S3 インベントリレポート - CSV 形式の Amazon S3 インベントリレポートである必要があります。インベントリレポートに関連付けられた manifest.json ファイルを指定する必要があります。インベントリレポートの詳細については、「 Amazon S3 インベントリ」を参照してください。インベントリレポートにバージョン ID が含まれている場合、S3 バッチオペレーションは特定のオブジェクトのバージョンに対して実行されます。

    注記

    S3 バッチオペレーションでは、AWS KMS で暗号化された CSV 形式のインベントリレポートがサポートされています。

  • CSV ファイル - ファイルの各行には、バケット名とオブジェクトのキーを含める必要があります。また、任意でオブジェクトのバージョンを含めることができます。オブジェクトキーは、次の例に示されているように、URL エンコードする必要があります。マニフェストには、すべてのオブジェクトのバージョン ID を含めるか、すべてのオブジェクトのバージョン ID を省略する必要があります。CSV 形式のマニフェストの詳細については、Amazon Simple Storage Service API リファレンスの「JobManifestSpec」を参照してください。

    注記

    S3 バッチオペレーションでは、AWS KMS で暗号化された CSV 形式のマニフェストファイルはサポートされていません。

    CSV 形式のマニフェスト(バージョン ID なし)の例を以下に示します。

    Examplebucket,objectkey1 Examplebucket,objectkey2 Examplebucket,objectkey3 Examplebucket,photos/jpgs/objectkey4 Examplebucket,photos/jpgs/newjersey/objectkey5 Examplebucket,object%20key%20with%20spaces

    CSV 形式のマニフェスト(バージョン ID あり)の例を以下に示します。

    Examplebucket,objectkey1,PZ9ibn9D5lP6p298B7S9_ceqx1n5EJ0p Examplebucket,objectkey2,YY_ouuAJByNW1LRBfFMfxMge7XQWxMBF Examplebucket,objectkey3,jbo9_jhdPEyB4RrmOxWS0kU0EoNrU_oI Examplebucket,photos/jpgs/objectkey4,6EqlikJJxLTsHsnbZbSRffn24_eh5Ny4 Examplebucket,photos/jpgs/newjersey/objectkey5,imHf3FAiRsvBW_EHB8GOu.NHunHO1gVs Examplebucket,object%20key%20with%20spaces,9HkPvDaZY5MVbMhn6TMn1YTb5ArQAo3w
重要

マニフェスト内のオブジェクトがバージョニング対応のバケット内にある場合は、そのオブジェクトのバージョン ID を指定する必要があります。ジョブを作成すると、S3 バッチオペレーションはジョブを実行する前にマニフェスト全体を解析します。ただし、これによってバケットの状態は「スナップショット」されません。

マニフェストには数十億ものオブジェクトを含めることができるため、ジョブの実行には長時間かかる場合があります。ジョブの実行中にオブジェクトを新しいバージョンで上書きし、そのオブジェクトのバージョン ID を指定しなかった場合、Amazon S3 はジョブの作成時に存在していたバージョンではなく、最新バージョンのオブジェクトに対してオペレーションを実行します。この動作を回避する唯一の方法は、マニフェスト内でリストされたオブジェクトにバージョン ID を指定することです。

バッチオペレーションジョブを作成するには

このセクションでは、S3 バッチオペレーションジョブの作成方法について説明します。ジョブリクエストの作成の詳細については、「バッチオペレーションジョブのリクエストの要素」を参照してください。ジョブの作成に必要なアクセス権限の設定については、Amazon S3 バッチオペレーションに対するアクセス許可の付与 を参照してください。

このセクションでは、Amazon S3 コンソールを使用して S3 バッチオペレーションジョブを作成する方法について説明します。

バッチジョブを作成するには

  1. AWS マネジメントコンソールにサインインして Amazon S3 コンソール (https://console.aws.amazon.com/s3/) を開きます。

  2. Amazon S3 コンソールのナビゲーションペインで [Batch Operations (バッチオペレーション)] を選択します。

  3. [ジョブの作成] を選択します。

  4. ジョブを作成する [Region (リージョン)] を選択します。

  5. [マニフェストの形式] で、使用するマニフェストオブジェクトのタイプを選択します。

    • [S3 inventory report (S3 インベントリレポート)] を選択する場合、CSV 形式のインベントリレポートの一部として Amazon S3 が生成する manifest.json オブジェクトへのパスと、最新のバージョンではなく特定のバージョンを使用する場合には、オプションでマニフェストオブジェクトのバージョン ID を入力します。

    • [CSV] を選択する場合は、CSV 形式のマニフェストオブジェクトへのパスを入力します。マニフェストオブジェクトは、コンソールで説明される形式に従う必要があります。最新のバージョンではなく特定のバージョンを使用する場合には、マニフェストオブジェクトのバージョン ID をオプションで含めることもできます。

  6. [Next (次へ)] を選択します。

  7. [Operation (オペレーション)] で、マニフェストに登録されたすべてのオブジェクトを実行するオペレーションを選択します。選択したオペレーションに関する情報を入力して、[次へ] を選択します。

  8. [追加オプションの設定] に関する情報を入力して、[次へ] を選択します。

  9. [Review (確認)] で、設定を確認します。変更が必要な場合は、[戻る] を選択します。それ以外の場合は、[ジョブの作成] を選択します。

次の例では、AWS CLI を使用して S3 バッチオペレーションジョブ S3PutObjectTagging を作成します。

バッチオペレーション S3PutObjectTagging ジョブを作成するには

  1. AWS Identity and Access Management (IAM) ロールを作成し、アクセス許可を割り当てます。このロールは、次のステップで作成する、ジョブのオブジェクトにタグを追加する Amazon S3 のアクセス許可を付与します。

    1. IAM ロールを次のように作成します。

      aws iam create-role \ --role-name S3BatchJobRole \ --assume-role-policy-document '{ "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Principal":{ "Service":"batchoperations.s3.amazonaws.com" }, "Action":"sts:AssumeRole" } ] }'

      ロールの Amazon リソースネーム (ARN) を記録します。ジョブの作成時にこの ARN が必要となります。

    2. アクセス許可を含む IAM ポリシーを作成し、前のステップで作成した IAM ロールにアタッチします。権限の詳細については、Amazon S3 バッチオペレーションに対するアクセス許可の付与を参照してください。

      aws iam put-role-policy \ --role-name S3BatchJobRole \ --policy-name PutObjectTaggingBatchJobPolicy \ --policy-document '{ "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Action":[ "s3:PutObjectTagging", "s3:PutObjectVersionTagging" ], "Resource": "arn:aws:s3:::{{TargetResource}}/*" }, { "Effect": "Allow", "Action": [ "s3:GetObject", "s3:GetObjectVersion", "s3:GetBucketLocation" ], "Resource": [ "arn:aws:s3:::{{ManifestBucket}}", "arn:aws:s3:::{{ManifestBucket}}/*" ] }, { "Effect":"Allow", "Action":[ "s3:PutObject", "s3:GetBucketLocation" ], "Resource":[ "arn:aws:s3:::{{ReportBucket}}", "arn:aws:s3:::{{ReportBucket}}/*" ] } ] }'

  2. S3PutObjectTagging ジョブを作成します。

    manifest.csv ファイルは、バケットのリストとオブジェクトキー値を提供します。このジョブは、マニフェストで識別されたオブジェクトに指定されたタグを適用します。ETagmanifest.csv オブジェクトの ETag であり、Amazon S3 コンソールから取得できます。このリクエストは no-confirmation-required パラメータを指定します。これによって、Amazon S3 を使用して確認する必要がなくなり、udpate-job-status コマンドによってジョブが実行できるようになります。

    aws s3control create-job \ --region us-west-2 \ --account-id acct-id \ --operation '{"S3PutObjectTagging": { "TagSet": [{"Key":"keyOne", "Value":"ValueOne"}] }}' \ --manifest '{"Spec":{"Format":"S3BatchOperations_CSV_20180820","Fields":["Bucket","Key"]},"Location":{"ObjectArn":"arn:aws:s3:::my_manifests/manifest.csv","ETag":"60e460c9d1046e73f7dde5043ac3ae85"}}' \ --report '{"Bucket":"arn:aws:s3:::bucket-where-completion-report-goes","Prefix":"final-reports", "Format":"Report_CSV_20180820","Enabled":true,"ReportScope":"AllTasks"}' \ --priority 42 \ --role-arn IAM-role \ --client-request-token $(uuidgen) \ --description "job Description" \ --no-confirmation-required

    応答として、Amazon S3 はジョブ ID (など 00e123a4-c0d8-41f4-a0eb-b46f9ba5b07c) を返します。次のコマンドでこの ID が必要になります。

次の例では、AWS SDK for Java を使用して S3 バッチオペレーションジョブを作成します。

package aws.example.s3control; import com.amazonaws.AmazonServiceException; import com.amazonaws.SdkClientException; import com.amazonaws.auth.profile.ProfileCredentialsProvider; import com.amazonaws.services.s3control.AWSS3Control; import com.amazonaws.services.s3control.AWSS3ControlClient; import com.amazonaws.services.s3control.model.*; import java.util.UUID; import java.util.ArrayList; import static com.amazonaws.regions.Regions.US_WEST_2; public class CreateJob { public static void main(String[] args) { String accountId = "Account ID"; String iamRoleArn = "IAM Role ARN"; String reportBucketName = "arn:aws:s3:::bucket-where-completion-report-goes"; String uuid = UUID.randomUUID().toString(); ArrayList tagSet = new ArrayList<S3Tag>(); tagSet.add(new S3Tag().withKey("keyOne").withValue("ValueOne")); try { JobOperation jobOperation = new JobOperation() .withS3PutObjectTagging(new S3SetObjectTaggingOperation() .withTagSet(tagSet) ); JobManifest manifest = new JobManifest() .withSpec(new JobManifestSpec() .withFormat("S3BatchOperations_CSV_20180820") .withFields(new String[]{ "Bucket", "Key" })) .withLocation(new JobManifestLocation() .withObjectArn("arn:aws:s3:::my_manifests/manifest.csv") .withETag("60e460c9d1046e73f7dde5043ac3ae85")); JobReport jobReport = new JobReport() .withBucket(reportBucketName) .withPrefix("reports") .withFormat("Report_CSV_20180820") .withEnabled(true) .withReportScope("AllTasks"); AWSS3Control s3ControlClient = AWSS3ControlClient.builder() .withCredentials(new ProfileCredentialsProvider()) .withRegion(US_WEST_2) .build(); s3ControlClient.createJob(new CreateJobRequest() .withAccountId(accountId) .withOperation(jobOperation) .withManifest(manifest) .withReport(jobReport) .withPriority(42) .withRoleArn(iamRoleArn) .withClientRequestToken(uuid) .withDescription("job description") .withConfirmationRequired(false) ); } catch (AmazonServiceException e) { // The call was transmitted successfully, but Amazon S3 couldn't process // it and returned an error response. e.printStackTrace(); } catch (SdkClientException e) { // Amazon S3 couldn't be contacted for a response, or the client // couldn't parse the response from Amazon S3. e.printStackTrace(); } } }

ジョブのレスポンス

Create Job リクエストが成功すると、Amazon S3 はジョブ ID を返します。ジョブ ID は Amazon S3 が自動的に生成する一意の識別子であるため、バッチオペレーションジョブを識別してそのステータスを監視できます。

AWS CLI、AWS SDK、または REST API を介してジョブを作成する場合、S3 バッチオペレーションを設定してジョブを自動的に処理することを開始できます。ジョブは準備ができるとすぐ実行され、高度な優先順位のジョブを待ちません。

AWS マネジメントコンソールからジョブを作成する場合、バッチオペレーションがジョブを処理する前に、ジョブの詳細を確認し、実行を確定する必要があります。ジョブの実行を確認した後は、他のメソッドのいずれかを使用してそれを作成した場合と同じように進行します。ジョブが 30 日以上停止状態のままになると、失敗します。