バッチ操作ジョブのリクエストの要素マニフェストの指定ジョブの作成ジョブのレスポンス

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

S3 バッチ操作を使用すると、特定の Amazon S3 オブジェクトのリストに対して大規模なバッチ操作を実行できます。このセクションでは、S3 バッチ操作ジョブの作成に必要な情報と Create Job リクエストの結果について説明します。また、AWS Management Console、AWS Command Line Interface (AWS CLI)、および AWS SDK for Java を使用したバッチ操作ジョブの作成手順についても説明します。

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

次の動画では、を使用してバッチ操作ジョブを作成する方法の簡単なデモンストレーションを示しますAWS Management Console

バッチ操作ジョブのリクエストの要素

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

オペレーション

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

マニフェスト

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

マニフェスト内のオブジェクトがバージョニング対応のバケット内にある場合は、そのオブジェクトのバージョン ID を指定すると特定のバージョンに対してオペレーションが実行されます。バッチ操作では、バージョン ID が指定されていない場合、最新バージョンでオペレーションが実行されます。マニフェストにバージョン ID フィールドが含まれている場合は、マニフェスト内にあるすべてのオブジェクトのバージョン 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" 付きで作成されていることを条件として、CreateJob を呼び出すアクセス許可をユーザーに付与できます。

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

Description (オプション)

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

マニフェストの指定

マニフェストは、Simple Storage Service (Amazon S3) でオペレーションを実行するオブジェクトのキーを含む Simple Storage Service (Amazon S3) のオブジェクトです。ジョブのマニフェストを作成するには、マニフェストオブジェクトキー、ETag、およびオプションでバージョン ID を指定します。マニフェストの内容は URL エンコードされている必要があります。デフォルトでは、Amazon S3 は、Amazon S3 マネージドキー (SSE-S3) によるサーバー側の暗号化を自動的に使用して、S3 バケット Amazon S3 にアップロードされたマニフェストを暗号化します。顧客指定のキーを使用したサーバー側の暗号化 (SSE-C) を使用するマニフェストはサポートされていません。AWS Key Management Service (AWS KMS) キー (SSE-KMS) でサーバー側の暗号化を使用するマニフェストは、CSV 形式のインベントリレポートを使用する場合にのみサポートされます。マニフェストには、各オブジェクトのバケット名、オブジェクトキー、およびオプションでオブジェクトバージョンを含める必要があります。マニフェストのその他のフィールドは、S3 バッチ操作では使用されません。

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

Amazon S3 インベントリレポート - CSV 形式の Amazon S3 インベントリレポートである必要があります。インベントリレポートに関連付けられた manifest.json ファイルを指定する必要があります。インベントリレポートの詳細については、「Amazon S3 インベントリ」を参照してください。インベントリレポートにバージョン ID が含まれている場合、S3 バッチ操作は特定のオブジェクトのバージョンに対して実行されます。
注記
- S3 バッチ操作では、AWS KMS で暗号化された CSV 形式のインベントリレポートがサポートされています。
- インベントリレポートマニフェストを AWS KMS で暗号化して送信する場合、IAM ポリシーでは manifest.json オブジェクトおよび関連するすべての CSV データファイルに対するアクセス許可の "kms:Decrypt" と "kms:GenerateDataKey" が必要です。
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 を指定しなかった場合、Simple Storage Service (Amazon S3) はジョブの作成時に存在していたバージョンではなく、最新バージョンのオブジェクトに対してオペレーションを実行します。この動作を回避する唯一の方法は、マニフェスト内でリストされたオブジェクトにバージョン ID を指定することです。

注記

Simple Storage Service (Amazon S3) には、S3 バッチレプリケーションジョブのマニフェストを作成するオプションがあります。バッチレプリケーションは、既存のオブジェクトをレプリケートするオンデマンドオペレーションです。バッチレプリケーションの詳細については、「S3 バッチレプリケーションを使用した既存のオブジェクトのレプリケーション」を参照してください。

ジョブの作成

S3 バッチオペレーションジョブは、AWS Management Console、AWS CLI、AWS SDK、または REST API を使用して作成できます。

ジョブリクエストの作成の詳細については、バッチ操作ジョブのリクエストの要素を参照してください。

前提条件

バッチ操作ジョブを作成する前に、関連する許可が設定されていることを確認します。詳細については、「Amazon S3 バッチ操作に対するアクセス許可の付与」を参照してください。

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

AWS Management Console にサインインし、Amazon S3 コンソール (https://console.aws.amazon.com/s3/) を開きます。
Amazon S3 コンソールのナビゲーションペインで [Batch Operations (バッチ操作)] を選択します。
[ジョブの作成] を選択します。
ジョブを作成する [Region (リージョン)] を選択します。
[マニフェストの形式] で、使用するマニフェストオブジェクトのタイプを選択します。
- [S3 inventory report (S3 インベントリレポート)] を選択する場合、CSV 形式のインベントリレポートの一部として Amazon S3 が生成する manifest.json オブジェクトへのパスと、最新のバージョンではなく特定のバージョンを使用する場合には、オプションでマニフェストオブジェクトのバージョン ID を入力します。
- [CSV] を選択する場合は、CSV 形式のマニフェストオブジェクトへのパスを入力します。マニフェストオブジェクトは、コンソールで説明される形式に従う必要があります。最新のバージョンではなく特定のバージョンを使用する場合には、マニフェストオブジェクトのバージョン ID をオプションで含めることもできます。
[Next (次へ)] を選択します。
[Operation (オペレーション)] で、マニフェストに登録されたすべてのオブジェクトを実行するオペレーションを選択します。選択したオペレーションに関する情報を入力して、[次へ] を選択します。
[追加オプションの設定] に関する情報を入力して、[次へ] を選択します。
[Review (確認)] で、設定を確認します。変更が必要な場合は、[戻る] を選択します。それ以外の場合は、[ジョブの作成] を選択します。

次の例では、AWS CLI を使用して S3 バッチ操作ジョブ S3PutObjectTagging を作成します。

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

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

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 が必要となります。

アクセス許可を含む 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}}/*"
      ]
    }
  ]
}'

S3PutObjectTagging ジョブを作成します。

manifest.csv ファイルは、バケットのリストとオブジェクトキー値を提供します。このジョブは、マニフェストで識別されたオブジェクトに指定されたタグを適用します。ETag は manifest.csv オブジェクトの ETag であり、Amazon S3 コンソールから取得できます。このリクエストは no-confirmation-required パラメータを指定するため、update-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();
        }
    }
}

REST API を使用して、バッチ操作ジョブを作成できます。詳細については、Amazon Simple Storage Service API リファレンスの「タスク REST API を作成する」を参照してください。

ジョブのレスポンス

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

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

AWS Management Console を使用してジョブを作成するときは、ジョブの詳細を確認し、バッチ操作がそのジョプの処理を開始する前に実行することを確認する必要があります。ジョブの実行を確認した後は、他のメソッドのいずれかを使用してそれを作成した場合と同じように進行します。ジョブが 30 日以上停止状態のままになると、失敗します。

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

アクセス許可の付与

サポートされているオペレーション