创建 S3 批处理操作作业 - Amazon Simple Storage Service
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

欢迎使用新的 Amazon S3 用户指南! Amazon S3 用户指南结合了以下三个已停用的指南中的信息和说明:Amazon S3 开发人员指南Amazon S3 控制台用户指南Amazon S3 入门指南

创建 S3 批处理操作作业

借助 S3 批处理操作,您可以对特定 Amazon S3 对象的列表执行大规模批处理操作。您可以使用 AWS 管理控制台、AWS 命令行界面 (AWS CLI)、AWS 开发工具包或 REST API 创建 S3 批处理操作作业。

有关批处理操作的更多信息,请参阅S3 批处理操作基础知识

本节介绍创建 S3 批处理操作作业所需的信息以及 Create Job 请求的结果。它还提供了创建批处理操作作业的说明。

当您创建 S3 批处理操作作业时,可以为全部任务或仅失败任务请求完成报告。只要成功调用了至少一个任务,S3 批处理操作即会为已完成、已失败或已取消的作业生成报告。有关更多信息,请参阅 S3 批处理操作完成报告

先决条件:在创建批处理操作作业之前,请确认您已配置相关权限。有关更多信息,请参阅 授予 Amazon S3 批处理操作的权限

批处理操作作业请求元素

要创建 S3 批处理操作作业,您必须提供以下信息:

操作

指定希望 S3 批处理操作对清单中的对象运行的操作。每种操作类型都接受特定于该操作的参数。这使您能够执行与针对每个对象逐一执行操作相同的任务。

清单

清单是您希望 S3 批处理操作对其运行指定操作的所有对象的列表。您可以使用 CSV 格式的 Amazon S3 清单报告作为清单,或使用您自己的自定义 CSV 对象列表。

如果清单中的对象位于受版本控制的存储桶中,则应指定对象的版本 ID。有关更多信息,请参阅 指定清单

优先级

使用作业优先级指示此作业相对于在您账户中运行的其他作业的优先级。数字越大,优先级越高。

作业优先级仅相对于为同一账户和区域中的其他作业设置的优先级有意义。您可以选择适合您的编号系统。例如,您可能要为所有 Initiate Restore Object 作业分配优先级 1,为所有 PUT Object Copy 作业分配优先级 2,为所有 Put Object ACL 作业分配优先级 3。

S3 批处理操作根据优先级编号确定作业的优先级,但不严格保证顺序。因此,您不应使用作业优先级来确保任何一个作业会在其他任何作业之前开始或完成。如果您需要确保严格的顺序,请等到一个作业完成后,再开始下一个作业。

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 批处理操作作业的访问。标签可用于确定谁负责批处理操作作业。您可以创建附加了标签的作业,并且可以在创建作业后向作业添加标签。例如,您可以授予 IAM 用户调用 CreateJob 的权限,前提是使用标签 "Department=Finance" 创建此作业。

有关更多信息,请参阅 使用标签控制访问和标记作业

描述(可选)

要跟踪和监控作业,您还可以提供最多包含 256 个字符的描述。只要返回有关作业的信息或在 Amazon S3 控制台中显示作业详细信息,Amazon S3 便会包含此描述。随后您便可以根据自己分配的描述轻松地对作业进行排序和筛选。描述不一定是唯一的,因此您可以使用描述作为类别(例如“每周日志复制作业”)来帮助您跟踪多组相似的作业。

指定清单

清单是一种 Amazon S3 对象,列出您希望 Amazon S3 采取操作的对象键。要为作业创建清单,您需要指定清单对象键、ETag 和可选的版本 ID。清单的内容必须是 URL 加密的。不支持使用以客户提供的密钥进行服务器端加密 (SSE-C) 和以 AWS Key Management Service 客户主密钥 (CMK) 进行服务器端加密 (SSE-KMS) 的清单。您的清单必须包括存储桶名称、对象键以及(可选)每个对象的对象版本。S3 批处理操作不使用清单中的任何其他字段。

您可以使用以下两种格式之一,在创建作业请求中指定清单。

  • 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. Manifest format (清单格式) 下,选择要使用的清单对象的类型。

    • 如果您选择 S3 inventory report (S3 清单报告),请输入 Amazon S3 在 CSV 格式的清单报告中生成的 manifest.json 对象的路径,以及(可选)输入清单对象的版本 ID(如果您要使用的版本不是最新版本)。

    • 如果您选择 CSV,请输入 CSV 格式清单对象的路径。清单对象必须遵循控制台中描述的格式。如果您希望使用并非最新的对象版本,则可以选择包含清单对象的版本 ID。

  6. 选择 Next (下一步)

  7. Operation (操作) 下,选择您希望对清单中列出的所有对象执行的操作。填写您所选操作的信息,然后选择下一步

  8. 填写配置额外选项的信息,然后选择下一步

  9. 对于审核,验证设置。如果需要进行更改,请选择 Previous。否则,选择创建作业

以下示例使用 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。

以下示例使用适用于 Java 的 AWS 开发工具包创建 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 开发工具包或 REST API 创建作业时,您可以设置 S3 批处理操作以开始自动处理作业。作业在准备就绪后立即开始运行,不会等待后面较高优先级的作业。

当您通过 AWS 管理控制台创建作业时,在批处理操作开始处理该作业之前,您必须查看作业详细信息并确认希望运行它。在您确认要运行作业后,作业的进度情况与您通过其他方法之一创建的作业一样。如果作业保持暂停状态超过 30 天,则它将失败。