创建 S3 分批操作任务
借助 S3 分批操作,您可以对特定 Amazon S3 对象的列表执行大规模分批操作。本节介绍创建 S3 分批操作任务所需的信息以及 Create Job
请求的结果。它还通过 Amazon Web Services Management Console、Amazon Command Line Interface (Amazon CLI) 和 Amazon SDK for Java 提供了创建分批操作任务的说明。
当您创建 S3 分批操作任务时,可以为全部任务或仅失败任务请求完成报告。只要成功调用了至少一个任务,S3 分批操作即会为已完成、已失败或已取消的任务生成报告。有关更多信息,请参阅 示例:S3 分批操作完成报告。
分批操作任务请求元素
要创建 S3 分批操作任务,您必须提供以下信息:
- 操作
-
指定希望 S3 分批操作对清单中的对象运行的操作。每种操作类型都接受特定于该操作的参数。这使您能够执行与针对每个对象逐一执行操作相同的任务。
- 清单
-
清单是您希望 S3 分批操作对其运行指定操作的所有对象的列表。您可以使用 CSV 格式的 Simple Storage Service (Amazon S3) 清单 报告作为清单,或使用您自己的自定义 CSV 对象列表。
如果清单中的对象位于受版本控制的桶中,指定对象的版本 ID 将在特定版本上执行此操作。如果未指定版本 ID,则批量操作将在最新版本上执行该操作。如果您的清单包含版本 ID 字段,则必须为清单中的所有对象提供版本 ID。有关更多信息,请参阅指定清单。
- 优先级
-
使用任务优先级指示此任务相对于在您账户中运行的其他任务的优先级。数字越大,优先级越高。
任务优先级仅相对于为同一账户和区域中的其他任务设置的优先级有意义。您可以选择适合您的编号系统。例如,您可能要为所有
Initiate Restore Object
任务分配优先级 1,为所有PUT Object Copy
任务分配优先级 2,为所有Put Object ACL
任务分配优先级 3。S3 分批操作根据优先级编号确定任务的优先级,但不严格保证顺序。因此,您不应使用任务优先级来确保任何一个任务会在其他任何任务之前开始或完成。如果您需要确保严格的顺序,请等到一个任务完成后,再开始下一个任务。
- RoleArn
-
指定将运行任务的 Amazon Identity and Access Management (IAM) 角色。您使用的 IAM 角色必须具有足够的权限来执行任务中指定的操作。例如,要运行
PUT Object Copy
任务,IAM 角色必须具有针对源桶的s3:GetObject
权限和针对目标桶的s3:PutObject
权限。该角色还需要读取清单和写入任务完成报告的权限。有关 IAM 角色的更多信息,请参阅《IAM 用户指南》中的 IAM 角色。
有关 Amazon S3 权限的更多信息,请参阅 Amazon S3 操作。
- 报告
-
指定您是否希望 S3 分批操作生成完成报告。如果您请求任务完成报告,还必须在此元素中提供报告参数。必要的信息包括:
-
您希望存储报告的桶
-
报告的格式
-
您希望报告包含所有任务的详细信息还是只包含失败的任务
-
可选的前缀字符串
-
- 标签(可选)
-
您可以通过添加标签来标记和控制对 S3 分批操作任务的访问。标签可用于确定谁负责分批操作任务。您可以创建附加了标签的任务,并且可以在创建任务后向任务添加标签。例如,您可以授予用户调用
CreateJob
的权限,前提是使用标签"Department=Finance"
创建此任务。有关更多信息,请参阅使用标签控制访问和标记任务。
- Description(可选)
-
要跟踪和监控任务,您还可以提供最多包含 256 个字符的描述。只要返回有关任务的信息或在 Amazon S3 控制台中显示任务详细信息,Amazon S3 便会包含此描述。随后您便可以根据自己分配的描述轻松地对任务进行排序和筛选。描述不一定是唯一的,因此您可以使用描述作为类别(例如“每周日志复制任务”)来帮助您跟踪多组相似的任务。
指定清单
清单是一种 Amazon S3 对象,其中包含您希望 Amazon S3 采取操作的对象键。要为任务创建清单,您需要指定清单对象键、ETag 和可选的版本 ID。清单的内容必须是 URL 编码的。原定设置情况下,Amazon S3 自动使用具有 Amazon S3 托管式密钥的服务器端加密(SSE-S3)对上传到 S3 桶 Amazon S3 的清单进行加密。不支持使用通过客户提供的密钥 (SSE-C) 进行服务器端加密的清单。仅当使用 CSV 格式的清单报告时,才支持使用具有 Amazon Key Management Service(Amazon KMS)密钥的服务器端加密(SSE-KMS)的清单。您的清单必须包括桶名称、对象键以及(可选)每个对象的对象版本。S3 分批操作不使用清单中的任何其他字段。
您可以使用以下两种格式之一,在创建任务请求中指定清单。
-
Amazon S3 清单报告 – 必须是 CSV 格式的 Amazon S3 清单报告。您必须指定与清单报告关联的
manifest.json
文件。有关清单报告的更多信息,请参阅 Simple Storage Service (Amazon S3) 清单。如果清单报告包括版本 ID,S3 分批操作将对特定对象版本进行操作。注意
-
S3 分批操作支持用 Amazon KMS 加密的 CSV 清单报告。
-
如果您提交使用 Amazon KMS 加密的清单报告清单,则 IAM policy 必须包含对于 manifest.json 对象以及所有关联 CSV 数据文件的
"kms:Decrypt"
和"kms:GenerateDataKey"
权限。
-
-
CSV 文件 – 文件中的每一行必须包括桶名称和对象键,还可选择包括对象版本。对象键必须进行 URL 编码,如以下示例所示。清单必须包含所有对象的版本 ID 或忽略所有对象的版本 ID。有关 CSV 清单格式的更多信息,请参阅《Amazon Simple Storage Service API 参考》中的 JobManifestSpec。
注意
S3 分批操作不支持 Amazon 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。
注意
Amazon S3 让您可以选择为 S3 分批复制任务创建清单。分批复制是复制现有对象的按需操作。有关分批复制的更多信息,请参阅 使用 S3 分批复制以复制现有对象。
创建任务
您可以使用 Amazon Web Services Management Console、Amazon CLI、Amazon SDK 或 REST API 创建 S3 批量操作任务。
有关创建任务请求的更多信息,请参阅 分批操作任务请求元素。
先决条件
在创建分批操作任务之前,请确认您已配置相关权限。有关更多信息,请参阅 授予 Amazon S3 分批操作的权限。
创建批量任务
登录到 Amazon Web Services Management Console,然后通过以下网址打开 Amazon S3 控制台:https://console.aws.amazon.com/s3/
。 -
在 Amazon S3 控制台的导航窗格中选择 Batch Operations (分批操作)。
-
请选择 Create job (创建任务)。
-
请选择要在其中创建任务的 Region (区域)。
-
在 Manifest format (清单格式) 下,请选择要使用的清单对象的类型。
-
如果您选择 S3 inventory report (S3 清单报告),请输入 Amazon S3 在 CSV 格式的清单报告中生成的 manifest.json 对象的路径,以及(可选)输入清单对象的版本 ID(如果您要使用的版本不是最新版本)。
-
如果您选择 CSV,请输入 CSV 格式清单对象的路径。清单对象必须遵循控制台中描述的格式。如果您希望使用并非最新的对象版本,则可以选择包含清单对象的版本 ID。
-
-
请选择 Next (下一步)。
-
在 Operation (操作) 下,请选择您希望对清单中列出的所有对象执行的操作。填写您所选操作的信息,然后选择下一步。
-
填写配置额外选项的信息,然后选择下一步。
-
对于审核,验证设置。如果需要进行更改,请选择 Previous。否则,请选择 Create job (创建任务)。
以下示例使用 Amazon CLI 创建 S3 分批操作 S3PutObjectTagging
任务。
创建分批操作 S3PutObjectTagging
任务
-
创建 Amazon 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 Resource Name (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
参数。因此,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-arnIAM-role
\ --client-request-token $(uuidgen) \ --description "job Description" \ --no-confirmation-required作为响应,Amazon S3 返回任务 ID(例如
00e123a4-c0d8-41f4-a0eb-b46f9ba5b07c
)。在接下来的命令中您需要该 ID。
以下示例使用 Amazon 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 参考中的 CreateJob REST API。
任务响应
如果 Create Job
请求成功,Amazon S3 将返回一个任务 ID。任务 ID 是 Amazon S3 自动生成的唯一标识符,以便于您标识分批操作任务并监控其状态。
通过 Amazon CLI、Amazon 开发工具包或 REST API 创建任务时,您可以设置 S3 分批操作以开始自动处理任务。任务在准备就绪后立即开始运行,不会等待后面较高优先级的任务。
当您通过 Amazon Web Services Management Console 创建任务时,在分批操作开始处理该任务之前,您必须查看任务详细信息并确认希望运行它。在您确认要运行任务后,任务的进度情况与您通过其他方法之一创建的任务一样。如果任务保持暂停状态超过 30 天,则它将失败。