• AWS Systems Manager CloudWatch 控制面板在 2026 年 4 月 30 日之后将不再可用。客户可以像现在一样继续使用 Amazon CloudWatch 控制台来查看、创建和管理其 Amazon CloudWatch 控制面板。有关更多信息，请参阅 [Amazon CloudWatch 控制面板文档](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Dashboards.html)。
# AWS Systems Manager Run Command
使用 Run Command（AWS Systems Manager 中的一项工具），您可以通过安全方式远程管理托管式节点的配置。*托管式节点*是在[混合和多云](operating-systems-and-machine-types.md#supported-machine-types)环境中已为 Systems Manager 配置的任何 Amazon Elastic Compute Cloud（Amazon EC2）实例或非 EC2 计算机。Run Command 支持您自动完成常见管理任务以及大规模执行一次性配置更改。您可以从 AWS 管理控制台、AWS Command Line Interface（AWS CLI）、AWS Tools for Windows PowerShell 或 AWS SDK 使用 Run Command。Run Command 不另外收费。要开始使用 Run Command，请打开 [Systems Manager 控制台](https://console.aws.amazon.com//systems-manager/run-command)。在导航窗格中，请选择 **Run Command**。
管理员可以使用 Run Command 安装或引导启动应用程序，构建部署管道，从 Auto Scaling 组移除实例时捕获日志文件，将实例加入 Windows 域，等等。
由于系统支持 API 的分布式特性，Run Command API 遵循最终一致性模型。这意味着您执行的对您的资源产生影响的 API 命令的结果可能不会立即对您运行的所有后续命令可见。在执行紧随上一个 API 命令的 API 命令时，应记住这一点。
**开始使用**
下表包含可帮助您开始使用 Run Command 的信息。
****
| Topic | Details |
| --- | --- |
| [为 AWS Systems Manager 设置托管节点](systems-manager-setting-up-nodes.md) | 验证您是否已在[混合和多云](operating-systems-and-machine-types.md#supported-machine-types)环境中完成 Amazon Elastic Compute Cloud（Amazon EC2）实例以及非 EC2 计算机的设置要求。 |
| [使用 Systems Manager 管理混合和多云环境中的节点](systems-manager-hybrid-multicloud.md) | （可选）将本地服务器和虚拟机注册到 AWS，以便可以使用 Run Command 来管理它们。 |
| [使用 Systems Manager 管理边缘设备](systems-manager-setting-up-edge-devices.md) | （可选）配置边缘设备，以便可以使用 Run Command 管理它们。 |
| [在托管节点上运行命令](running-commands.md) | 了解如何使用 AWS 管理控制台 运行以一个或多个托管式节点为目标的命令。 |
| [Run Command 演练](run-command-walkthroughs.md) | 了解如何使用 Tools for Windows PowerShell 或 AWS CLI 运行命令。 |
**EventBridge 支持**
在 Amazon EventBridge 规则中，支持将此 Systems Manager 工具作为*事件*类型和*目标*类型。有关信息，请参阅 [使用 Amazon EventBridge 监控 Systems Manager 事件](monitoring-eventbridge-events.md) 和 [引用：Amazon EventBridge 事件模式和 Systems Manager 类型](reference-eventbridge-events.md)。
**更多信息**
+ [在 EC2 实例上远程 Run Command（10 分钟教程）](https://aws.amazon.com/getting-started/hands-on/remotely-run-commands-ec2-instance-systems-manager/)
+ 请参阅*《Amazon Web Services 一般参考》*中的 [Systems Manager 服务配额](https://docs.aws.amazon.com/general/latest/gr/ssm.html#limits_ssm)
+ [AWS Systems Manager API 参考](https://docs.aws.amazon.com/systems-manager/latest/APIReference/)
**Topics**
+ [设置 Run Command](run-command-setting-up.md)
+ [在托管节点上运行命令](running-commands.md)
+ [在命令中使用退出代码](run-command-handle-exit-status.md)
+ [了解命令状态](monitor-commands.md)
+ [Run Command 演练](run-command-walkthroughs.md)
+ [对 Systems Manager Run Command 进行故障排除](troubleshooting-remote-commands.md)
# 设置 Run Command
必须先为将运行命令的用户配置 AWS Identity and Access Management（IAM）策略，然后才能使用 Run Command（AWS Systems Manager 中的一项工具）管理节点。如果您在 IAM 策略中使用任何全局条件键执行 `SendCommand` 操作，则必须包含 `aws:ViaAWSService` 条件键并将布尔值设置为 `true`。示例如下：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:SendCommand"
],
"Resource": [
"arn:aws:ssm:us-east-1:111122223333:document/YourDocument"
],
"Condition": {
"StringEquals": {
"aws:SourceVpce": [
"vpce-1234567890abcdef0"
]
}
}
},
{
"Effect": "Allow",
"Action": [
"ssm:SendCommand"
],
"Resource": [
"arn:aws:ssm:us-east-1:111122223333:document/YourDocument"
],
"Condition": {
"Bool": {
"aws:ViaAWSService": "true"
}
}
}
]
}
```
------
您还必须为 Systems Manager 配置节点。有关更多信息，请参阅 [为 AWS Systems Manager 设置托管节点](systems-manager-setting-up-nodes.md)。
我们建议您完成以下可选设置任务，以帮助最大限度地改善托管式节点的安保状况并尽量减少节点的日常管理工作。
使用 Amazon EventBridge 监控命令执行情况
您可以使用 Eventbridge 记录命令执行状态更改。您可以创建一个规则，只要状态发生变换或者在变换到一个或多个感兴趣的状态时，就运行该规则。此外，您还可以将 Run Command 指定为发生 EventBridge 事件时的目标操作。有关更多信息，请参阅 [为 Systems Manager 事件配置 EventBridge](monitoring-systems-manager-events.md)。
使用 Amazon CloudWatch Logs 监控命令执行情况
您可以将 Run Command 配置为定期将所有命令输出和错误日志发送到 Amazon CloudWatch 日志组。您可以近乎实时地监控这些输出日志，搜索特定短语、值或模式，以及基于搜索创建警报。有关更多信息，请参阅 [为 Run Command 配置 Amazon CloudWatch Logs](sysman-rc-setting-up-cwlogs.md)。
限制对特定托管式节点的 Run Command 访问
您可以通过使用 AWS Identity and Access Management (IAM) 来限制用户在托管式节点上运行命令的能力。特别是，您可以创建 IAM policy，其中包含一个条件，规定用户只能在使用特定标签标记的托管节点上运行命令。有关更多信息，请参阅 [根据标签限制 Run Command 访问](#tag-based-access)。
## 根据标签限制 Run Command 访问
本节介绍如何通过在 IAM policy 中指定标签条件来限制用户在托管式节点上运行命令的能力。托管式节点包括[混合和多云](operating-systems-and-machine-types.md#supported-machine-types)环境中为 Systems Manager 配置的 Amazon EC2 实例和非 EC2 节点。尽管没有明确显示相关信息，但您也可以限制对托管式 AWS IoT Greengrass 核心设备的访问。首先，您必须标记 AWS IoT Greengrass 设备。有关更多信息，请参阅 *AWS IoT Greengrass Version 2 开发人员指南*中的[标记 AWS IoT Greengrass Version 2 资源](https://docs.aws.amazon.com/greengrass/v2/developerguide/tag-resources.html)。
您可以通过创建一个 IAM policy 将命令执行限制到特定托管节点，该策略包括一个条件，规定用户只能在带有特定标签的节点上运行命令。在以下示例中，通过以下方式来允许用户使用 Run Command (`Effect: Allow, Action: ssm:SendCommand`)：在任何节点 (`Resource: arn:aws:ec2:*:*:instance/*`) 上使用任何 SSM 文档 (`Resource: arn:aws:ssm:*:*:document/*`)，条件是节点为 Finance WebServer (`ssm:resourceTag/Finance: WebServer`)。如果用户向未经标记或具有除 `Finance: WebServer` 以外的任何标签的节点发送命令，则执行结果将显示 `AccessDenied`。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":[
"ssm:SendCommand"
],
"Resource":[
"arn:aws:ssm:*:*:document/*"
]
},
{
"Effect":"Allow",
"Action":[
"ssm:SendCommand"
],
"Resource":[
"arn:aws:ec2:*:*:instance/*"
],
"Condition":{
"StringLike":{
"ssm:resourceTag/Finance":[
"WebServers"
]
}
}
}
]
}
```
------
您可以创建允许用户在使用多个标签标记的托管式节点上运行命令的 IAM policy。以下策略允许用户在具有两个标签的托管式节点上运行命令。如果用户向未使用这两个标签标记的节点发送命令，则执行结果将显示 `AccessDenied`。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":[
"ssm:SendCommand"
],
"Resource":"*",
"Condition":{
"StringLike":{
"ssm:resourceTag/tag_key1":[
"tag_value1"
],
"ssm:resourceTag/tag_key2":[
"tag_value2"
]
}
}
},
{
"Effect":"Allow",
"Action":[
"ssm:SendCommand"
],
"Resource":[
"arn:aws:ssm:us-west-1::document/AWS-*",
"arn:aws:ssm:us-east-2::document/AWS-*"
]
},
{
"Effect":"Allow",
"Action":[
"ssm:UpdateInstanceInformation",
"ssm:ListCommands",
"ssm:ListCommandInvocations",
"ssm:GetDocument"
],
"Resource":"*"
}
]
}
```
------
您也可以创建允许用户在多个已标记托管式节点组上运行命令的 IAM policy。以下示例策略允许用户在任一已标记节点组或两个已标记节点组上运行命令。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":[
"ssm:SendCommand"
],
"Resource":"*",
"Condition":{
"StringLike":{
"ssm:resourceTag/tag_key1":[
"tag_value1"
]
}
}
},
{
"Effect":"Allow",
"Action":[
"ssm:SendCommand"
],
"Resource":"*",
"Condition":{
"StringLike":{
"ssm:resourceTag/tag_key2":[
"tag_value2"
]
}
}
},
{
"Effect":"Allow",
"Action":[
"ssm:SendCommand"
],
"Resource":[
"arn:aws:ssm:us-west-1::document/AWS-*",
"arn:aws:ssm:us-east-2::document/AWS-*"
]
},
{
"Effect":"Allow",
"Action":[
"ssm:UpdateInstanceInformation",
"ssm:ListCommands",
"ssm:ListCommandInvocations",
"ssm:GetDocument"
],
"Resource":"*"
}
]
}
```
------
有关创建 IAM policy 的更多信息，请参阅**《IAM 用户指南》中的[托管策略与内联策略](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html)。有关标记托管式节点的更多信息，请参阅 *AWS Resource Groups 用户指南*中的[标签编辑器](https://docs.aws.amazon.com/ARG/latest/userguide/tag-editor.html)。
# 在托管节点上运行命令
本节包括有关如何发送从 AWS Systems Manager 控制台到托管式节点的命令的信息。此部分还包括有关如何取消命令的信息。
请注意，如果节点为 var 目录配置了 `noexec` 挂载选项，Run Command 将无法成功运行命令。
**重要**
当您使用 Run Command 发送命令时，不要包含纯文本格式的敏感信息，例如密码、配置数据或其他密钥。您账户中的所有 Systems Manager API 活动都将记录在 AWS CloudTrail 日志的 S3 存储桶中。这意味着任何有权访问该 Amazon S3 存储桶的用户都能够查看这些密钥的纯文本值。因此，我们建议您创建和使用 `SecureString` 参数，以便加密您在 Systems Manager 操作中使用的敏感数据。
有关更多信息，请参阅 [使用 IAM 策略限制对 Parameter Store 参数的访问](sysman-paramstore-access.md)。
**执行历史记录保留**
每个命令的历史记录最多可保留 30 天。此外，您可以在 Amazon Simple Storage Service 中存储所有日志文件的副本，或在 AWS CloudTrail 中保存所有 API 调用的审计跟踪。
**相关信息**
有关使用其他工具发送命令的信息，请参阅以下主题：
+ [演练：将 AWS Tools for Windows PowerShell 与 Run Command 结合使用](walkthrough-powershell.md)或者 [AWS Tools for PowerShell Cmdlet 参考的 AWS Systems Manager 部分](https://docs.aws.amazon.com/powershell/latest/reference/items/AWS_Systems_Manager_cmdlets.html)中的示例。
+ [演练：将 AWS CLI 与 Run Command 结合使用](walkthrough-cli.md)或者 [SSM CLI 参考](https://docs.aws.amazon.com/cli/latest/reference/ssm/)中的示例
**Topics**
+ [从控制台运行命令](running-commands-console.md)
+ [使用指令文档版本运行命令](run-command-version.md)
+ [大规模运行命令](send-commands-multiple.md)
+ [取消命令](cancel-run-command.md)
# 从控制台运行命令
在不必登录的情况下，可以通过 AWS 管理控制台使用 Run Command（AWS Systems Manager 中的一项工具）配置托管式节点。此主题包括演示如何使用 Run Command 在托管式节点上[更新 SSM Agent](run-command-tutorial-update-software.md#rc-console-agentexample) 的示例。
**开始前的准备工作**
在使用 Run Command 发送命令之前，请确认托管式节点符合 Systems Manager [设置要求](systems-manager-setting-up-nodes.md)。
**使用 Run Command 发送命令**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Run Command**。
1. 选择 **Run command（运行命令）**。
1. 在**命令文档**列表中，请选择 Systems Manager 文档。
1. 在 **Command parameters (命令参数)** 部分中，为必需的参数指定值。
1. 在 **Targets**（目标）部分中，通过指定标签、手动选择实例或边缘设备或指定资源组，选择要在其上运行此操作的托管式节点。
**提示**
如果未列出您希望看到的托管式节点，请参阅 [排除托管式节点可用性的问题](fleet-manager-troubleshooting-managed-nodes.md) 以获取故障排除技巧。
1. 对于 **Other parameters（其他参数）**：
+ 对于 **Comment（注释）**，请输入有关此命令的信息。
+ 对于 **Timeout (seconds) (超时 (秒))**，请指定在整个命令执行失败之前系统等待的秒数。
1. 对于 **Rate control（速率控制）**：
+ 对于 **Concurrency**（并发），请指定要同时运行该命令的托管式节点的数量或百分比。
**注意**
如果您通过指定应用于托管式节点的标签或指定 AWS Resource Groups 来选择目标，但不确定有多少个托管式节点已被设为目标，则可通过指定百分比来限制可同时运行该文档的目标的数量。
+ 对于 **Error threshold**（错误阈值），请指定当命令在一定数量或百分比的节点上失败后，何时在其他托管式节点上停止运行该命令。例如，如果您指定三个错误，Systems Manager 将在收到第四个错误时停止发送该命令。仍在处理该命令的托管式节点也可能发送错误。
1. （可选）选择一个 CloudWatch 警报以应用于您的命令进行监控。要将 CloudWatch 警报附加到命令，运行命令的 IAM 主体必须具有 `iam:createServiceLinkedRole` 操作的权限。有关 CloudWatch 警报的更多信息，请参阅[使用 Amazon CloudWatch 警报](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html)。请注意，如果您的警报激活，任何待处理的命令调用都不会运行。
1. （可选）对于 **输出选项**，要将命令输出保存到文件，请选中 **将命令输出写入 S3 存储桶** 框。在输入框中输入存储桶和前缀（文件夹）名称。
**注意**
授予将数据写入 S3 存储桶的能力的 S3 权限，是分配给实例的实例配置文件（适用于 EC2 实例）或 IAM 服务角色（混合激活的计算机）的权限，而不是执行此任务的 IAM 用户的权限。有关更多信息，请参阅[配置 Systems Manager 所需的实例权限](setup-instance-permissions.md)或[为混合环境创建 IAM 服务角色](hybrid-multicloud-service-role.md)。此外，如果指定的 S3 存储桶位于不同的 AWS 账户 中，请确保与该托管式节点关联的实例配置文件或 IAM 服务角色具有写入该存储桶的所需权限。
1. 在 **SNS 通知**部分，如果需要发送有关命令执行状态的通知，请选中 **Enable SNS notifications（启用 SNS 通知）**复选框。
有关为 Run Command 配置 Amazon SNS 通知的更多信息，请参阅 [使用 Amazon SNS 通知监控 Systems Manager 状态更改](monitoring-sns-notifications.md)。
1. 选择 **Run（运行）**。
有关取消命令的信息，请参阅 [取消命令](cancel-run-command.md)。
## 重新运行命令
Systems Manager 包含两个选项，可帮助您从 Systems Manager 控制台中的 **Run Command** 页面重新运行命令。
+ **Rerun (重新运行)**：利用此按钮，您可以运行同一个命令而不对其进行更改。
+ **复制到新项目**：此按钮将一个命令的设置复制到一个新命令，并为您提供在运行该命令之前编辑这些设置的选项。
**重新运行命令**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Run Command**。
1. 选择要重新运行的命令。从命令详细信息页面执行命令后，可以立即重新运行此命令。或者，您可以从 **Command history (命令历史记录)** 选项卡中选择先前运行的命令。
1. 选择 **Rerun (重新运行)** 以在不进行更改的情况下运行相同的命令，或者选择**复制到新项目**以在运行命令之前编辑命令设置。
# 使用指令文档版本运行命令
您可以使用文档版本参数指定在运行命令时使用 AWS Systems Manager 文档的哪个版本。您可以为此参数指定以下选项之一：
+ \$1DEFAULT
+ \$1LATEST
+ 版本号
运行以下过程，使用文档版本参数运行命令。
------
#### [ Linux ]
**在本地 Linux 计算机上使用 AWS CLI 运行命令**
1. 安装并配置 AWS Command Line Interface（AWS CLI）（如果尚未执行该操作）。
有关信息，请参阅[安装或更新 AWS CLI 的最新版本](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)。
1. 列出所有可用文档
此命令将基于 AWS Identity and Access Management (IAM) 权限列出您的账户可用的所有文档。
```
aws ssm list-documents
```
1. 运行以下命令，查看文档的不同版本。将*文档名称*替换为您自己的信息。
```
aws ssm list-document-versions \
--name "document name"
```
1. 运行以下命令，运行使用 SSM 文档版本的命令。将每个*示例资源占位符*替换为您自己的信息。
```
aws ssm send-command \
--document-name "AWS-RunShellScript" \
--parameters commands="echo Hello" \
--instance-ids instance-ID \
--document-version '$LATEST'
```
------
#### [ Windows ]
**在本地 Windows 计算机上使用 AWS CLI 运行命令**
1. 安装并配置 AWS Command Line Interface（AWS CLI）（如果尚未执行该操作）。
有关信息，请参阅[安装或更新 AWS CLI 的最新版本](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)。
1. 列出所有可用文档
此命令将基于 AWS Identity and Access Management (IAM) 权限列出您的账户可用的所有文档。
```
aws ssm list-documents
```
1. 运行以下命令，查看文档的不同版本。将*文档名称*替换为您自己的信息。
```
aws ssm list-document-versions ^
--name "document name"
```
1. 运行以下命令，运行使用 SSM 文档版本的命令。将每个*示例资源占位符*替换为您自己的信息。
```
aws ssm send-command ^
--document-name "AWS-RunShellScript" ^
--parameters commands="echo Hello" ^
--instance-ids instance-ID ^
--document-version "$LATEST"
```
------
#### [ PowerShell ]
**要使用 Tools for PowerShell 运行命令，请执行以下步骤：**
1. 如果您尚未安装和配置 AWS Tools for PowerShell（适用于 Windows PowerShell 的工具），请执行这些操作。
有关信息，请参阅[安装 AWS Tools for PowerShell](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-getting-set-up.html)。
1. 列出所有可用文档
此命令将基于 AWS Identity and Access Management (IAM) 权限列出您的账户可用的所有文档。
```
Get-SSMDocumentList
```
1. 运行以下命令，查看文档的不同版本。将*文档名称*替换为您自己的信息。
```
Get-SSMDocumentVersionList `
-Name "document name"
```
1. 运行以下命令，运行使用 SSM 文档版本的命令。将每个*示例资源占位符*替换为您自己的信息。
```
Send-SSMCommand `
-DocumentName "AWS-RunShellScript" `
-Parameter @{commands = "echo helloWorld"} `
-InstanceIds "instance-ID" `
-DocumentVersion $LATEST
```
------
# 大规模运行命令
您可以使用 Run Command（AWS Systems Manager 中的一项工具）通过使用 `targets` 在托管式节点实例集上运行命令。`targets` 参数根据您为托管式节点指定的标签接受 `Key,Value` 组合。当您运行该命令时，系统会找到并尝试在匹配指定标签的所有托管式节点上运行命令。有关标记托管式实例的更多信息，请参阅《Tagging AWS Resources User Guide》**中的 [Tagging your AWS resources](https://docs.aws.amazon.com/tag-editor/latest/userguide/tag-editor.html)。有关标记托管式 IoT 设备的信息，请参阅 *AWS IoT Greengrass Version 2 开发人员指南*中的[标记 AWS IoT Greengrass Version 2 资源](https://docs.aws.amazon.com/greengrass/v2/developerguide/tag-resources.html)。
您也可以使用 `targets` 参数将特定托管式节点 ID 的列表设为目标，如下一部分中所述。
为控制数百个或数千个托管式节点的命令运行，Run Command 还包含一些参数，用于限制同时处理一个请求的节点数量以及取消命令前其可引发的错误数量。
**Topics**
+ [将多个托管式节点设为目标](#send-commands-targeting)
+ [使用速率控制](#send-commands-rate)
## 将多个托管式节点设为目标
您可以通过指定标签、AWS 资源组名称或托管式节点 ID 来运行命令并将托管式节点设为目标。
以下示例显示使用 AWS Command Line Interface (AWS CLI ) 中的 Run Command 时的命令格式。将每个*示例资源占位符*替换为您自己的信息。本部分的示例命令使用 `[...]` 进行截断。
**示例 1：将标签设为目标**
------
#### [ Linux & macOS ]
```
aws ssm send-command \
--document-name document-name \
--targets Key=tag:tag-name,Values=tag-value \
[...]
```
------
#### [ Windows ]
```
aws ssm send-command ^
--document-name document-name ^
--targets Key=tag:tag-name,Values=tag-value ^
[...]
```
------
示**例 2：通过名称将 AWS 资源组设为目标**
您最多可以为每个命令指定一个资源组名称。当您创建资源组时，我们建议您包含 `AWS::SSM:ManagedInstance` 和 `AWS::EC2::Instance` 作为分组条件中的资源类型。
**注意**
为发送将资源组设为目标的命令，您必须已获得列出或查看属于该组的资源的 AWS Identity and Access Management (IAM) 权限。有关更多信息，请参阅 *AWS Resource Groups 用户指南*中的[设置权限](https://docs.aws.amazon.com/ARG/latest/userguide/gettingstarted-prereqs.html#gettingstarted-prereqs-permissions)。
------
#### [ Linux & macOS ]
```
aws ssm send-command \
--document-name document-name \
--targets Key=resource-groups:Name,Values=resource-group-name \
[...]
```
------
#### [ Windows ]
```
aws ssm send-command ^
--document-name document-name ^
--targets Key=resource-groups:Name,Values=resource-group-name ^
[...]
```
------
**示例 3：通过资源类型将 AWS 资源组设为目标**
您最多可以为每个命令指定五个资源组类型。当您创建资源组时，我们建议您包含 `AWS::SSM:ManagedInstance` 和 `AWS::EC2::Instance` 作为分组条件中的资源类型。
**注意**
为了发送将资源组设为目标的命令，您必须已被授予列出或查看属于该组的资源的 IAM 权限。有关更多信息，请参阅 *AWS Resource Groups 用户指南*中的[设置权限](https://docs.aws.amazon.com/ARG/latest/userguide/gettingstarted-prereqs.html#gettingstarted-prereqs-permissions)。
------
#### [ Linux & macOS ]
```
aws ssm send-command \
--document-name document-name \
--targets Key=resource-groups:ResourceTypeFilters,Values=resource-type-1,resource-type-2 \
[...]
```
------
#### [ Windows ]
```
aws ssm send-command ^
--document-name document-name ^
--targets Key=resource-groups:ResourceTypeFilters,Values=resource-type-1,resource-type-2 ^
[...]
```
------
**示例 4：将实例 ID 设为目标**
以下示例演示如何使用 `instanceids` 密钥和 `targets` 参数将托管式节点设为目标。您可以使用此密钥来将托管式 AWS IoT Greengrass 核心设备设为目标，因为每台设备分配到了 mi-*ID\$1NUMBER*。您可以在 Fleet Manager（AWS Systems Manager 中的一项工具）中查看设备 ID。
------
#### [ Linux & macOS ]
```
aws ssm send-command \
--document-name document-name \
--targets Key=instanceids,Values=instance-ID-1,instance-ID-2,instance-ID-3 \
[...]
```
------
#### [ Windows ]
```
aws ssm send-command ^
--document-name document-name ^
--targets Key=instanceids,Values=instance-ID-1,instance-ID-2,instance-ID-3 ^
[...]
```
------
如果您使用名为 `Environment` 的 `Key`，以及 `Development`、`Test`、`Pre-production` 和 `Production` 的 `Values` 标记不同环境的托管式节点，则可以使用采用以下语法的 `targets` 参数，向其中*一个*环境的所有托管式节点发送命令。
------
#### [ Linux & macOS ]
```
aws ssm send-command \
--document-name document-name \
--targets Key=tag:Environment,Values=Development \
[...]
```
------
#### [ Windows ]
```
aws ssm send-command ^
--document-name document-name ^
--targets Key=tag:Environment,Values=Development ^
[...]
```
------
通过添加到 `Values` 列表，您可以将其他环境中的其他托管式节点设为目标。使用逗号分隔项目。
------
#### [ Linux & macOS ]
```
aws ssm send-command \
--document-name document-name \
--targets Key=tag:Environment,Values=Development,Test,Pre-production \
[...]
```
------
#### [ Windows ]
```
aws ssm send-command ^
--document-name document-name ^
--targets Key=tag:Environment,Values=Development,Test,Pre-production ^
[...]
```
------
**变体**：使用多个 `Key` 条件细化您的目标。
通过包括多个 `Key` 条件，您可以细化您的命令的目标数。如果包括多个 `Key` 条件，系统会将符合*所有*条件的托管式节点设为目标。以下命令会将标记为财务部门*和*标记为数据库服务器角色的所有托管式节点设为目标。
------
#### [ Linux & macOS ]
```
aws ssm send-command \
--document-name document-name \
--targets Key=tag:Department,Values=Finance Key=tag:ServerRole,Values=Database \
[...]
```
------
#### [ Windows ]
```
aws ssm send-command ^
--document-name document-name ^
--targets Key=tag:Department,Values=Finance Key=tag:ServerRole,Values=Database ^
[...]
```
------
**变体**：使用多个 `Key` 和 `Value` 条件
对上一个示例进行扩展，您可以通过在 `Values` 条件中包括其他项目来将多个部门和多个服务器角色设为目标。
------
#### [ Linux & macOS ]
```
aws ssm send-command \
--document-name document-name \
--targets Key=tag:Department,Values=Finance,Marketing Key=tag:ServerRole,Values=WebServer,Database \
[...]
```
------
#### [ Windows ]
```
aws ssm send-command ^
--document-name document-name ^
--targets Key=tag:Department,Values=Finance,Marketing Key=tag:ServerRole,Values=WebServer,Database ^
[...]
```
------
**变体**：使用多个 `Values` 条件将已标记托管式节点设为目标
如果您使用名为 `Department` 的 `Key`，以及 `Sales` 和 `Finance` 的 `Values` 标记不同环境的托管式节点，则可以使用采用以下语法的 `targets` 参数，向这些环境的所有节点发送命令。
------
#### [ Linux & macOS ]
```
aws ssm send-command \
--document-name document-name \
--targets Key=tag:Department,Values=Sales,Finance \
[...]
```
------
#### [ Windows ]
```
aws ssm send-command ^
--document-name document-name ^
--targets Key=tag:Department,Values=Sales,Finance ^
[...]
```
------
您最多可以为每个键指定五个键和五个值。
如果某个标签密钥（标签名称）或某个标签值包含空格，则需要将该标签密钥或该值用引号引起来，如以下示例所示。
**示例**： `Value` 标签中的空格
------
#### [ Linux & macOS ]
```
aws ssm send-command \
--document-name document-name \
--targets Key=tag:OS,Values="Windows Server 2016" \
[...]
```
------
#### [ Windows ]
```
aws ssm send-command ^
--document-name document-name ^
--targets Key=tag:OS,Values="Windows Server 2016" ^
[...]
```
------
**示例**： `tag` 键和 `Value` 中的空格
------
#### [ Linux & macOS ]
```
aws ssm send-command \
--document-name document-name \
--targets Key="tag:Operating System",Values="Windows Server 2016" \
[...]
```
------
#### [ Windows ]
```
aws ssm send-command ^
--document-name document-name ^
--targets Key="tag:Operating System",Values="Windows Server 2016" ^
[...]
```
------
**示例**：`Values` 的列表中一个项目中的空格
------
#### [ Linux & macOS ]
```
aws ssm send-command \
--document-name document-name \
--targets Key=tag:Department,Values="Sales","Finance","Systems Mgmt" \
[...]
```
------
#### [ Windows ]
```
aws ssm send-command ^
--document-name document-name ^
--targets Key=tag:Department,Values="Sales","Finance","Systems Mgmt" ^
[...]
```
------
## 使用速率控制
您可以使用*并发控件*和*错误控件*，控制将命令发送到组中托管式节点的速率。
**Topics**
+ [使用并发控件](#send-commands-velocity)
+ [使用错误控件](#send-commands-maxerrors)
### 使用并发控件
您可以使用 `max-concurrency` 参数 [**Run a command**（运行命令）页面中的 **Concurrency**（并发）选项] 来控制同时运行命令的托管式节点数量。您可以指定绝对数量的托管式节点（例如 **10**），也可以指定目标集百分比（例如 **10%**）。队列系统将命令传递给单个节点，并等待系统确认了初始调用，再将命令发送到两个或更多节点。系统以指数增长方式将命令发送到更多节点，直到系统达到 `max-concurrency` 值。`max-concurrency` 值默认为 50。下列示例介绍如何为 `max-concurrency` 参数指定值。
------
#### [ Linux & macOS ]
```
aws ssm send-command \
--document-name document-name \
--max-concurrency 10 \
--targets Key=tag:Environment,Values=Development \
[...]
```
```
aws ssm send-command \
--document-name document-name \
--max-concurrency 10% \
--targets Key=tag:Department,Values=Finance,Marketing Key=tag:ServerRole,Values=WebServer,Database \
[...]
```
------
#### [ Windows ]
```
aws ssm send-command ^
--document-name document-name ^
--max-concurrency 10 ^
--targets Key=tag:Environment,Values=Development ^
[...]
```
```
aws ssm send-command ^
--document-name document-name ^
--max-concurrency 10% ^
--targets Key=tag:Department,Values=Finance,Marketing Key=tag:ServerRole,Values=WebServer,Database ^
[...]
```
------
### 使用错误控件
您也可以使用 `max-errors` 参数 [**Run a command**（运行命令）页面中的 **Error threshold**（错误阈值）字段] 设置错误限制，将命令的执行控制在几百个或几千个托管式节点范围内。该参数指定系统停止向其他托管式节点发送命令之前所允许的错误数。您可以指定绝对数量的错误（例如 **10**），也可以指定目标集百分比（例如 **10%**）。例如，如果您指定 **3**，系统将在收到第四个错误时停止发送命令。如果您指定 **0**，则系统会在返回第一个错误结果后停止向其他托管式节点发送命令。如果您向 50 个托管式节点发送命令并将 `max-errors` 设置为 **10%**，则系统会在收到第六个错误时停止向其他节点发送命令。
当达到 `max-errors` 时，允许完成已经运行命令的调用，但是其中一些调用也可能失败。如果您需要确保失败的调用数不超过 `max-errors`，请将 `max-concurrency` 设置为 **1**，以便一次进行一个调用。max-errors 默认为 0。下列示例介绍如何为 `max-errors` 参数指定值。
------
#### [ Linux & macOS ]
```
aws ssm send-command \
--document-name document-name \
--max-errors 10 \
--targets Key=tag:Database,Values=Development \
[...]
```
```
aws ssm send-command \
--document-name document-name \
--max-errors 10% \
--targets Key=tag:Environment,Values=Development \
[...]
```
```
aws ssm send-command \
--document-name document-name \
--max-concurrency 1 \
--max-errors 1 \
--targets Key=tag:Environment,Values=Production \
[...]
```
------
#### [ Windows ]
```
aws ssm send-command ^
--document-name document-name ^
--max-errors 10 ^
--targets Key=tag:Database,Values=Development ^
[...]
```
```
aws ssm send-command ^
--document-name document-name ^
--max-errors 10% ^
--targets Key=tag:Environment,Values=Development ^
[...]
```
```
aws ssm send-command ^
--document-name document-name ^
--max-concurrency 1 ^
--max-errors 1 ^
--targets Key=tag:Environment,Values=Production ^
[...]
```
------
# 取消命令
只要服务指明命令处于 Pending (待处理) 或 Executing (正在执行) 状态，您就可以尝试取消命令。但是，即使命令仍处于其中某种状态，我们也无法保证该命令将被取消并且基础流程将停止。
**使用控制台取消命令**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，选择 **Run Command**。
1. 选择要取消的命令调用。
1. 选择**取消命令**。
**使用 AWS CLI 取消命令**
运行以下命令。将每个*示例资源占位符*替换为您自己的信息。
------
#### [ Linux & macOS ]
```
aws ssm cancel-command \
--command-id "command-ID" \
--instance-ids "instance-ID"
```
------
#### [ Windows ]
```
aws ssm cancel-command ^
--command-id "command-ID" ^
--instance-ids "instance-ID"
```
------
有关已取消命令的状态的信息，请参阅 [了解命令状态](monitor-commands.md)。
# 在命令中使用退出代码
在某些情况下，您可能需要使用退出代码管理处理命令的方式。
## 在命令中指定退出代码
使用 Run Command（AWS Systems Manager 中的一项工具），您可以指定退出代码来确定命令的处理方式。默认情况下，脚本中运行的最后一个命令的退出代码将报告为整个脚本的退出代码。例如，您有一个包含三个命令的脚本。第一个命令失败，但以下命令成功。由于最后一个命令成功，因此执行状态报告为 `succeeded`。
**Shell 脚本**
要在第一个命令失败时使整个脚本失败，您可以包含一个 shell 条件语句，以便在最后一个命令失败之前退出脚本。请使用以下方法。
```
if [ $? != 0 ]
then
exit
fi
```
在以下示例中，如果第一个命令失败，则整个脚本将失败。
```
cd /test
if [ $? != 0 ]
then
echo "Failed"
exit 1
fi
date
```
**PowerShell 脚本**
PowerShell 要求您在脚本中显式调用 `exit`，使 Run Command 能够成功捕获退出代码。
```
if ($?) {}
else {exit }
exit
```
示例如下：
```
cd C:\
if ($?) {echo "Success"}
else {exit 1}
date
```
# 运行命令时处理重启问题
如果使用 Run Command（AWS Systems Manager 中的一项工具）运行脚本来重启托管式节点，建议在脚本中指定退出代码。如果您使用其他一些机制尝试通过脚本重启节点，则即使重启是脚本的最后一步，脚本执行状态也可能无法正确更新。对于 Windows 托管式节点，您需在脚本中指定 `exit 3010`。对于 Linux 和 macOS 托管式节点，需要指定 `exit 194`。退出代码用于指示 AWS Systems Manager Agent (SSM Agent) 重启托管式节点，然后在重启完成后重新启动脚本。在重启开始之前，SSM Agent 会通知云中的 Systems Manager 服务，通信将在服务器重启期间中断。
**注意**
重启脚本不能作为 `aws:runDocument` 插件的一部分。如果一个文档包含重启脚本，另一个文档尝试通过 `aws:runDocument` 插件运行该文档，则 SSM Agent 会返回错误。
**创建幂等脚本**
在开发用于重启托管式节点的脚本时，使脚本具有幂等性，以便脚本执行在重启后从中断的位置继续进行。幂等脚本管理状态并验证是否执行了该操作。当一个步骤设定为仅运行一次时，可以防止该步骤多次运行。
以下是多次重启托管式节点的幂等脚本的概要示例。
```
$name = Get current computer name
If ($name –ne $desiredName)
{
Rename computer
exit 3010
}
$domain = Get current domain name
If ($domain –ne $desiredDomain)
{
Join domain
exit 3010
}
If (desired package not installed)
{
Install package
exit 3010
}
```
**示例**
以下脚本示例使用退出代码来重新启动托管式节点。Linux 示例在 Amazon Linux 上安装软件包更新，然后重新启动该节点。Windows Server 示例在节点上安装 Telnet-Client，然后重新启动该节点。
------
#### [ Amazon Linux 2 ]
```
#!/bin/bash
yum -y update
needs-restarting -r
if [ $? -eq 1 ]
then
exit 194
else
exit 0
fi
```
------
#### [ Windows ]
```
$telnet = Get-WindowsFeature -Name Telnet-Client
if (-not $telnet.Installed)
{
# Install Telnet and then send a reboot request to SSM Agent.
Install-WindowsFeature -Name "Telnet-Client"
exit 3010
}
```
------
# 了解命令状态
Run Command 是 AWS Systems Manager 中的一项工具，报告关于处理过程中命令经历的不同状态以及处理该命令的每个托管式节点的详细状态信息。您可以使用以下方法监控命令状态：
+ 在 Run Command 控制台界面的 **Commands**（命令）选项卡上选择 **Refresh**（刷新）图标。
+ 使用 AWS Command Line Interface (AWS CLI) 调用 [list-commands](https://docs.aws.amazon.com/cli/latest/reference/ssm/list-commands.html) 或 [list-command-invocations](https://docs.aws.amazon.com/cli/latest/reference/ssm/list-command-invocations.html)。或者，使用 AWS Tools for Windows PowerShell 调用 [Get-SSMCommand](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-SSMCommand.html) 或 [Get-SSMCommandInvocation](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-SSMCommandInvocation.html)。
+ 配置 Amazon EventBridge 以响应状态或状态更改。
+ 将 Amazon Simple Notification Service (Amazon SNS) 配置为发送所有状态更改或特定状态（例如 `Failed` 或 `TimedOut`）的通知。
## Run Command 状态
Run Command 报告以下三个区域的状态详情：插件、调用和总体命令状态。*插件*是在命令的 SSM 文档中定义的代码执行数据块。有关插件的更多信息，请参阅 [命令文档插件参考](documents-command-ssm-plugin-reference.md)。
在将一条命令同时发送给多个托管式节点时，针对每个节点的命令的每个副本均为一个*命令调用*。例如，如果您使用 `AWS-RunShellScript` 文档并将一个 `ifconfig` 命令发送到 20 个 Linux 实例，则该命令具有 20 个调用。每个命令调用都会单独报告状态。给定命令调用的插件也会单独报告状态。
最后，Run Command 包含适用于所有插件和调用的聚合命令状态。聚合命令状态可能不同于插件或调用报告的状态，如下表所述。
**注意**
如果您使用 `max-concurrency` 或 `max-errors` 参数在大量托管式节点上运行命令，则命令状态会反映这些参数施加的限制，如下表所述。有关这些参数的更多信息，请参阅 [大规模运行命令](send-commands-multiple.md)。
**命令插件和调用的详细状态**
| Status | Details |
| --- | --- |
| 待处理 | 命令尚未发送到托管式节点，或者 SSM Agent 尚未接收到此类命令。如果代理在等于 Timeout (seconds) (超时 (秒)) 参数和 Execution timeout (执行超时) 参数总和的时间长度之前没有收到命令，则状态将更改为 Delivery Timed Out (传输超时)。 |
| InProgress | Systems Manager 正在尝试将命令发送到托管式节点，或者 SSM Agent 已接收到此类命令并且命令已开始在实例上运行。根据所有命令插件的结果，状态会变为 Success (成功)、Failed (失败)、Delivery Timed Out (传输超时) 或 Execution Timed Out (执行超时)。例外：如果代理未在节点上运行或在节点上不可用，则在代理再次可用或达到执行超时限制之前，命令状态将保持为 In Progress（正在进行）。随后，状态会更改为最终状态。 |
| 延迟 | 系统尝试向托管式节点发送命令，但未成功。系统再次重试。 |
| 成功 | 在各种条件下都会返回此状态。此状态并不意味着命令已在节点上得到处理。例如，由于您的 PowerShell ExecutionPolicy 阻止命令运行，因此在托管式节点上，SSM Agent 可接收到命令，而且命令返回为零的退出代码。这是最终状态。导致命令返回 Success 状态的条件是：[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/monitor-commands.html) 当以资源组为目标时，同样的条件也适用。要解决错误或获取有关命令执行的更多信息，请通过返回适当的退出代码 (针对命令失败的非零退出代码) 来发送一个处理错误或异常的命令。 |
| DeliveryTimedOut | 命令未在总超时过期之前传输到托管式节点。总超时不计入父命令的 max-errors 限制，但是有助于区别父命令的状态是 Success（成功）、Incomplete（未完成）还是 Delivery Timed Out（传输超时）。这是最终状态。 |
| ExecutionTimedOut | 命令自动化在托管式节点上开始，但是命令未在执行超时过期之前完成。执行超时算作失败，这样就会发送一个非零回复，Systems Manager 将退出运行命令自动化的尝试，并报告失败状态。 |
| 失败 | 托管式节点上的命令失败。对于插件，这表示结果代码不为 0。对于命令调用，这表示一个或多个插件的结果代码不为 0。调用失败不计入父命令的 max-errors 限制。这是最终状态。 |
| 已取消 | 命令在完成之前被取消。这是最终状态。 |
| 无法传输 | 命令无法传输到托管式节点。节点可能不存在或可能未响应。无法传输的调用不计入父命令的 max-errors 限制，但是有助于区别父命令的状态是 Success (成功) 还是 Incomplete (未完成)。（例如，如果命令中的所有调用具有 Undeliverable (无法传输) 状态，则返回的命令状态为 Failed (失败)。不过，如果命令具有 5 个调用，其中的 4 个调用返回 Undeliverable (无法传输) 状态，一个调用返回 Success (成功) 状态，则父命令的状态为 Success (成功)。这是最终状态。 |
| 已终止 | 父命令超过其 max-errors 限制且系统取消了后续命令调用。这是最终状态。 |
| InvalidPlatform | 命令被发送到与所选文档指定的所需平台不匹配的托管式节点。Invalid Platform（无效平台）不计入父命令的最大错误数限制，但是有助于区别父命令的状态是 Success（成功）还是 Failed（失败）。（例如，如果命令中的所有调用具有 Invalid Platform (无法传输) 状态，则返回的命令状态为 Failed (失败)。不过，如果命令具有 5 个调用，其中的 4 个调用返回 Invalid Platform (无法传输) 状态，一个调用返回 Success (成功) 状态，则父命令的状态为 Success (成功)。这是最终状态。 |
| AccessDenied | 启动命令的 AWS Identity and Access Management (IAM) 用户或角色无权访问目标托管式节点。Access Denied（拒绝访问）不计入父命令的 max-errors（最大错误数）限制，但是有助于区别父命令的状态是 Success（成功）还是 Failed（失败）。（例如，如果命令中的所有调用具有 Access Denied (无法传输) 状态，则返回的命令状态为 Failed (失败)。不过，如果命令具有 5 个调用，其中的 4 个调用返回 Access Denied (无法传输) 状态，一个调用返回 Success (成功) 状态，则父命令的状态为 Success (成功)。这是最终状态。 |
**命令的详细状态**
| Status | Details |
| --- | --- |
| 待处理 | 任何托管式节点上的代理都尚未收到命令。 |
| InProgress | 命令已发送到至少一个托管式节点，但是在所有节点上都未达到最终状态。 |
| 延迟 | 系统尝试向节点发送命令，但未成功。系统再次重试。 |
| 成功 | 命令由所有指定的或设为目标的托管式节点上的 SSM Agent 接收，并返回了一个为零的退出代码。所有命令调用都已达到最终状态，且未达到 max-errors 的值。此状态并不意味着命令已在所有指定的或设为目标的托管式节点上成功得到处理。这是最终状态。 要解决错误或获取有关命令执行的更多信息，请通过返回适当的退出代码 (针对命令失败的非零退出代码) 来发送一个处理错误或异常的命令。 |
| DeliveryTimedOut | 命令未在总超时过期之前传输到托管式节点。max-errors 值或更多命令调用显示 Delivery Timed Out 状态。这是最终状态。 |
| 失败 | 托管式节点上的命令失败。`max-errors` 值或更多命令调用显示 `Failed` 状态。这是最终状态。 |
| 未完成 | 已尝试在所有托管式节点上执行命令，且一个或多个调用不具有 Success（成功）值。不过，调用失败的次数不足以使状态变为 Failed。这是最终状态。 |
| 已取消 | 命令在完成之前被取消。这是最终状态。 |
| RateExceeded | 作为命令目标的托管式节点数量超出了待处理调用的账户配额。系统在任何节点上执行命令之前取消了命令。这是最终状态。 |
| AccessDenied | 启动命令的用户或角色无权访问目标资源组。AccessDenied 不计入父命令的 max-errors 限制，但是有助于区别父命令的状态是 Success 还是 Failed。（例如，如果命令中的所有调用具有 AccessDenied (拒绝访问) 状态，则返回的命令状态为 Failed (失败)。不过，如果命令具有 5 个调用，其中的 4 个调用返回 AccessDenied (拒绝访问) 状态，1 个调用返回 Success (成功) 状态，则父命令的状态为 Success(成功)。） 这是最终状态。 |
| 在标签中没有实例 | 作为命令目标的标签密钥对值或资源组与任何托管式节点都不匹配。这是最终状态。 |
## 了解命令超时值
在运行命令时，Systems Manager 强制执行以下超时值。
**总超时**
在 Systems Manager 控制台中，您可以在 **Timeout (seconds)**（超时（秒））字段中指定超时值。发送命令后，Run Command 会检查命令是否已过期。如果命令达到命令过期限制（总超时），它会将所有状态为 `InProgress` (正在进行)、`Pending` (待处理) 或 `Delayed` (延迟) 的调用的状态更改为 `DeliveryTimedOut` (传输超时)。
![\[Systems Manager 控制台中的 Timeout (seconds) (超时 (秒)) 字段\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/images/run-command-delivery-time-out-time-out-seconds.png)
在更深的技术层面上，总超时（**Timeout (seconds)**（超时（秒）））是两个超时值的总和，如下所示：
`Total timeout = "Timeout(seconds)" from the console + "timeoutSeconds": "{{ executionTimeout }}" from your SSM document`
例如，在 Systems Manager 控制台中，**Timeout (seconds) (超时 (秒))** 的默认值是 600 秒。如果使用 `AWS-RunShellScript` SSM 文档运行命令，则 **"timeoutSeconds": "\$1\$1 executionTimeout \$1\$1"** 的默认值为 3600 秒，如以下示例文档所示：
```
"executionTimeout": {
"type": "String",
"default": "3600",
"runtimeConfig": {
"aws:runShellScript": {
"properties": [
{
"timeoutSeconds": "{{ executionTimeout }}"
```
这意味着，在系统将命令状态设置为 `DeliveryTimedOut` 之前，该命令运行了 4200 秒（70 分钟）。
**执行超时**
在 Systems Manager 控制台中，您可以在 **Execution Timeout (执行超时)** 字段中指定执行超时值（如果可用）。并非所有 SSM 文档都要求指定执行超时值。**Execution Timeout**（执行超时）字段仅在 SSM 文档中定义了相应的输入参数时才会显示。如果已指定该值，则命令必须在此时段内完成。
**注意**
Run Command 依靠 SSM Agent 文档最终响应来确定命令是否已传输给代理。SSM Agent 必须发送一个 `ExecutionTimedOut` 信号，才能将调用或命令标记为 `ExecutionTimedOut`。
![\[Systems Manager 控制台中的 Execution Timeout (执行超时) 字段\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/images/run-command-execution-timeout-console.png)
**默认执行超时**
如果 SSM 文档不要求您明确指定执行超时值，则 Systems Manager 会强制执行硬编码的默认执行超时。
**Systems Manager 如何报告超时**
如果 Systems Manager 收到来自目标上的 SSM Agent 的 `execution timeout` 回复，则 Systems Manager 会将命令调用标记为 `executionTimeout`。
如果 Run Command 没有收到 SSM Agent 文档最终响应，则命令调用被标记为 `deliveryTimeout`。
为了确定目标的超时状态，SSM Agent 将合并 SSM 文档的所有参数和内容来计算 `executionTimeout`。如果 SSM Agent 确定某条命令已超时，它会向服务发送 `executionTimeout`。
**Timeout (seconds) (超时 (秒))** 的默认值为 3600 秒。**Execution Timeout (执行超时)** 的默认值也为 3600 秒。因此，命令的总超时默认为 7200 秒。
**注意**
SSM Agent 采用不同的方式处理 `executionTimeout`，具体取决于 SSM 文档的类型和文档版本。
# Run Command 演练
本节中的演练说明如何借助 AWS Command Line Interface（AWS CLI）或 AWS Tools for Windows PowerShell，使用 Run Command（AWS Systems Manager 中的一项工具）来运行命令。
**Topics**
+ [使用 Run Command 更新软件](run-command-tutorial-update-software.md)
+ [演练：将 AWS CLI 与 Run Command 结合使用](walkthrough-cli.md)
+ [演练：将 AWS Tools for Windows PowerShell 与 Run Command 结合使用](walkthrough-powershell.md)
您还可以查看以下参考中的示例命令。
+ [Systems Manager AWS CLI 参考](https://docs.aws.amazon.com/cli/latest/reference/ssm/)
+ [AWS Tools for Windows PowerShell - AWS Systems Manager](https://docs.aws.amazon.com/powershell/latest/reference/items/SimpleSystemsManagement_cmdlets.html)
# 使用 Run Command 更新软件
以下步骤说明如何在托管节点上更新软件。
## 使用 Run Command 更新 SSM Agent
以下过程介绍如何更新在托管式节点上运行的 SSM Agent。您可以更新到最新版本的 SSM Agent 或降级到较旧版本。在运行命令时，系统将从 AWS 下载并安装需要的版本，然后卸载运行命令前存在的版本。如果此过程中出现错误，系统将回滚到命令运行之前服务器上的版本，并且命令状态将显示命令失败。
**注意**
如果实例运行 macOS 版本 13.0（Ventura）或更高版本，则该实例必须带有 SSM Agent 版本 3.1.941.0 或更高版本才能运行 AWS-UpdateSSMAgent 文档。如果实例运行 3.1.941.0 之前发布的 SSM Agent 版本，那么您可以通过运行 `brew update` 和 `brew upgrade amazon-ssm-agent` 命令来更新 SSM Agent，从而运行 AWS-UpdateSSMAgent 文档。
要获得有关 SSM Agent 更新的通知，请在 GitHub 上订阅 [SSM Agent 发布说明](https://github.com/aws/amazon-ssm-agent/blob/mainline/RELEASENOTES.md)页面。
**使用 Run Command 更新 SSM Agent**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Run Command**。
1. 选择 **Run command（运行命令）**。
1. 在 **Command document** (命令文档) 列表中，请选择 **`AWS-UpdateSSMAgent`**。
1. 在**命令参数**部分中，根据需要为以下参数指定值：
1. （可选）对于 **Version (版本)**，输入要安装的 SSM Agent 的版本。您可以安装代理的[较旧版本](https://github.com/aws/amazon-ssm-agent/blob/mainline/RELEASENOTES.md)。如果您不指定版本，则服务将安装最新版本。
1. （可选）对于 **Allow Downgrade (允许降级)**，选择 **true (真)** 以安装 SSM Agent的早期版本。如果选择此选项，需要指定[较早](https://github.com/aws/amazon-ssm-agent/blob/mainline/RELEASENOTES.md)的版本号。选择 **false** 以仅安装此服务的最新版本。
1. 在 **Targets**（目标）部分中，通过指定标签、手动选择实例或边缘设备或指定资源组，选择要在其上运行此操作的托管式节点。
**提示**
如果未列出您希望看到的托管式节点，请参阅 [排除托管式节点可用性的问题](fleet-manager-troubleshooting-managed-nodes.md) 以获取故障排除技巧。
1. 对于 **Other parameters（其他参数）**：
+ 对于 **Comment（注释）**，请输入有关此命令的信息。
+ 对于 **Timeout (seconds) (超时 (秒))**，请指定在整个命令执行失败之前系统等待的秒数。
1. 对于 **Rate control（速率控制）**：
+ 对于 **Concurrency**（并发），请指定要同时运行该命令的托管式节点的数量或百分比。
**注意**
如果您通过指定应用于托管式节点的标签或指定 AWS Resource Groups 来选择目标，但不确定有多少个托管式节点已被设为目标，则可通过指定百分比来限制可同时运行该文档的目标的数量。
+ 对于 **Error threshold**（错误阈值），请指定当命令在一定数量或百分比的节点上失败后，何时在其他托管式节点上停止运行该命令。例如，如果您指定三个错误，Systems Manager 将在收到第四个错误时停止发送该命令。仍在处理该命令的托管式节点也可能发送错误。
1. （可选）对于 **输出选项**，要将命令输出保存到文件，请选中 **将命令输出写入 S3 存储桶** 框。在输入框中输入存储桶和前缀（文件夹）名称。
**注意**
授予将数据写入 S3 存储桶的能力的 S3 权限，是分配给实例的实例配置文件（适用于 EC2 实例）或 IAM 服务角色（混合激活的计算机）的权限，而不是执行此任务的 IAM 用户的权限。有关更多信息，请参阅[配置 Systems Manager 所需的实例权限](setup-instance-permissions.md)或[为混合环境创建 IAM 服务角色](hybrid-multicloud-service-role.md)。此外，如果指定的 S3 存储桶位于不同的 AWS 账户 中，请确保与该托管式节点关联的实例配置文件或 IAM 服务角色具有写入该存储桶的所需权限。
1. 在 **SNS 通知**部分，如果需要发送有关命令执行状态的通知，请选中 **Enable SNS notifications（启用 SNS 通知）**复选框。
有关为 Run Command 配置 Amazon SNS 通知的更多信息，请参阅 [使用 Amazon SNS 通知监控 Systems Manager 状态更改](monitoring-sns-notifications.md)。
1. 选择 **Run（运行）**。
## 使用 Run Command 更新 PowerShell
以下过程介绍如何在 Windows Server 2012 和 2012 R2 托管式节点上将 PowerShell 更新到版本 5.1。此过程中提供的脚本将下载 Windows 管理框架 (WMF) 5.1 版更新，并开始安装此更新。在此过程中，节点会重启，因为在安装 WMF 5.1 时要求这么做。完成下载和安装更新大约需要 5 分钟。
**要使用 Run Command 更新 PowerShell，请执行以下步骤：**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Run Command**。
1. 选择 **Run command（运行命令）**。
1. 在 **Command document**（命令文档）列表中，请选择 **`AWS-RunPowerShellScript`**。
1. 在 **Commands (命令)** 部分中，粘贴以下适用于您的操作系统的命令。
------
#### [ Windows Server 2012 R2 ]
```
Set-Location -Path "C:\Windows\Temp"
Invoke-WebRequest "https://go.microsoft.com/fwlink/?linkid=839516" -OutFile "Win8.1AndW2K12R2-KB3191564-x64.msu"
Start-Process -FilePath "$env:systemroot\system32\wusa.exe" -Verb RunAs -ArgumentList ('Win8.1AndW2K12R2-KB3191564-x64.msu', '/quiet')
```
------
#### [ Windows Server 2012 ]
```
Set-Location -Path "C:\Windows\Temp"
Invoke-WebRequest "https://go.microsoft.com/fwlink/?linkid=839513" -OutFile "W2K12-KB3191565-x64.msu"
Start-Process -FilePath "$env:systemroot\system32\wusa.exe" -Verb RunAs -ArgumentList ('W2K12-KB3191565-x64.msu', '/quiet')
```
------
1. 在 **Targets**（目标）部分中，通过指定标签、手动选择实例或边缘设备或指定资源组，选择要在其上运行此操作的托管式节点。
**提示**
如果未列出您希望看到的托管式节点，请参阅 [排除托管式节点可用性的问题](fleet-manager-troubleshooting-managed-nodes.md) 以获取故障排除技巧。
1. 对于 **Other parameters（其他参数）**：
+ 对于 **Comment（注释）**，请输入有关此命令的信息。
+ 对于 **Timeout (seconds) (超时 (秒))**，请指定在整个命令执行失败之前系统等待的秒数。
1. 对于 **Rate control（速率控制）**：
+ 对于 **Concurrency**（并发），请指定要同时运行该命令的托管式节点的数量或百分比。
**注意**
如果您通过指定应用于托管式节点的标签或指定 AWS Resource Groups 来选择目标，但不确定有多少个托管式节点已被设为目标，则可通过指定百分比来限制可同时运行该文档的目标的数量。
+ 对于 **Error threshold**（错误阈值），请指定当命令在一定数量或百分比的节点上失败后，何时在其他托管式节点上停止运行该命令。例如，如果您指定三个错误，Systems Manager 将在收到第四个错误时停止发送该命令。仍在处理该命令的托管式节点也可能发送错误。
1. （可选）对于 **输出选项**，要将命令输出保存到文件，请选中 **将命令输出写入 S3 存储桶** 框。在输入框中输入存储桶和前缀（文件夹）名称。
**注意**
授予将数据写入 S3 存储桶的能力的 S3 权限，是分配给实例的实例配置文件（适用于 EC2 实例）或 IAM 服务角色（混合激活的计算机）的权限，而不是执行此任务的 IAM 用户的权限。有关更多信息，请参阅[配置 Systems Manager 所需的实例权限](setup-instance-permissions.md)或[为混合环境创建 IAM 服务角色](hybrid-multicloud-service-role.md)。此外，如果指定的 S3 存储桶位于不同的 AWS 账户 中，请确保与该托管式节点关联的实例配置文件或 IAM 服务角色具有写入该存储桶的所需权限。
1. 在 **SNS 通知**部分，如果需要发送有关命令执行状态的通知，请选中 **Enable SNS notifications（启用 SNS 通知）**复选框。
有关为 Run Command 配置 Amazon SNS 通知的更多信息，请参阅 [使用 Amazon SNS 通知监控 Systems Manager 状态更改](monitoring-sns-notifications.md)。
1. 选择 **Run（运行）**。
在托管式节点重启且更新安装完成后，连接到您的节点，以确认 PowerShell 已成功升级到版本 5.1。要检查您的节点上的 PowerShell 版本，打开 PowerShell 并输入 `$PSVersionTable`。如果升级成功，输出表中的 `PSVersion` 值将显示为 5.1。
如果 `PSVersion` 值不是 5.1（例如 3.0 或 4.0），请在事件查看器中查看 **Windows Logs (Windows 日志)** 下的 **Setup (设置)** 日志。这些日志说明了更新安装失败的原因。
# 演练：将 AWS CLI 与 Run Command 结合使用
以下示例演练介绍了如何使用 AWS Command Line Interface (AWS CLI) 查看有关命令和命令参数的信息、如何运行命令以及如何查看这些命令的状态。
**重要**
仅允许受信任的管理员使用本主题中所示的 AWS Systems Manager 预配置文档。在 Systems Manager 文档中指定的命令和脚本需要管理权限才能在您的托管式节点上运行。如果用户有权运行任何预定义的 Systems Manager 文档（任何以 `AWS-` 开头的文档），则该用户也具有节点的管理员访问权限。对于所有其他用户，您应创建限制性文档并与特定用户共享这些文档。
**Topics**
+ [步骤 1：入门](#walkthrough-cli-settings)
+ [步骤 2：运行 Shell 脚本以查看资源详细信息](#walkthrough-cli-run-scripts)
+ [步骤 3：使用 `AWS-RunShellScript` 文档发送简单命令](#walkthrough-cli-example-1)
+ [步骤 4：使用 Run Command 运行简单 Python 脚本](#walkthrough-cli-example-2)
+ [步骤 5：使用 Run Command 运行 Bash 脚本](#walkthrough-cli-example-3)
## 步骤 1：入门
您必须具有要配置的托管式节点的管理员权限，或必须已获得 AWS Identity and Access Management (IAM) 中的适当权限。另请注意，此示例使用美国东部（俄亥俄州）区域（us-east-2）。Run Command 在《Amazon Web Services 一般参考》**的 [Systems Manager service endpoints](https://docs.aws.amazon.com/general/latest/gr/ssm.html#ssm_region) 列出的 AWS 区域 中可用。有关更多信息，请参阅 [为 AWS Systems Manager 设置托管节点](systems-manager-setting-up-nodes.md)。
**使用 AWS CLI 运行命令**
1. 安装并配置 AWS Command Line Interface（AWS CLI）（如果尚未执行该操作）。
有关信息，请参阅[安装或更新 AWS CLI 的最新版本](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)。
1. 列出所有可用文档。
此命令将基于 IAM 权限列出您的账户可用的所有文档。
```
aws ssm list-documents
```
1. 确认托管式节点已准备好接收命令。
以下命令的输出会显示托管式节点是否处于联机状态。
------
#### [ Linux & macOS ]
```
aws ssm describe-instance-information \
--output text --query "InstanceInformationList[*]"
```
------
#### [ Windows ]
```
aws ssm describe-instance-information ^
--output text --query "InstanceInformationList[*]"
```
------
1. 运行以下命令来查看有关特定托管式节点的详细信息。
**注意**
要运行本演练中的命令，请替换实例和命令 ID。对于托管式 AWS IoT Greengrass 核心设备，对实例 ID 使用 mi-*ID\$1NUMBER*。命令 ID 将作为对 **send-command** 的响应返回。可从 Fleet Manager（AWS Systems Manager 中的一项工具）中获得实例 ID。
------
#### [ Linux & macOS ]
```
aws ssm describe-instance-information \
--instance-information-filter-list key=InstanceIds,valueSet=instance-ID
```
------
#### [ Windows ]
```
aws ssm describe-instance-information ^
--instance-information-filter-list key=InstanceIds,valueSet=instance-ID
```
------
## 步骤 2：运行 Shell 脚本以查看资源详细信息
利用 Run Command 和 `AWS-RunShellScript` 文档，您可以在托管式节点上运行任何命令或脚本，就像您已在本地登录一样。
**查看说明和可用参数**
运行以下命令，查看 Systems Manager JSON 文档的描述。
------
#### [ Linux & macOS ]
```
aws ssm describe-document \
--name "AWS-RunShellScript" \
--query "[Document.Name,Document.Description]"
```
------
#### [ Windows ]
```
aws ssm describe-document ^
--name "AWS-RunShellScript" ^
--query "[Document.Name,Document.Description]"
```
------
运行以下命令，查看可用参数和有关这些参数的详细信息。
------
#### [ Linux & macOS ]
```
aws ssm describe-document \
--name "AWS-RunShellScript" \
--query "Document.Parameters[*]"
```
------
#### [ Windows ]
```
aws ssm describe-document ^
--name "AWS-RunShellScript" ^
--query "Document.Parameters[*]"
```
------
## 步骤 3：使用 `AWS-RunShellScript` 文档发送简单命令
运行以下命令，获取 Linux 托管式节点的 IP 信息。
如果您将 Windows Server 托管式节点设为目标，请将 `document-name` 更改为 `AWS-RunPowerShellScript`，并将 `command` 从 `ifconfig` 更改为 `ipconfig`。
------
#### [ Linux & macOS ]
```
aws ssm send-command \
--instance-ids "instance-ID" \
--document-name "AWS-RunShellScript" \
--comment "IP config" \
--parameters commands=ifconfig \
--output text
```
------
#### [ Windows ]
```
aws ssm send-command ^
--instance-ids "instance-ID" ^
--document-name "AWS-RunShellScript" ^
--comment "IP config" ^
--parameters commands=ifconfig ^
--output text
```
------
**使用响应数据获取命令信息**
以下命令使用从上一个命令返回的命令 ID 来获取命令执行的详细信息和响应数据。如果命令已完成，系统将返回响应数据。如果命令执行显示 `"Pending"` 或 `"InProgress"`，您再次运行此命令来查看响应数据。
------
#### [ Linux & macOS ]
```
aws ssm list-command-invocations \
--command-id $sh-command-id \
--details
```
------
#### [ Windows ]
```
aws ssm list-command-invocations ^
--command-id $sh-command-id ^
--details
```
------
**标识用户**
以下命令将显示运行命令的默认用户。
------
#### [ Linux & macOS ]
```
sh_command_id=$(aws ssm send-command \
--instance-ids "instance-ID" \
--document-name "AWS-RunShellScript" \
--comment "Demo run shell script on Linux managed node" \
--parameters commands=whoami \
--output text \
--query "Command.CommandId")
```
------
**获取命令状态**
以下命令使用命令 ID 获取托管式节点上的命令执行状态。此示例使用上一个命令中返回的命令 ID。
------
#### [ Linux & macOS ]
```
aws ssm list-commands \
--command-id "command-ID"
```
------
#### [ Windows ]
```
aws ssm list-commands ^
--command-id "command-ID"
```
------
**获取命令详细信息**
以下命令使用上一命令中的命令 ID 来获取每个托管式节点的命令执行状态。
------
#### [ Linux & macOS ]
```
aws ssm list-command-invocations \
--command-id "command-ID" \
--details
```
------
#### [ Windows ]
```
aws ssm list-command-invocations ^
--command-id "command-ID" ^
--details
```
------
**获取包含特定托管式节点的响应数据的命令信息**
以下命令会返回特定托管式节点的原始 `aws ssm send-command` 请求的输出。
------
#### [ Linux & macOS ]
```
aws ssm list-command-invocations \
--instance-id instance-ID \
--command-id "command-ID" \
--details
```
------
#### [ Windows ]
```
aws ssm list-command-invocations ^
--instance-id instance-ID ^
--command-id "command-ID" ^
--details
```
------
**显示 Python 版本**
以下命令会返回在节点上运行的 Python 的版本。
------
#### [ Linux & macOS ]
```
sh_command_id=$(aws ssm send-command \
--instance-ids "instance-ID" \
--document-name "AWS-RunShellScript" \
--comment "Demo run shell script on Linux Instances" \
--parameters commands='python -V' \
--output text --query "Command.CommandId") \
sh -c 'aws ssm list-command-invocations \
--command-id "$sh_command_id" \
--details \
--query "CommandInvocations[].CommandPlugins[].{Status:Status,Output:Output}"'
```
------
## 步骤 4：使用 Run Command 运行简单 Python 脚本
以下命令使用 Run Command 运行一个简单的 Python“Hello World”脚本。
------
#### [ Linux & macOS ]
```
sh_command_id=$(aws ssm send-command \
--instance-ids "instance-ID" \
--document-name "AWS-RunShellScript" \
--comment "Demo run shell script on Linux Instances" \
--parameters '{"commands":["#!/usr/bin/python","print \"Hello World from python\""]}' \
--output text \
--query "Command.CommandId") \
sh -c 'aws ssm list-command-invocations \
--command-id "$sh_command_id" \
--details \
--query "CommandInvocations[].CommandPlugins[].{Status:Status,Output:Output}"'
```
------
## 步骤 5：使用 Run Command 运行 Bash 脚本
此部分中的示例演示如何使用 Run Command 运行以下 Bash 脚本。
有关使用 Run Command 运行存储在远程位置的脚本的示例，请参阅[从 Amazon S3 运行脚本](integration-s3.md)和[从 GitHub 运行脚本](integration-remote-scripts.md)。
```
#!/bin/bash
yum -y update
yum install -y ruby
cd /home/ec2-user
curl -O https://aws-codedeploy-us-east-2.s3.amazonaws.com/latest/install
chmod +x ./install
./install auto
```
此脚本将在 Amazon Linux 和 Red Hat Enterprise Linux (RHEL) 实例上安装 AWS CodeDeploy 代理，如《AWS CodeDeploy 用户指南》中的[为 CodeDeploy 创建 Amazon EC2 实例](https://docs.aws.amazon.com/codedeploy/latest/userguide/instances-ec2-create.html)所述。**
该脚本将从 AWS 托管的 S3 存储桶安装 CodeDeploy 代理程序，该存储桶位于美国东部（俄亥俄州）区域（us-east-2）（`aws-codedeploy-us-east-2`）。
**在 AWS CLI 命令中运行 Bash 脚本**
以下示例演示了如何使用 `--parameters` 选项在 CLI 命令中包含 Bash 脚本。
------
#### [ Linux & macOS ]
```
aws ssm send-command \
--document-name "AWS-RunShellScript" \
--targets '[{"Key":"InstanceIds","Values":["instance-id"]}]' \
--parameters '{"commands":["#!/bin/bash","yum -y update","yum install -y ruby","cd /home/ec2-user","curl -O https://aws-codedeploy-us-east-2.s3.amazonaws.com/latest/install","chmod +x ./install","./install auto"]}'
```
------
**在 JSON 文件中运行 Bash 脚本**
在以下示例中，Bash 脚本的内容存储在一个 JSON 文件中，该文件通过使用 `--cli-input-json` 选项包含在命令中。
------
#### [ Linux & macOS ]
```
aws ssm send-command \
--document-name "AWS-RunShellScript" \
--targets "Key=InstanceIds,Values=instance-id" \
--cli-input-json file://installCodeDeployAgent.json
```
------
#### [ Windows ]
```
aws ssm send-command ^
--document-name "AWS-RunShellScript" ^
--targets "Key=InstanceIds,Values=instance-id" ^
--cli-input-json file://installCodeDeployAgent.json
```
------
引用的 `installCodeDeployAgent.json` 文件的内容如以下示例所示。
```
{
"Parameters": {
"commands": [
"#!/bin/bash",
"yum -y update",
"yum install -y ruby",
"cd /home/ec2-user",
"curl -O https://aws-codedeploy-us-east-2.s3.amazonaws.com/latest/install",
"chmod +x ./install",
"./install auto"
]
}
}
```
# 演练：将 AWS Tools for Windows PowerShell 与 Run Command 结合使用
以下示例说明如何使用 AWS Tools for Windows PowerShell 查看有关命令和命令参数的信息、如何运行命令以及如何查看这些命令的状态。本演练为每个预定义的 AWS Systems Manager 文档包含了一个示例。
**重要**
仅允许受信任的管理员使用本主题中所示的 Systems Manager 预配置文档。在 Systems Manager 文档中指定的命令和脚本需要管理权限才能在您的托管式节点上运行。如果用户有权运行任何预定义的 Systems Manager 文档（任何以 AWS 开头的文档），则该用户也具有节点的管理员访问权限。对于所有其他用户，您应创建限制性文档并与特定用户共享这些文档。
**Topics**
+ [配置 AWS Tools for Windows PowerShell 会话设置](#walkthrough-powershell-settings)
+ [列出所有可用文档](#walkthrough-powershell-all-documents)
+ [运行 PowerShell 命令或脚本](#walkthrough-powershell-run-script)
+ [使用 `AWS-InstallApplication` 文档安装应用程序](#walkthrough-powershell-install-application)
+ [使用 `AWS-InstallPowerShellModule` JSON 文档安装 PowerShell 模块](#walkthrough-powershell-install-module)
+ [使用 `AWS-JoinDirectoryServiceDomain` JSON 文档将托管式节点加入域中](#walkthrough-powershell-domain-join)
+ [使用 `AWS-ConfigureCloudWatch` 文档将 Windows 指标发送到 Amazon CloudWatch Logs](#walkthrough-powershell-windows-metrics)
+ [使用 `AWS-ConfigureWindowsUpdate` 文档启用或关闭 Windows 自动更新](#walkthrough-powershell-enable-windows-update)
+ [使用 Run Command 管理 Windows 更新](#walkthough-powershell-windows-updates)
## 配置 AWS Tools for Windows PowerShell 会话设置
**指定您的凭证**
在本地计算机上打开 **Tools for Windows PowerShell** 并运行以下命令以指定您的凭证。您必须具有要配置的托管式节点的管理员权限，或必须已获得 AWS Identity and Access Management (IAM) 中的适当权限。有关更多信息，请参阅 [为 AWS Systems Manager 设置托管节点](systems-manager-setting-up-nodes.md)。
```
Set-AWSCredentials –AccessKey key-name –SecretKey key-name
```
**设置默认 AWS 区域**
运行以下命令为 PowerShell 会话设置区域。此示例使用美国东部（俄亥俄州）区域（us-east-2）。Run Command 在《Amazon Web Services 一般参考》**的 [Systems Manager service endpoints](https://docs.aws.amazon.com/general/latest/gr/ssm.html#ssm_region) 列出的 AWS 区域 中可用。
```
Set-DefaultAWSRegion `
-Region us-east-2
```
## 列出所有可用文档
此命令将列出您的账户可用的所有文档。
```
Get-SSMDocumentList
```
## 运行 PowerShell 命令或脚本
利用 Run Command 和 `AWS-RunPowerShell` 文档，您可以在托管式节点上运行任何命令或脚本，就像您已在本地登录一样。您可以发出命令或输入本地脚本的路径以运行命令。
**注意**
有关在使用 Run Command 调用脚本时重启托管式节点的信息，请参阅 [运行命令时处理重启问题](send-commands-reboot.md)。
**查看说明和可用参数**
```
Get-SSMDocumentDescription `
-Name "AWS-RunPowerShellScript"
```
**查看有关参数的更多信息**
```
Get-SSMDocumentDescription `
-Name "AWS-RunPowerShellScript" | Select -ExpandProperty Parameters
```
### 使用 `AWS-RunPowerShellScript` 文档发送命令
以下命令在两个托管式节点上显示 `"C:\Users"` 目录的内容和 `"C:\"` 目录的内容。
```
$runPSCommand = Send-SSMCommand `
-InstanceIds @("instance-ID-1", "instance-ID-2") `
-DocumentName "AWS-RunPowerShellScript" `
-Comment "Demo AWS-RunPowerShellScript with two instances" `
-Parameter @{'commands'=@('dir C:\Users', 'dir C:\')}
```
**获取命令请求详细信息**
以下命令使用 `CommandId` 获取两个托管式节点上的命令执行状态。此示例使用上一个命令中返回的 `CommandId`。
```
Get-SSMCommand `
-CommandId $runPSCommand.CommandId
```
此示例中命令的状态可以是 Success、Pending 或 InProgress。
**获取每个托管式节点的命令信息**
以下命令使用上一命令中的 `CommandId` 来获取每个托管式节点的命令执行状态。
```
Get-SSMCommandInvocation `
-CommandId $runPSCommand.CommandId
```
**获取包含特定托管式节点的响应数据的命令信息**
以下命令会返回特定托管式节点的原始 `Send-SSMCommand` 的输出。
```
Get-SSMCommandInvocation `
-CommandId $runPSCommand.CommandId `
-Details $true `
-InstanceId instance-ID | Select -ExpandProperty CommandPlugins
```
### 取消命令
以下命令取消 `AWS-RunPowerShellScript` 文档的 `Send-SSMCommand`。
```
$cancelCommand = Send-SSMCommand `
-InstanceIds @("instance-ID-1","instance-ID-2") `
-DocumentName "AWS-RunPowerShellScript" `
-Comment "Demo AWS-RunPowerShellScript with two instances" `
-Parameter @{'commands'='Start-Sleep –Seconds 120; dir C:\'}
Stop-SSMCommand -CommandId $cancelCommand.CommandId
```
**查看命令状态**
以下命令检查 `Cancel` 命令的状态。
```
Get-SSMCommand `
-CommandId $cancelCommand.CommandId
```
## 使用 `AWS-InstallApplication` 文档安装应用程序
利用 Run Command 和 `AWS-InstallApplication` 文档，您可以在托管式节点上安装、修复或卸载应用程序。该命令需要 MSI 的路径或地址。
**注意**
有关在使用 Run Command 调用脚本时重启托管式节点的信息，请参阅 [运行命令时处理重启问题](send-commands-reboot.md)。
**查看说明和可用参数**
```
Get-SSMDocumentDescription `
-Name "AWS-InstallApplication"
```
**查看有关参数的更多信息**
```
Get-SSMDocumentDescription `
-Name "AWS-InstallApplication" | Select -ExpandProperty Parameters
```
### 使用 `AWS-InstallApplication` 文档发送命令
以下命令将以无人值守的模式在托管式节点上安装 Python 版本，并将输出记录在 `C:` 驱动器上的本地文本文件中。
```
$installAppCommand = Send-SSMCommand `
-InstanceId instance-ID `
-DocumentName "AWS-InstallApplication" `
-Parameter @{'source'='https://www.python.org/ftp/python/2.7.9/python-2.7.9.msi'; 'parameters'='/norestart /quiet /log c:\pythoninstall.txt'}
```
**获取每个托管式节点的命令信息**
以下命令使用 `CommandId` 获取命令执行的状态。
```
Get-SSMCommandInvocation `
-CommandId $installAppCommand.CommandId `
-Details $true
```
**获取包含特定托管式节点的响应数据的命令信息**
以下命令返回 Python 安装的结果。
```
Get-SSMCommandInvocation `
-CommandId $installAppCommand.CommandId `
-Details $true `
-InstanceId instance-ID | Select -ExpandProperty CommandPlugins
```
## 使用 `AWS-InstallPowerShellModule` JSON 文档安装 PowerShell 模块
您可使用 Run Command 在托管式节点上安装 PowerShell 模块。有关 PowerShell 模块的更多信息，请参阅 [Windows PowerShell 模块](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_modules?view=powershell-6)。
**查看说明和可用参数**
```
Get-SSMDocumentDescription `
-Name "AWS-InstallPowerShellModule"
```
**查看有关参数的更多信息**
```
Get-SSMDocumentDescription `
-Name "AWS-InstallPowerShellModule" | Select -ExpandProperty Parameters
```
### 安装 PowerShell 模块
以下命令下载 EZOut.zip 文件，安装该文件，然后运行另一个命令来安装 XPS Viewer。最后，输出此命令将上传到一个名为“amzn-s3-demo-bucket”的 S3 存储桶中。
```
$installPSCommand = Send-SSMCommand `
-InstanceId instance-ID `
-DocumentName "AWS-InstallPowerShellModule" `
-Parameter @{'source'='https://gallery.technet.microsoft.com/EZOut-33ae0fb7/file/110351/1/EZOut.zip';'commands'=@('Add-WindowsFeature -name XPS-Viewer -restart')} `
-OutputS3BucketName amzn-s3-demo-bucket
```
**获取每个托管式节点的命令信息**
以下命令使用 `CommandId` 获取命令执行的状态。
```
Get-SSMCommandInvocation `
-CommandId $installPSCommand.CommandId `
-Details $true
```
**获取包含托管式节点的响应数据的命令信息**
以下命令返回特定 `CommandId` 的原始 `Send-SSMCommand` 的输出。
```
Get-SSMCommandInvocation `
-CommandId $installPSCommand.CommandId `
-Details $true | Select -ExpandProperty CommandPlugins
```
## 使用 `AWS-JoinDirectoryServiceDomain` JSON 文档将托管式节点加入域中
借助 Run Command，您可以将托管式节点快速加入 AWS Directory Service 域中。执行此命令前，请[创建目录](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/ms_ad_getting_started_create_directory.html)。还建议您了解 Directory Service 的更多信息。有关更多信息，请参阅 [AWS Directory Service 管理指南](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/)。
您只能将托管式节点加入域中，无法从域中删除节点。
**注意**
有关在使用 Run Command 调用脚本时托管式节点的信息，请参阅 [运行命令时处理重启问题](send-commands-reboot.md)。
**查看说明和可用参数**
```
Get-SSMDocumentDescription `
-Name "AWS-JoinDirectoryServiceDomain"
```
**查看有关参数的更多信息**
```
Get-SSMDocumentDescription `
-Name "AWS-JoinDirectoryServiceDomain" | Select -ExpandProperty Parameters
```
### 将托管式节点加入域中
以下命令可将托管式节点加入给定的 Directory Service 域中，并将生成的任何输出上传至示例 Amazon Simple Storage Service（Amazon S3）存储桶。
```
$domainJoinCommand = Send-SSMCommand `
-InstanceId instance-ID `
-DocumentName "AWS-JoinDirectoryServiceDomain" `
-Parameter @{'directoryId'='d-example01'; 'directoryName'='ssm.example.com'; 'dnsIpAddresses'=@('192.168.10.195', '192.168.20.97')} `
-OutputS3BucketName amzn-s3-demo-bucket
```
**获取每个托管式节点的命令信息**
以下命令使用 `CommandId` 获取命令执行的状态。
```
Get-SSMCommandInvocation `
-CommandId $domainJoinCommand.CommandId `
-Details $true
```
**获取包含托管式节点的响应数据的命令信息**
此命令返回特定 `CommandId` 的原始 `Send-SSMCommand` 的输出。
```
Get-SSMCommandInvocation `
-CommandId $domainJoinCommand.CommandId `
-Details $true | Select -ExpandProperty CommandPlugins
```
## 使用 `AWS-ConfigureCloudWatch` 文档将 Windows 指标发送到 Amazon CloudWatch Logs
您可以将应用程序、系统、安全和 Windows 事件跟踪 (ETW) 日志中的 Windows Server 消息发送到 Amazon CloudWatch Logs。在首次允许日志记录时，Systems Manager 会发送从您开始上传该应用程序、系统、安全和 ETW 日志时起一 (1) 分钟内生成的所有日志。其中不包括在此时间之前产生的日志。如果您关闭日志记录并在以后再次启用日志记录，Systems Manager 会从其上次停止的时间继续发送日志。对于任何自定义日志文件和 Internet Information Services (IIS) 日志，Systems Manager 会从头读取日志文件。此外，Systems Manager 还可以将性能计数器数据发送到 CloudWatch Logs。
如果先前在 EC2Config 中启用了 CloudWatch 集成，则 Systems Manager 设置会覆盖 `C:\Program Files\Amazon\EC2ConfigService\Settings\AWS.EC2.Windows.CloudWatch.json` 文件中本地存储在托管式节点上的任何设置。有关使用 EC2Config 管理单个托管式节点上的性能计数器和日志的更多信息，请参阅 *Amazon CloudWatch 用户指南*中的[使用 CloudWatch 代理从 Amazon EC2 实例和本地服务器收集指标和日志](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html)。
**查看说明和可用参数**
```
Get-SSMDocumentDescription `
-Name "AWS-ConfigureCloudWatch"
```
**查看有关参数的更多信息**
```
Get-SSMDocumentDescription `
-Name "AWS-ConfigureCloudWatch" | Select -ExpandProperty Parameters
```
### 将应用程序日志发送到 CloudWatch
以下命令可配置托管式节点并将 Windows 应用程序日志移至 CloudWatch。
```
$cloudWatchCommand = Send-SSMCommand `
-InstanceID instance-ID `
-DocumentName "AWS-ConfigureCloudWatch" `
-Parameter @{'properties'='{"engineConfiguration": {"PollInterval":"00:00:15", "Components":[{"Id":"ApplicationEventLog", "FullName":"AWS.EC2.Windows.CloudWatch.EventLog.EventLogInputComponent,AWS.EC2.Windows.CloudWatch", "Parameters":{"LogName":"Application", "Levels":"7"}},{"Id":"CloudWatch", "FullName":"AWS.EC2.Windows.CloudWatch.CloudWatchLogsOutput,AWS.EC2.Windows.CloudWatch", "Parameters":{"Region":"region", "LogGroup":"my-log-group", "LogStream":"instance-id"}}], "Flows":{"Flows":["ApplicationEventLog,CloudWatch"]}}}'}
```
**获取每个托管式节点的命令信息**
以下命令使用 `CommandId` 获取命令执行的状态。
```
Get-SSMCommandInvocation `
-CommandId $cloudWatchCommand.CommandId `
-Details $true
```
**获取包含特定托管式节点的响应数据的命令信息**
以下命令返回 Amazon CloudWatch 配置的结果。
```
Get-SSMCommandInvocation `
-CommandId $cloudWatchCommand.CommandId `
-Details $true `
-InstanceId instance-ID | Select -ExpandProperty CommandPlugins
```
### 使用 `AWS-ConfigureCloudWatch` 文档将性能计数器发送到 CloudWatch
以下演示命令将性能计数器数据上传到 CloudWatch。有关更多信息，请参阅《*[Amazon CloudWatch 用户指南](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/)*》。
```
$cloudWatchMetricsCommand = Send-SSMCommand `
-InstanceID instance-ID `
-DocumentName "AWS-ConfigureCloudWatch" `
-Parameter @{'properties'='{"engineConfiguration": {"PollInterval":"00:00:15", "Components":[{"Id":"PerformanceCounter", "FullName":"AWS.EC2.Windows.CloudWatch.PerformanceCounterComponent.PerformanceCounterInputComponent,AWS.EC2.Windows.CloudWatch", "Parameters":{"CategoryName":"Memory", "CounterName":"Available MBytes", "InstanceName":"", "MetricName":"AvailableMemory", "Unit":"Megabytes","DimensionName":"", "DimensionValue":""}},{"Id":"CloudWatch", "FullName":"AWS.EC2.Windows.CloudWatch.CloudWatch.CloudWatchOutputComponent,AWS.EC2.Windows.CloudWatch", "Parameters":{"AccessKey":"", "SecretKey":"","Region":"region", "NameSpace":"Windows-Default"}}], "Flows":{"Flows":["PerformanceCounter,CloudWatch"]}}}'}
```
## 使用 `AWS-ConfigureWindowsUpdate` 文档启用或关闭 Windows 自动更新
利用 Run Command 和 `AWS-ConfigureWindowsUpdate` 文档，您可以在 Windows Server 托管式节点上启用或关闭 Windows 自动更新。此命令将 Windows 更新代理配置为在您指定的日期和时间下载并安装 Windows 更新。如果更新需要重启，托管式节点将在安装更新 15 分钟后自动重启。利用此命令，您还可以将 Windows 更新配置为检查更新但不安装更新。`AWS-ConfigureWindowsUpdate` 文档在 Windows Server 2012 及更高版本上获得官方支持。
**查看说明和可用参数**
```
Get-SSMDocumentDescription `
–Name "AWS-ConfigureWindowsUpdate"
```
**查看有关参数的更多信息**
```
Get-SSMDocumentDescription `
-Name "AWS-ConfigureWindowsUpdate" | Select -ExpandProperty Parameters
```
### 启用 Windows 自动更新
以下命令将 Windows 更新配置为在每天晚上 22:00 自动下载和安装更新。
```
$configureWindowsUpdateCommand = Send-SSMCommand `
-InstanceId instance-ID `
-DocumentName "AWS-ConfigureWindowsUpdate" `
-Parameters @{'updateLevel'='InstallUpdatesAutomatically'; 'scheduledInstallDay'='Daily'; 'scheduledInstallTime'='22:00'}
```
**查看用于允许 Windows 自动更新的命令状态**
以下命令使用 `CommandId` 获取用于允许 Windows 自动更新的命令执行的状态。
```
Get-SSMCommandInvocation `
-Details $true `
-CommandId $configureWindowsUpdateCommand.CommandId | Select -ExpandProperty CommandPlugins
```
### 关闭 Windows 自动更新
以下命令可降低 Windows 更新通知级别，使系统检查更新但不自动更新托管式节点。
```
$configureWindowsUpdateCommand = Send-SSMCommand `
-InstanceId instance-ID `
-DocumentName "AWS-ConfigureWindowsUpdate" `
-Parameters @{'updateLevel'='NeverCheckForUpdates'}
```
**查看用于关闭 Windows 自动更新的命令状态**
以下命令使用 `CommandId` 获取用于关闭 Windows 自动更新的命令执行的状态。
```
Get-SSMCommandInvocation `
-Details $true `
-CommandId $configureWindowsUpdateCommand.CommandId | Select -ExpandProperty CommandPlugins
```
## 使用 Run Command 管理 Windows 更新
使用 Run Command 和 `AWS-InstallWindowsUpdates` 文档，您可以管理 Windows Server 托管式节点的更新。此命令在托管式节点上扫描或安装缺少的更新，并且可以选择在安装后重启。还可以为在您的环境中安装的更新指定相应的分类和严重性级别。
**注意**
有关在使用 Run Command 调用脚本时重启托管式节点的信息，请参阅 [运行命令时处理重启问题](send-commands-reboot.md)。
以下示例说明了如何执行指定的 Windows Update 管理任务。
### 搜索所有缺少的 Windows 更新
```
Send-SSMCommand `
-InstanceId instance-ID `
-DocumentName "AWS-InstallWindowsUpdates" `
-Parameters @{'Action'='Scan'}
```
### 安装特定的 Windows 更新
```
Send-SSMCommand `
-InstanceId instance-ID `
-DocumentName "AWS-InstallWindowsUpdates" `
-Parameters @{'Action'='Install';'IncludeKbs'='kb-ID-1,kb-ID-2,kb-ID-3';'AllowReboot'='True'}
```
### 安装缺少的重要 Windows 更新
```
Send-SSMCommand `
-InstanceId instance-ID `
-DocumentName "AWS-InstallWindowsUpdates" `
-Parameters @{'Action'='Install';'SeverityLevels'='Important';'AllowReboot'='True'}
```
### 安装缺少的 Windows 更新 (带特定排除内容)
```
Send-SSMCommand `
-InstanceId instance-ID `
-DocumentName "AWS-InstallWindowsUpdates" `
-Parameters @{'Action'='Install';'ExcludeKbs'='kb-ID-1,kb-ID-2';'AllowReboot'='True'}
```
# 对 Systems Manager Run Command 进行故障排除
Run Command（AWS Systems Manager 中的一项工具）在每次命令执行时提供状态详细信息。有关命令状态的更多信息，请参阅 [了解命令状态](monitor-commands.md)。您也可以使用本主题中的信息来帮助排查 Run Command 问题。
**Topics**
+ [我的部分托管式节点缺失](#where-are-instances)
+ [我的脚本中的一个步骤失败，但总体状态为 “succeeded”。](#ts-exit-codes)
+ [SSM Agent 未正常运行](#ts-ssmagent-linux)
## 我的部分托管式节点缺失
在 **Run a command**（运行命令）页面上，选择要运行的 SSM 文档并在 **Targets**（目标）部分中选择 **Manually selecting instances**（手动选择实例）后，将显示托管式节点的列表，您可以从中选择要在其上运行命令的节点。
如果未列出您希望看到的托管式节点，请参阅 [排除托管式节点可用性的问题](fleet-manager-troubleshooting-managed-nodes.md) 以获取故障排除技巧。
创建、激活、重新引导或重新启动托管式节点、在节点上安装 Run Command 或将 AWS Identity and Access Management (IAM) 实例配置文件附加到节点后，该托管式节点可能需要几分钟时间才会添加到列表中。
## 我的脚本中的一个步骤失败，但总体状态为 “succeeded”。
您可以使用 Run Command 定义脚本如何处理退出代码。默认情况下，脚本中运行的最后一个命令的退出代码将报告为整个脚本的退出代码。但是，如果在最后一个命令失败之前有任何命令，则可以包含条件语句来退出脚本。有关信息以及示例，请参阅 [在命令中指定退出代码](run-command-handle-exit-status.md#command-exit-codes)。
## SSM Agent 未正常运行
如果在使用 Run Command 运行命令时遇到问题，可能是因为 SSM Agent 存在问题。有关调查 SSM Agent 的相关问题的信息，请参阅 [排除 SSM Agent 问题](troubleshooting-ssm-agent.md)。