创建 S3 批量操作任务 - Amazon Simple Storage Service
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

创建 S3 批量操作任务

借助 Amazon S3 批量操作,您可以对特定 Amazon S3 对象的列表执行大规模批量操作。本节介绍创建 S3 批量操作任务所需的信息以及 CreateJob 请求的结果。它还提供说明,讲解如何通过使用 Amazon S3 控制台、Amazon Command Line Interface(Amazon CLI)和 Amazon SDK for Java 创建批量操作任务。

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

批量操作任务请求元素

要创建 S3 批量操作任务,您必须提供以下信息:

操作

指定希望 S3 批量操作对清单中的对象运行的操作。每种操作类型都接受特定于该操作的参数。借助批量操作功能,您可以批量执行操作,其结果与对每个对象逐个执行该操作相同。

清单

清单是您希望 S3 批量操作对其运行指定操作的所有对象的列表。您可以使用以下方法为批量操作任务指定清单。

  • 手动创建您自己自定义的 CSV 格式的对象列表。

  • 选择现有的 CSV 格式的 Amazon S3 清单 报告。

  • 直接批量操作功能可根据您在创建任务时指定的对象筛选条件自动生成清单。此选项适用于您在 Amazon S3 控制台中创建的批量复制任务,也适用于您使用 Amazon CLI、Amazon SDK 或 Amazon S3 REST API 创建的任何任务类型。

注意
  • 无论您如何指定清单,列表本身都必须存储在通用存储桶中。批量操作无法从目录存储桶中导入现有清单,也无法将生成的清单保存到目录存储桶。但是,清单中描述的对象可以存储在目录存储桶中。有关更多信息,请参阅目录存储桶

  • 如果清单中的对象位于受版本控制的存储桶中,指定对象的版本 ID 时,批量操作将在特定版本上执行此操作。如果未指定版本 ID,则批量操作将针对最新对象版本执行该操作。如果您的清单包含版本 ID 字段,则必须为清单中的所有对象提供版本 ID。

有关更多信息,请参阅指定清单

优先级

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

任务优先级仅相对于为同一账户和区域中的其他任务设置的优先级有意义。您可以选择适合您的编号系统。例如,您可能希望将所有还原RestoreObject)任务的优先级指定为 1,将所有复制CopyObject)任务的优先级指定为 2,并将所有替换访问控制列表(ACL)PutObjectAcl)任务的优先级指定为 3。

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

RoleArn

指定将运行任务的 Amazon Identity and Access Management (IAM) 角色。您使用的 IAM 角色必须具有足够的权限来执行任务中指定的操作。例如,要运行 CopyObject 任务,IAM 角色必须具有针对源存储桶的 s3:GetObject 权限和针对目标存储桶的 s3:PutObject 权限。该角色还需要读取清单和写入任务完成报告的权限。

有关 IAM 角色的更多信息,请参阅《IAM 用户指南》中的 IAM 角色

有关 Amazon S3 权限的更多信息,请参阅 Amazon S3 操作

注意

对目录存储桶执行操作的批量操作任务需要特定的权限。有关更多信息,请参阅适用于 S3 Express One Zone 的 Amazon Identity and Access Management(IAM)

报告

指定您是否希望 S3 批量操作生成完成报告。如果您请求任务完成报告,还必须在此元素中提供报告参数。必要的信息包括:

  • 您希望存储报告的存储桶

    注意

    报告必须存储在通用存储桶中。批量操作功能无法将报告保存到目录存储桶中。有关更多信息,请参阅目录存储桶

  • 报告的格式

  • 您希望报告包含所有任务的详细信息还是只包含失败的任务

  • 可选的前缀字符串

标签(可选)

您可以通过添加标签来标记和控制对 S3 批量操作任务的访问。您可以使用标签来标识谁负责批量操作任务,或者控制用户与批量操作任务的交互方式。任务标签的存在可授予或限制用户取消任务、激活处于确认状态的任务或更改任务优先级的能力。例如,您可以授予用户调用 CreateJob 操作的权限,前提是使用标签 "Department=Finance" 创建此任务。

您可以创建附加了标签的任务,并且可以在创建任务后向任务添加标签。

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

Description(可选)

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

指定清单

清单是一种 Amazon S3 对象,其中包含您希望 Amazon S3 采取操作的对象键。您可以通过下列方式之一提供清单:

  • 手动创建新的清单文件。

  • 使用现有的清单。

  • 直接批量操作功能可根据您在创建任务时指定的对象筛选条件自动生成清单。此选项适用于您在 Amazon S3 控制台中创建的批量复制任务,也适用于您使用 Amazon CLI、Amazon SDK 或 Amazon S3 REST API 创建的任何任务类型。

注意

无论您如何指定清单,列表本身都必须存储在通用存储桶中。批量操作无法从目录存储桶中导入现有清单,也无法将生成的清单保存到目录存储桶。但是,清单中描述的对象可以存储在目录存储桶中。有关更多信息,请参阅目录存储桶

创建清单文件

要手动创建清单文件,您需要采用 CSV 格式列表的形式,指定清单对象键、ETag(实体键)和可选的版本 ID。清单的内容必须是 URL 编码的。

默认情况下,Amazon S3 自动使用具有 Amazon S3 托管密钥的服务器端加密(SSE-S3)对上传到 Amazon S3 存储桶的清单进行加密。不支持使用具有客户提供密钥(SSE-C)的服务器端加密的清单。仅当使用 CSV 格式的清单报告时,才支持使用具有 Amazon Key Management Service(Amazon KMS)密钥的服务器端加密(SSE-KMS)的清单。

您的清单必须包括存储桶名称、对象键以及(可选)每个对象的对象版本。S3 批量操作不使用清单中的任何其他字段。

注意

如果清单中的对象位于受版本控制的存储桶中,指定对象的版本 ID 时,批量操作将在特定版本上执行此操作。如果未指定版本 ID,则批量操作将针对最新对象版本执行该操作。如果您的清单包含版本 ID 字段,则必须为清单中的所有对象提供版本 ID。

下面是 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

指定现有的清单文件

您可以使用以下两种格式之一,在创建任务请求中指定清单文件:

  • Amazon S3 清单报告 – 必须是 CSV 格式的 Amazon S3 清单报告。您必须指定与清单报告关联的 manifest.json 文件。有关清单报告的更多信息,请参阅 Amazon S3 清单。如果清单报告包括版本 ID,S3 批量操作将对特定对象版本进行操作。

    注意
    • S3 批量操作支持用 SSE-KMS 加密的 CSV 格式清单报告

    • 如果您提交使用 SSE-KMS 加密的清单报告清单,则 IAM 策略必须包含对于 manifest.json 对象以及所有关联 CSV 数据文件的 "kms:Decrypt""kms:GenerateDataKey" 权限。

  • CSV 文件 – 文件中的每一行必须包括存储桶名称和对象键,还可选择包括对象版本。对象键必须进行 URL 编码,如以下示例所示。清单必须包含所有对象的版本 ID 或忽略所有对象的版本 ID。有关 CSV 清单格式的更多信息,请参阅《Amazon Simple Storage Service API 参考》中的 JobManifestSpec

    注意

    S3 批量操作不支持使用 SSE-KMS 加密的 CSV 清单文件

重要

当您使用手动创建的清单和受版本控制的存储桶时,我们建议您指定对象的版本 ID。创建任务时,S3 批量操作会在运行任务之前解析整个清单。不过,它不会获取存储桶状态的“快照”。

由于清单可以包含数十亿个对象,因此任务可能需要很长时间才能运行完,这可能会影响任务所针对的对象版本。假设您在任务运行时用新版本覆盖某个对象,但未指定该对象的版本 ID。在这种情况下,Amazon S3 将对该对象的最新版本(而不是在创建作业时存在的版本)执行操作。避免此行为的唯一方式是为清单中列出的对象指定版本 ID。

自动生成清单

您可以指示 Amazon S3 批量操作根据创建任务时指定的对象筛选条件自动生成清单。此选项适用于您在 Amazon S3 控制台中创建的批量复制任务,也适用于您使用 Amazon CLI、Amazon SDK 或 Amazon S3 REST API 创建的任何任务类型。有关分批复制的更多信息,请参阅 使用 S3 分批复制以复制现有对象

要自动生成清单,请在任务创建请求中指定以下元素:

  • 有关包含您的源对象的存储桶的信息,包括存储桶拥有者和 Amazon 资源名称(ARN)

  • 有关清单输出的信息,包括用于创建清单文件的标志、输出存储桶拥有者、ARN、前缀、文件格式和加密类型

  • 按创建日期、密钥名称、大小、存储类和标签来筛选对象的可选标准

对象筛选标准

要筛选要包含在自动生成的清单中的对象列表,您可以指定以下标准。有关更多信息,请参阅《Amazon S3 API 参考》中的 JobManifestGeneratorFilter

CreatedAfter

如果提供,则生成的清单仅包含在此时间之后创建的源存储桶对象。

CreatedBefore

如果提供,则生成的清单仅包含在此时间之前创建的源存储桶对象。

EligibleForReplication

如果提供,则生成的清单仅包含根据源存储桶上的复制配置而符合复制条件的对象。

KeyNameConstraint

如果提供,则生成的清单仅包含下面这样的源存储桶对象:其对象密钥与 MatchAnySubstringMatchAnyPrefixMatchAnySuffix 所指定的字符串约束相匹配。

MatchAnySubstring – 如果提供,则当指定的字符串出现在对象密钥字符串中的任何位置时,生成的清单将包含对象。

MatchAnyPrefix – 如果提供,则当指定的字符串出现在对象密钥字符串的开头时,生成的清单将包含对象。

MatchAnySuffix – 如果提供,则当指定的字符串出现在对象密钥字符串的末尾时,生成的清单将包含对象。

MatchAnyStorageClass

如果提供,则生成的清单仅包含以指定存储类存储的源存储桶对象。

ObjectReplicationStatuses

如果提供,则生成的清单仅包含具有指定复制状态之一的源存储桶对象。

ObjectSizeGreaterThanBytes

如果提供,则生成的清单仅包含文件大小大于指定字节数的源存储桶对象。

ObjectSizeLessThanBytes

如果提供,则生成的清单仅包含文件大小小于指定字节数的源存储桶对象。

注意

您无法克隆大多数自动生成清单的任务。可以克隆批量复制任务,除非它们使用 KeyNameConstraintMatchAnyStorageClassObjectSizeGreaterThanBytesObjectSizeLessThanBytes 清单筛选标准。

指定清单标准的语法因您用于创建任务的方法而异。有关示例,请参阅创建作业

创建作业

您可以使用 Amazon S3 控制台、Amazon CLI、Amazon SDK 或 Amazon S3 REST API 创建 S3 批量操作任务。

有关创建任务请求的更多信息,请参阅 批量操作任务请求元素

先决条件

在创建批量操作任务之前,请确认您已配置相关权限。有关更多信息,请参阅授予 Amazon S3 分批操作的权限

创建批量任务
  1. 登录到 Amazon Web Services Management Console,然后通过以下网址打开 Amazon S3 控制台:https://console.aws.amazon.com/s3/

  2. 在 Amazon S3 控制台的导航窗格中选择 Batch Operations(批量操作)

  3. 请选择 Create job (创建任务)

  4. 请选择要在其中创建任务的 Region (区域)

  5. Manifest format (清单格式) 下,请选择要使用的清单对象的类型。

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

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

    注意

    Amazon S3 控制台仅支持对批量复制任务自动生成清单。对于其他所有任务类型,如果您希望 Amazon S3 根据您指定的筛选标准自动生成清单,则必须使用 Amazon CLI、Amazon SDK 或 Amazon S3 REST API 配置您的任务。

  6. 请选择 Next(下一步)

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

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

  9. 对于审核,验证设置。如果需要进行更改,请选择 Previous。否则,请选择 Create job (创建任务)

Specify manifest

以下示例说明如何创建 S3 批量操作 S3PutObjectTagging 任务,以便处理现有清单文件中列出的对象。

创建批量操作 S3PutObjectTagging 任务
  1. 使用以下命令创建 Amazon Identity and Access Management(IAM)角色,然后创建一个 IAM 策略来分配相关权限。以下角色和策略授予 Amazon S3 添加对象标签的权限,您在后续步骤中创建任务时将需要用到该权限。

    1. 使用以下示例命令创建 IAM 角色供批量操作使用。要使用此示例命令,请将 S3BatchJobRole 替换为要为角色指定的名称。

      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 分批操作的权限

      注意

      对目录存储桶执行操作的批量操作任务需要特定的权限。有关更多信息,请参阅适用于 S3 Express One Zone 的 Amazon Identity and Access Management(IAM)

      要使用此示例命令,请按如下方式替换 user input placeholders

      • S3BatchJobRole 替换为您的 IAM 角色的名称。请确保此名称与您之前使用的名称一致。

      • PutObjectTaggingBatchJobPolicy 替换为要为 IAM 策略指定的名称。

      • DOC-EXAMPLE-DESTINATION-BUCKET 替换为包含要应用标签的对象的存储桶的名称。

      • DOC-EXAMPLE-MANIFEST-BUCKET 替换为包含清单的存储桶的名称。

      • DOC-EXAMPLE-REPORT-BUCKET 替换为要将完成报告交付到的存储桶的名称。

      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:::DOC-EXAMPLE-DESTINATION-BUCKET/*" }, { "Effect": "Allow", "Action": [ "s3:GetObject", "s3:GetObjectVersion", "s3:GetBucketLocation" ], "Resource": [ "arn:aws:s3:::DOC-EXAMPLE-MANIFEST-BUCKET", "arn:aws:s3:::DOC-EXAMPLE-MANIFEST-BUCKET/*" ] }, { "Effect":"Allow", "Action":[ "s3:PutObject", "s3:GetBucketLocation" ], "Resource":[ "arn:aws:s3:::DOC-EXAMPLE-REPORT-BUCKET", "arn:aws:s3:::DOC-EXAMPLE-REPORT-BUCKET/*" ] } ] }'
  2. 使用以下示例命令创建 S3PutObjectTagging 任务。

    manifest.csv 文件提供存储桶和对象键值的列表。任务将指定的标签应用到清单中标识的对象。ETagmanifest.csv 对象的 ETag,可以从 Amazon S3 控制台获取。此请求指定了 no-confirmation-required 参数,这样您就可以运行任务,而不必使用 update-job-status 命令进行确认。有关更多信息,请参阅 Amazon CLI 命令参考 中的 create-job

    要使用此示例命令,请将 user input placeholders 替换为您自己的信息。将 IAM-role 替换为您之前创建的 IAM 角色的 ARN。

    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:::DOC-EXAMPLE-REPORT-BUCKET","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 来识别、监控和修改任务。

Generate manifest

以下示例说明如何创建 S3 批量操作 S3DeleteObjectTagging 任务,该任务会根据您的对象筛选标准自动生成清单。此标准包括创建日期、密钥名称、大小、存储类和标签。

创建批量操作 S3DeleteObjectTagging 任务
  1. 使用以下命令创建 Amazon Identity and Access Management(IAM)角色,然后创建一个 IAM 策略来分配权限。以下角色和策略授予 Amazon S3 删除对象标签的权限,您在后续步骤中创建任务时将需要用到该权限。

    1. 使用以下示例命令创建 IAM 角色供批量操作使用。要使用此示例命令,请将 S3BatchJobRole 替换为要为角色指定的名称。

      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 分批操作的权限

      注意

      对目录存储桶执行操作的批量操作任务需要特定的权限。有关更多信息,请参阅适用于 S3 Express One Zone 的 Amazon Identity and Access Management(IAM)

      要使用此示例命令,请按如下方式替换 user input placeholders

      • S3BatchJobRole 替换为您的 IAM 角色的名称。请确保此名称与您之前使用的名称一致。

      • DeleteObjectTaggingBatchJobPolicy 替换为要为 IAM 策略指定的名称。

      • DOC-EXAMPLE-DESTINATION-BUCKET 替换为包含要应用标签的对象的存储桶的名称。

      • DOC-EXAMPLE-MANIFEST-OUTPUT-BUCKET 替换为您想用于保存清单的存储桶的名称。

      • DOC-EXAMPLE-REPORT-BUCKET 替换为要将完成报告交付到的存储桶的名称。

      aws iam put-role-policy \ --role-name S3BatchJobRole \ --policy-name DeleteObjectTaggingBatchJobPolicy \ --policy-document '{ "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Action":[ "s3:DeleteObjectTagging", "s3:DeleteObjectVersionTagging" ], "Resource": "arn:aws:s3:::DOC-EXAMPLE-DESTINATION-BUCKET/*" }, { "Effect":"Allow", "Action":[ "s3:PutInventoryConfiguration" ], "Resource": "arn:aws:s3:::DOC-EXAMPLE-DESTINATION-BUCKET" }, { "Effect": "Allow", "Action": [ "s3:GetObject", "s3:GetObjectVersion", "s3:ListBucket" ], "Resource": [ "arn:aws:s3:::DOC-EXAMPLE-MANIFEST-OUTPUT-BUCKET", "arn:aws:s3:::DOC-EXAMPLE-MANIFEST-OUTPUT-BUCKET/*" ] }, { "Effect":"Allow", "Action":[ "s3:PutObject", "s3:ListBucket" ], "Resource":[ "arn:aws:s3:::DOC-EXAMPLE-REPORT-BUCKET", "arn:aws:s3:::DOC-EXAMPLE-REPORT-BUCKET/*", "arn:aws:s3:::DOC-EXAMPLE-MANIFEST-OUTPUT-BUCKET/*" ] } ] }'

  2. 使用以下命令创建 S3DeleteObjectTagging 任务。

    在此示例中,--report 部分中的值指定了将生成的任务报告的存储桶、前缀、格式和范围。该 --manifest -generator 部分指定了有关包含任务将处理的对象的源存储桶的信息、有关将为任务生成的清单输出列表的信息,以及按创建日期、名称限制、大小和存储类来缩小要包含在清单中的对象范围的筛选标准。该命令还指定任务的优先级、IAM 角色和 Amazon Web Services 区域。

    有关更多信息,请参阅 Amazon CLI 命令参考 中的 create-job

    要使用此示例命令,请将 user input placeholders 替换为您自己的信息。将 IAM-role 替换为您之前创建的 IAM 角色的 ARN。

    aws s3control create-job \ --account-id 012345678901 \ --operation '{ "S3DeleteObjectTagging": {} }' \ --report '{ "Bucket":"arn:aws:s3:::DOC-EXAMPLE-REPORT-BUCKET", "Prefix":"reports", "Format":"Report_CSV_20180820", "Enabled":true, "ReportScope":"AllTasks" }' \ --manifest-generator '{ "S3JobManifestGenerator": { "ExpectedBucketOwner": "012345678901", "SourceBucket": "arn:aws:s3:::DOC-EXAMPLE-SOURCE-BUCKET", "EnableManifestOutput": true, "ManifestOutputLocation": { "ExpectedManifestBucketOwner": "012345678901", "Bucket": "arn:aws:s3:::DOC-EXAMPLE-MANIFEST-OUTPUT-BUCKET", "ManifestPrefix": "prefix", "ManifestFormat": "S3InventoryReport_CSV_20211130" }, "Filter": { "CreatedAfter": "2023-09-01", "CreatedBefore": "2023-10-01", "KeyNameConstraint": { "MatchAnyPrefix": [ "prefix" ], "MatchAnySuffix": [ "suffix" ] }, "ObjectSizeGreaterThanBytes": 100, "ObjectSizeLessThanBytes": 200, "MatchAnyStorageClass": [ "STANDARD", "STANDARD_IA" ] } } }' \ --priority 2 \ --role-arn IAM-role \ --region us-east-1

    作为响应,Amazon S3 返回任务 ID(例如 00e123a4-c0d8-41f4-a0eb-b46f9ba5b07c)。您将需要此任务 ID 来识别、监控或修改任务。

Specify manifest

以下示例说明如何创建 S3 批量操作 S3PutObjectTagging 任务,以便处理现有清单文件中列出的对象。要使用此示例,请将 user input placeholders 替换为您自己的信息。

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:::DOC-EXAMPLE-REPORT-BUCKET"; 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(); } } }
Generate manifest

以下示例说明如何创建 S3 批量操作 s3PutObjectCopy 任务,以便根据对象筛选标准(包括创建日期、密钥名称和大小)自动生成清单。要使用此示例,请将 user input placeholders 替换为您自己的信息。

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.CreateJobRequest; import com.amazonaws.services.s3control.model.CreateJobResult; import com.amazonaws.services.s3control.model.JobManifestGenerator; import com.amazonaws.services.s3control.model.JobManifestGeneratorFilter; import com.amazonaws.services.s3control.model.JobOperation; import com.amazonaws.services.s3control.model.JobReport; import com.amazonaws.services.s3control.model.KeyNameConstraint; import com.amazonaws.services.s3control.model.S3JobManifestGenerator; import com.amazonaws.services.s3control.model.S3ManifestOutputLocation; import com.amazonaws.services.s3control.model.S3SetObjectTaggingOperation; import com.amazonaws.services.s3control.model.S3Tag; import java.time.Instant; import java.util.Date; import java.util.UUID; import java.util.ArrayList; import static com.amazonaws.regions.Regions.US_WEST_2; public class test { public static void main(String[] args) { String accountId = "012345678901"; String iamRoleArn = "arn:aws:iam::012345678901:role/ROLE"; String sourceBucketName = "arn:aws:s3:::DOC-EXAMPLE-SOURCE-BUCKET"; String reportBucketName = "arn:aws:s3:::DOC-EXAMPLE-REPORT-BUCKET"; String manifestOutputBucketName = "arn:aws:s3:::DOC-EXAMPLE-MANIFEST-OUTPUT-BUCKET"; String uuid = UUID.randomUUID().toString(); long minimumObjectSize = 100L; ArrayList<S3Tag> tagSet = new ArrayList<>(); tagSet.add(new S3Tag().withKey("keyOne").withValue("ValueOne")); ArrayList<String> prefixes = new ArrayList<>(); prefixes.add("s3KeyStartsWith"); try { JobOperation jobOperation = new JobOperation() .withS3PutObjectTagging(new S3SetObjectTaggingOperation() .withTagSet(tagSet) ); S3ManifestOutputLocation manifestOutputLocation = new S3ManifestOutputLocation() .withBucket(manifestOutputBucketName) .withManifestPrefix("manifests") .withExpectedManifestBucketOwner(accountId) .withManifestFormat("S3InventoryReport_CSV_20211130"); JobManifestGeneratorFilter jobManifestGeneratorFilter = new JobManifestGeneratorFilter() .withEligibleForReplication(true) .withKeyNameConstraint( new KeyNameConstraint() .withMatchAnyPrefix(prefixes)) .withCreatedBefore(Date.from(Instant.now())) .withObjectSizeGreaterThanBytes(minimumObjectSize); S3JobManifestGenerator s3JobManifestGenerator = new S3JobManifestGenerator() .withEnableManifestOutput(true) .withManifestOutputLocation(manifestOutputLocation) .withFilter(jobManifestGeneratorFilter) .withSourceBucket(sourceBucketName); JobManifestGenerator jobManifestGenerator = new JobManifestGenerator() .withS3JobManifestGenerator(s3JobManifestGenerator); 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(); CreateJobResult createJobResult = s3ControlClient.createJob(new CreateJobRequest() .withAccountId(accountId) .withOperation(jobOperation) .withManifestGenerator(jobManifestGenerator) .withReport(jobReport) .withPriority(42) .withRoleArn(iamRoleArn) .withClientRequestToken(uuid) .withDescription("job description") .withConfirmationRequired(true) ); System.out.println("Created job " + createJobResult.getJobId()); } 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

任务响应

如果 CreateJob 请求成功,Amazon S3 将返回一个任务 ID。任务 ID 是 Amazon S3 自动生成的唯一标识符,以便于您标识批量操作任务并监控其状态。

通过 Amazon CLI、Amazon SDK 或 REST API 创建任务时,您可以设置 S3 批量操作以开始自动处理任务。任务在准备就绪后立即开始运行,而不是等待后面较高优先级的任务。

当您通过 Amazon S3 控制台创建任务时,在批量操作开始处理该任务之前,您必须查看任务详细信息并确认希望运行它。如果任务保持暂停状态超过 30 天,则它将失败。