本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# Amazon Systems Manager 运行命令执行块
<a name="ssm-send-command-block"></a>

在故障转移期间，您可能需要对自行管理的数据库或在 Amazon EC2 实例上运行的其他应用程序组件执行操作，例如，对自管理的数据库（例如 SQL Server、Oracle 或 MySQL）进行故障切换，或者运行其他特定于应用程序的故障转移或验证步骤。使用 Amazon Systems Manager Run Command 执行模块，您可以在这些实例上运行 Amazon Systems Manager 命令文档，作为区域切换计划中的一个步骤，并在计划中跟踪其进度、完成情况和重试次数。

此执行块仅支持类型为`Command`（Amazon Systems Manager Run Command）的 Amazon Systems Manager 文档，它以 Amazon Systems Manager 托管节点为目标。它不支持其他文档类型或其他目标资源类型。

## 配置
<a name="ssm-send-command-block-config"></a>

要配置 Amazon Systems Manager Run Command 执行块，请输入以下值。

**重要**  
在配置执行块之前，请确保计划的执行角色具有正确的 IAM 策略。有关更多信息，请参阅 [Amazon Systems Manager 运行命令执行区块示例策略](security_iam_region_switch_ssm.md)。

1. **步骤名称：**输入名称。

1. **步骤描述（可选）：**输入步骤的描述。

1. **每个区域的文档配置：**对于计划中的每个区域，您需要提供要运行的 Amazon Systems Manager 文档的 ARN。Region switch 在该文档 ARN 中指定的区域中运行命令，该区域必须与计划位于同一个分区中，并且是计划的其中一个区域。
   + **文档 ARN：**输入要运行的文档的亚马逊资源名称 (ARN)。 Amazon Systems Manager 必须提供 ARN；不接受裸文档名称。例如，`arn:aws:ssm:us-east-1:123456789012:document/MyDocument`。 Amazon 拥有的公共文件可以省略账户 ID。
   + **文档版本（可选）：**输入要运行的文档版本（`$DEFAULT``$LATEST`、或版本号）。省略此值时，将 Amazon Systems Manager 运行文档的默认版本。
   + **目标：**添加最多 5 个目标。每个目标都有一个 **Target 密钥**（例如`tag:Name`或`InstanceIds`），用于 Amazon Systems Manager 选择托管节点的方式。每个目标还有 **Target 值**（与键匹配的逗号分隔值，最多 50 个值）。一个键的多个值与组合在一起`OR`。

1. **参数（可选）：**添加最多 30 个参数以传递给文档。每个参数都有一个**参数名称**和**参数值**。每个参数最多可以有 50 个值，每个值最多可以包含 65,535 个字符，组合参数最多可以为 64 KiB。

1. **超时：**输入超时值。

1. **重试间隔：**输入重试间隔，从 1 到 1,440 分钟不等，让区域切换在返回失败时重试运行该命令。

1. **在不正常执行时跳过：选择是否在非优雅**（计划外）执行期间跳过此步骤。当您选择此选项时，区域切换将在不正常执行期间跳过此步骤。

然后，选择**保存步骤**。

此执行区块支持跨账户资源。要在不同账户下的区域中运行命令文档，请使用**Cross-account 访问**选项卡。有关更多信息，请参阅 [Cross-account 支持区域切换](cross-account-resources-rs.md)。

## 工作原理
<a name="ssm-send-command-block-how"></a>

当计划执行到此步骤时，Region switch 会调用文档 ARN 中指定的区域中的 Amazon Systems Manager `SendCommand` API，并传递您配置的文档版本、目标和参数。为了确定该命令是由区域切换计划触发的，区域切换将在命令的可选注释字段中传递计划 ARN。

区域切换使用 Amazon Systems Manager `SendCommand`默认值 `MaxConcurrency` (50) 和 `MaxErrors` (0) 来运行该命令。您无法修改这些值。

调用后`SendCommand`，Region switch 会通过调用 `ListCommandInvocations` API 来监控该命令，直到每次调用都达到终端状态。然后，区域切换会将该步骤报告为执行成功或失败。

**成功执行。**当命令在每个目标托管节点上达到`Success`状态时，即成功执行。成功执行后，步骤即完成，计划继续执行下一步。

**执行失败。**当命令在一个或多个目标托管节点上失败，或者当区域切换由于请求错误（例如文档、实例 ID 或参数无效）而无法启动命令时，执行失败。

**重试行为。**执行失败时，Region switch 会自动重试该命令，对同一组目标重新运行相同的文档。区域切换会继续按照您设置的时间间隔重试，直到命令成功或步骤达到超时为止。如果该步骤在命令成功之前达到超时时间，则该步骤将失败，计划将暂停执行失败的步骤。区域切换不会重试确定性 Amazon Systems Manager 请求错误（例如`InvalidDocument`、、或验证错误）`InvalidInstanceId``InvalidParameters`，因为同一个请求无法成功；这些错误会立即使步骤失败。您可以使用 “重**试间隔” 字段控制区域切换重试**的频率，该字段对应于区域切换 API `retryIntervalMinutes` 中。

**暂停并恢复。**如果您在命令运行时暂停计划，则区域切换不会对该命令执行任何操作。该命令将继续在托管节点上运行，并且计划将保持暂停状态，直到您恢复或取消该计划。恢复时，Region switch 会发出新的`SendCommand`呼叫，而不是恢复之前的命令。因此，命令文档应该是等效的。

**正在取消。**如果您在命令运行时取消该步骤，则区域切换会进行尽力`CancelCommand`调用。 `CancelCommand`不能保证已在托管节点上运行的命令会停止或暂停。

**不雅的处决。**这个区块支持优雅和不雅的执行。如果启用**了不正常执行时跳过**，则区域切换将在不正常执行期间跳过此步骤。