• 2026 年 4 月 30 日之後將不再提供 AWS Systems Manager CloudWatch Dashboard。客戶可以繼續使用 Amazon CloudWatch 主控台來檢視、建立和管理其 Amazon CloudWatch 儀表板，就像現在一樣。如需詳細資訊，請參閱 [Amazon CloudWatch Dashboard 文件](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 可讓您自動執行常見的管理任務，並進行大規模的單次組態變更。您可以從 Run Command AWS 管理主控台、 AWS Command Line Interface (AWS CLI) AWS Tools for Windows PowerShell或 AWS SDKs使用 。 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。
****
| 主題 | 詳細資訊 |
| --- | --- |
| [設定 的受管節點 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) | （選用） 向 註冊現場部署伺服器和VMs 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**
此 Systems Manager 工具作為 Amazon EventBridge 規則中的*事件*類型和*目標*類型受到支援。如需詳細資訊，請參閱 [使用 Amazon EventBridge 監控 Systems Manager](monitoring-eventbridge-events.md) 及 [參考：Systems Manager 的 Amazon EventBridge 事件模式和類型](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 執行命令](troubleshooting-remote-commands.md)
# 設定 Run Command
在您可以使用 中的工具來管理節點之前Run Command，請為將執行命令的任何使用者 AWS Systems Manager設定 AWS Identity and Access Management (IAM) 政策。如果針對 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 來記錄命令執行狀態變更。您可以建立規則，在有狀態轉換或有轉移到一或多個與您相關的狀態時執行。您也可以指定在 EventBridge 事件發生時，將 Run Command 做為目標動作。如需詳細資訊，請參閱[為 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 政策，其條件是使用者只能在標記了特定標籤的受管節點上執行命令。如需詳細資訊，請參閱[根據標籤限制 Run Command 存取](#tag-based-access)。
## 根據標籤限制 Run Command 存取
本節描述了如何透過在 IAM 政策中指定標籤條件，限制使用者在受管節點上執行命令的能力。受管節點包含針對 Systems Manager 設定之[混合多雲端](operating-systems-and-machine-types.md#supported-machine-types)環境中的 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 政策 (其中包含條件，限制使用者只能在具有特定標籤的節點上執行命令)，來限制只針對特定受管節點執行命令。在下列範例中，使用者可以在任何節點 (`Resource: arn:aws:ec2:*:*:instance/*`) 使用任何 SSM 文件 (`Resource: arn:aws:ssm:*:*:document/*`) 來使用 Run Command (`Effect: Allow, Action: ssm:SendCommand`)，條件為節點是 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 政策，可讓使用者在以多個標籤所標記的受管節點上執行命令。以下政策可讓使用者在擁有兩個標籤的受管理節點上執行命令。如果使用者將命令傳送至未以那兩個標記所標記的節點，執行結果會顯示 `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 政策，其可讓使用者在多組加上標籤的受管節點上執行命令。以下範例政策可讓使用者在一組或兩組含標記的節點上執行命令。
------
#### [ 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 政策的詳細資訊，請參閱《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 活動都會記錄在 S3 儲存貯體中的 AWS CloudTrail 日誌。這意味著任何具有權存取該 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 Systems ManagerAWS Tools for PowerShell Cmdlet 參考 區段](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)
# 從主控台執行命令
您可以從 使用 中的Run Command工具 AWS 管理主控台 來設定受管節點 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：//[https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/) 開啟 AWS Systems Manager 主控台。
1. 在導覽窗格中，選擇 **Run Command**。
1. 選擇**執行命令**。
1. 在 **Command document** (命令文件) 清單中，選擇 Systems Manager 文件。
1. 在 **Command parameters (命令參數)** 區段，指定所需的參數值。
1. 在 **Targets** (目標) 區段中，透過手動指定標籤、選取執行個體或邊緣裝置，或指定資源群組，選擇您要執行這項操作的受管節點。
**提示**
如果您預期看到的受管節點未列出，請參閱 [疑難排解受管節點的可用性](fleet-manager-troubleshooting-managed-nodes.md) 以取得疑難排解秘訣。
1. 對於**其他參數**：
+ 在 **Comment** (註解) 中，輸入此命令的相關資訊。
+ 在**逾時 (秒)** 中，指定在命令執行全面失敗之前，系統要等候的秒數。
1. 對於 **Rate control** (速率控制)：
+ 在**並行**中，指定可同時執行命令的受管節點數目或百分比。
**注意**
如果您透過指定套用至受管節點的標籤或指定 AWS 資源群組來選取目標，而且不確定目標的受管節點數量，則透過指定百分比來限制可同時執行文件的目標數量。
+ 在 **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 通知**區段中，如果您要傳送有關命令執行狀態的通知，請選取**啟用 SNS 通知**核取方塊。
如需為 Run Command 設定 Amazon SNS 通知的詳細資訊，請參閱 [使用 Amazon SNS 通知監控 Systems Manager 狀態變更](monitoring-sns-notifications.md)。
1. 選擇**執行**。
如需取消命令的詳細資訊，請參閱 [取消命令](cancel-run-command.md)。
## 重新執行命令
Systems Manager 包含兩個選項，可協助您從 Systems Manager 主控台的 **Run Command** (執行命令) 頁面重新執行命令。
+ **Rerun **(重新執行)：此按鈕可讓您執行相同的命令，而不對其進行變更。
+ **Copy to new (複製到新命令)**：此按鈕會將一個命令的設定複製到新命令，並讓您選擇在執行之前編輯這些設定。
**重新執行命令**
1. 在 https：//[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 (重新執行)** 以在不進行變更的情況下執行相同的命令，或選擇 **Copy to new (複製到新的)** 以在執行命令之前先行編輯命令設定。
# 使用特定文件版本執行命令
您可以使用文件版本參數來在命令執行時，指定要使用的 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 (Tools for 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` 組。當您執行命令時，系統會尋找並嘗試在符合指定標記的所有受管節點上執行命令。如需標記受管執行個體的詳細資訊，請參閱[《標記資源使用者指南》中的標記您的 AWS](https://docs.aws.amazon.com/tag-editor/latest/userguide/tag-editor.html)資源。 * AWS *如需有關標記受管 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，執行命令和目標受管節點。
下列範例顯示Run Command從 AWS Command Line Interface () 使用 時的命令格式AWS CLI 。將每個*範例資源預留位置*取代為您自己的資訊。使用 `[...]` 將此區段中的範本命令截斷。
**範例 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` 的 `Values` 以及 `Production`，為不同環境的受管節點加上標記，則您可以使用 `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** (執行命令) 頁面中的 **Concurrecy** (並行) 選項) 控制同時執行之受管節點的數量。您可以指定絕對數量的受管節點 (例如 **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**，系統會在收到第 4 個錯誤時停止傳送命令。如果您指定 **0**，系統會在第一個錯誤結果傳回後停止將命令傳送至其他受管節點。如果您將命令傳送至 50 個受管節點，並將 `max-errors` 設為 **10%**，系統會在收到第六個錯誤時停止將命令傳送至其他節點。
達到 `max-errors` 時，系統會允許完成已在執行命令的呼叫，但一些呼叫也可能會失敗。如果您需要確保不會有超過 `max-errors` 個失敗的呼叫，請將 `max-concurrency` 設定為 **1**，以每次執行一個呼叫。錯誤上限預設值為 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 ^
[...]
```
------
# 取消命令
只要該服務會顯示為待定或執行中狀態，您就可以嘗試取消命令。不過，即使命令仍處於其中一個狀態，我們無法保證命令是否會取消且基本程序會停止。
**使用主控台來取消命令**
1. 開啟位於 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/) 的 AWS Systems Manager 主控台。
1. 在導覽窗格中，選擇 **Run Command**。
1. 選取您要取消的命令呼叫。
1. 選擇 **Cancel command (取消命令)**。
**使用 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 客服人員 (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 () 呼叫 [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 CLI。或使用 呼叫 [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) AWS Tools for Windows PowerShell。
+ 設定 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 個執行個體，該命令會有 20 個叫用。每個命令呼叫會個別報告狀態。指定命令叫用的外掛程式也會個別報告狀態。
最後，Run Command 包含所有外掛程式和呼叫的彙總命令狀態。彙總命令狀態可能會與外掛程式或呼叫所回報的狀態不同，如以下資料表所示。
**注意**
如果您使用 `max-concurrency` 或 `max-errors` 參數對大量受管節點執行命令，命令狀態會反映這些參數所實施的限制，如下列資料表所述。如需這些參數的相關資訊，請參閱 [大規模執行命令](send-commands-multiple.md)。
**命令外掛程式和呼叫的詳細狀態**
| 狀態 | 詳細資訊 |
| --- | --- |
| 待定 | 該命令尚未傳送至受管節點或尚未被 SSM Agent 接收。如果代理程式未收到命令之前的時間長度等於 Timeout (seconds) (逾時 (秒)) 參數與 Execution timeout (執行逾時) 參數的總和，則狀態會變更為 Delivery Timed Out。 |
| InProgress | Systems Manager 嘗試將命令傳送至執行個體，或由 SSM Agent 接收命令，並開始在受管節點上執行。根據所有命令外掛程式的結果，狀態變更為 Success、Failed、Delivery Timed Out 或 Execution Timed Out。異常情形：如果代理程式未執行或在節點上不可用，則命令狀態會保留在 In Progress，直到代理程式再次可用，或直到達到執行逾時限制為止。此狀態會接著變更為終止狀態。 |
| 延遲 | 系統嘗試將命令傳送至受管節點，但未成功。系統會再次重試。 |
| 成功 | 此狀態會在各種條件下傳回。此狀態不代表命令在節點成功處理。例如，SSM Agent 可以在受管節點上接收命令，並且由於 PowerShell ExecutionPolicy 阻止命令執行，命令會傳回零的結束程式碼。這是一個終端狀態。導致命令傳回 Success 狀態的條件為：[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/systems-manager/latest/userguide/monitor-commands.html) 以資源群組為目標時，同樣的條件也適用。若要排除錯誤或取得更多命令執行的相關資訊，透過傳回適當的結束代碼 (非零結束代碼適用於命令失敗)，傳送處理錯誤或例外狀況的命令。 |
| DeliveryTimedOut | 在總逾時過期前，不會將此命令傳送到受管理節點。總逾時不會計入父命令的 max-errors 限制，但它們不會影響父命令狀態是否為 Success、Incomplete 或 Delivery Timed Out。這是一個終端狀態。 |
| ExecutionTimedOut | 命令自動化會在受管節點上開始，但是命令在執行逾時過期前未完成。執行超時計算為失敗，這將會傳送非零回覆，Systems Manager 將會停止嘗試執行命令自動化，並回報失敗狀態。 |
| 失敗 | 命令在受管節點上未成功執行。若是外掛程式，這表示結果碼不為零。若是命令叫用，這表示一或多個外掛程式的結果碼不為零。呼叫失敗不會計入父命令的 max-errors 限制。這是一個終端狀態。 |
| 已取消 | 命令在完成前已取消。這是一個終端狀態。 |
| 交付成果 | 無法將命令傳送至受管節點。節點可能不存在或可能不回應。交付成果呼叫不會計入父命令的 max-errors 限制，但它們不會影響父命令狀態是否為 Success 或 Incomplete。例如，若命令中所有的呼叫狀態都是 Undeliverable，則命令狀態會傳回 Failed。但是，若命令進行 5 次呼叫，其中 4 次傳回了狀態 Undeliverable，1 次則傳回了狀態 Success，則父命令的狀態便是 Success。這是一個終端狀態。 |
| 已終止 | 父命令超過其 max-errors 限制和系統已取消後續命令呼叫。這是一個終端狀態。 |
| InvalidPlatform | 命令已傳送到與所選文件指定的所需平台不相符的受管節點。Invalid Platform 不會計入父命令的最高錯誤限制，但它確實會影響父命令狀態為成功或失敗。例如，若命令中所有的呼叫狀態都是 Invalid Platform，則命令狀態會傳回 Failed。但是，若命令進行 5 次呼叫，其中 4 次傳回了狀態 Invalid Platform，1 次則傳回了狀態 Success，則父命令的狀態便是 Success。這是一個終端狀態。 |
| AccessDenied | 啟動命令的 AWS Identity and Access Management (IAM) 使用者或角色無法存取目標受管節點。 Access Denied不會計入父命令max-errors的限制，但確實會導致父命令狀態為 Success或 Failed。例如，若命令中所有的呼叫狀態都是 Access Denied，則命令狀態會傳回 Failed。但是，若命令進行 5 次呼叫，其中 4 次傳回了狀態 Access Denied，1 次則傳回了狀態 Success，則父命令的狀態便是 Success。這是一個終端狀態。 |
**命令的詳細狀態**
| 狀態 | 詳細資訊 |
| --- | --- |
| 待定 | 任何受管節點上的代理程式都尚未收到命令。 |
| 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_tw/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` 之前，執行時間為 4,200 秒 (70 分鐘)。
**執行逾時**
在 Systems Manager 主控台中，您可以在 **Execution Timeout** (執行逾時) 欄位中指定執行逾時值 (如果有的話)。並非所有 SSM 文件都需要您指定執行逾時。僅在 SSM 文件中已定義對應的輸入參數時，才會顯示**執行逾時**欄位。如果指定了逾時，命令即必須在此期間內完成。
**注意**
Run Command 依賴於 SSM Agent 文件終端機回應，以判斷命令是否已傳遞給代理程式。SSM Agent 必須傳送用於叫用或命令、被標記為 `ExecutionTimedOut` 的 `ExecutionTimedOut` 信號。
![\[Systems Manager 主控台中的 Execution Timeout (執行逾時) 欄位\]](http://docs.aws.amazon.com/zh_tw/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 會根據 SSM 文件類型和文件版本的不同，來處理 `executionTimeout`。
# 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：//[https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/) 開啟 AWS Systems Manager 主控台。
1. 在導覽窗格中，選擇 **Run Command**。
1. 選擇**執行命令**。
1. 在 **Command document** (命令文件) 清單，請選擇 **`AWS-UpdateSSMAgent`**。
1. 在 **Command parameters (命令參數)** 區段，依您所需指定下列參數值：
1. (選用) 對於 **Version** (版本)，輸入要安裝的 SSM Agent 版本。您可以安裝[較舊版本](https://github.com/aws/amazon-ssm-agent/blob/mainline/RELEASENOTES.md)的代理程式。如果您未指定版本，該服務會安裝最新版本。
1. (選用) 針對 **Allow Downgrade (允許降級)**，請選擇 **true (true)** 來安裝舊版 SSM Agent。如果選擇此選項，則指定[舊](https://github.com/aws/amazon-ssm-agent/blob/mainline/RELEASENOTES.md)版本編號。選擇 **false (false)** 來僅安裝最新版的服務。
1. 在 **Targets** (目標) 區段中，透過手動指定標籤、選取執行個體或邊緣裝置，或指定資源群組，選擇您要執行這項操作的受管節點。
**提示**
如果您預期看到的受管節點未列出，請參閱 [疑難排解受管節點的可用性](fleet-manager-troubleshooting-managed-nodes.md) 以取得疑難排解秘訣。
1. 對於**其他參數**：
+ 在 **Comment** (註解) 中，輸入此命令的相關資訊。
+ 在**逾時 (秒)** 中，指定在命令執行全面失敗之前，系統要等候的秒數。
1. 對於 **Rate control** (速率控制)：
+ 在**並行**中，指定可同時執行命令的受管節點數目或百分比。
**注意**
如果您透過指定套用至受管節點的標籤或指定 AWS 資源群組來選取目標，而且不確定目標的受管節點數量，則透過指定百分比來限制可同時執行文件的目標數量。
+ 在 **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 通知**區段中，如果您要傳送有關命令執行狀態的通知，請選取**啟用 SNS 通知**核取方塊。
如需為 Run Command 設定 Amazon SNS 通知的詳細資訊，請參閱 [使用 Amazon SNS 通知監控 Systems Manager 狀態變更](monitoring-sns-notifications.md)。
1. 選擇**執行**。
## 使用 Run Command 更新 PowerShell
下列處理程序說明如何將 PowerShell 更新至 Windows Server 2012 和 2012 R2 受管節點 5.1 版。此處理程序中提供的指令碼會下載 Windows 管理架構 (WMF) 5.1 版更新，並開始安裝更新。節點會在此程序期間重新開機，因為在安裝 WMF 5.1 時需要這樣進行。更新的下載和安裝大約需要五分鐘才能完成。
**使用 Run Command 更新 PowerShell**
1. 在 https：//[https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/) 開啟 AWS Systems Manager 主控台。
1. 在導覽窗格中，選擇 **Run Command**。
1. 選擇**執行命令**。
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. 對於**其他參數**：
+ 在 **Comment** (註解) 中，輸入此命令的相關資訊。
+ 在**逾時 (秒)** 中，指定在命令執行全面失敗之前，系統要等候的秒數。
1. 對於 **Rate control** (速率控制)：
+ 在**並行**中，指定可同時執行命令的受管節點數目或百分比。
**注意**
如果您透過指定套用至受管節點的標籤或指定 AWS 資源群組來選取目標，而且不確定目標的受管節點數量，則透過指定百分比來限制可同時執行文件的目標數量。
+ 在 **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 通知**區段中，如果您要傳送有關命令執行狀態的通知，請選取**啟用 SNS 通知**核取方塊。
如需為 Run Command 設定 Amazon SNS 通知的詳細資訊，請參閱 [使用 Amazon SNS 通知監控 Systems Manager 狀態變更](monitoring-sns-notifications.md)。
1. 選擇**執行**。
受管節點重新開機且更新安裝完成後，請連線到節點，以確認 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 可在 中 [Systems Manager 服務端點](https://docs.aws.amazon.com/general/latest/gr/ssm.html#ssm_region)中 AWS 區域 列出的 中使用*Amazon Web Services 一般參考*。如需詳細資訊，請參閱[設定 的受管節點 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** 的回應。執行個體 IDs可從 中取得Fleet Manager。 AWS Systems Manager
------
#### [ 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` 文件，在受管節點上執行任何命令或指令碼，如同您在本機登入一樣。
**View the description and available parameters (查看描述和可用參數)**
請執行下列命令以檢視 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 Simple Storage Service (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)中所述。
指令碼會從位於美國東部 （俄亥俄） 區域 (us-east-2) 的 AWS 受管 S3 儲存貯體安裝 CodeDeploy 代理程式`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 可在 中 [Systems Manager 服務端點](https://docs.aws.amazon.com/general/latest/gr/ssm.html#ssm_region)中 AWS 區域 列出的 中使用*Amazon Web Services 一般參考*。
```
Set-DefaultAWSRegion `
-Region us-east-2
```
## 列出所有可用的文件
此命令會列出可供您帳戶使用的所有文件。
```
Get-SSMDocumentList
```
## 執行 PowerShell 命令或指令碼
您可以使用 Run Command 和 `AWS-RunPowerShell` 文件，在受管節點上執行任何命令或指令碼，如同您在本機登入一樣。您可以發出命令或在本機指令碼輸入路徑來執行命令。
**注意**
如需使用 Run Command 呼叫指令碼時重新啟動受管節點的資訊，請參閱 [執行命令時處理重新啟動](send-commands-reboot.md)。
**View the description and available parameters (查看描述和可用參數)**
```
Get-SSMDocumentDescription `
-Name "AWS-RunPowerShellScript"
```
**View more information about parameters (檢視參數的詳細資訊)**
```
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)。
**View the description and available parameters (查看描述和可用參數)**
```
Get-SSMDocumentDescription `
-Name "AWS-InstallApplication"
```
**View more information about parameters (檢視參數的詳細資訊)**
```
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)。
**View the description and available parameters (查看描述和可用參數)**
```
Get-SSMDocumentDescription `
-Name "AWS-InstallPowerShellModule"
```
**View more information about parameters (檢視參數的詳細資訊)**
```
Get-SSMDocumentDescription `
-Name "AWS-InstallPowerShellModule" | Select -ExpandProperty Parameters
```
### 安裝 PowerShell 模組
以下命令會下載 EZOut.zip 檔案、進行安裝，然後執行額外的命令來安裝 XPS 檢視器。最後，此命令的輸出會上傳到名為 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)。
**View the description and available parameters (查看描述和可用參數)**
```
Get-SSMDocumentDescription `
-Name "AWS-JoinDirectoryServiceDomain"
```
**View more information about parameters (檢視參數的詳細資訊)**
```
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)。
**View the description and available parameters (查看描述和可用參數)**
```
Get-SSMDocumentDescription `
-Name "AWS-ConfigureCloudWatch"
```
**View more information about parameters (檢視參數的詳細資訊)**
```
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 更新設定為檢查更新，但不加以安裝。Windows Server 2012 及更新版本正式支援 `AWS-ConfigureWindowsUpdate` 文件。
**View the description and available parameters (查看描述和可用參數)**
```
Get-SSMDocumentDescription `
–Name "AWS-ConfigureWindowsUpdate"
```
**View more information about parameters (檢視參數的詳細資訊)**
```
Get-SSMDocumentDescription `
-Name "AWS-ConfigureWindowsUpdate" | Select -ExpandProperty Parameters
```
### 開啟 Windows 自動更新
以下命令會將 Windows Update 設定為每日下午 10: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是 中的工具 AWS Systems Manager，提供每個命令執行的狀態詳細資訊。如需命令列狀態的詳細資訊，請參閱 [了解命令狀態](monitor-commands.md)。您也可以使用此主題中的資訊，以協助排除與 Run Command 有關的問題。
**Topics**
+ [遺漏了我的一些受管節點](#where-are-instances)
+ [我指令碼中的一個步驟失敗，但整體狀態是「成功」](#ts-exit-codes)
+ [SSM Agent 未正常執行](#ts-ssmagent-linux)
## 遺漏了我的一些受管節點
在 **Run Command** (執行命令) 頁面中，選擇要執行的 SSM 文件並在 **Targets** (目標)區段選取 **Manually selecting instances** (手動選取執行個體) 後，會顯示您可以選擇在其中執行命令的受管節點清單。
如果您預期看到的受管節點未列出，請參閱 [疑難排解受管節點的可用性](fleet-manager-troubleshooting-managed-nodes.md) 以取得疑難排解秘訣。
在您建立、啟用、重新啟動或重新啟動受管節點、在節點Run Command上安裝 ，或將 AWS Identity and Access Management (IAM) 執行個體描述檔連接至節點後，可能需要幾分鐘的時間，受管節點才會新增至清單。
## 我指令碼中的一個步驟失敗，但整體狀態是「成功」
使用 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)。