# 跟踪任务状态和完成报告
<a name="batch-ops-job-status"></a>

借助 S3 分批操作，您可以查看和更新任务状态、添加通知和日志记录、跟踪任务失败以及生成完成报告。

**Topics**
+ [任务状态](#batch-ops-job-status-table)
+ [更新任务状态](#updating-job-statuses)
+ [通知和日志记录](#batch-ops-notifications)
+ [跟踪任务失败](#batch-ops-job-status-failure)
+ [完成报告](#batch-ops-completion-report)
+ [示例：通过 Amazon CloudTrail 在 Amazon EventBridge 中跟踪 S3 分批操作任务。](batch-ops-examples-event-bridge-cloud-trail.md)
+ [示例：S3 分批操作完成报告](batch-ops-examples-reports.md)

## 任务状态
<a name="batch-ops-job-status-table"></a>

在您创建和运行任务之后，该任务会逐步经过一系列状态。下表描述了状态以及状态之间可能的转换。


| Status | 说明 | 转换 | 
| --- | --- | --- | 
| `New` | 在您创建任务时，任务首先处于 `New` 状态。 | Amazon S3 开始处理清单对象时，任务自动转入 `Preparing` 状态。 | 
| `Preparing` | Amazon S3 正在处理清单对象及其他任务参数，以设置和运行任务。 | Amazon S3 完成清单和其他参数的处理之后，任务自动转入 `Ready` 状态。然后，任务随时可以在清单中列出的对象上开始运行指定的操作。如果任务要求在运行之前确认，就像您在使用 Amazon S3 控制台创建任务时那样，则任务从 `Preparing` 转换为 `Suspended`。在您确认希望运行之前，任务将保持在 `Suspended` 状态。 | 
| `Suspended` | 任务需要确认，但您尚未确认您想要运行该任务。只有使用 Amazon S3 控制台创建的任务需要确认。使用控制台创建的任务在 `Preparing` 之后立即进入 `Suspended` 状态。在您确认希望运行任务并且任务成为 `Ready` 状态之后，它不会再返回 `Suspended` 状态。 | 在您确认希望运行任务之后，其状态将更改为 `Ready`。 | 
| `Ready` | Amazon S3 已准备好开始运行请求的对象操作。 | Amazon S3 开始运行任务时，任务自动转入 `Active` 状态。任务保持在 `Ready` 状态的时间长度取决于您是否已经在运行具有较高优先级的任务，以及完成这些任务需要多长时间。 | 
| `Active` | Amazon S3 正在对清单中列出的对象执行请求的操作。当任务处于 `Active` 状态时，您可使用 Amazon S3 控制台，或者通过 REST API、Amazon CLI 或 Amazon 开发工具包使用 `DescribeJob` 操作监控其进度。 | 当任务不再在对象上运行操作时，该任务就移出 `Active` 状态。此行为自动发生，例如在任务成功完成或失败时。或者，此行为也可作为用户操作的结果发生，例如取消某个任务。任务转入的状态取决于发生转换的原因。 | 
| `Pausing` | 任务从其他状态转换为 `Paused`。 | `Paused` 阶段完成时，任务自动转入 `Pausing` 状态。 | 
| `Paused` | 在当前任务正在运行时，如果您提交了具有更高优先级的其他任务，任务可以进入 `Paused` 状态。 | 对于处于 `Paused` 状态的任务，如果阻止了该任务的任何较高优先级的任务执行完成、失败或暂停，则该任务自动返回 `Active` 状态。 | 
| `Completing` | 任务从其他状态转换为 `Complete`。 | `Complete` 阶段完成时，任务自动转入 `Completing` 状态。 | 
| `Complete` | 任务已完成对清单中所有对象执行请求的操作。对于每个对象，操作可能成功或失败。如果您配置任务生成完成报告，则在任务处于 `Complete` 状态之后报告立即可用。 | `Complete` 是最终状态。任务一旦进入 `Complete` 状态，就不会转换为任何其它状态。 | 
| `Cancelling` | 任务转换为 `Cancelled` 状态。 | `Cancelled` 阶段完成时，任务自动转入 `Cancelling` 状态。 | 
| `Cancelled` | 您请求取消任务，而 S3 批量操作已成功取消了任务。任务将不会向 Amazon S3 提交任何新请求。 | `Cancelled` 是最终状态。任务进入 `Cancelled` 状态之后，就不会转换为任何其它状态。 | 
| `Failing` | 任务转换为 `Failed` 状态。 | `Failed` 阶段完成后，任务自动转入 `Failing` 状态。 | 
| `Failed` | 任务已失败，不再运行。有关任务失败的更多信息，请参阅 [跟踪任务失败](#batch-ops-job-status-failure)。 | `Failed` 是最终状态。任务进入 `Failed` 状态之后，就不会转换为任何其它状态。 | 

## 更新任务状态
<a name="updating-job-statuses"></a>

以下 Amazon CLI 和适用于 Java 的 Amazon SDK 示例更新批量操作任务的状态。有关使用 Amazon S3 控制台管理批量操作任务的更多信息，请参阅[使用 Amazon S3 控制台管理 S3 分批操作任务](batch-ops-managing-jobs.md#batch-ops-manage-console)。

### 使用 Amazon CLI
<a name="batch-ops-example-cli-update-job-status"></a>

要使用以下示例命令，请将 *`user input placeholders`* 替换为您自己的信息。
+ 如果未在 `create-job` 命令中指定 `--no-confirmation-required` 参数，则任务将保持为暂停状态，直至通过将其状态设置为 `Ready` 来确认任务。然后，Amazon S3 会使任务符合执行的条件。

  ```
  aws s3control update-job-status \
      --region us-west-2 \
      --account-id 123456789012 \
      --job-id 00e123a4-c0d8-41f4-a0eb-b46f9ba5b07c \
      --requested-job-status 'Ready'
  ```
+ 通过将任务状态设置为 `Cancelled` 来取消任务。

  ```
  aws s3control update-job-status \
       --region us-west-2 \
       --account-id 123456789012 \
       --job-id 00e123a4-c0d8-41f4-a0eb-b46f9ba5b07c \
       --status-update-reason "No longer needed" \
       --requested-job-status Cancelled
  ```

### 使用适用于 Java 的 Amazon 开发工具包
<a name="batch-ops-examples-java-update-job-status"></a>

有关如何使用适用于 Java 的 Amazon SDK 更新任务状态的示例，请参阅《Amazon S3 API Reference》**中的 [Update the status of a batch job](https://docs.amazonaws.cn/AmazonS3/latest/API/s3-control_example_s3-control_UpdateJobStatus_section.html)。

## 通知和日志记录
<a name="batch-ops-notifications"></a>

除了请求完成报告外，还可以使用 Amazon CloudTrail 捕获、查看和审计批量操作活动。由于批量操作使用现有的 Amazon S3 API 操作来执行任务，因此，这些任务还会发出与您直接调用这些操作时相同的事件。因此，可以使用相同的通知、日志记录和审计工具以及已用于 Amazon S3 的过程，来跟踪和记录任务及其所有工作的进度。有关更多信息，请参阅以下部分中的示例。

**注意**  
批量操作会在任务执行期间在 CloudTrail 中同时生成管理事件和数据事件。这些事件的数量随每个任务的清单中的键数量而扩展。有关更多信息，请参阅 [CloudTrail 定价](https://www.amazonaws.cn/cloudtrail/pricing/)页面，其中包括定价如何根据您在账户中配置的跟踪数量而变化的示例。要了解如何配置和记录事件以满足您的需求，请参阅《*Amazon CloudTrail 用户指南*》中的[创建您的第一个跟踪](https://docs.amazonaws.cn/awscloudtrail/latest/userguide/cloudtrail-tutorial.html#tutorial-step2)。

有关 Amazon S3 事件的更多信息，请参阅 [Amazon S3 事件通知](EventNotifications.md)。

## 跟踪任务失败
<a name="batch-ops-job-status-failure"></a>

如果 S3 分批操作任务遇到的问题使其无法成功运行（如无法读取指定清单），则该任务失败。任务失败时，系统会生成一个或多个故障代码或失败原因。S3 批量操作将故障代码和原因与任务一起存储，便于您通过请求任务的详细信息来查看它们。如果您请求任务的完成报告，同时还会显示故障代码和原因。

为防止任务运行大量不成功的操作，Amazon S3 会对每个分批操作任务施加任务失败阈值。当任务已运行至少 1000 项工作时，Amazon S3 将监控工作失败率。在任何时刻，如果失败率（失败的任务数占已运行任务总数的比例）超过 50%，则任务失败。如果任务由于超过了任务失败阈值而失败，您可以确定造成失败的原因。例如，您可能在清单中意外地包括了一些指定存储桶中不存在的对象。修复错误之后，您可以重新提交任务。

**注意**  
S3 批量操作异步进行操作，而工作并不一定按照清单中列出对象的顺序来运行。因此您不能使用清单顺序来确定哪些对象的任务成功，哪些对象的任务失败。而是可以通过查看任务的完成报告（如果已请求）或查看 Amazon CloudTrail 事件日志来帮助确定失败原因。

## 完成报告
<a name="batch-ops-completion-report"></a>

在创建任务时，您可以请求完成报告。只要 S3 批量操作成功调用至少一项工作，Amazon S3 便会在任务完成运行工作、失败或被取消后生成完成报告。可对完成报告进行配置，以包含所有任务或只包含失败的任务。

完成报告包含任务配置、状态以及每项工作的信息，包括对象键和版本、状态、错误代码以及有关任何错误的描述。完成报告提供了以合并格式查看任务结果的简单途径，且无需进行任何附加设置。完成报告使用具有 Amazon S3 托管式密钥的服务器端加密（SSE-S3）来进行加密。有关完成报告的示例，请参阅 [示例：S3 分批操作完成报告](batch-ops-examples-reports.md)。

如果您未配置完成报告，则仍可使用 CloudTrail 和 Amazon CloudWatch 监控并审计您的任务及其各项工作。有关更多信息，请参阅以下主题：

**Topics**
+ [任务状态](#batch-ops-job-status-table)
+ [更新任务状态](#updating-job-statuses)
+ [通知和日志记录](#batch-ops-notifications)
+ [跟踪任务失败](#batch-ops-job-status-failure)
+ [完成报告](#batch-ops-completion-report)
+ [示例：通过 Amazon CloudTrail 在 Amazon EventBridge 中跟踪 S3 分批操作任务。](batch-ops-examples-event-bridge-cloud-trail.md)
+ [示例：S3 分批操作完成报告](batch-ops-examples-reports.md)