• 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 Documents
AWS Systems Manager 文件 (SSM 文件） 定義 Systems Manager 在受管執行個體上執行的動作。Systems Manager 包含 100 多個預先設定的文件，可讓您用來在執行時間時指定參數。透過選擇 **Owned by Amazon** (Amazon 擁有) 索引標籤，或者在呼叫 `ListDocuments` API 操作時為 `Owner` 篩選條件指定 Amazon，您可以在 Systems Manager 文件主控台中找到預先設定的文件。文件使用 JavaScript 物件標記法 (JSON) 或 YAML，其中包括您指定的步驟和參數。
為了增強安全性，截至 2025 年 7 月 14 日，SSM 文件在處理參數時支援環境變數插補。此功能 (在結構描述為 2.2 版，SSM Agent 為 3.3.2746.0 版或更新版本時可用) 有助於防止命令注入攻擊。
若要開始使用 SSM 文件，請開啟 [Systems Manager 主控台](https://console.aws.amazon.com/systems-manager/documents)。在導覽窗格中，選擇 **Documents (文件)**。
**重要**
在 Systems Manager 中，*Amazon 擁有的* SSM 文件是由 Amazon Web Services 本身建立和管理的文件。*Amazon 擁有的*文件的文件名中包含如 `AWS-*` 的字首。文件的擁有者被視為 Amazon，而不是其中的特定使用者帳戶 AWS。這些文件公開供所有人使用。
## 文件工具對我的組織有哪些益處？
文件是 中的工具 AWS Systems Manager，可提供以下優點：
+ **文件類別**
為了幫助您找到所需文件，請根據要搜尋的文件類型選擇類別。若要擴大搜尋範圍，您可以選擇同一文件類型的多個類別。不支援選擇不同文件類型的類別。僅支援 Amazon 擁有的文件類別。
+ **文件版本**
您可以建立和儲存不同版本的文件。然後，您可以為每個文件指定一個預設版本。預設版本的文件更新到較新版本或可恢復到舊版的文件。當您變更文件的內容時，Systems Manager 會自動增加文件版本。您可以在 主控台、 AWS Command Line Interface (AWS CLI) 命令或 API 呼叫中指定文件版本，以擷取或使用文件的任何版本。
+ **根據需求自訂文件**
如果您要在文件中自訂步驟和動作，您可以建立自己的步驟和動作。系統會將 文件與 存放在 AWS 區域 您建立文件的 AWS 帳戶 中。如需有關如何建立 SSM 文件的詳細資訊，請參閱 [建立 SSM 文件內容](documents-creating-content.md)。
+ **標記文件**
您可以在文件加上標籤，根據您指派給文件的標籤可以協助您快速找出一或多個文件。例如，您可以為用定的環境、部門、使用者、群組或時段來標記文件。您也可以透過建立指定使用者或群組可存取之標籤的 AWS Identity and Access Management (IAM) 政策來限制文件的存取。
+ **共用文件**
您可以將文件設定為公開或者與相同 AWS 區域中特定的 AWS 帳戶 分享。例如，若想讓您提供給客戶或員工的所有 Amazon Elastic Compute Cloud (Amazon EC2) 執行個體都有相同的組態，在帳戶之間共用文件就非常實用。除了將執行個體上的應用程式或修補程式保持在最新狀態，您可能想要限制客戶執行個體避免進行特定的活動。或者，您可能想要確保在組織中員工帳戶所使用的執行個體獲得特定內部資源的存取權。如需詳細資訊，請參閱[共用 SSM 文件](documents-ssm-sharing.md)。
## 誰應該使用 Documents？
+ 任何想要使用 Systems Manager 工具來大規模提高營運效率、減少與手動介入相關的錯誤，以及縮短解決常見問題的時間 AWS 的客戶。
+ 希望自動化部署和組態任務的基礎設施專家。
+ 希望可靠地解決常見問題、提高疑難排解效率和減少重複性操作的管理員。
+ 希望自動化通常手動執行之任務的使用者。
## SSM 文件有哪些類型？
下表說明不同類型的 SSM 文件和其使用案例。
****
| Type | 搭配使用 | 詳細資訊 |
| --- | --- | --- |
| ApplicationConfiguration ApplicationConfigurationSchema | [AWS AppConfig](https://docs.aws.amazon.com/appconfig/latest/userguide/what-is-appconfig.html) | AWS AppConfig是 中的工具 AWS Systems Manager，可讓您建立、管理和快速部署應用程式組態。您可以藉由建立使用 `ApplicationConfiguration` 文件類型的文件，在 SSM 文件中存放組態資料。如需詳細資訊，請參閱*《AWS AppConfig 使用者指南》*中的 [Freeform 組態](https://docs.aws.amazon.com/appconfig/latest/userguide/appconfig-creating-configuration-and-profile.html#free-form-configurations)。 如果您在 SSM 文件中建立組態，則必須指定相應的 JSON 結構描述。該結構描述使用 `ApplicationConfigurationSchema` 文件類型，且與一組規則一樣，會定義每個應用程式組態設定允許的屬性。如需詳細資訊，請參閱*《AWS AppConfig 使用者指南》*中的[關於驗證器](https://docs.aws.amazon.com/appconfig/latest/userguide/appconfig-creating-configuration-and-profile-validators.html)。 |
| Automation Runbook | [自動化](systems-manager-automation.md) [State Manager](systems-manager-state.md) [Maintenance Windows](maintenance-windows.md) | 在執行常見的維護和部署任務 (例如建立或更新 Amazon Machine Image (AMI)) 時使用 Automation Runbook。State Manager 會使用 Automation Runbook 來套用組態。您可以在執行個體生命週期期間的任何時間點對一個或多個目標執行這些動作。Maintenance Windows 會使用 Automation Runbook，根據指定的排程執行常見的維護和部署任務。 基於 Linux 的作業系統支援的所有 Automation Runbook 在 macOS 的 EC2 執行個體上也受支援。 |
| 變更行事曆文件 | [Change Calendar](systems-manager-change-calendar.md) | Change Calendar中的工具 AWS Systems Manager使用 `ChangeCalendar` 文件類型。Change Calendar 文件會存放行事曆項目和相關聯事件，這些事件可允許或防止自動化動作變更您的環境。在 Change Calendar 中，文件會以純文字格式存放 [iCalendar 2.0](https://icalendar.org/) 資料。 macOS 的 EC2 執行個體不支援 Change Calendar。 |
| AWS CloudFormation 範本 | [AWS CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html) | AWS CloudFormation 範本說明您要在 CloudFormation 堆疊中佈建的資源。透過將 CloudFormation 範本存放為 Systems Manager 文件，可讓您從 Systems Manager 文件功能中受益。其中包括建立和比較範本的多個版本，以及與相同 AWS 區域中的其他帳戶共用範本。 使用 Application Manager (Systems Manager 中的工具)，您可以建立和編輯 CloudFormation 範本和堆疊。如需詳細資訊，請參閱[在 中使用 CloudFormation 範本和堆疊 Application Manager](application-manager-working-stacks.md)。 |
| 指令文件 | [Run Command](run-command.md) [State Manager](systems-manager-state.md) [Maintenance Windows](maintenance-windows.md) | Run Command中的工具 AWS Systems Manager會使用命令文件來執行命令。 State Manager中的工具 AWS Systems Manager會使用命令文件來套用組態。這些動作可以在執行個體生命週期的任何時間點於一或多個目標上執行。 Maintenance Windows是 中的工具 AWS Systems Manager，使用 命令文件來根據指定的排程套用組態。 Systems Manager 支援的所有 Linux 和 Windows Server 作業系統支援大部分命令文件。macOS 的 EC2 執行個體支援下列 Command 文件： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/systems-manager/latest/userguide/documents.html) |
| AWS Config 一致性套件範本 | [AWS Config](https://docs.aws.amazon.com/config/latest/developerguide/WhatIsConfig.html) | AWS Config 一致性套件範本是 YAML 格式的文件，用於建立一致性套件，其中包含受管或自訂規則和修補動作的 AWS Config 清單。 如需詳細資訊，請參閱[一致性套件](https://docs.aws.amazon.com/config/latest/developerguide/conformance-packs.html)。 |
| 套件文件 | [Distributor](distributor.md) | 在 Distributor ( AWS Systems Manager中的工具) 中，套件由 SSM 文件來表示。套件文件包含 ZIP 封存檔案，封存檔包含要安裝在受管執行個體上的軟體或資產。在 Distributor 中建立套件會建立套件文件。 Oracle Linux 和 macOS 受管執行個體不支援 Distributor。 |
| 政策文件 | [State Manager](systems-manager-state.md) | 中的庫存工具 AWS Systems Manager會使用`AWS-GatherSoftwareInventory`政策文件與State Manager關聯，從受管執行個體收集庫存資料。建立您自己的 SSM 文件時，Automation Runbook 和命令文件是在受管執行個體上強制執行政策的慣用方法。 Systems Manager 支援的所有作業系統都支援 Systems Manager Inventory 和 `AWS-GatherSoftwareInventory` 政策文件。 |
| 事件後分析範本 | [Incident Manager 事件後分析](https://docs.aws.amazon.com/incident-manager/latest/userguide/analysis.html) | Incident Manager 會使用事件後分析範本，根據 AWS 操作管理最佳實務建立分析。 使用範本建立的分析可供團隊用來找出事件回應的改進。 |
| 工作階段文件 | [Session Manager](session-manager.md) | Session Manager中的工具 AWS Systems Manager會使用工作階段文件來決定要啟動的工作階段類型，例如連接埠轉送工作階段、執行互動式命令的工作階段，或建立 SSH 通道的工作階段。 Systems Manager 支援的所有 Linux 和 Windows Server 作業系統支援工作階段文件。macOS 的 EC2 執行個體支援下列命令文件： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/systems-manager/latest/userguide/documents.html) |
**SSM 文件配額**
如需有關 SSM 文件配額的資訊，請參閱《Amazon Web Services 一般參考》**中的 [Systems Manager 服務配額](https://docs.aws.amazon.com/general/latest/gr/ssm.html#limits_ssm)一節。
**Topics**
+ [文件工具對我的組織有哪些益處？](#ssm-docs-benefits)
+ [誰應該使用 Documents？](#documents-who)
+ [SSM 文件有哪些類型？](#what-are-document-types)
+ [文件組成部分](documents-components.md)
+ [建立 SSM 文件內容](documents-creating-content.md)
+ [使用文件](documents-using.md)
+ [對參數處理問題進行疑難排解](parameter-troubleshooting.md)
# 文件組成部分
本節包含有關 SSM 文件組成部分件的資訊。
**Topics**
+ [結構描述、功能以及範例](documents-schemas-features.md)
+ [資料元素和參數](documents-syntax-data-elements-parameters.md)
+ [命令文件外掛程式參考](documents-command-ssm-plugin-reference.md)
# 結構描述、功能以及範例
AWS Systems Manager (SSM) 文件使用以下結構描述版本。
+ `Command` 類型的文件可以使用結構描述 1.2、2.0 和 2.2 版本。如果您使用的文件為結構描述 1.2 版本，我們建議您使用結構描述 2.2 版本建立文件。
+ `Policy` 類型的文件必須使用結構描述 2.0 版本或更新版本。
+ `Automation` 類型的文件必須使用結構描述 0.3 版本。
+ `Session` 類型的文件必須使用結構描述 1.0 版本。
+ 您可以以 JSON 或 YAML 建立文件。
如需有關`Session`文件結構描述的詳細資訊，請參閱[工作階段文件結構描述](session-manager-schema.md)。
`Command` 和 `Policy` 文件使用最新的結構描述版本，您可以善用以下功能。
**結構描述版本 2.2 文件的功能**
| 功能 | 詳細資訊 |
| --- | --- |
| 文件編輯 | 文件現在可以進行更新。在版本 1.2 中，您需要將文件中任何更新儲存為不同名稱的文件。 |
| 自動版本控制 | 文件中任何更新建立新的版本。這並非結構描述的版本，而是文件的版本。 |
| 預設版本 | 如果您有多個版本的文件，您可以指定哪個版本為預設的文件。 |
| 定序 | 文件中中的外掛程式或*步驟*將按照您所指定的順序執行。 |
| 跨平台支援 | 跨平台支援允許您在相同的 SSM 文件中為不同的外掛程式指定不同的作業系統。跨平台支援使用 `precondition` 參數，只需要幾個步驟。 |
| 參數插補 | 插補表示將變數值插入或替換為字串。將其視為在使用字串前，使用實際值填入空格。在 SSM 文件環境中，參數插補允許字串參數在命令執行之前，插入到環境變數中，提供更高安全性以防止命令注入。設定為 `ENV_VAR` 時，Agent 會建立名為 `SSM_parameter-name` 的環境變數，其中包含參數的值。 |
**注意**
您必須將執行個體上的 AWS Systems Manager SSM Agent 更新為最新版本，才能使用新的 Systems Manager 功能和 SSM 文件功能。如需詳細資訊，請參閱[使用 Run Command 更新 SSM Agent](run-command-tutorial-update-software.md#rc-console-agentexample)。
下表列出了主要的結構描述各版本的差異。
****
| 第 1.2 版 | 版本 2.2 (最新版本) | 詳細資訊 |
| --- | --- | --- |
| runtimeConfig | mainSteps | 在版本 2.2 中，`mainSteps` 區塊取代了 `runtimeConfig`。`mainSteps` 區段可讓 Systems Manager 按順序執行步驟。 |
| 屬性 | inputs | 在版本 2.2 中，`inputs` 區塊取代了 `properties` 區塊。`inputs` 區塊接受了參數的做法步驟。 |
| commands | runCommand | 在版本 2.2 中，`inputs` 區塊接受 `runCommand` 的參數，而非 `commands` 的參數。 |
| id | 動作 | 在版本 2.2 中，`Action` 取代了 `ID`。這是名稱變更。 |
| 不適用 | name | 在版本 2.2 中，`name` 是一個任何使用者替步驟定義的名稱。 |
**使用 precondition 參數**
使用結構描述 2.2 版或更新版本，您可以使用 `precondition` 參數為每個外掛程式指定目標作業系統，或驗證您在 SSM 文件中定義的輸入參數。`precondition` 參數支援引用 SSM 文件的輸入參數，以及使用值 `Linux`、`MacOS` 以及 `Windows` 的 `platformType`。只支援 `StringEquals` 運算子。
對於文件使用結構描述版本 2.2 或更新版本，如果未指定 `precondition`，每個外掛程式是根據外掛程式的相容性來決定在作業系統執行或略過。與作業系統的外掛程式相容性會在 `precondition` 之前評估。對於文件使用結構描述 2.0 或更舊版本，不相容的外掛程式會產生錯誤。
例如，在結構描述版本 2.2 文件中，如果未指定 `precondition` 但有列出`aws:runShellScript` 外掛程式，則在 Linux 執行個體上會執行該步驟，但在 Windows Server 執行個體上會略過該步驟，因為 `aws:runShellScript` 與 Windows Server 執行個體不相容。但就結構描述版本 2.0 文件來說，如果您指定 `aws:runShellScript` 外掛程式，然後在 Windows Server 執行個體上執行該文件，則執行會失敗。您可以在本節稍後的 SSM 文件中查看先決條件參數範例。
## 結構描述版本 2.2
**頂層元素**
以下範例顯示使用結構描述版本 2.2 的 SSM 文件上層元素。
------
#### [ YAML ]
```
---
schemaVersion: "2.2"
description: A description of the document.
parameters:
parameter 1:
property 1: "value"
property 2: "value"
parameter 2:
property 1: "value"
property 2: "value"
mainSteps:
- action: Plugin name
name: A name for the step.
inputs:
input 1: "value"
input 2: "value"
input 3: "{{ parameter 1 }}"
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "A description of the document.",
"parameters": {
"parameter 1": {
"property 1": "value",
"property 2": "value"
},
"parameter 2":{
"property 1": "value",
"property 2": "value"
}
},
"mainSteps": [
{
"action": "Plugin name",
"name": "A name for the step.",
"inputs": {
"input 1": "value",
"input 2": "value",
"input 3": "{{ parameter 1 }}"
}
}
]
}
```
------
**結構描述版本 2.2 範例**
下列範例會使用 `aws:runPowerShellScript` 外掛程式在目標執行個體上執行 PowerShell 命令。
------
#### [ YAML ]
```
---
schemaVersion: "2.2"
description: "Example document"
parameters:
Message:
type: "String"
description: "Example parameter"
default: "Hello World"
allowedValues:
- "Hello World"
mainSteps:
- action: "aws:runPowerShellScript"
name: "example"
inputs:
timeoutSeconds: '60'
runCommand:
- "Write-Output {{Message}}"
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "Example document",
"parameters": {
"Message": {
"type": "String",
"description": "Example parameter",
"default": "Hello World",
"allowedValues": ["Hello World"]
}
},
"mainSteps": [
{
"action": "aws:runPowerShellScript",
"name": "example",
"inputs": {
"timeoutSeconds": "60",
"runCommand": [
"Write-Output {{Message}}"
]
}
}
]
}
```
------
**結構描述版本 2.2 precondition 參數範例**
結構描述版本 2.2 提供跨平台支援。這表示您可以在同一個 SSM 文件中為不同的外掛程式指定不同的作業系統。跨平台支援在步驟中使用 `precondition` 參數，如下所示。您也可以使用 `precondition` 參數來驗證您在 SSM 文件中定義的輸入參數。您可以在以下第二個範例中看到它。
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: cross-platform sample
mainSteps:
- action: aws:runPowerShellScript
name: PatchWindows
precondition:
StringEquals:
- platformType
- Windows
inputs:
runCommand:
- cmds
- action: aws:runShellScript
name: PatchLinux
precondition:
StringEquals:
- platformType
- Linux
inputs:
runCommand:
- cmds
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "cross-platform sample",
"mainSteps": [
{
"action": "aws:runPowerShellScript",
"name": "PatchWindows",
"precondition": {
"StringEquals": [
"platformType",
"Windows"
]
},
"inputs": {
"runCommand": [
"cmds"
]
}
},
{
"action": "aws:runShellScript",
"name": "PatchLinux",
"precondition": {
"StringEquals": [
"platformType",
"Linux"
]
},
"inputs": {
"runCommand": [
"cmds"
]
}
}
]
}
```
------
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
parameters:
action:
type: String
allowedValues:
- Install
- Uninstall
confirmed:
type: String
allowedValues:
- True
- False
mainSteps:
- action: aws:runShellScript
name: InstallAwsCLI
precondition:
StringEquals:
- "{{ action }}"
- "Install"
inputs:
runCommand:
- sudo apt install aws-cli
- action: aws:runShellScript
name: UninstallAwsCLI
precondition:
StringEquals:
- "{{ action }} {{ confirmed }}"
- "Uninstall True"
inputs:
runCommand:
- sudo apt remove aws-cli
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"parameters": {
"action": {
"type": "String",
"allowedValues": [
"Install",
"Uninstall"
]
},
"confirmed": {
"type": "String",
"allowedValues": [
true,
false
]
}
},
"mainSteps": [
{
"action": "aws:runShellScript",
"name": "InstallAwsCLI",
"precondition": {
"StringEquals": [
"{{ action }}",
"Install"
]
},
"inputs": {
"runCommand": [
"sudo apt install aws-cli"
]
}
},
{
"action": "aws:runShellScript",
"name": "UninstallAwsCLI",
"precondition": {
"StringEquals": [
"{{ action }} {{ confirmed }}",
"Uninstall True"
]
},
"inputs": {
"runCommand": [
"sudo apt remove aws-cli"
]
}
}
]
}
```
------
**具有 3.3.2746.0 之前 SSM Agent 版本的結構描述 2.2 版插補範例**
在 3.3.2746.0 之前的 SSM Agent 版本上，Agent 會忽略 `interpolationType` 參數，並改為執行原始字串替換。如果您明確參考 `SSM_parameter-name`，則必須明確設定此項目。在下列的 Linux 範例中，明確參考了 `SSM_Message` 環境變數。
```
{
"schemaVersion": "2.2",
"description": "An example document",
"parameters": {
"Message": {
"type": "String",
"description": "Message to be printed",
"default": "Hello",
"interpolationType" : "ENV_VAR",
"allowedPattern: "^[^"]*$"
}
},
"mainSteps": [{
"action": "aws:runShellScript",
"name": "printMessage",
"inputs": {
"runCommand": [
"if [ -z "${SSM_Message+x}" ]; then",
" export SSM_Message=\"{{Message}}\"",
"fi",
"",
"echo $SSM_Message"
]
}
}
}
```
**注意**
如果 SSM 文件不使用雙括號，則技術上不需要 `allowedPattern`：`{{ }}`
**結構描述版本 2.2 State Manager 範例**
您可以搭配使用以下 SSM 文件與 State Manager (Systems Manager 中的工具)，以下載並安裝 ClamAV 防毒軟體。State Manager 會強制實施特定組態，這表示每次執行 State Manager 關聯時，系統會檢查是否已安裝 ClamAV 軟體。如果不是，State Manager 會重新執行此文件。
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: State Manager Bootstrap Example
parameters: {}
mainSteps:
- action: aws:runShellScript
name: configureServer
inputs:
runCommand:
- sudo yum install -y httpd24
- sudo yum --enablerepo=epel install -y clamav
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "State Manager Bootstrap Example",
"parameters": {},
"mainSteps": [
{
"action": "aws:runShellScript",
"name": "configureServer",
"inputs": {
"runCommand": [
"sudo yum install -y httpd24",
"sudo yum --enablerepo=epel install -y clamav"
]
}
}
]
}
```
------
**結構描述版本 2.2 庫存範例**
您可以搭配使用以下 SSM 文件與 State Manager，收集有關執行個體的庫存中繼資料。
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: Software Inventory Policy Document.
parameters:
applications:
type: String
default: Enabled
description: "(Optional) Collect data for installed applications."
allowedValues:
- Enabled
- Disabled
awsComponents:
type: String
default: Enabled
description: "(Optional) Collect data for AWS Components like amazon-ssm-agent."
allowedValues:
- Enabled
- Disabled
networkConfig:
type: String
default: Enabled
description: "(Optional) Collect data for Network configurations."
allowedValues:
- Enabled
- Disabled
windowsUpdates:
type: String
default: Enabled
description: "(Optional) Collect data for all Windows Updates."
allowedValues:
- Enabled
- Disabled
instanceDetailedInformation:
type: String
default: Enabled
description: "(Optional) Collect additional information about the instance, including
the CPU model, speed, and the number of cores, to name a few."
allowedValues:
- Enabled
- Disabled
customInventory:
type: String
default: Enabled
description: "(Optional) Collect data for custom inventory."
allowedValues:
- Enabled
- Disabled
mainSteps:
- action: aws:softwareInventory
name: collectSoftwareInventoryItems
inputs:
applications: "{{ applications }}"
awsComponents: "{{ awsComponents }}"
networkConfig: "{{ networkConfig }}"
windowsUpdates: "{{ windowsUpdates }}"
instanceDetailedInformation: "{{ instanceDetailedInformation }}"
customInventory: "{{ customInventory }}"
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "Software Inventory Policy Document.",
"parameters": {
"applications": {
"type": "String",
"default": "Enabled",
"description": "(Optional) Collect data for installed applications.",
"allowedValues": [
"Enabled",
"Disabled"
]
},
"awsComponents": {
"type": "String",
"default": "Enabled",
"description": "(Optional) Collect data for AWS Components like amazon-ssm-agent.",
"allowedValues": [
"Enabled",
"Disabled"
]
},
"networkConfig": {
"type": "String",
"default": "Enabled",
"description": "(Optional) Collect data for Network configurations.",
"allowedValues": [
"Enabled",
"Disabled"
]
},
"windowsUpdates": {
"type": "String",
"default": "Enabled",
"description": "(Optional) Collect data for all Windows Updates.",
"allowedValues": [
"Enabled",
"Disabled"
]
},
"instanceDetailedInformation": {
"type": "String",
"default": "Enabled",
"description": "(Optional) Collect additional information about the instance, including\nthe CPU model, speed, and the number of cores, to name a few.",
"allowedValues": [
"Enabled",
"Disabled"
]
},
"customInventory": {
"type": "String",
"default": "Enabled",
"description": "(Optional) Collect data for custom inventory.",
"allowedValues": [
"Enabled",
"Disabled"
]
}
},
"mainSteps": [
{
"action": "aws:softwareInventory",
"name": "collectSoftwareInventoryItems",
"inputs": {
"applications": "{{ applications }}",
"awsComponents": "{{ awsComponents }}",
"networkConfig": "{{ networkConfig }}",
"windowsUpdates": "{{ windowsUpdates }}",
"instanceDetailedInformation": "{{ instanceDetailedInformation }}",
"customInventory": "{{ customInventory }}"
}
}
]
}
```
------
**結構描述版本 2.2 `AWS-ConfigureAWSPackage` 範例**
以下範例顯示 `AWS-ConfigureAWSPackage` 文件。`mainSteps` 區段包含 `action` 步驟中的 `aws:configurePackage` 外掛程式。
**注意**
在 Linux 作業系統上，只有支援 `AmazonCloudWatchAgent` 和 `AWSSupport-EC2Rescue` 的套件。
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: 'Install or uninstall the latest version or specified version of an AWS
package. Available packages include the following: AWSPVDriver, AwsEnaNetworkDriver,
AwsVssComponents, and AmazonCloudWatchAgent, and AWSSupport-EC2Rescue.'
parameters:
action:
description: "(Required) Specify whether or not to install or uninstall the package."
type: String
allowedValues:
- Install
- Uninstall
name:
description: "(Required) The package to install/uninstall."
type: String
allowedPattern: "^arn:[a-z0-9][-.a-z0-9]{0,62}:[a-z0-9][-.a-z0-9]{0,62}:([a-z0-9][-.a-z0-9]{0,62})?:([a-z0-9][-.a-z0-9]{0,62})?:package\\/[a-zA-Z][a-zA-Z0-9\\-_]{0,39}$|^[a-zA-Z][a-zA-Z0-9\\-_]{0,39}$"
version:
type: String
description: "(Optional) A specific version of the package to install or uninstall."
mainSteps:
- action: aws:configurePackage
name: configurePackage
inputs:
name: "{{ name }}"
action: "{{ action }}"
version: "{{ version }}"
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "Install or uninstall the latest version or specified version of an AWS package. Available packages include the following: AWSPVDriver, AwsEnaNetworkDriver, AwsVssComponents, and AmazonCloudWatchAgent, and AWSSupport-EC2Rescue.",
"parameters": {
"action": {
"description":"(Required) Specify whether or not to install or uninstall the package.",
"type":"String",
"allowedValues":[
"Install",
"Uninstall"
]
},
"name": {
"description": "(Required) The package to install/uninstall.",
"type": "String",
"allowedPattern": "^arn:[a-z0-9][-.a-z0-9]{0,62}:[a-z0-9][-.a-z0-9]{0,62}:([a-z0-9][-.a-z0-9]{0,62})?:([a-z0-9][-.a-z0-9]{0,62})?:package\\/[a-zA-Z][a-zA-Z0-9\\-_]{0,39}$|^[a-zA-Z][a-zA-Z0-9\\-_]{0,39}$"
},
"version": {
"type": "String",
"description": "(Optional) A specific version of the package to install or uninstall."
}
},
"mainSteps":[
{
"action": "aws:configurePackage",
"name": "configurePackage",
"inputs": {
"name": "{{ name }}",
"action": "{{ action }}",
"version": "{{ version }}"
}
}
]
}
```
------
## 結構描述版本 1.2
以下範例顯示結構描述版本 1.2 文件的上層元素。
```
{
"schemaVersion":"1.2",
"description":"A description of the SSM document.",
"parameters":{
"parameter 1":{
"one or more parameter properties"
},
"parameter 2":{
"one or more parameter properties"
},
"parameter 3":{
"one or more parameter properties"
}
},
"runtimeConfig":{
"plugin 1":{
"properties":[
{
"one or more plugin properties"
}
]
}
}
}
```
**結構描述版本 1.2 `aws:runShellScript` 範例**
以下範例顯示 `AWS-RunShellScript` SSM 文件。**runtimeConfig** 區段包含 `aws:runShellScript` 外掛程式。
```
{
"schemaVersion":"1.2",
"description":"Run a shell script or specify the commands to run.",
"parameters":{
"commands":{
"type":"StringList",
"description":"(Required) Specify a shell script or a command to run.",
"minItems":1,
"displayType":"textarea"
},
"workingDirectory":{
"type":"String",
"default":"",
"description":"(Optional) The path to the working directory on your instance.",
"maxChars":4096
},
"executionTimeout":{
"type":"String",
"default":"3600",
"description":"(Optional) The time in seconds for a command to complete before it is considered to have failed. Default is 3600 (1 hour). Maximum is 172800 (48 hours).",
"allowedPattern":"([1-9][0-9]{0,3})|(1[0-9]{1,4})|(2[0-7][0-9]{1,3})|(28[0-7][0-9]{1,2})|(28800)"
}
},
"runtimeConfig":{
"aws:runShellScript":{
"properties":[
{
"id":"0.aws:runShellScript",
"runCommand":"{{ commands }}",
"workingDirectory":"{{ workingDirectory }}",
"timeoutSeconds":"{{ executionTimeout }}"
}
]
}
}
}
```
## 結構描述版本 0.3
**頂層元素**
下列範例以 JSON 格式顯示結構描述 0.3 版 Automation Runbook 的最上層元素。
```
{
"description": "document-description",
"schemaVersion": "0.3",
"assumeRole": "{{assumeRole}}",
"parameters": {
"parameter1": {
"type": "String",
"description": "parameter-1-description",
"default": ""
},
"parameter2": {
"type": "String",
"description": "parameter-2-description",
"default": ""
}
},
"variables": {
"variable1": {
"type": "StringMap",
"description": "variable-1-description",
"default": {}
},
"variable2": {
"type": "String",
"description": "variable-2-description",
"default": "default-value"
}
},
"mainSteps": [
{
"name": "myStepName",
"action": "action-name",
"maxAttempts": 1,
"inputs": {
"Handler": "python-only-handler-name",
"Runtime": "runtime-name",
"Attachment": "script-or-zip-name"
},
"outputs": {
"Name": "output-name",
"Selector": "selector.value",
"Type": "data-type"
}
}
],
"files": {
"script-or-zip-name": {
"checksums": {
"sha256": "checksum"
},
"size": 1234
}
}
}
```
**YAML Automation Runbook 範例**
下列範例以 YAML 格式顯示 Automation Runbook 的內容。文件結構描述的這份 0.3 版運作範例，也示範了如何使用 Markdown 來格式化文件描述。
```
description: >-
##Title: LaunchInstanceAndCheckState
-----
**Purpose**: This Automation runbook first launches an EC2 instance
using the AMI ID provided in the parameter ```imageId```. The second step of
this document continuously checks the instance status check value for the
launched instance until the status ```ok``` is returned.
##Parameters:
-----
Name | Type | Description | Default Value
------------- | ------------- | ------------- | -------------
assumeRole | String | (Optional) The ARN of the role that allows Automation to
perform the actions on your behalf. | -
imageId | String | (Optional) The AMI ID to use for launching the instance.
The default value uses the latest Amazon Linux AMI ID available. | {{
ssm:/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-x86_64 }}
schemaVersion: '0.3'
assumeRole: 'arn:aws:iam::111122223333::role/AutomationServiceRole'
parameters:
imageId:
type: String
default: '{{ ssm:/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-x86_64 }}'
description: >-
(Optional) The AMI ID to use for launching the instance. The default value
uses the latest released Amazon Linux AMI ID.
tagValue:
type: String
default: ' LaunchedBySsmAutomation'
description: >-
(Optional) The tag value to add to the instance. The default value is
LaunchedBySsmAutomation.
instanceType:
type: String
default: t2.micro
description: >-
(Optional) The instance type to use for the instance. The default value is
t2.micro.
mainSteps:
- name: LaunchEc2Instance
action: 'aws:executeScript'
outputs:
- Name: payload
Selector: $.Payload
Type: StringMap
inputs:
Runtime: python3.11
Handler: launch_instance
Script: ''
InputPayload:
image_id: '{{ imageId }}'
tag_value: '{{ tagValue }}'
instance_type: '{{ instanceType }}'
Attachment: launch.py
description: >-
**About This Step**
This step first launches an EC2 instance using the ```aws:executeScript```
action and the provided python script.
- name: WaitForInstanceStatusOk
action: 'aws:executeScript'
inputs:
Runtime: python3.11
Handler: poll_instance
Script: |-
def poll_instance(events, context):
import boto3
import time
ec2 = boto3.client('ec2')
instance_id = events['InstanceId']
print('[INFO] Waiting for instance status check to report ok', instance_id)
instance_status = "null"
while True:
res = ec2.describe_instance_status(InstanceIds=[instance_id])
if len(res['InstanceStatuses']) == 0:
print("Instance status information is not available yet")
time.sleep(5)
continue
instance_status = res['InstanceStatuses'][0]['InstanceStatus']['Status']
print('[INFO] Polling to get status of the instance', instance_status)
if instance_status == 'ok':
break
time.sleep(10)
return {'Status': instance_status, 'InstanceId': instance_id}
InputPayload: '{{ LaunchEc2Instance.payload }}'
description: >-
**About This Step**
The python script continuously polls the instance status check value for
the instance launched in Step 1 until the ```ok``` status is returned.
files:
launch.py:
checksums:
sha256: 18871b1311b295c43d0f...[truncated]...772da97b67e99d84d342ef4aEXAMPLE
```
## 安全參數處理範例
下列範例示範使用環境變數 `interpolationType` 來安全處理參數。
### 基本安全命令執行
此範例說明如何安全地處理命令參數：
**注意**
在不使用雙括號的 SSM 文件中，技術上不需要 `allowedPattern`：`{{ }}`
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: An example document.
parameters:
Message:
type: String
description: "Message to be printed"
default: Hello
interpolationType: ENV_VAR
allowedPattern: "^[^"]*$"
mainSteps:
- action: aws:runShellScript
name: printMessage
precondition:
StringEquals:
- platformType
- Linux
inputs:
runCommand:
- echo {{Message}}
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "An example document.",
"parameters": {
"Message": {
"type": "String",
"description": "Message to be printed",
"default": "Hello",
"interpolationType": "ENV_VAR",
"allowedPattern": "^[^"]*$"
}
},
"mainSteps": [{
"action": "aws:runShellScript",
"name": "printMessage",
"precondition": {
"StringEquals": ["platformType", "Linux"]
},
"inputs": {
"runCommand": [
"echo {{Message}}"
]
}
}]
}
```
------
### 以編譯語言使用參數
此範例示範在 Python 中安全處理參數：
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: 'Secure Python script execution'
parameters:
inputData:
type: String
description: 'Input data for processing'
interpolationType: 'ENV_VAR'
mainSteps:
- action: aws:runPowerShellScript
name: runPython
inputs:
runCommand:
- |
python3 -c '
import os
import json
# Safely access parameter through environment variable
input_data = os.environ.get("SSM_inputData", "")
# Process the data
try:
processed_data = json.loads(input_data)
print(f"Successfully processed: {processed_data}")
except json.JSONDecodeError:
print("Invalid JSON input")
'
```
------
### 回溯相容性範例
此範例說明如何安全地處理參數，同時保持回溯相容性：
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: 'Backwards compatible secure parameter handling'
parameters:
userInput:
type: String
description: 'User input to process'
interpolationType: 'ENV_VAR'
allowedPattern: '^[^"]*$'
mainSteps:
- action: aws:runShellScript
name: processInput
inputs:
runCommand:
- |
# Handle both modern and legacy agent versions
if [ -z "${SSM_userInput+x}" ]; then
# Legacy agent - fall back to direct parameter reference
export SSM_userInput="{{userInput}}"
fi
# Process the input securely
echo "Processing input: $SSM_userInput"
```
------
**注意**
在不使用雙括號的 SSM 文件中，技術上不需要 `allowedPattern`：`{{ }}`
## 參數安全最佳實務
處理 SSM 文件中的參數時，請遵循下列最佳實務：
+ **使用環境變數插補** – 一律將 `interpolationType: "ENV_VAR"` 用於在命令執行中使用的字串參數。
+ **實作輸入驗證** – 使用 `allowedPattern`，將參數值限制為安全模式。
+ **處理舊式系統** – 包含不支援環境變數插補之舊版 SSM Agent 的備用邏輯。
+ **逸出特殊字元** – 在命令中使用參數值時，請正確逸出特殊字元，以防止 shell 解譯。
+ **限制參數範圍** – 為您的使用案例使用最嚴格的參數模式。
# 資料元素和參數
本主題描述 SSM 文件中使用的資料元素。用於建立文件的結構描述版本會定義文件接受的語法和資料元素。建議命令文件使用結構描述版本 2.2 或更新版本。Automation Runbook 使用結構描述版本 0.3。此外，Automation Runbook 支援使用 Markdown (一種標示語言)，可讓您新增維基樣式的描述至文件內，以及在文件內新增個別步驟。如需關於使用 Markdown 的詳細資訊，請參閱《AWS 管理主控台 入門指南》中的[在主控台中使用 Markdown](https://docs.aws.amazon.com/general/latest/gr/aws-markdown.html)。
下一節說明您可以在 SSM 文件中包含的資料元素。
## 頂層資料元素
**schemaVersion**
要使用的結構描述版本。
類型：版本
必要：是
**description**
您提供來描述文件用途的資訊。您也可以使用此欄位來指定參數是否需要執行文件的值，或者提供參數的值是否為選用項目。您可以在本主題的範例中看到必要參數和選用參數。
類型：字串
必要：否
**parameters**
一種結構，定義文件接受的參數。
為了在處理字串參數時增強安全性，您可以透過指定 `interpolationType` 屬性，使用環境變數插補。設定為 `ENV_VAR` 時，系統會建立名為 `SSM_parameter-name` 的環境變數，其中包含參數值。
以下包含使用環境變數 `interpolationType` 的參數範例：
```
{
"schemaVersion": "2.2",
"description": "An example document.",
"parameters": {
"Message": {
"type": "String",
"description": "Message to be printed",
"default": "Hello",
"interpolationType" : "ENV_VAR",
"allowedPattern": "^[^"]*$"
}
},
"mainSteps": [{
"action": "aws:runShellScript",
"name": "printMessage",
"precondition" : {
"StringEquals" : ["platformType", "Linux"]
},
"inputs": {
"runCommand": [
"echo {{Message}}"
]
}
}
}
```
在不使用雙括號的 SSM 文件中，技術上不需要 `allowedPattern`：`{{ }}`
對於常用的參數，建議您將這些參數存放在 Parameter Store ( AWS Systems Manager中的工具) 中。然後，您可以在文件中定義參考 Parameter Store 參數作為預設值的參數。若要參考 Parameter Store 參數，請使用下列語法。
```
{{ssm:parameter-name}}
```
您可以使用參考 Parameter Store 參數的參數，方式與任何其他文件參數相同。在下列範例中，`commands` 參數的預設值是 Parameter Store 參數 `myShellCommands`。透過將 `commands` 參數指定為 `runCommand` 字串，文件會執行在 `myShellCommands` 參數中儲存的命令。
```
---
schemaVersion: '2.2'
description: runShellScript with command strings stored as Parameter Store parameter
parameters:
commands:
type: StringList
description: "(Required) The commands to run on the instance."
default: ["{{ ssm:myShellCommands }}"],
interpolationType : 'ENV_VAR'
allowedPattern: '^[^"]*$'
mainSteps:
- action: aws:runShellScript
name: runShellScriptDefaultParams
inputs:
runCommand:"{{ commands }}"
```
```
{
"schemaVersion": "2.2",
"description": "runShellScript with command strings stored as Parameter Store parameter",
"parameters": {
"commands": {
"type": "StringList",
"description": "(Required) The commands to run on the instance.",
"default": ["{{ ssm:myShellCommands }}"],
"interpolationType" : "ENV_VAR"
}
},
"mainSteps": [
{
"action": "aws:runShellScript",
"name": "runShellScriptDefaultParams",
"inputs": {
"runCommand": [
"{{ commands }}"
]
}
}
]
}
```
您在文件的 `parameters` 部分可以參考 `String` 和 `StringList` Parameter Store 參數。您無法參考 `SecureString` Parameter Store 參數。
如需有關 Parameter Store 的詳細資訊，請參閱「[AWS Systems Manager Parameter Store](systems-manager-parameter-store.md)」。
類型：結構
`parameters` 結結構接受下列的欄位和數值：
+ `type`：(必要) 允許的值包括：`String`、`StringList`、`Integer`、`Boolean`、`MapList` 和 `StringMap`。若要查看每個類型的範例，在下一個部分請參閱 [SSM 文件參數 `type` 範例](#top-level-properties-type)。
**注意**
指令類型文件僅支援 `String` 和 `StringList` 參數類型。
+ `description`(選用) 參數說明。
+ `default`：(選擇性) 在 Parameter Store 中預設的參數值或參考值。
+ `allowedValues`：(選擇性) 參數允許的值陣列。定義參數的允許值會驗證使用者輸入。如果使用者輸入不允許的值，則無法開始執行。
------
#### [ YAML ]
```
DirectoryType:
type: String
description: "(Required) The directory type to launch."
default: AwsMad
allowedValues:
- AdConnector
- AwsMad
- SimpleAd
```
------
#### [ JSON ]
```
"DirectoryType": {
"type": "String",
"description": "(Required) The directory type to launch.",
"default": "AwsMad",
"allowedValues": [
"AdConnector",
"AwsMad",
"SimpleAd"
]
}
```
------
+ `allowedPattern`：(選擇性) 規則運算式，可驗證使用者輸入是否符合參數定義的模式。如果使用者輸入不符合允許的模式，則無法開始執行。
**注意**
Systems Manager 執行兩次 `allowedPattern` 驗證。當您使用文件時，在 API 層級使用 [Java regex 程式庫](https://docs.oracle.com/javase/8/docs/api/java/util/regex/package-summary.html)執行第一次驗證。在處理文件之前，藉由使用 [GO Regexp 程式庫](https://pkg.go.dev/regexp)，在 SSM Agent 上執行第二次驗證。
------
#### [ YAML ]
```
InstanceId:
type: String
description: "(Required) The instance ID to target."
allowedPattern: "^i-(?:[a-f0-9]{8}|[a-f0-9]{17})$"
default: ''
```
------
#### [ JSON ]
```
"InstanceId": {
"type": "String",
"description": "(Required) The instance ID to target.",
"allowedPattern": "^i-(?:[a-f0-9]{8}|[a-f0-9]{17})$",
"default": ""
}
```
------
+ `displayType`：（選用） 用來在 `textarea`中顯示 `textfield`或 AWS 管理主控台。 `textfield` 是單行文字方塊。 `textarea` 是多行文字區域。
+ `minItems`：(選擇性) 允許項目數量的最小值。
+ `maxItems`：(選擇性) 允許項目數量的最大值。
+ `minChars`：(選擇性) 允許參數字元數量的最小值。
+ `maxChars`：(選擇性) 允許參數字元數量的最大值。
+ `interpolationType`：(選用) 定義在命令執行之前如何處理參數值。設定為 `ENV_VAR` 時，參數值將作為名為 `SSM_parameter-name` 的環境變數。此功能將參數值視為常值字串，有助於防止命令注入。
類型：字串
有效值：`ENV_VAR`
必要：否
**variables**
(僅限結構描述版本 0.3) 您可以在 Automation 執行手冊中的整個步驟中參考或更新的值。變數類似於參數，但有一個非常重要的差異。參數值在執行手冊的內容中是靜態的，但變數的值可以在執行手冊的內容中進行變更。更新變數的值時，資料類型必須與定義的資料類型相符。如需有關在自動化操作中更新變數值的資訊，請參閱 [`aws:updateVariable` - 更新執行手冊變數的值](automation-action-update-variable.md)
類型：布林值 \$1 整數 \$1 MapList \$1 字串 \$1 StringList \$1 StringMap
必要：否
```
variables:
payload:
type: StringMap
default: "{}"
```
```
{
"variables": [
"payload": {
"type": "StringMap",
"default": "{}"
}
]
}
```
**runtimeConfig**
(結構描述 1.2 版) 一個或多個 Systems Manager 外掛程式套用的執行個體組態。不能保證外掛程式按順序執行。
類型：Dictionary
必要：否
**mainSteps**
(僅限結構描述版本 0.3、2.0 和 2.2) 可以包含多個步驟 (外掛程式) 的物件。外掛程式在步驟中定義。步驟會按文件中列出的順序執行。
類型：Dictionary
必要：是
**outputs**
(僅限結構描述版本 0.3) 執行此文件所產生的資料，可用於其他程序。例如，如果您的文件建立新 AMI，您可以將 "CreateImage.ImageId" 指定為輸出值，然後使用此輸出在後續自動化執行中建立新的執行個體。如需輸出的詳細資訊，請參閱 [使用動作輸出作為輸入](automation-action-outputs-inputs.md)。
類型：Dictionary
必要：否
**files**
(僅限結構描述 0.3) 連接至文件並在自動化執行期間執行的指令碼檔案 (及其檢查總和)。僅適用於包含 `aws:executeScript` 動作，以及已在一或多個步驟中指定附件的文件。
若要了解 Automation 執行手冊支援的執行時期，請參閱 [`aws:executeScript` – 執行指令碼](automation-action-executeScript.md)。如需有關在 Automation Runbook 中包含指令碼的詳細資訊，請參閱 [在執行手冊中使用指令碼](automation-document-script-considerations.md) 和 [Automation 執行手冊的視覺化設計體驗](automation-visual-designer.md)。
使用附件建立 Automation Runbook 時，您還必須使用 `--attachments` 選項 （適用於 AWS CLI) 或 `Attachments`（適用於 API 和 SDK) 指定附件檔案。您可以為存放在 Amazon Simple Storage Service (Amazon S3) 儲存貯體中的 SSM 文件和檔案指定檔案位置。如需詳細資訊，請參閱 AWS Systems Manager API 參考中的[附件](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreateDocument.html#systemsmanager-CreateDocument-request-Attachments)。
```
---
files:
launch.py:
checksums:
sha256: 18871b1311b295c43d0f...[truncated]...772da97b67e99d84d342ef4aEXAMPLE
```
```
"files": {
"launch.py": {
"checksums": {
"sha256": "18871b1311b295c43d0f...[truncated]...772da97b67e99d84d342ef4aEXAMPLE"
}
}
}
```
類型：Dictionary
必要：否
## SSM 文件參數 `type` 範例
SSM 文件中的參數類型是靜態的。這意味著參數類型在定義後便無法變更。將參數與 SSM 文件外掛程式搭配使用時，無法在外掛程式的輸入中動態變更參數的類型。例如，您無法在 `aws:runShellScript` 外掛程式的 `runCommand` 輸入中參考 `Integer` 參數，因為此輸入接受字串或字串清單。若要對外掛程式輸入使用參數，參數類型必須與接受的類型相符。例如，您必須為 `aws:updateSsmAgent` 外掛程式的 `allowDowngrade` 輸入指定 `Boolean` 類型參數。如果您的參數類型與外掛程式的輸入類型不相符，則 SSM 文件便無法驗證，且系統不會建立文件。在其他外掛程式或 AWS Systems Manager 自動化動作的輸入內使用下游參數時，也是如此。例如，您無法參考 `aws:runDocument` 外掛程式 `documentParameters` 輸入中的 `StringList` 參數。即使下游 SSM 文件參數類型是 `StringList` 參數且與您參考的參數相符，此 `documentParameters` 輸入仍會接受字串映射。
搭配使用參數與 自動化動作時，在大多數情況下建立 SSM 文件並不會驗證參數類型。只有當您使用 `aws:runCommand` 動作時，才會在您建立 SSM 文件時驗證參數類型。在所有其他情況下，則會在執行動作之前驗證動作的輸入之時，在自動化執行期間進行參數驗證。例如，如果您的輸入參數為 `String`，而您將其參考為 `aws:runInstances` 動作的 `MaxInstanceCount` 輸入的數值，則會建立 SSM 文件。不過，執行文件時，自動化會在驗證 `aws:runInstances` 動作時會失敗，因為 `MaxInstanceCount` 輸入需要 `Integer`.
以下是每個參數 `type` 的範例。
String
一連串零或多個 Unicode 字元以雙引號框住。例如，"i-1234567890abcdef0"。使用反斜線逸出。
字串參數可包含具有 `ENV_VAR` 值的選用 `interpolationType` 欄位，以啟用環境變數插補，進而提升安全性。
```
---
InstanceId:
type: String
description: "(Optional) The target EC2 instance ID."
interpolationType: ENV_VAR
```
```
"InstanceId":{
"type":"String",
"description":"(Optional) The target EC2 instance ID.",
"interpolationType": "ENV_VAR"
}
```
StringList
由逗號分隔的字串項目清單。例如，["cd 〜", "pwd"]。
```
---
commands:
type: StringList
description: "(Required) Specify a shell script or a command to run."
default: ""
minItems: 1
displayType: textarea
```
```
"commands":{
"type":"StringList",
"description":"(Required) Specify a shell script or a command to run.",
"minItems":1,
"displayType":"textarea"
}
```
Boolean
僅接受 `true` 或 `false`。不接受「true」或 0。
```
---
canRun:
type: Boolean
description: ''
default: true
```
```
"canRun": {
"type": "Boolean",
"description": "",
"default": true
}
```
Integer
整數號碼。不接受十進位小數，例如 3.14159 或以雙引號括住的號碼，例如 "3"。
```
---
timeout:
type: Integer
description: The type of action to perform.
default: 100
```
```
"timeout": {
"type": "Integer",
"description": "The type of action to perform.",
"default": 100
}
```
StringMap
金鑰與值的映射。金鑰和值必須是字串。例如，\$1"Env": "Prod"\$1。
```
---
notificationConfig:
type: StringMap
description: The configuration for events to be notified about
default:
NotificationType: 'Command'
NotificationEvents:
- 'Failed'
NotificationArn: "$dependency.topicArn"
maxChars: 150
```
```
"notificationConfig" : {
"type" : "StringMap",
"description" : "The configuration for events to be notified about",
"default" : {
"NotificationType" : "Command",
"NotificationEvents" : ["Failed"],
"NotificationArn" : "$dependency.topicArn"
},
"maxChars" : 150
}
```
MapList
StringMap 物件清單。
```
blockDeviceMappings:
type: MapList
description: The mappings for the create image inputs
default:
- DeviceName: "/dev/sda1"
Ebs:
VolumeSize: "50"
- DeviceName: "/dev/sdm"
Ebs:
VolumeSize: "100"
maxItems: 2
```
```
"blockDeviceMappings":{
"type":"MapList",
"description":"The mappings for the create image inputs",
"default":[
{
"DeviceName":"/dev/sda1",
"Ebs":{
"VolumeSize":"50"
}
},
{
"DeviceName":"/dev/sdm",
"Ebs":{
"VolumeSize":"100"
}
}
],
"maxItems":2
}
```
## 檢視 SSM 命令文件內容
若要預覽 AWS Systems Manager (SSM) 命令文件的必要和選用參數，除了文件執行的動作之外，您還可以在 Systems Manager 主控台中檢視文件的內容。
**若要檢視 SSM 命令文件內容**
1. 在 https：//[https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/) 開啟 AWS Systems Manager 主控台。
1. 在導覽窗格中，選擇 **Documents (文件)**。
1. 在搜尋方塊中，選取 **Document type** (文件類型)，然後選取 **Command** (命令)。
1. 選擇文件名稱，然後選擇 ** Content** (內容) 標籤。
1. 在內容欄位中，檢閱文件的可用參數和動作步驟。
例如，下圖顯示 (1) `version` 與 (2) `allowDowngrade` 是 `AWS-UpdateSSMAgent` 文件的可選參數，並且文件執行的第一個操作是 (3) `aws:updateSsmAgent`。
![\[在 Systems Manager 主控台中檢視 SSM 文件內容\]](http://docs.aws.amazon.com/zh_tw/systems-manager/latest/userguide/images/view-document-content.png)
# 命令文件外掛程式參考
此參考說明您可以在 AWS Systems Manager (SSM) 命令類型文件中指定的外掛程式。這些外掛程式無法在使用 Automation 動作時用於 SSM Automation Runbook。如需 AWS Systems Manager 自動化動作的詳細資訊，請參閱 [Systems Manager Automation 動作參考](automation-actions.md)。
Systems Manager 會讀取 SSM 文件的內容，以決定在受管執行個體上執行的動作。每個文件包含程式碼執行部分。根據您文件的結構描述版本，這個程式碼執行部分可以包含一或多個外掛程式或步驟。有關於此的說明主題，外掛程式和步驟稱為 *外掛程式*。本節包含關於每個 Systems Manager 外掛程式的資訊。如需有關文件，包含建立文件和結構描述版本之間差異的更多資訊，請參閱 [AWS Systems Manager Documents](documents.md)。
對於接受字串參數的外掛程式 (例如 `aws:runShellScript` 和 `aws:runPowerShellScript`)，`interpolationType` 參數可以透過將參數輸入視為字串常值，而非潛在的可執行命令，來增強安全性。例如：
```
{
"schemaVersion": "2.2",
"description": "runShellScript with command strings stored as Parameter Store parameter",
"parameters": {
"commands": {
"type": "StringList",
"description": "(Required) The commands to run on the instance.",
"default": ["{{ ssm:myShellCommands }}"],
"interpolationType" : "ENV_VAR"
}
},
//truncated
}
```
**注意**
此處說明的一些外掛程式僅能夠在 Windows Server 執行個體或 Linux 執行個體上執行。每個外掛程式須注意平台相容性。
macOS 的 Amazon Elastic Compute Cloud (Amazon EC2) 執行個體支援下列文件外掛程式：
`aws:refreshAssociation`
`aws:runShellScript`
`aws:runPowerShellScript`
`aws:softwareInventory`
`aws:updateSsmAgent`
**Topics**
+ [共用的輸入](#shared-inputs)
+ [`aws:applications`](#aws-applications)
+ [`aws:cloudWatch`](#aws-cloudWatch)
+ [`aws:configureDocker`](#aws-configuredocker)
+ [`aws:configurePackage`](#aws-configurepackage)
+ [`aws:domainJoin`](#aws-domainJoin)
+ [`aws:downloadContent`](#aws-downloadContent)
+ [`aws:psModule`](#aws-psModule)
+ [`aws:refreshAssociation`](#aws-refreshassociation)
+ [`aws:runDockerAction`](#aws-rundockeraction)
+ [`aws:runDocument`](#aws-rundocument)
+ [`aws:runPowerShellScript`](#aws-runPowerShellScript)
+ [`aws:runShellScript`](#aws-runShellScript)
+ [`aws:softwareInventory`](#aws-softwareinventory)
+ [`aws:updateAgent`](#aws-updateagent)
+ [`aws:updateSsmAgent`](#aws-updatessmagent)
## 共用的輸入
透過 SSM Agent 3.0.502 版及更新版本，所有外掛程式都可使用以下輸入：
**finallyStep**
您想要文件執行的最後一個步驟。如果對步驟定義了此輸入，則它的優先順序高於在 `onFailure` 或 `onSuccess` 輸入中指定的 `exit` 值。若要讓具有此輸入的步驟預期執行，該步驟必須是在文件的 `mainSteps` 中定義的最後一步。
類型：布林值
有效值：`true` \$1 `false`
必要：否
**onFailure**
如果您為具有 `exit` 值的外掛程式指定此輸入，且該步驟失敗，則步驟狀態會反映失敗，而且文件不會執行任何剩餘的步驟，除非已定義 `finallyStep`。如果您為具有 `successAndExit` 值的外掛程式指定此輸入，且該步驟失敗，則步驟狀態會顯示成功，而且文件不會執行任何剩餘的步驟，除非已定義 `finallyStep`。
類型：字串
有效值：`exit` \$1 `successAndExit`
必要：否
**onSuccess**
如果您為外掛程式指定此輸入，且該步驟成功執行，則文件不會執行任何剩餘的步驟，除非已定義 `finallyStep`。
類型：字串
有效值：`exit`
必要：否
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: Shared inputs example
parameters:
customDocumentParameter:
type: String
description: Example parameter for a custom Command-type document.
mainSteps:
- action: aws:runDocument
name: runCustomConfiguration
inputs:
documentType: SSMDocument
documentPath: "yourCustomDocument"
documentParameters: '"documentParameter":{{customDocumentParameter}}'
onSuccess: exit
- action: aws:runDocument
name: ifConfigurationFailure
inputs:
documentType: SSMDocument
documentPath: "yourCustomRepairDocument"
onFailure: exit
- action: aws:runDocument
name: finalConfiguration
inputs:
documentType: SSMDocument
documentPath: "yourCustomFinalDocument"
finallyStep: true
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "Shared inputs example",
"parameters": {
"customDocumentParameter": {
"type": "String",
"description": "Example parameter for a custom Command-type document."
}
},
"mainSteps":[
{
"action": "aws:runDocument",
"name": "runCustomConfiguration",
"inputs": {
"documentType": "SSMDocument",
"documentPath": "yourCustomDocument",
"documentParameters": "\"documentParameter\":{{customDocumentParameter}}",
"onSuccess": "exit"
}
},
{
"action": "aws:runDocument",
"name": "ifConfigurationFailure",
"inputs": {
"documentType": "SSMDocument",
"documentPath": "yourCustomRepairDocument",
"onFailure": "exit"
}
},
{
"action": "aws:runDocument",
"name":"finalConfiguration",
"inputs": {
"documentType": "SSMDocument",
"documentPath": "yourCustomFinalDocument",
"finallyStep": true
}
}
]
}
```
------
## `aws:applications`
安裝、修復或解除安裝在 EC2 執行個體上的應用程式。這個外掛程式只能在 Windows Server 作業系統上執行。
### 語法
#### 結構描述 2.2
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: aws:applications plugin
parameters:
source:
description: "(Required) Source of msi."
type: String
mainSteps:
- action: aws:applications
name: example
inputs:
action: Install
source: "{{ source }}"
```
------
#### [ JSON ]
```
{
"schemaVersion":"2.2",
"description":"aws:applications",
"parameters":{
"source":{
"description":"(Required) Source of msi.",
"type":"String"
}
},
"mainSteps":[
{
"action":"aws:applications",
"name":"example",
"inputs":{
"action":"Install",
"source":"{{ source }}"
}
}
]
}
```
------
#### 結構描述 1.2
------
#### [ YAML ]
```
---
runtimeConfig:
aws:applications:
properties:
- id: 0.aws:applications
action: "{{ action }}"
parameters: "{{ parameters }}"
source: "{{ source }}"
sourceHash: "{{ sourceHash }}"
```
------
#### [ JSON ]
```
{
"runtimeConfig":{
"aws:applications":{
"properties":[
{
"id":"0.aws:applications",
"action":"{{ action }}",
"parameters":"{{ parameters }}",
"source":"{{ source }}",
"sourceHash":"{{ sourceHash }}"
}
]
}
}
}
```
------
### Properties
**動作**
採取動作
類型：列舉
有效值：`Install` \$1 `Repair` \$1 `Uninstall`
必要：是
**parameters**
安裝的參數。
類型：字串
必要：否
**source**
應用程式的 `.msi` 檔案 URL。
類型：字串
必要：是
**sourceHash**
`.msi` 檔案的 SHA256 雜湊。
類型：字串
必要：否
## `aws:cloudWatch`
將資料從 Windows Server 匯出到 Amazon CloudWatch 或 Amazon CloudWatch Logs，並使用 CloudWatch 指標監控資料。這個外掛程式只能在 Windows Server 作業系統上執行。如需有關設定 CloudWatch 與 Amazon Elastic Compute Cloud (Amazon EC2) 整合的詳細資訊，請參閱《Amazon CloudWatch 使用者指南》**中的 [Collecting metrics, logs, and traces with the CloudWatch agent](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html)。
**重要**
統一的 CloudWatch 代理程式已取代 SSM Agent 作為將日誌資料傳送至 Amazon CloudWatch Logs 的工具。不支援 SSM Agent aws:cloudWatch 插件。建議只使用統一的 CloudWatch 代理程式來執行日誌收集流程。如需詳細資訊，請參閱下列主題：
[將節點日誌傳送至統一 CloudWatch Logs (CloudWatch 代理程式)](monitoring-cloudwatch-agent.md)
[將 Windows Server 節點日誌收集遷移到 CloudWatch 代理程式](monitoring-cloudwatch-agent.md#monitoring-cloudwatch-agent-migrate)
《Amazon CloudWatch 使用者指南》**中的 [Collecting metrics, logs, and traces with the CloudWatch agent](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html)。
您可以匯出和監控以下資料類型：
**ApplicationEventLog**
將應用程式事件日誌資料傳送至 CloudWatch Logs。
**CustomLogs**
將任何文字類日誌檔案傳送至 Amazon CloudWatch Logs。CloudWatch 外掛程式為日誌檔案建立指紋。系統會將資料位移與每個指紋建立關聯。當檔案改變時，外掛程式上傳檔案並記錄位移然後建立與指紋的關聯。此方法用於避免使用者開啟外掛程式，將服務與包含大量檔案的目錄關聯，並且系統會上傳所有檔案。
請注意，如果您的應用程式在輪詢時嘗試截斷或清理日誌的任何日誌，任何 `LogDirectoryPath` 指定的日誌將可能遺失項目。例如，如果您想要限制的日誌檔案大小，達到該限制時建立新的日誌檔，然後持續將資料寫入新的檔案。
**ETW**
將 Event Tracing for Windows (ETW) 資料傳送到 CloudWatch Logs。
**IIS**
將 IIS 日誌資料傳送到 CloudWatch Logs。
**PerformanceCounter**
將 Windows 效能計數器傳送到 CloudWatch。您可以選擇不同類別以作為指標上傳至 CloudWatch。對於每個您要上傳的效能計數器，建立一個 **PerformanceCounter** 部分具有唯一的 ID (例如，「PerformanceCounter2」、」 PerformanceCounter3」等) 和屬性設定。
如果 AWS Systems Manager SSM Agent或 CloudWatch 外掛程式停止，效能計數器資料不會記錄在 CloudWatch 中。此行為不同於自訂日誌或 Windows 事件日誌。自訂日誌和 Windows 事件日誌會保留效能計數器資料，並且在 SSM Agent 或 CloudWatch 外掛程式能夠使用之後，將這些資料上傳到 CloudWatch。
**SecurityEventLog**
將安全性日誌資料傳送至 CloudWatch Logs。
**SystemEventLog**
將系統事件日誌資料傳送至 CloudWatch Logs。
您可以定義以下資料的目的地：
**CloudWatch**
傳送您的效能計數器指標資料的目的地。您可以用唯一的 ID 增加多個區段 (例如「CloudWatch2」和「CloudWatch3」)，並替不同的區域指定新的 ID 然後傳遞相同的資料到不同的地點。
**CloudWatchLogs**
傳送您的效能計數器日誌資料的目的地。您可以用唯一的 ID 增加多個區段 (例如「CloudWatchLogs2」和「CloudWatchLogs3」)，並替不同的區域指定新的 ID 然後傳遞相同的資料到不同的地點。
### 語法
```
"runtimeConfig":{
"aws:cloudWatch":{
"settings":{
"startType":"{{ status }}"
},
"properties":"{{ properties }}"
}
}
```
### 設定和屬性
**AccessKey**
您的 存取金鑰 ID。此屬性是必要的，除非您使用 IAM 角色啟動執行個體。此屬性無法用於 SSM。
類型：字串
必要：否
**CategoryName**
效能監控從效能計數器類別而來。
類型：字串
必要：是
**CounterName**
效能監控的名稱從效能計數器類別而來。
類型：字串
必要：是
**CultureName**
要記錄時間戳記的所在地區。如果 **CultureName** 為空白，它會預設為 Windows Server 執行個體使用的相同地區設定。
類型：字串
有效的數值: 支援數值的清單，請參閱 Microsoft 網頁中的 [National Language Support (NLS) (國家語言支援 (NLS) 參考)](https://msdn.microsoft.com/en-us/library/cc233982.aspx)。不支援 **div**、**div-MV**、**hu** 和 **hu-HU** 值。
必要：否
**DimensionName**
Amazon CloudWatch 指標的維度。若您指定 `DimensionName`，您必須指定 `DimensionValue`。在列出指標時，這些參數會提供另一種視圖。您也可以針對多個指標使用同一種維度，如此就能檢視屬於特定維度的所有指標。
類型：字串
必要：否
**DimensionValue**
Amazon CloudWatch 指標的維度值。
類型：字串
必要：否
**編碼**
使用的檔案編碼 (例如，UTF-8)。使用編碼名稱，而非顯示名稱。
類型：字串
有效數值: 如需支援值的清單，請參閱 Microsoft Learn Library 中的[編碼類別](https://learn.microsoft.com/en-us/dotnet/api/system.text.encoding?view=net-7.0)。
必要：是
**篩選條件**
日誌名稱的字首。將此參數留白，以監控所有檔案。
類型：字串
有效數值: 如需支援值的清單，請參閱 [ MSDN 上的 FileSystemWatcherFilter 屬性](http://msdn.microsoft.com/en-us/library/system.io.filesystemwatcher.filter.aspx)主題。
必要：否
**流程**
要上傳的每個資料類型，以及資料目的地 (CloudWatch 或 CloudWatch Logs)。例如，若要將在 `"Id": "PerformanceCounter"` 下定義的效能計數器傳送至在 `"Id": "CloudWatch"` 下定義的 CloudWatch 目的地，請輸入 **"PerformanceCounter,CloudWatch"**。同樣，若要將自訂日誌、ETW 日誌和系統日誌傳送至在 `"Id": "ETW"` 下定義的 CloudWatch Logs 目的地，請輸入 **"(ETW),CloudWatchLogs"**。除此之外，您可以將相同的效能計數器或日誌檔案傳送到一個以上的目的地。例如，如果要將應用程式日誌傳送到您在 `"Id": "CloudWatchLogs"` 和 `"Id": "CloudWatchLogs2"` 區段中所定義的兩個不同目的地，輸入 **"ApplicationEventLog,(CloudWatchLogs, CloudWatchLogs2)"**。
類型：字串
有效數值 (來源): `ApplicationEventLog` \$1 `CustomLogs` \$1 `ETW` \$1 `PerformanceCounter` \$1 `SystemEventLog` \$1 `SecurityEventLog`
有效值 (目的地)：`CloudWatch` \$1 `CloudWatchLogs` \$1 `CloudWatch`*n* \$1 `CloudWatchLogs`*n*
必要：是
**FullName**
元件的完全名稱。
類型：字串
必要：是
**Id**
識別資料來源或目的地。這識別符在組態檔案中必須是唯一的。
類型：字串
必要：是
**InstanceName**
效能計數器執行個體的名稱。請勿使用星號 (\$1) 來表示所有的執行個體，因為每個效能計數器元件只支援一個指標。不過您可以使用 **\$1Total**。
類型：字串
必要：是
**層級**
要傳送至 Amazon CloudWatch 的訊息類型。
類型：字串
有效值：
+ **1** – 只上傳錯誤訊息。
+ **2** – 只上傳警告訊息。
+ **4** – 只上傳資訊訊息。
您可以一起新增值，以包含多個類型訊息。例如，**3** 表示錯誤訊息 (**1**) 和警告訊息 (**2**)都包含。數值 **7** 表示包含錯誤訊息 (**1**)、警告訊息 (**2**) 和資訊訊息 (**4**)。
必要：是
Windows Security Logs 應該設定層級為 7。
**LineCount**
標頭中的行數，以辨識日誌檔案。例如，IIS 日誌檔幾乎都具有相同的標頭。您可以輸入 **3**，這會讀取日誌檔標頭的前三行來進行辨識。在 IIS 日誌檔中，第三行是日期和時間戳記，這在不同的日誌檔中是不一樣的。
類型：整數
必要：否
**LogDirectoryPath**
對於 CustomLogs，此屬性是指 EC2 執行個體上存放日誌的路徑。對於 IIS 日誌，資料夾替個別的網站存放 IIS 日誌 (例如，**C:\$1\$1inetpub\$1\$1logs\$1\$1LogFiles\$1\$1W3SVC*n***)。IIS 日誌只支援 W3C 日誌格式。不支援 IIS、NCSA 和自訂格式。
類型：字串
必要：是
**LogGroup**
您的日誌群組名稱。CloudWatch 主控台的 **Log Groups** (日誌群組) 畫面中會顯示此名稱。
類型：字串
必要：是
**LogName**
日誌檔案的名稱。
1. 若要在導覽窗格的事件檢視器中查找日誌名稱，請選取 **Applications and Services Logs** (應用程式和服務日誌)。
1. 在日誌清單中，在您要上傳的日誌上按一下滑鼠右鍵 (例如 `Microsoft` > `Windows` > `Backup` > `Operational`)，然後選取**建立自訂檢視**。
1. 在 **Create Custom View** (建立自訂檢視) 對話方塊中，選取 **XML** 標籤。**LogName** 位於 < 選取途徑 => 標籤 (例如，`Microsoft-Windows-Backup`)。複製此文字到 **LogName** 參數。
類型：字串
有效值：`Application` \$1 `Security` \$1 `System` \$1 `Microsoft-Windows-WinINet/Analytic`
必要：是
**LogStream**
日誌串流目的地的名稱 若您使用 **\$1instance\$1id\$1**，日誌串流名稱是這個執行個體 ID 的預設值。
類型：字串
有效值：`{instance_id}` \$1 `{hostname}` \$1 `{ip_address}` **
如果輸入的日誌串流名稱尚未存在，CloudWatch Logs 會自動為您建立。您可以使用文字字串或預先定義的變數 (**\$1instance\$1id\$1**, **\$1hostname\$1**, **\$1ip\$1address\$1**，或是組合全部三者來定義日誌串流名稱。
此參數中指定的日誌串流名稱會顯示在 CloudWatch 主控台的**Log Groups > Streams for **** (日誌群組 > YourLogStream 串流) 畫面中。
必要：是
**MetricName**
您希望能包含效能資料的 CloudWatch 指標。
請不要在名稱中使用特殊字元。如果您這麼做了、指標和相關警示可能不會運作。
類型：字串
必要：是
**NameSpace**
將會在指標命名空間寫入效能計數器資料。
類型：字串
必要：是
**PollInterval**
上傳新的效能計數器和日誌資料時需要延遲多少秒。
類型：整數
有效值：將此屬性設為 5 個或多個秒。十五秒 (00:00:15) 是建議。
必要：是
**區域**
您要傳送日誌資料的 AWS 區域 。雖然您可以將效能計數器，傳送到與您傳送日誌資料所在位置不同的區域，還是建議您將此參數，設定為與執行個體執行位置相同的區域。
類型：字串
有效值：Systems Manager 和 CloudWatch Logs AWS 區域 支援的 區域 IDs，例如 `us-east-2`、 `eu-west-1`和 `ap-southeast-1`。如需每個服務 AWS 區域 支援的 清單，請參閱《》中的 [Amazon CloudWatch Logs Service Endpoints](https://docs.aws.amazon.com/general/latest/gr/cwl_region.html#cwl_region) 和 [Systems Manager 服務端點](https://docs.aws.amazon.com/general/latest/gr/ssm.html#ssm_region)*Amazon Web Services 一般參考*。
必要：是
**SecretKey**
您的 私密存取金鑰。此屬性是必要的，除非您使用 IAM 角色啟動執行個體。
類型：字串
必要：否
**startType**
開啟或關閉執行個體上的 CloudWatch。
類型：字串
有效值：`Enabled` \$1 `Disabled`
必要：是
**TimestampFormat**
要使用的時間戳記格式。如需支援值的清單，請參閱 MSDN 上的[自訂日期和時間格式字串](http://msdn.microsoft.com/en-us/library/8kb3ddd4.aspx)主題。
類型：字串
必要：是
**TimeZoneKind**
當您的日誌時間戳記中沒有時區資訊時，您需要提供時區資訊。如果此參數保留空白，且如果您的時間戳記不包含時區資訊，則 CloudWatch Logs 預設為本機時區。如果時間戳記已包含時區資訊，則會忽略此參數。
類型：字串
有效值：`Local` \$1 `UTC`
必要：否
**單位**
適合指標的測量單位。
類型：字串
有效數值: 秒 \$1 微秒 \$1 毫秒 \$1 位元組 \$1 千位元組 (KB) \$1 百萬位元組 (MB) \$1 十億位元組 (GB) \$1 兆位元組 (TB) \$1 位元 \$1 千位元 (kb) \$1 百萬位元 (Mb) \$1 十億位元 (Gb) \$1 兆位元 (Tb) \$1 百分比 \$1 計數 \$1 位元組/秒 \$1 千位元組 (KB)/秒 \$1 百萬位元組 (MB)/秒 \$1 十億位元組 (GB)/秒 \$1 兆位元組 (TB)/秒 \$1 位元/秒 \$1 千位元 (kb)/ 秒 \$1 百萬位元 (Mb)/秒 \$1 十億位元 (Gb)/秒 \$1 兆位元 (Tb)/秒 \$1 計數/秒 \$1 無。
必要：是
## `aws:configureDocker`
(結構描述 2.0 版本或更新版本) 設定執行個體來處理 Docker 和容器。大部分 Linux 變體和 Windows Server 作業系統都支援此外掛程式。
### 語法
#### 結構描述 2.2
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: aws:configureDocker
parameters:
action:
description: "(Required) The type of action to perform."
type: String
default: Install
allowedValues:
- Install
- Uninstall
mainSteps:
- action: aws:configureDocker
name: configureDocker
inputs:
action: "{{ action }}"
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "aws:configureDocker plugin",
"parameters": {
"action": {
"description": "(Required) The type of action to perform.",
"type": "String",
"default": "Install",
"allowedValues": [
"Install",
"Uninstall"
]
}
},
"mainSteps": [
{
"action": "aws:configureDocker",
"name": "configureDocker",
"inputs": {
"action": "{{ action }}"
}
}
]
}
```
------
### 輸入
**動作**
執行動作的類型。
類型：列舉
有效值：`Install` \$1 `Uninstall`
必要：是
## `aws:configurePackage`
（結構描述 2.0 版或更新版本） 安裝或解除安裝 AWS Systems Manager Distributor套件。您可以安裝最新版本、預設版本或您指定的套件版本。也支援 AWS 提供的套件。這個外掛程式可在 Windows Server 和 Linux 作業系統上執行，但 Linux 作業系統不支援所有的可用套件。
的可用 AWS 套件Windows Server包括下列項目：`AWSPVDriver`、`AWSNVMe`、`AwsEnaNetworkDriver`、`AwsVssComponents`、`CodeDeployAgent`、 `AmazonCloudWatchAgent`和 `AWSSupport-EC2Rescue.`
Linux 作業系統的可用 AWS 套件包括下列項目：`CodeDeployAgent`、 `AmazonCloudWatchAgent`和 `AWSSupport-EC2Rescue`。
### 語法
#### 結構描述 2.2
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: aws:configurePackage
parameters:
name:
description: "(Required) The name of the AWS package to install or uninstall."
type: String
action:
description: "(Required) The type of action to perform."
type: String
default: Install
allowedValues:
- Install
- Uninstall
ssmParameter:
description: "(Required) Argument stored in Parameter Store."
type: String
default: "{{ ssm:parameter_store_arg }}"
mainSteps:
- action: aws:configurePackage
name: configurePackage
inputs:
name: "{{ name }}"
action: "{{ action }}"
additionalArguments:
"{\"SSM_parameter_store_arg\": \"{{ ssmParameter }}\", \"SSM_custom_arg\": \"myValue\"}"
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "aws:configurePackage",
"parameters": {
"name": {
"description": "(Required) The name of the AWS package to install or uninstall.",
"type": "String"
},
"action": {
"description": "(Required) The type of action to perform.",
"type": "String",
"default": "Install",
"allowedValues": [
"Install",
"Uninstall"
]
},
"ssmParameter": {
"description": "(Required) Argument stored in Parameter Store.",
"type": "String",
"default": "{{ ssm:parameter_store_arg }}"
}
},
"mainSteps": [
{
"action": "aws:configurePackage",
"name": "configurePackage",
"inputs": {
"name": "{{ name }}",
"action": "{{ action }}",
"additionalArguments": "{\"SSM_parameter_store_arg\": \"{{ ssmParameter }}\", \"SSM_custom_arg\": \"myValue\"}"
}
}
]
}
```
------
### 輸入
**name**
要安裝或解除安裝的 AWS 套件名稱。可用套件包括：`AWSPVDriver`、`AwsEnaNetworkDriver`、`AwsVssComponents` 和 `AmazonCloudWatchAgent`。
類型：字串
必要：是
**動作**
安裝或解除安裝套件
類型：列舉
有效值：`Install` \$1 `Uninstall`
必要：是
**installationType**
要執行的安裝類型。如果您指定 `Uninstall and reinstall`，套件會完全解除安裝，然後重新安裝。在重新安裝完成之前，應用程式無法使用。如果您指定 `In-place update`，根據您在更新指令碼中提供的指示，只會將新的或變更的檔案新增至現有的安裝。應用程式在整個更新程序中仍然可用。已發佈 AWS的套件不支援 `In-place update`選項。 `Uninstall and reinstall`是預設值。
類型：列舉
有效值：`Uninstall and reinstall` \$1 `In-place update`
必要：否
**additionalArguments**
提供給安裝、解除安裝或更新指令碼的 JSON 字串格式的其他參數。每個參數必須加上字首 `SSM_`。通過使用慣例 `{{ssm:parameter-name}}`，您可以參考其他引數中的 Parameter Store 參數。若要在安裝、解除安裝或更新指令碼中使用其他參數，您必須使用適用於作業系統的語法，將參數作為環境變數參考。例如，在 PowerShell 中，將 `SSM_arg` 引數作為 `$Env:SSM_arg` 參考。您定義的引數數目沒有限制，但額外的引數輸入有 4096 個字元限制。此限制包括您定義的所有金鑰和值。
類型：StringMap
必要：否
**version**
特定版本的套件安裝或解除安裝。如果安裝，系統預設會安裝最新發佈的版本。如果移除，系統預設移除目前已安裝的版本。如果沒有找到任何安裝的版本，執行下載和解除安裝最新版本的動作。
類型：字串
必要：否
## `aws:domainJoin`
將 EC2 執行個體加入網域。這個外掛程式可在 Linux 和 Windows Server 作業系統上執行。此外掛程式會將 Linux 執行個體的主機名稱變更為 EC2AMAZ-*XXXXXXX* 格式。如需加入 EC2 執行個體的詳細資訊，請參閱《 *AWS Directory Service 管理指南*》中的[將 EC2 執行個體加入您的 AWS Managed Microsoft AD Directory](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/ms_ad_join_instance.html)。
### 語法
#### 結構描述 2.2
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: aws:domainJoin
parameters:
directoryId:
description: "(Required) The ID of the directory."
type: String
directoryName:
description: "(Required) The name of the domain."
type: String
directoryOU:
description: "(Optional) The organizational unit to assign the computer object to."
type: String
dnsIpAddresses:
description: "(Required) The IP addresses of the DNS servers for your directory."
type: StringList
hostname:
description: "(Optional) The hostname you want to assign to the node."
type: String
mainSteps:
- action: aws:domainJoin
name: domainJoin
inputs:
directoryId: "{{ directoryId }}"
directoryName: "{{ directoryName }}"
directoryOU: "{{ directoryOU }}"
dnsIpAddresses: "{{ dnsIpAddresses }}"
hostname: "{{ hostname }}"
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "aws:domainJoin",
"parameters": {
"directoryId": {
"description": "(Required) The ID of the directory.",
"type": "String"
},
"directoryName": {
"description": "(Required) The name of the domain.",
"type": "String"
},
"directoryOU": {
"description": "(Optional) The organizational unit to assign the computer object to.",
"type": "String"
},
"dnsIpAddresses": {
"description": "(Required) The IP addresses of the DNS servers for your directory.",
"type": "StringList"
},
"hostname": {
"description": "(Optional) The hostname you want to assign to the node.",
"type": "String"
}
},
"mainSteps": [
{
"action": "aws:domainJoin",
"name": "domainJoin",
"inputs": {
"directoryId": "{{ directoryId }}",
"directoryName": "{{ directoryName }}",
"directoryOU":"{{ directoryOU }}",
"dnsIpAddresses":"{{ dnsIpAddresses }}",
"hostname":"{{ hostname }}"
}
}
]
}
```
------
#### 結構描述 1.2
------
#### [ YAML ]
```
---
runtimeConfig:
aws:domainJoin:
properties:
directoryId: "{{ directoryId }}"
directoryName: "{{ directoryName }}"
directoryOU: "{{ directoryOU }}"
dnsIpAddresses: "{{ dnsIpAddresses }}"
```
------
#### [ JSON ]
```
{
"runtimeConfig":{
"aws:domainJoin":{
"properties":{
"directoryId":"{{ directoryId }}",
"directoryName":"{{ directoryName }}",
"directoryOU":"{{ directoryOU }}",
"dnsIpAddresses":"{{ dnsIpAddresses }}"
}
}
}
}
```
------
### Properties
**directoryId**
目錄的 ID。
類型：字串
必要：是
範例："directoryId": "d-1234567890"
**directoryName**
網域的名稱。
類型：字串
必要：是
範例："directoryName": "example.com"
**directoryOU**
組織單位 (OU)。
類型：字串
必要：否
範例："directoryOU": "OU=test,DC=example,DC=com"
**dnsIpAddresses**
DNS 的 IP 地址。
類型：StringList
必要：是
範例："dnsIpAddresses": ["198.51.100.1","198.51.100.2"]
**hostname**
要指派給節點的主機名稱。如果未提供，則不會變更 Windows Server 執行個體的名稱，而 Linux 執行個體將使用預設命名模式。如果提供，Windows Server 執行個體將使用確切提供的值，而對於 Linux 執行個體，其作為字首 (除非 `keepHostName` 設定為 "true")。
類型：字串
必要：否
**keepHostName**
確定在加入網域時是否變更 Linux 執行個體的主機名稱。這是僅限 Linux 的參數。依預設 (沒有對 `hostname`、`hostnameNumAppendDigits` 的輸入，而且 `keepHostName` 為 "false")，Linux 主機將被重新命名為模式 EC2AMAZ-XXXXXX。設定為 "true" 時，主機會保留原始主機名稱，並忽略對 `hostname` 和 `hostnameNumAppendDigits` 的輸入。
類型：布林值
必要：否
**hostnameNumAppendDigits**
定義要在主機名稱值之後附加的隨機數字位數數量。這是僅限 Linux 的參數，並且可與 `hostname` 參數搭配使用。如果未提供 `hostname`，則會予以忽略。
類型：字串
允許的值：1 至 5
必要：否
### 範例
如需範例，請參閱[AWS Managed Microsoft AD管理指南](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/ec2-join-aws-domain.html)中的*將 Amazon EC2 執行個體加入您的AWS Directory Service *。
## `aws:downloadContent`
(結構描述 2.0 版本或更新版本) 從遠端位置下載 SSM 文件和指令碼。不支援 GitHub Enterprise 儲存庫。Linux 和 Windows Server 作業系統上支援此外掛程式。
### 語法
#### 結構描述 2.2
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: aws:downloadContent
parameters:
sourceType:
description: "(Required) The download source."
type: String
sourceInfo:
description: "(Required) The information required to retrieve the content from
the required source."
type: StringMap
mainSteps:
- action: aws:downloadContent
name: downloadContent
inputs:
sourceType: "{{ sourceType }}"
sourceInfo: "{{ sourceInfo }}"
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "aws:downloadContent",
"parameters": {
"sourceType": {
"description": "(Required) The download source.",
"type": "String"
},
"sourceInfo": {
"description": "(Required) The information required to retrieve the content from the required source.",
"type": "StringMap"
}
},
"mainSteps": [
{
"action": "aws:downloadContent",
"name": "downloadContent",
"inputs": {
"sourceType":"{{ sourceType }}",
"sourceInfo":"{{ sourceInfo }}"
}
}
]
}
```
------
### 輸入
**sourceType**
下載來源。Systems Manager 支援下列來源類型，用於下載指令碼和 SSM 文件：`GitHub`、`Git`、`HTTP`、`S3` 和 `SSMDocument`。
類型：字串
必要：是
**sourceInfo**
從所需的來源中擷取所需的資訊內容。
類型：StringMap
必要：是
**對於來源類型 `GitHub,`，請指定以下資訊：**
+ 擁有者：儲存庫擁有者。
+ 儲存庫: 儲存庫的名稱。
+ 路徑：您想要下載的檔案或目錄路徑。
+ getOptions：可從主要分支以外的分支或從儲存庫中的特定遞交中擷取內容的額外選項。如果您使用主要分支中的最新遞交，則可省略 getOptions。如果您的儲存庫是在 2020 年 10 月 1 日之後建立的，則預設分支可能被命名為 main 而不是 master。在此情況下，您需要指定 getOptions 參數的值。
此參數使用以下的格式：
+ branch:refs/heads/*branch\$1name*
預設值為 `master`。
若要指定非預設分支，請使用以下格式：
branch:refs/heads/*branch\$1name*
+ commitID：*commitID*
預設值為 `head`。
若要在最新遞交以外之其他遞交中使用您 SSM 文件的版本，請指定完整的遞交 ID。例如：
```
"getOptions": "commitID:bbc1ddb94...b76d3bEXAMPLE",
```
+ tokenInfo：您存放 GitHub 存取權杖資訊所在的 Systems Manager 參數 (SecureString 參數)，格式為 `{{ssm-secure:secure-string-token-name}}`。
**注意**
此 `tokenInfo` 欄位是唯一支援 SecureString 參數的 SSM 文件外掛程式欄位。其他欄位不支援 SecureString 參數，其他 SSM 文件外掛程式也不支援。
```
{
"owner":"TestUser",
"repository":"GitHubTest",
"path":"scripts/python/test-script",
"getOptions":"branch:master",
"tokenInfo":"{{ssm-secure:secure-string-token}}"
}
```
**對於來源類型 `Git`，您必須指定以下資訊：**
+ repository
您想要下載的檔案或目錄的 Git 存放庫 URL。
類型：字串
此外，您還可以指定下列選用參數：
+ getOptions
可從主要分支以外的分支或從儲存庫中的特定遞交中擷取內容的額外選項。如果您使用主要分支中的最新遞交，則可省略 getOptions。
類型：字串
此參數使用以下的格式：
+ branch:refs/heads/*branch\$1name*
預設值為 `master`。
只有當 SSM 文件存放於 `master` 以外的分支時，才需要 `"branch"`。例如：
```
"getOptions": "branch:refs/heads/main"
```
+ commitID：*commitID*
預設值為 `head`。
若要在最新遞交以外之其他遞交中使用您 SSM 文件的版本，請指定完整的遞交 ID。例如：
```
"getOptions": "commitID:bbc1ddb94...b76d3bEXAMPLE",
```
+ privateSSHKey
連線至您指定的 `repository` 時，要使用的 SSH 金鑰。您可以使用下列格式來參考 SSH 金鑰值的 `SecureString` 參數：`{{ssm-secure:your-secure-string-parameter}}`。
類型：字串
+ skipHostKeyChecking
連線至您指定的 `repository` 時，確定 StrictHostKeyChecking 選項的值。預設值為 `false`。
類型：布林值
+ 使用者名稱
使用 HTTP 連線至您指定的 `repository` 時，要使用的使用者名稱。您可以使用下列格式來參考使用者名稱值的 `SecureString` 參數：`{{ssm-secure:your-secure-string-parameter}}`。
類型：字串
+ password
使用 HTTP 連線至您指定的 `repository` 時，要使用的密碼。您可以使用下列格式來參考密碼值的 `SecureString` 參數：`{{ssm-secure:your-secure-string-parameter}}`。
類型：字串
**對於來源類型 `HTTP`，您必須指定以下資訊：**
+ url
您想要下載的檔案或目錄的 URL。
類型：字串
此外，您還可以指定下列選用參數：
+ allowInsecureDownload
判斷是否可透過未使用 Secure Socket Layer (SSL) 或 Transport Layer Security (TLS) 進行加密的連線來執行下載。預設值為 `false`。不建議在未加密的情況下執行下載。如果您選擇這樣做，您應承擔所有相關風險。安全性是 AWS 與您之間的共同責任。這被描述為共同的責任模式。如需進一步了解，請參閱[共同的責任模型](https://aws.amazon.com/compliance/shared-responsibility-model/)。
類型：布林值
+ authMethod
當連線至您指定的 `url` 時，判斷是否要使用使用者名稱和密碼進行身分驗證。如果您指定 `Basic` 或 `Digest`，則必須提供 `username` 和 `password` 參數的值。若要使用 `Digest` 方法，必須在您的執行個體上安裝 SSM Agent 3.0.1181.0 版或更新版本。`Digest` 方法支援 MD5 和 SHA256 加密。
類型：字串
有效值：`None` \$1 `Basic` \$1 `Digest`
+ 使用者名稱
使用 `Basic` 身分驗證連線至您指定的 `url` 時，要使用的使用者名稱。您可以使用下列格式來參考使用者名稱值的 `SecureString` 參數：`{{ssm-secure:your-secure-string-parameter}}`。
類型：字串
+ password
使用 `Basic` 身分驗證連線至您指定的 `url` 時，要使用的密碼。您可以使用下列格式來參考密碼值的 `SecureString` 參數：`{{ssm-secure:your-secure-string-parameter}}`。
類型：字串
**對於來源類型 `S3`，請指定以下資訊：**
+ 路徑：您想要從 Amazon S3 中下載的檔案或目錄的 URL。
從 S3 儲存貯體下載檔案時，.etag 檔案會在下載目錄中產生。
```
{
"path": "https://s3.amazonaws.com/amzn-s3-demo-bucket/powershell/helloPowershell.ps1"
}
```
**對於來源類型 `SSMDocument`，請指定下列其中*一項*：**
+ 名稱：名稱和文件的版本，格式如下：`name:version`。版本是非必須的。
```
{
"name": "Example-RunPowerShellScript:3"
}
```
+ 名稱：文件的 ARN，格式如下：`arn:aws:ssm:region:account_id:document/document_name`
```
{
"name":"arn:aws:ssm:us-east-2:3344556677:document/MySharedDoc"
}
```
**destinationPath**
將您想要下載的檔案選用在的執行個體上的本機路徑。如果您不指定路徑的相對路徑，內容會下載到您的命令 ID 相對應的路徑。
類型：字串
必要：否
## `aws:psModule`
在 Amazon EC2 執行個體上安裝 PowerShell 模組。這個外掛程式只能在 Windows Server 作業系統上執行。
### 語法
#### 結構描述 2.2
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: aws:psModule
parameters:
source:
description: "(Required) The URL or local path on the instance to the application
.zip file."
type: String
mainSteps:
- action: aws:psModule
name: psModule
inputs:
source: "{{ source }}"
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "aws:psModule",
"parameters": {
"source": {
"description": "(Required) The URL or local path on the instance to the application .zip file.",
"type": "String"
}
},
"mainSteps": [
{
"action": "aws:psModule",
"name": "psModule",
"inputs": {
"source": "{{ source }}"
}
}
]
}
```
------
#### 結構描述 1.2
------
#### [ YAML ]
```
---
runtimeConfig:
aws:psModule:
properties:
- runCommand: "{{ commands }}"
source: "{{ source }}"
sourceHash: "{{ sourceHash }}"
workingDirectory: "{{ workingDirectory }}"
timeoutSeconds: "{{ executionTimeout }}"
```
------
#### [ JSON ]
```
{
"runtimeConfig":{
"aws:psModule":{
"properties":[
{
"runCommand":"{{ commands }}",
"source":"{{ source }}",
"sourceHash":"{{ sourceHash }}",
"workingDirectory":"{{ workingDirectory }}",
"timeoutSeconds":"{{ executionTimeout }}"
}
]
}
}
}
```
------
### Properties
**runCommand**
在模組安裝完畢後，PowerShell 的命令來執行。
類型：StringList
必要：否
**source**
在的執行個體上應用程式 `.zip` 檔案的本機路徑或 URL。
類型：字串
必要：是
**sourceHash**
`.zip` 檔案的 SHA256 雜湊。
類型：字串
必要：否
**timeoutSeconds**
在命令完成到被認定為失敗之間的秒數。
類型：字串
必要：否
**workingDirectory**
在您的執行個體上的工作目錄路徑。
類型：字串
必要：否
## `aws:refreshAssociation`
(結構描述 2.0 版本或更新版本) 更新 (強制套用) 有需要的關聯。這個動作會根據選中的關聯或者全部與目標有聯結的關聯裡的定義來改變系統的狀態。這個外掛程式可在 Linux 和 Microsoft Windows Server 作業系統上執行。
### 語法
#### 結構描述 2.2
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: aws:refreshAssociation
parameters:
associationIds:
description: "(Optional) List of association IDs. If empty, all associations bound
to the specified target are applied."
type: StringList
mainSteps:
- action: aws:refreshAssociation
name: refreshAssociation
inputs:
associationIds:
- "{{ associationIds }}"
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "aws:refreshAssociation",
"parameters": {
"associationIds": {
"description": "(Optional) List of association IDs. If empty, all associations bound to the specified target are applied.",
"type": "StringList"
}
},
"mainSteps": [
{
"action": "aws:refreshAssociation",
"name": "refreshAssociation",
"inputs": {
"associationIds": [
"{{ associationIds }}"
]
}
}
]
}
```
------
### 輸入
**associationIds**
列出的關聯 ID。如果空，所有綁定到指定的目標的關聯都會被套用。
類型：StringList
必要：否
## `aws:runDockerAction`
(結構描述 2.0 版本或更新版本) 在容器上執行 Docker 動作。這個外掛程式可在 Linux 和 Microsoft Windows Server 作業系統上執行。
### 語法
#### 結構描述 2.2
------
#### [ YAML ]
```
---
mainSteps:
- action: aws:runDockerAction
name: RunDockerAction
inputs:
action: "{{ action }}"
container: "{{ container }}"
image: "{{ image }}"
memory: "{{ memory }}"
cpuShares: "{{ cpuShares }}"
volume: "{{ volume }}"
cmd: "{{ cmd }}"
env: "{{ env }}"
user: "{{ user }}"
publish: "{{ publish }}"
workingDirectory: "{{ workingDirectory }}"
timeoutSeconds: "{{ timeoutSeconds }}"
```
------
#### [ JSON ]
```
{
"mainSteps":[
{
"action":"aws:runDockerAction",
"name":"RunDockerAction",
"inputs":{
"action":"{{ action }}",
"container":"{{ container }}",
"image":"{{ image }}",
"memory":"{{ memory }}",
"cpuShares":"{{ cpuShares }}",
"volume":"{{ volume }}",
"cmd":"{{ cmd }}",
"env":"{{ env }}",
"user":"{{ user }}",
"publish":"{{ publish }}",
"workingDirectory": "{{ workingDirectory }}",
"timeoutSeconds": "{{ timeoutSeconds }}"
}
}
]
}
```
------
### 輸入
**動作**
執行動作的類型。
類型：字串
必要：是
**容器**
Docker 容器的 ID。
類型：字串
必要：否
**image**
Docker 影像名稱
類型：字串
必要：否
**命令提示字元**
容器指令
類型：字串
必要：否
**memory**
容器記憶體限制。
類型：字串
必要：否
**cpuShares**
CPU 容器共享 (相對重量)。
類型：字串
必要：否
**磁碟區**
容器磁碟容量。
類型：StringList
必要：否
**env**
容器的環境變數。
類型：字串
必要：否
**user**
容器的使用者名稱。
類型：字串
必要：否
**發布**
容器發佈的連接埠。
類型：字串
必要：否
**workingDirectory**
您受管節點上的工作目錄路徑。
類型：字串
必要：否
**timeoutSeconds**
在命令完成到被認定為失敗之間的秒數。
類型：字串
必要：否
## `aws:runDocument`
(結構描述 2.0 版本或更新版本) 執行存放在 Systems Manager 或在本機共用的 SSM 文件。您可以搭配使用此外掛程式與 [`aws:downloadContent`](#aws-downloadContent)外掛程式，將 SSM 文件從遠端位置下載到本機共用，然後執行它。Linux 和 Windows Server 作業系統上支援此外掛程式。此外掛程式不支援執行 `AWS-UpdateSSMAgent` 文件或任何使用 `aws:updateSsmAgent` 外掛程式的文件。
### 語法
#### 結構描述 2.2
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: aws:runDocument
parameters:
documentType:
description: "(Required) The document type to run."
type: String
allowedValues:
- LocalPath
- SSMDocument
mainSteps:
- action: aws:runDocument
name: runDocument
inputs:
documentType: "{{ documentType }}"
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "aws:runDocument",
"parameters": {
"documentType": {
"description": "(Required) The document type to run.",
"type": "String",
"allowedValues": [
"LocalPath",
"SSMDocument"
]
}
},
"mainSteps": [
{
"action": "aws:runDocument",
"name": "runDocument",
"inputs": {
"documentType": "{{ documentType }}"
}
}
]
}
```
------
### 輸入
**documentType**
執行的文件類型。您可以執行本機文件 (`LocalPath`) 或存放在 Systems Manager (`SSMDocument`) 的文件。
類型：字串
必要：是
**documentPath**
文件的路徑。如果 `documentType` 是 `LocalPath`，請指定在本機共享的文件路徑。如果 `documentType` 是 `SSMDocument`，請指定文件的名稱。
類型：字串
必要：否
**documentParameters**
文件的參數。
類型：StringMap
必要：否
## `aws:runPowerShellScript`
執行 PowerShell 指令碼或指定路徑來執行指令碼。這個外掛程式可在 Microsoft Windows Server 和 Linux 作業系統上執行。
### 語法
#### 結構描述 2.2
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: aws:runPowerShellScript
parameters:
commands:
type: String
description: "(Required) The commands to run or the path to an existing script
on the instance."
default: Write-Host "Hello World"
mainSteps:
- action: aws:runPowerShellScript
name: runPowerShellScript
inputs:
timeoutSeconds: '60'
runCommand:
- "{{ commands }}"
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "aws:runPowerShellScript",
"parameters": {
"commands": {
"type": "String",
"description": "(Required) The commands to run or the path to an existing script on the instance.",
"default": "Write-Host \"Hello World\""
}
},
"mainSteps": [
{
"action": "aws:runPowerShellScript",
"name": "runPowerShellScript",
"inputs": {
"timeoutSeconds": "60",
"runCommand": [
"{{ commands }}"
]
}
}
]
}
```
------
#### 結構描述 1.2
------
#### [ YAML ]
```
---
runtimeConfig:
aws:runPowerShellScript:
properties:
- id: 0.aws:runPowerShellScript
runCommand: "{{ commands }}"
workingDirectory: "{{ workingDirectory }}"
timeoutSeconds: "{{ executionTimeout }}"
```
------
#### [ JSON ]
```
{
"runtimeConfig":{
"aws:runPowerShellScript":{
"properties":[
{
"id":"0.aws:runPowerShellScript",
"runCommand":"{{ commands }}",
"workingDirectory":"{{ workingDirectory }}",
"timeoutSeconds":"{{ executionTimeout }}"
}
]
}
}
}
```
------
### Properties
**runCommand**
指定命令或指定在執行個體上現有的指令碼的路徑來執行。
類型：StringList
必要：是
**timeoutSeconds**
在命令完成到被認定為失敗之間的秒數。如果達到逾時，Systems Manager 停止命令執行。
類型：字串
必要：否
**workingDirectory**
在您的執行個體上的工作目錄路徑。
類型：字串
必要：否
## `aws:runShellScript`
執行 Linux shell 指令碼或指定路徑來執行指令碼。這個外掛程式只可在 Linux 作業系統上執行。
### 語法
#### 結構描述 2.2
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: aws:runShellScript
parameters:
commands:
type: String
description: "(Required) The commands to run or the path to an existing script
on the instance."
default: echo Hello World
mainSteps:
- action: aws:runShellScript
name: runShellScript
inputs:
timeoutSeconds: '60'
runCommand:
- "{{ commands }}"
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "aws:runShellScript",
"parameters": {
"commands": {
"type": "String",
"description": "(Required) The commands to run or the path to an existing script on the instance.",
"default": "echo Hello World"
}
},
"mainSteps": [
{
"action": "aws:runShellScript",
"name": "runShellScript",
"inputs": {
"timeoutSeconds": "60",
"runCommand": [
"{{ commands }}"
]
}
}
]
}
```
------
#### 結構描述 1.2
------
#### [ YAML ]
```
---
runtimeConfig:
aws:runShellScript:
properties:
- runCommand: "{{ commands }}"
workingDirectory: "{{ workingDirectory }}"
timeoutSeconds: "{{ executionTimeout }}"
```
------
#### [ JSON ]
```
{
"runtimeConfig":{
"aws:runShellScript":{
"properties":[
{
"runCommand":"{{ commands }}",
"workingDirectory":"{{ workingDirectory }}",
"timeoutSeconds":"{{ executionTimeout }}"
}
]
}
}
}
```
------
### Properties
**runCommand**
指定命令或指定在執行個體上現有的指令碼的路徑來執行。
類型：StringList
必要：是
**timeoutSeconds**
在命令完成到被認定為失敗之間的秒數。如果達到逾時，Systems Manager 停止命令執行。
類型：字串
必要：否
**workingDirectory**
在您的執行個體上的工作目錄路徑。
類型：字串
必要：否
## `aws:softwareInventory`
(結構描述 2.0 版本或更新版本) 在受管執行個體上收集與應用程式、檔案和組態相關的中繼資料。這個外掛程式可在 Linux 和 Microsoft Windows Server 作業系統上執行。當您設定清查集合時，請先建立 AWS Systems Manager State Manager關聯。Systems Manager 會在執行關聯時收集庫存資料。如果沒有先建立關聯，則當您試圖叫用 `aws:softwareInventory` 外掛程式時，系統會傳回以下錯誤：
```
The aws:softwareInventory plugin can only be invoked via ssm-associate.
```
執行個體一次只能設定一個庫存關聯。若您為執行個體設定兩個以上的關聯，庫存關聯便不會執行，並且也不會收集任何庫存資料。如需收集庫存的相關資訊，請參閱 [AWS Systems Manager庫存](systems-manager-inventory.md)。
### 語法
#### 結構描述 2.2
------
#### [ YAML ]
```
---
mainSteps:
- action: aws:softwareInventory
name: collectSoftwareInventoryItems
inputs:
applications: "{{ applications }}"
awsComponents: "{{ awsComponents }}"
networkConfig: "{{ networkConfig }}"
files: "{{ files }}"
services: "{{ services }}"
windowsRoles: "{{ windowsRoles }}"
windowsRegistry: "{{ windowsRegistry}}"
windowsUpdates: "{{ windowsUpdates }}"
instanceDetailedInformation: "{{ instanceDetailedInformation }}"
customInventory: "{{ customInventory }}"
```
------
#### [ JSON ]
```
{
"mainSteps":[
{
"action":"aws:softwareInventory",
"name":"collectSoftwareInventoryItems",
"inputs":{
"applications":"{{ applications }}",
"awsComponents":"{{ awsComponents }}",
"networkConfig":"{{ networkConfig }}",
"files":"{{ files }}",
"services":"{{ services }}",
"windowsRoles":"{{ windowsRoles }}",
"windowsRegistry":"{{ windowsRegistry}}",
"windowsUpdates":"{{ windowsUpdates }}",
"instanceDetailedInformation":"{{ instanceDetailedInformation }}",
"customInventory":"{{ customInventory }}"
}
}
]
}
```
------
### 輸入
**應用程式**
(選用) 收集已安裝應用程式的中繼資料。
類型：字串
必要：否
**awsComponents**
（選用） 收集 amazon-ssm-agent 等 AWS 元件的中繼資料。
類型：字串
必要：否
**files**
(選用，需要 SSM Agent 2.2.64.0 版或更新版本) 收集檔案的中繼資料，包括檔案名稱、檔案的建立時間、上次修改和存取檔案的時間以及檔案大小等。如需收集檔案庫存的相關資訊，請參閱 [使用檔案與 Windows 登錄檔清查](inventory-file-and-registry.md)。
類型：字串
必要：否
**networkConfig**
(選用) 收集網路組態的中繼資料。
類型：字串
必要：否
**billingInfo**
(選用) 收集與 AMI 帳單代碼相關聯的平台詳細資訊中繼資料。
類型：字串
必要：否
**windowsUpdates**
(選用) 收集所有 Windows 更新的中繼資料。
類型：字串
必要：否
**instanceDetailedInformation**
(選用) 收集的執行個體資訊比預設庫存外掛程式 (`aws:instanceInformation`) 提供的更多，包括 CPU 模型、速度和核心數量等。
類型：字串
必要：否
**services**
(選用，僅 Windows 作業系統需要 SSM Agent 2.2.64.0 版或更新版本) 收集服務組態的中繼資料。
類型：字串
必要：否
**windowsRegistry**
(選用，僅 Windows 作業系統需要 SSM Agent 2.2.64.0 版或更新版本) 收集 Windows 登錄機碼和值。而且，您還能選擇機碼路徑，並以遞迴方式收集所有機碼和值。此外，您也可以收集指定路徑的特定登錄機碼及其值。庫存將收集機碼路徑、名稱、類型與值。如需收集 Windows 登錄檔庫存的詳細資訊，請參閱 [使用檔案與 Windows 登錄檔清查](inventory-file-and-registry.md)。
類型：字串
必要：否
**windowsRoles**
(選用，僅 Windows 作業系統需要 SSM Agent 2.2.64.0 版或更新版本) 收集適用於 Microsoft Windows 角色組態的中繼資料。
類型：字串
必要：否
**customInventory**
(選用) 收集自訂庫存資料。如需自訂庫存的詳細資訊，請參閱[使用自訂庫存](inventory-custom.md)。
類型：字串
必要：否
**customInventoryDirectory**
(選用) 從指定的目錄中收集自訂庫存資料。如需自訂庫存的詳細資訊，請參閱[使用自訂庫存](inventory-custom.md)。
類型：字串
必要：否
## `aws:updateAgent`
更新 EC2Config 服務到最新版本或指定 EC2Config 服務的舊版本。這個外掛程式只能在 Microsoft Windows Server 作業系統上執行。如需有關 EC2Config 服務的詳細資訊，請參閱《Amazon EC2 使用者指南》**中的 [Configuring a Windows Instance using the EC2Config service (legacy)](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2config-service.html)。
### 語法
#### 結構描述 2.2
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: aws:updateAgent
mainSteps:
- action: aws:updateAgent
name: updateAgent
inputs:
agentName: Ec2Config
source: https://s3.{Region}.amazonaws.com/aws-ssm-{Region}/manifest.json
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "aws:updateAgent",
"mainSteps": [
{
"action": "aws:updateAgent",
"name": "updateAgent",
"inputs": {
"agentName": "Ec2Config",
"source": "https://s3.{Region}.amazonaws.com/aws-ssm-{Region}/manifest.json"
}
}
]
}
```
------
#### 結構描述 1.2
------
#### [ YAML ]
```
---
runtimeConfig:
aws:updateAgent:
properties:
agentName: Ec2Config
source: https://s3.{Region}.amazonaws.com/aws-ssm-{Region}/manifest.json
allowDowngrade: "{{ allowDowngrade }}"
targetVersion: "{{ version }}"
```
------
#### [ JSON ]
```
{
"runtimeConfig":{
"aws:updateAgent":{
"properties":{
"agentName":"Ec2Config",
"source":"https://s3.{Region}.amazonaws.com/aws-ssm-{Region}/manifest.json",
"allowDowngrade":"{{ allowDowngrade }}",
"targetVersion":"{{ version }}"
}
}
}
}
```
------
### Properties
**agentName**
EC2Config。這是執行 EC2Config 服務的代理名稱。
類型：字串
必要：是
**allowDowngrade**
允許 EC2Config 服務降級到較舊的版本。如果設定為非，該服務只可以升級到較新版本 (預設)。如果設定為是，指定之前的舊版本。
類型：布林值
必要：否
**source**
Systems Manager 複製 EC2Config 版本進行安裝的位置。您無法變更此位置。
類型：字串
必要：是
**targetVersion**
安裝指定版本的 EC2Config 服務。如果未指定，服務會更新到最新版本。
類型：字串
必要：否
## `aws:updateSsmAgent`
將 SSM Agent 更新到最新版本或指定舊版本。這個外掛程式可在 Linux 和 Windows Server 作業系統上執行。如需詳細資訊，請參閱[使用 SSM Agent](ssm-agent.md)。
### 語法
#### 結構描述 2.2
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: aws:updateSsmAgent
parameters:
allowDowngrade:
default: 'false'
description: "(Optional) Allow the Amazon SSM Agent service to be downgraded to
an earlier version. If set to false, the service can be upgraded to newer versions
only (default). If set to true, specify the earlier version."
type: String
allowedValues:
- 'true'
- 'false'
mainSteps:
- action: aws:updateSsmAgent
name: updateSSMAgent
inputs:
agentName: amazon-ssm-agent
source: https://s3.{Region}.amazonaws.com/amazon-ssm-{Region}/ssm-agent-manifest.json
allowDowngrade: "{{ allowDowngrade }}"
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "aws:updateSsmAgent",
"parameters": {
"allowDowngrade": {
"default": "false",
"description": "(Required) Allow the Amazon SSM Agent service to be downgraded to an earlier version. If set to false, the service can be upgraded to newer versions only (default). If set to true, specify the earlier version.",
"type": "String",
"allowedValues": [
"true",
"false"
]
}
},
"mainSteps": [
{
"action": "aws:updateSsmAgent",
"name": "awsupdateSsmAgent",
"inputs": {
"agentName": "amazon-ssm-agent",
"source": "https://s3.{Region}.amazonaws.com/amazon-ssm-{Region}/ssm-agent-manifest.json",
"allowDowngrade": "{{ allowDowngrade }}"
}
}
]
}
```
------
#### 結構描述 1.2
------
#### [ YAML ]
```
---
runtimeConfig:
aws:updateSsmAgent:
properties:
- agentName: amazon-ssm-agent
source: https://s3.{Region}.amazonaws.com/aws-ssm-{Region}/manifest.json
allowDowngrade: "{{ allowDowngrade }}"
```
------
#### [ JSON ]
```
{
"runtimeConfig":{
"aws:updateSsmAgent":{
"properties":[
{
"agentName":"amazon-ssm-agent",
"source":"https://s3.{Region}.amazonaws.com/aws-ssm-{Region}/manifest.json",
"allowDowngrade":"{{ allowDowngrade }}"
}
]
}
}
}
```
------
### Properties
**agentName**
amazon-ssm-agent。這是在執行個體上處理請求和執行命令的 Systems Manager 代理程式名稱。
類型：字串
必要：是
**allowDowngrade**
允許 SSM Agent 降級到較早的版本。如果設定為非，代理程式只可以升級到較新版本 (預設)。如果設定為是，指定之前的舊版本。
類型：布林值
必要：是
**source**
Systems Manager 複製 SSM Agent 版本進行安裝的位置。您無法變更此位置。
類型：字串
必要：是
**targetVersion**
指定安裝 SSM Agent 的版本。如果未指定，代理程式會更新到最新版本。
類型：字串
必要：否
# 建立 SSM 文件內容
如果 AWS Systems Manager 公有文件未執行您想要在 AWS 資源上執行的所有動作，您可以建立自己的 SSM 文件。您也可以使用主控台複製 SSM 文件。複製文件會將現有文件的內容複製到您可以修改的新文件中。建立或複製文件時，文件的內容不得超過 64 KB。此配額也包括在執行階段為輸入參數指定的內容。當您建立新的 `Command` 或 `Policy` 文件時，我們建議您使用結構描述 2.2 或更新版本，以便您可以利用最新的功能，例如文件編輯、自動版本控制、排序等。
## 撰寫 SSM 文件內容
若要建立您自己的 SSM 文件內容，請務必瞭解 SSM 文件提供的不同結構描述、功能、外掛程式和語法。我們建議您熟悉下列資源。
+ [撰寫您自己的 AWS Systems Manager 文件](https://aws.amazon.com/blogs//mt/writing-your-own-aws-systems-manager-documents/)
+ [資料元素和參數](documents-syntax-data-elements-parameters.md)
+ [結構描述、功能以及範例](documents-schemas-features.md)
+ [命令文件外掛程式參考](documents-command-ssm-plugin-reference.md)
+ [Systems Manager Automation 動作參考](automation-actions.md)
+ [自動化系統變數](automation-variables.md)
+ [其他執行手冊範例](automation-document-examples.md)
+ 透過 AWS Toolkit for Visual Studio Code 來[使用 Systems Manager Automation Runbook](https://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/systems-manager-automation-docs.html)
+ [Automation 執行手冊的視覺化設計體驗](automation-visual-designer.md)
+ [在執行手冊中使用指令碼](automation-document-script-considerations.md)
AWS 預先定義的 SSM 文件可能會執行您需要的一些動作。您可以根據文件類型，在自訂 SSM 文件中使用 `aws:runDocument`、`aws:runCommand` 或 `aws:executeAutomation` 外掛程式來呼叫這些文件。您也可以將這些文件的部分複製到自訂 SSM 文件中，然後編輯內容以符合您的需求。
**提示**
建立 SSM 文件內容時，您可能會在測試時數次變更內容並更新 SSM 文件。下列命令會以您的最新內容更新 SSM 文件，並將文件的預設版本更新為文件的最新版本。
Linux 和 Windows 命令使用 `jq` 命令列工具來篩選 JSON 回應資料。
```
latestDocVersion=$(aws ssm update-document \
--content file://path/to/file/documentContent.json \
--name "ExampleDocument" \
--document-format JSON \
--document-version '$LATEST' \
| jq -r '.DocumentDescription.LatestVersion')
aws ssm update-document-default-version \
--name "ExampleDocument" \
--document-version $latestDocVersion
```
```
latestDocVersion=$(aws ssm update-document ^
--content file://C:\path\to\file\documentContent.json ^
--name "ExampleDocument" ^
--document-format JSON ^
--document-version "$LATEST" ^
| jq -r '.DocumentDescription.LatestVersion')
aws ssm update-document-default-version ^
--name "ExampleDocument" ^
--document-version $latestDocVersion
```
```
$content = Get-Content -Path "C:\path\to\file\documentContent.json" | Out-String
$latestDocVersion = Update-SSMDocument `
-Content $content `
-Name "ExampleDocument" `
-DocumentFormat "JSON" `
-DocumentVersion '$LATEST' `
| Select-Object -ExpandProperty LatestVersion
Update-SSMDocumentDefaultVersion `
-Name "ExampleDocument" `
-DocumentVersion $latestDocVersion
```
### SSM 文件的安全最佳實務
建立 SSM 文件時，請遵循這些安全最佳實務，以協助防止命令注入，確保安全處理參數：
+ 針對將在命令或指令碼中使用的字串參數，使用環境變數插補。將具有 `ENV_VAR` 值的 `interpolationType` 屬性新增至字串參數：
```
{
"command": {
"type": "String",
"description": "Command to execute",
"interpolationType": "ENV_VAR"
}
}
```
您可以透過指定在插補傳遞的值中不接受雙引號，進一步提高 SSM 文件的安全性：
```
{
"command": {
"type": "String",
"description": "Command to execute",
"interpolationType": "ENV_VAR",
"allowedPattern": "^[^"]*$"
}
}
```
+ 使用 Python、Ruby 或 Node.js 等編譯語言時，請使用適當的環境變數語法來參考參數：
```
# Python example
import os
command = os.environ['SSM_Message']
```
+ 為了回溯相容於舊版 SSM Agent (3.3.2746.0 版之前)，請包含環境變數的備用邏輯：
```
if [ -z "${SSM_command+x}" ]; then
export SSM_command="{{command}}"
fi
```
+ 將環境變數插補與 `allowedPattern` 結合，以進行額外的輸入驗證。在下列範例中，`allowedPattern` 值 `^[^"]*$` 會特別防止字串值中的雙引號：
```
{
"command": {
"type": "String",
"interpolationType": "ENV_VAR",
"allowedPattern": "^[a-zA-Z0-9_-]+$"
}
}
```
+ 實作 SSM 文件之前，請驗證下列安全性考量：
+ 接受使用者輸入的所有字串參數會適時使用環境變數插補。
+ 盡可能使用 `allowedPattern` 實作輸入驗證。
+ 文件包含適用於參數處理的適當錯誤處理。
+ 對於使用舊版 SSM Agent 的環境，會維持回溯相容性。
如需有關 Systems Manager 存取 AWS 的服務擁有資源以及如何設定資料周邊政策的資訊，請參閱 [中的資料周邊 AWS Systems Manager](data-perimeters.md)。
## 複製 SSM 文件
您可以使用 Systems Manager 文件主控台來複製 AWS Systems Manager 文件，以建立 SSM 文件。複製 SSM 文件會將現有文件的內容複製到您可以修改的新文件中。您無法複製大於 64 KB 的文件。
**若要複製 SSM 文件**
1. 在 https：//[https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/) 開啟 AWS Systems Manager 主控台。
1. 在導覽窗格中，選擇 **Documents (文件)**。
1. 在搜尋方塊中，輸入您要複製的文件的名稱。
1. 選擇您要翻製的文件名稱，然後選擇 **Actions** (動作) 下拉式選單中的 **Clone document** (複製文件)。
1. 視需要修改文件，然後選擇 **Create document** (建立文件) 以儲存文件。
撰寫 SSM 文件內容之後，您可以使用下列其中一種方法來建立 SSM 文件。
**Topics**
+ [撰寫 SSM 文件內容](#writing-ssm-doc-content)
+ [複製 SSM 文件](#cloning-ssm-document)
+ [建立複合文件](#documents-creating-composite)
## 建立複合文件
*composite* AWS Systems Manager (SSM) 文件是一種自訂文件，可透過執行一或多個次要 SSM 文件來執行一系列動作。複合文件提升了 *infrastructure as code*，讓您能夠為常見任務建立一組標準的 SSM 文件，例如自舉軟體或網域加入執行個體。然後，您可以在相同的 AWS 帳戶 中跨 共用這些文件 AWS 區域 ，以減少 SSM 文件維護並確保一致性。
例如，您可以建立複合的文件來執行下列動作：
1. 安裝允許清單中的所有修補程式。
1. 安裝防毒軟體
1. 從 GitHub 下載指令碼並執行指令碼。
在這個範例中，自訂 SSM 文件中包含下列外掛程式以執行下列動作：
1. 用於執行 `AWS-RunPatchBaseline` 文件的 `aws:runDocument` 外掛程式，可安裝所有允許列出的修補程式。
1. 用於執行 `AWS-InstallApplication` 文件的 `aws:runDocument` 外掛程式，可安裝防毒軟體。
1. 用於從 GitHub 下載並執行指令碼的 `aws:downloadContent` 外掛程式。
複合和次要文件可以存放在 Systems Manager、GitHub (公有和私有儲存庫) 或 Amazon S3。您可以用 JSON 或 YAML 格式建立複合文件和次要文件。
**注意**
複合文件的執行深度最多只能為三個文件。這表示複合文件可以呼叫一個子文件，以及該子文件可以再呼叫一個文件。
若要建立複合文件，需要在自訂 SSM 文件中新增 [`aws:runDocument`](documents-command-ssm-plugin-reference.md#aws-rundocument) 外掛程式，並指定所需的輸入。下列的範例是個建立複合的文件來執行下列動作：
1. 執行 [`aws:downloadContent`](documents-command-ssm-plugin-reference.md#aws-downloadContent) 外掛程式，將 SSM 文件從 GitHub 公有儲存庫下載到名為 bootstrap 的本機目錄。此 SSM 文件稱為 StateManagerBootstrap.yml (YAML 文件)。
1. 執行 `aws:runDocument` 外掛程式，以執行 StateManagerBootstrap.yml 文件。無需指定參數。
1. 執行 `aws:runDocument` 外掛程式，以執行 `AWS-ConfigureDocker pre-defined` SSM 文件。指定的參數在執行個體上安裝 Docker。
```
{
"schemaVersion": "2.2",
"description": "My composite document for bootstrapping software and installing Docker.",
"parameters": {
},
"mainSteps": [
{
"action": "aws:downloadContent",
"name": "downloadContent",
"inputs": {
"sourceType": "GitHub",
"sourceInfo": "{\"owner\":\"TestUser1\",\"repository\":\"TestPublic\", \"path\":\"documents/bootstrap/StateManagerBootstrap.yml\"}",
"destinationPath": "bootstrap"
}
},
{
"action": "aws:runDocument",
"name": "runDocument",
"inputs": {
"documentType": "LocalPath",
"documentPath": "bootstrap",
"documentParameters": "{}"
}
},
{
"action": "aws:runDocument",
"name": "configureDocker",
"inputs": {
"documentType": "SSMDocument",
"documentPath": "AWS-ConfigureDocker",
"documentParameters": "{\"action\":\"Install\"}"
}
}
]
}
```
**詳細資訊**
+ 如需使用 Run Command 呼叫指令碼時重新開機伺服器和執行個體的資訊，請參閱 [執行命令時處理重新啟動](send-commands-reboot.md)。
+ 如需有關您能夠新增至自訂 SSM 文件的外掛程式的詳細資訊，請參閱 [命令文件外掛程式參考](documents-command-ssm-plugin-reference.md)。
+ 如果您只想簡單從遠端位置 (無須建立複合文件) 執行文件的詳細資訊，請參閱 [從遠端位置執行 文件](documents-running-remote-github-s3.md)。
# 使用文件
本節包含有關如何使用及處理 SSM 文件的資訊。
**Topics**
+ [比較 SSM 文件版本](comparing-versions.md)
+ [建立 SSM 文件](create-ssm-console.md)
+ [刪除自訂 SSM 文件](deleting-documents.md)
+ [從遠端位置執行 文件](documents-running-remote-github-s3.md)
+ [共用 SSM 文件](documents-ssm-sharing.md)
+ [搜尋 SSM 文件](ssm-documents-searching.md)
# 比較 SSM 文件版本
您可以在 Systems Manager 文件主控台中比較 AWS Systems Manager (SSM) 文件版本之間的內容差異。比較 SSM 文件的版本時，會反白顯示版本內容之間的差異。
**若要比較 SSM 文件內容 (主控台)**
1. 開啟位於 AWS Systems Managerhttps://console.aws.amazon.com/systems-manager/ 的主控台。[https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)
1. 在導覽窗格中，選擇 **Documents (文件)**。
1. 在文件清單中，選擇您要比較其內容的文件。
1. 在 **Content** (內容) 索引標籤中，選取 **Compare versions** (比較版本)，然後選擇您要與之比較內容的文件版本。
# 建立 SSM 文件
如 [撰寫 SSM 文件內容](documents-creating-content.md#writing-ssm-doc-content) 中所述，建立自訂 SSM 文件的內容後，您可以使用 Systems Manager 主控台，以您的內容建立 SSM 文件。
**建立 SSM 文件**
1. 開啟位於 AWS Systems Managerhttps://console.aws.amazon.com/systems-manager/ 的主控台。[https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)
1. 在導覽窗格中，選擇 **Documents (文件)**。
1. 選擇 **Create command or session (建立命令或工作階段)**。
1. 輸入文件的描述性名稱。
1. (選用) 針對 **Target type (目標類型)**，指定文件可在其上執行的資源類型。
1. 在 **Document type (文件類型)**清單中，選擇您要建立的文件類型。
1. 刪除 **Content (內容)** 欄位中的括號，然後貼上先前建立的文件。
1. (選用) 展開 **Document tags (文件標籤)** 區段，將一或多個標籤鍵值組套用至文件。
標籤是您指派給資源的選用性中繼資料。標籤允許您以不同的方式 (例如用途、擁有者或環境) 將資源分類。例如，您可能想要標記文件來識別其執行的任務類型、目標作業系統類型以及其執行所在的環境。在這種情況下，您可以指定以下索引鍵名稱/值對：
+ `Key=TaskType,Value=MyConfigurationUpdate`
+ `Key=OS,Value=AMAZON_LINUX_2`
+ `Key=Environment,Value=Production`
1. 選擇 **Create document (建立文件)** 以儲存文件。
# 刪除自訂 SSM 文件
如果您不想再使用自訂 SSM 文件，則可以使用 AWS Systems Manager 主控台刪除它。
**刪除 SSM 文件**
1. 開啟位於 AWS Systems Managerhttps://console.aws.amazon.com/systems-manager/ 的主控台。[https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)
1. 在導覽窗格中，選擇 **Documents (文件)**。
1. 選取您要刪除的文件。
1. 選取 **Delete** (刪除)。當提示您刪除文件時，請選取 **Delete** (刪除)。
如需使用命令列工具或 SDK 刪除 SSM 文件的範例，請參閱[`DeleteDocument` 搭配 AWS SDK 或 CLI 使用](example_ssm_DeleteDocument_section.md)。
# 從遠端位置執行 文件
您可以使用`AWS-RunDocument`預先定義的 SSM 文件，從遠端位置執行 AWS Systems Manager (SSM) 文件。本文件支援執行在下列位置存放的 SSM 文件：
+ 公有和私有 GitHub 儲存庫 (不支援 GitHub Enterprise)
+ Amazon S3 儲存貯體
+ Systems Manager
雖然您也可以在 中使用 State Manager或 自動化工具來執行遠端文件 AWS Systems Manager，但下列程序僅說明如何在 Systems Manager 主控台中使用 AWS Systems Manager Run Command 來執行遠端 SSM 文件。
**注意**
`AWS-RunDocument` 只能用來執行命令類型的 SSM 文件，而不能執行其他類型，例如 Automation Runbook。`AWS-RunDocument` 使用 `aws:downloadContent` 外掛程式。如需有關 `aws:downloadContent` 外掛程式的詳細資訊，請參閱 [`aws:downloadContent`](documents-command-ssm-plugin-reference.md#aws-downloadContent)。
**警告**
`AWS-RunDocument` 可以從各種來源執行文件內容 (SSM 文件、GitHub、S3、URLs)。執行遠端文件時，評估的 IAM 許可是遠端文件`ssm:GetDocument`上的 和 `ssm:SendCommand`上的 `AWS-RunDocument`。如果您有拒絕存取特定 SSM 文件的 IAM 政策，具有`AWS-RunDocument`許可的使用者仍然可以透過將文件內容傳遞為參數來執行這些拒絕的文件，這可能不受相同文件特定 IAM 限制的約束。
若要正確限制文件執行，請使用下列其中一種方法：
**允許清單核准來源**：如果您需要使用巢狀文件執行，請使用每種來源類型的適當控制項來限制對核准來源的存取：用於控制 SSM 文件來源`ssm:GetDocument`的 IAM 政策、用於 Amazon S3 來源的 IAM 和 Amazon S3 儲存貯體政策，以及用於公有網際網路來源的網路設定 （例如 VPC 端點或安全群組）。
**限制對 AWS-RunDocument 的存取**：拒絕 `AWS-RunDocument`和任何其他在 IAM 政策中使用`aws:runDocument`外掛程式的文件，以防止巢狀文件執行。 `ssm:SendCommand`
**使用許可界限**：實作 IAM 許可界限來設定使用者的最大許可，防止他們執行未經授權的文件，無論執行方法為何。
如需 IAM 最佳實務和許可界限的詳細資訊，請參閱*AWS Identity and Access Management 《 使用者指南*》中的 [IAM 實體的許可界限](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html)。
**開始之前**
在您可以開始執行遠端文件之前，請必須完成以下工作。
+ 建立一份 SSM 命令文件，並將它儲存在遠端位置。如需詳細資訊，請參閱[建立 SSM 文件內容](documents-creating-content.md)
+ 如果您打算執行存放在 GitHub 私有儲存庫中的遠端文件，則必須為 GitHub 安全存取權杖建立一個 Systems Manager `SecureString` 參數。您無法透過 SSH 手動傳遞權杖來存取 GitHub 私有儲存庫中的遠端文件。您必須將存取字符做為 Systems Manager `SecureString` 參數傳遞。如需建立 `SecureString` 參數的詳細資訊，請參閱 [在 Systems Manager 中建立 Parameter Store 參數](sysman-paramstore-su-create.md)。
## 執行遠端文件 (主控台)
**執行遠端文件**
1. 在 https：//[https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/) 開啟 AWS Systems Manager 主控台。
1. 在導覽窗格中，選擇 **Run Command**。
1. 選擇**執行命令**。
1. 在 **Document** (文件) 清單中，請選擇 **`AWS-RunDocument`**。
1. 在 **Command parameters (命令參數)** 中，針對 **Source Type (來源類型)** 選擇選項。
+ 如果選擇 **GitHub**，請指定**來源資訊**，資訊格式如下：
```
{
"owner": "owner_name",
"repository": "repository_name",
"path": "path_to_document",
"getOptions":"branch:branch_name",
"tokenInfo": "{{ssm-secure:secure-string-token}}"
}
```
例如：
```
{
"owner":"TestUser",
"repository":"GitHubTestExamples",
"path":"scripts/python/test-script",
"getOptions":"branch:exampleBranch",
"tokenInfo":"{{ssm-secure:my-secure-string-token}}"
}
```
**注意**
`getOptions` 是可從主要分支以外的分支或從儲存庫中的特定遞交中擷取內容的額外選項。如果您使用主要分支中的最新遞交，則可省略 `getOptions`。只有當 SSM 文件存放於 `master` 以外的分支時，才需要 `branch` 參數。
若要使用存放庫中特定「遞交」**中的 SSM 文件，請使用 `commitID` 與 `getOptions` 來代替 `branch`。例如：
```
"getOptions": "commitID:bbc1ddb94...b76d3bEXAMPLE",
```
+ 如果您選擇 **S3**，指定 **Source Info (來源資訊)** 的資訊格式如下：
```
{"path":"URL_to_document_in_S3"}
```
例如：
```
{"path":"https://s3.amazonaws.com/amzn-s3-demo-bucket/scripts/ruby/mySSMdoc.json"}
```
+ 如果您選擇 **SSMDocument**，指定 **Source Info (來源資訊)** 的資訊格式如下：
```
{"name": "document_name"}
```
例如：
```
{"name": "mySSMdoc"}
```
1. 在 **Document Parameters** (文件參數) 欄位中輸入遠端 SSM 文件的參數。例如，如果您執行 `AWS-RunPowerShell` 文件，您可以指定：
```
{"commands": ["date", "echo \"Hello World\""]}
```
如果您執行 `AWS-ConfigureAWSPack` 文件，您可以指定：
```
{
"action":"Install",
"name":"AWSPVDriver"
}
```
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 呼叫指令碼時重新開機伺服器和執行個體的資訊，請參閱 [執行命令時處理重新啟動](send-commands-reboot.md)。
# 共用 SSM 文件
您可以私下或公開地與相同 中的帳戶共用 AWS Systems Manager (SSM) 文件 AWS 區域。若要私下共用文件，您需要修改文件許可，並根據特定人員的 AWS 帳戶 ID 允許其進行存取。若要公開共用 SSM 文件，請修改文件許可並指定 `All`。文件不能同時公開和私下共用。
**警告**
只能使用受信任來源的共用 SSM 文件。當您使用任何共用文件，請在使用文件之前仔細檢視文件的內容，讓您了解文件將會如何改變您執行個體的組態。如需共用文件的最佳實務詳細資訊，請參閱 [共用 SSM 文件的最佳實務](#best-practices-shared)。
**限制**
當您開始使用 SSM 文件時，請注意以下限制。
+ 只有文件擁有者可以分享文件。
+ 您必須停止共用文件，才能刪除文件。如需詳細資訊，請參閱[修改共用 SSM 文件的許可](#modify-permissions-shared)。
+ 您可以共用最多 1000 個文件 AWS 帳戶。您可以在 [支援 中心](https://console.aws.amazon.com/support/home#/case/create?issueType=service-limit-increase)請求提高此限制。對於 **Limit type** (限制類型)，選擇 *EC2 Systems Manager* 並說明請求的原因。
+ 您最多可以公開共用五個 SSM 文件。您可以在 [支援 中心](https://console.aws.amazon.com/support/home#/case/create?issueType=service-limit-increase)請求提高此限制。對於 **Limit type** (限制類型)，選擇 *EC2 Systems Manager* 並說明請求的原因。
+ 文件只能與相同 中的其他帳戶共用 AWS 區域 。不支援跨區域共用。
**重要**
在 Systems Manager 中，*Amazon 擁有的* SSM 文件是由 Amazon Web Services 本身建立和管理的文件。*Amazon 擁有的*文件的文件名中包含如 `AWS-*` 的字首。文件的擁有者被視為 Amazon，而不是其中的特定使用者帳戶 AWS。這些文件公開供所有人使用。
如需有關 Systems Manager 服務配額的詳細資訊，請參閱 [AWS Systems Manager Service Quotas](https://docs.aws.amazon.com/general/latest/gr/ssm.html#limits_ssm)。
**Topics**
+ [共用 SSM 文件的最佳實務](#best-practices-shared)
+ [封鎖 SSM 文件的公有共用](#block-public-access)
+ [共用 SSM 文件](#ssm-how-to-share)
+ [修改共用 SSM 文件的許可](#modify-permissions-shared)
+ [使用共用的 SSM 文件](#using-shared-documents)
## 共用 SSM 文件的最佳實務
共享或使用共用文件之前，請檢閱下列指導方針。
**移除敏感的資訊**
請仔細檢閱您的 AWS Systems Manager (SSM) 文件，並移除任何敏感資訊。例如，確認文件不包含您的 AWS 登入資料。如果您與特定個人共享文件，這些使用者可以檢視文件中的資訊。如果您將文件設定為公開，任何使用者可以檢視文件中的資訊。
**封鎖文件的公有共用**
檢閱帳戶中所有公開共用的 SSM 文件，並確認是否要繼續共用它們。若要停止公開共用文件，必須依照本主題的[修改共用 SSM 文件的許可](#modify-permissions-shared)章節所述修改文件許可設定。開啟封鎖公開共用設定不會影響目前正在公開共用的任何文件。除非您的使用案例需要公開共用文件，否則建議在 Systems Manager 文件主控台的**偏好設定**區段中開啟 SSM 文件的封鎖公開共用設定。開啟此設定可避免 SSM 文件遭到不必要的存取。封鎖公有共用設定是帳戶層級設定，每個 AWS 區域各有不同。
**使用 IAM 信任政策來限制 Run Command 動作**
為可存取 文件的使用者建立限制性 AWS Identity and Access Management (IAM) 政策。IAM 政策決定使用者可以在 Amazon Elastic Compute Cloud (Amazon EC2) 主控台或使用 `ListDocuments` AWS Command Line Interface (AWS CLI) 或 呼叫 來查看哪些 SSM 文件 AWS Tools for Windows PowerShell。此政策也限制使用者在 SSM 文件上可執行哪些動作。您可以建立嚴格的政策，讓使用者只能使用特定的文件。如需詳細資訊，請參閱[客戶管理政策範例](security_iam_id-based-policy-examples.md#customer-managed-policies)。
**請小心使用共用的 SSM 文件**
檢閱每個與您共享的文件內容，特別是公有文件。了解那些將在您的執行個體上執行的指令。文件執行後可能會有意或無意地產生負面影響。如果文件參考外部網路、先檢閱外部來源，然後再使用文件。
**使用文件雜湊來傳送命令**
當您共用文件，系統會建立一個 SHA-256 雜湊並將其指派給文件。系統還會儲存文件內容的快照。當您使用共用文件來傳送命令，您可以在您的命令中指定雜湊以確保以下條件為真：
+ 您正在執行正確的 Systems Manager 文件的命令
+ 自從與您共用文件後，文件內容尚未變更。
如果雜湊不符合指定的文件或者如果共用文件的內容被更改過，命令會傳回 `InvalidDocument` 的錯誤例外訊息。雜湊無法從外部位置驗證文件的內容。
**使用插補參數來改善安全性**
對於 SSM 文件中的 `String` 類型參數，請使用參數和 `interpolationType": "ENV_VAR` 值，透過將參數輸入視為字串常值，而非潛在可執行命令，來提高安全性以防止命令注入攻擊。在此情況下，Agent 會使用參數的值，建立名為 `SSM_parameter-name` 的環境變數。建議您更新所有包含 `String` 類型參數的現有 SSM 文件，以包含 `"interpolationType": "ENV_VAR"`。如需詳細資訊，請參閱[撰寫 SSM 文件內容](documents-creating-content.md#writing-ssm-doc-content)。
## 封鎖 SSM 文件的公有共用
開始之前，請檢閱 AWS 帳戶 中所有公開共用的 SSM 文件，並確認是否要繼續共用它們。若要停止公開共用 SSM 文件，必須依照本主題的[修改共用 SSM 文件的許可](#modify-permissions-shared)章節所述修改文件許可設定。開啟封鎖公開共用設定不會影響目前正在公開共用的任何 SSM 文件。啟用封鎖公開共用設定後，您將無法公開共用任何其他 SSM 文件。
除非您的使用案例需要公開共用文件，否則建議開啟 SSM 文件的封鎖公開共用設定。開啟此設定可避免 SSM 文件遭到不必要的存取。封鎖公開共用設定是帳戶層級設定，每個設定可能有所不同 AWS 區域。完成下列任務，為目前未共用的 SSM 文件封鎖公開共用。
### 封鎖公有共用 (主控台)
**若要封鎖 SSM 文件的公有共用**
1. 在 https：//[https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/) 開啟 AWS Systems Manager 主控台。
1. 在導覽窗格中，選擇 **Documents (文件)**。
1. 選擇 **Preferences** (偏好設定)，然後在 **Block public sharing** (封鎖公有共用) 區段中選擇 **Edit** (編輯)。
1. 選取 **Block public sharing** (封鎖公有共用) 核取方塊，再選擇 **Save** (儲存)。
### 封鎖公有共用 (命令列)
在本機 AWS Tools for Windows PowerShell 電腦上開啟 AWS Command Line Interface (AWS CLI) 或 ，並執行下列命令來封鎖 SSM 文件的公開共用。
------
#### [ Linux & macOS ]
```
aws ssm update-service-setting \
--setting-id /ssm/documents/console/public-sharing-permission \
--setting-value Disable \
--region 'The AWS 區域 you want to block public sharing in'
```
------
#### [ Windows ]
```
aws ssm update-service-setting ^
--setting-id /ssm/documents/console/public-sharing-permission ^
--setting-value Disable ^
--region "The AWS 區域 you want to block public sharing in"
```
------
#### [ PowerShell ]
```
Update-SSMServiceSetting `
-SettingId /ssm/documents/console/public-sharing-permission `
-SettingValue Disable `
–Region The AWS 區域 you want to block public sharing in
```
------
使用以下命令來確認設定值已更新。
------
#### [ Linux & macOS ]
```
aws ssm get-service-setting \
--setting-id /ssm/documents/console/public-sharing-permission \
--region The AWS 區域 you blocked public sharing in
```
------
#### [ Windows ]
```
aws ssm get-service-setting ^
--setting-id /ssm/documents/console/public-sharing-permission ^
--region "The AWS 區域 you blocked public sharing in"
```
------
#### [ PowerShell ]
```
Get-SSMServiceSetting `
-SettingId /ssm/documents/console/public-sharing-permission `
-Region The AWS 區域 you blocked public sharing in
```
------
### 限制存取以封鎖與 IAM 的公有共用
您可以建立 AWS Identity and Access Management (IAM) 政策，限制使用者修改封鎖公開共用設定。這可防止使用者允許 SSM 文件的不必要存取。
以下是防止使用者更新封鎖公有共用設定的 IAM 政策範例。若要使用此範例，您必須用您自己的帳戶 ID 取代範例 Amazon Web Services 帳戶 ID。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Deny",
"Action": "ssm:UpdateServiceSetting",
"Resource": "arn:aws:ssm:*:444455556666:servicesetting/ssm/documents/console/public-sharing-permission"
}
]
}
```
------
## 共用 SSM 文件
您可以使用 Systems Manager 主控台共用 AWS Systems Manager (SSM) 文件。從主控台共用文件時，只能共用文件的預設版本。您也可以透過使用 (AWS CLI) 或 AWS SDK 呼叫 `ModifyDocumentPermission` API AWS Command Line Interface 操作 AWS Tools for Windows PowerShell，以程式設計方式共用 SSM 文件。在共用文件之前，先取得您要與其共用的人員的 AWS 帳戶 ID。當您要共享文件時，您可以指定這些帳戶 ID。
### 分享文件 (主控台)
1. 在 https：//[https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/) 開啟 AWS Systems Manager 主控台。
1. 在導覽窗格中，選擇 **Documents (文件)**。
1. 在文件清單中，選擇要共享的文件，然後選擇 **View details (查看詳細資訊)**。在 **Permissions** (許可) 索引標籤中，驗證您是文件的擁有者。只有文件擁有者可以分享文件。
1. 選擇**編輯**。
1. 若要公開共享命令，選擇 **Public (公有)**，然後選擇 **Save (儲存)**。若要私下共用命令，選擇 **Private** (私有)，輸入 AWS 帳戶 ID，選擇 **Add permission** (新增許可)，然後選擇 **Save** (儲存)。
### 分享文件 (命令列)
下列程序需要您 AWS 區域 為命令列工作階段指定 。
1. 在本機 AWS Tools for Windows PowerShell 電腦上開啟 AWS CLI 或 ，並執行下列命令來指定您的登入資料。
在下列命令中，用您自己的資訊取代*區域*。如需支援的 *region* 值的清單，請參閱《Amazon Web Services 一般參考》**中 [Systems Manager 服務端點](https://docs.aws.amazon.com/general/latest/gr/ssm.html#ssm_region)一節的**區域**資料欄。
------
#### [ Linux & macOS ]
```
aws config
AWS Access Key ID: [your key]
AWS Secret Access Key: [your key]
Default region name: region
Default output format [None]:
```
------
#### [ Windows ]
```
aws config
AWS Access Key ID: [your key]
AWS Secret Access Key: [your key]
Default region name: region
Default output format [None]:
```
------
#### [ PowerShell ]
```
Set-AWSCredentials –AccessKey your key –SecretKey your key
Set-DefaultAWSRegion -Region region
```
------
1. 使用下列命令列出所有可供您使用的 SSM 文件。清單中包含您建立和與您共享的文件。
------
#### [ Linux & macOS ]
```
aws ssm list-documents
```
------
#### [ Windows ]
```
aws ssm list-documents
```
------
#### [ PowerShell ]
```
Get-SSMDocumentList
```
------
1. 使用下列命令來取得特定的文件：
------
#### [ Linux & macOS ]
```
aws ssm get-document \
--name document name
```
------
#### [ Windows ]
```
aws ssm get-document ^
--name document name
```
------
#### [ PowerShell ]
```
Get-SSMDocument `
–Name document name
```
------
1. 請使用下列命令取得文件的說明。
------
#### [ Linux & macOS ]
```
aws ssm describe-document \
--name document name
```
------
#### [ Windows ]
```
aws ssm describe-document ^
--name document name
```
------
#### [ PowerShell ]
```
Get-SSMDocumentDescription `
–Name document name
```
------
1. 使用下列的指令來查看文件的許可權限：
------
#### [ Linux & macOS ]
```
aws ssm describe-document-permission \
--name document name \
--permission-type Share
```
------
#### [ Windows ]
```
aws ssm describe-document-permission ^
--name document name ^
--permission-type Share
```
------
#### [ PowerShell ]
```
Get-SSMDocumentPermission `
–Name document name `
-PermissionType Share
```
------
1. 使用下列的指令來修改文件的許可權限並共享文件。您必須文件的擁有者才能夠編輯許可權限。對於與特定 AWS 帳戶 ID 共用的文件，也可以使用 `--shared-document-version` 參數指定要共用的文件版本。如果您未指定版本，則會共用文件的 `Default` 版本。如果您與 `all` 公開共用文件，則預設為共用指定文件的所有版本。下列範例命令會根據該人員的 AWS 帳戶 ID，私下與特定個人共用文件。
------
#### [ Linux & macOS ]
```
aws ssm modify-document-permission \
--name document name \
--permission-type Share \
--account-ids-to-add AWS 帳戶 ID
```
------
#### [ Windows ]
```
aws ssm modify-document-permission ^
--name document name ^
--permission-type Share ^
--account-ids-to-add AWS 帳戶 ID
```
------
#### [ PowerShell ]
```
Edit-SSMDocumentPermission `
–Name document name `
-PermissionType Share `
-AccountIdsToAdd AWS 帳戶 ID
```
------
1. 使用下列命令來公開共享的文件：
**注意**
如果您與 `all` 公開共用文件，則預設為共用指定文件的所有版本。
------
#### [ Linux & macOS ]
```
aws ssm modify-document-permission \
--name document name \
--permission-type Share \
--account-ids-to-add 'all'
```
------
#### [ Windows ]
```
aws ssm modify-document-permission ^
--name document name ^
--permission-type Share ^
--account-ids-to-add "all"
```
------
#### [ PowerShell ]
```
Edit-SSMDocumentPermission `
-Name document name `
-PermissionType Share `
-AccountIdsToAdd ('all')
```
------
## 修改共用 SSM 文件的許可
如果您共用命令，使用者可以檢視和使用該命令，直到您移除對 AWS Systems Manager (SSM) 文件的存取權或刪除 SSM 文件為止。不過，您無法刪除正在共享的文件。您必須先停止共享，然後才能將其刪除止。
### 停止分享文件 (主控台)
**停止共享文件**
1. 在 https：//[https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/) 開啟 AWS Systems Manager 主控台。
1. 在導覽窗格中，選擇 **Documents (文件)**。
1. 在文件清單中，選擇要停止共用的文件，然後選擇**詳細資訊**。在**許可**區段中，確認您是文件擁有者。只有文件擁有者可以停止共享文件。
1. 選擇**編輯**。
1. 選擇 **X** 刪除不應再存取命令的 AWS 帳戶 ID，然後選擇**儲存**。
### 停止分享文件 (命令列)
在本機 AWS Tools for Windows PowerShell 電腦上開啟 AWS CLI 或 ，並執行下列命令來停止共用命令。
------
#### [ Linux & macOS ]
```
aws ssm modify-document-permission \
--name document name \
--permission-type Share \
--account-ids-to-remove 'AWS 帳戶 ID'
```
------
#### [ Windows ]
```
aws ssm modify-document-permission ^
--name document name ^
--permission-type Share ^
--account-ids-to-remove "AWS 帳戶 ID"
```
------
#### [ PowerShell ]
```
Edit-SSMDocumentPermission `
-Name document name `
-PermissionType Share `
–AccountIdsToRemove AWS 帳戶 ID
```
------
## 使用共用的 SSM 文件
當您共用 AWS Systems Manager (SSM) 文件時，系統會產生 Amazon Resource Name (ARN)，並將其指派給 命令。如果您從 Systems Manager 主控台選取和執行共用文件，則不會看到 ARN。但是，如果您想要使用 Systems Manager 主控台以外的其他方法執行共用的 SSM 文件，則必須為 `DocumentName` 請求參數指定文件的完整 ARN。當您執行命令列出文件時，系統會顯示 SSM 文件的完整 ARN。
**注意**
您不需要為 AWS 公有文件 （以 開頭的文件`AWS-*`) 或您擁有的文件指定 ARNs。
### 使用共用的 SSM 文件 (命令列)
**列出所有公有 SSM 文件**
------
#### [ Linux & macOS ]
```
aws ssm list-documents \
--filters Key=Owner,Values=Public
```
------
#### [ Windows ]
```
aws ssm list-documents ^
--filters Key=Owner,Values=Public
```
------
#### [ PowerShell ]
```
$filter = New-Object Amazon.SimpleSystemsManagement.Model.DocumentKeyValuesFilter
$filter.Key = "Owner"
$filter.Values = "Public"
Get-SSMDocumentList `
-Filters @($filter)
```
------
**列出已與您共用的私有 SSM 文件**
------
#### [ Linux & macOS ]
```
aws ssm list-documents \
--filters Key=Owner,Values=Private
```
------
#### [ Windows ]
```
aws ssm list-documents ^
--filters Key=Owner,Values=Private
```
------
#### [ PowerShell ]
```
$filter = New-Object Amazon.SimpleSystemsManagement.Model.DocumentKeyValuesFilter
$filter.Key = "Owner"
$filter.Values = "Private"
Get-SSMDocumentList `
-Filters @($filter)
```
------
**列出可供您使用的所有 SSM 文件**
------
#### [ Linux & macOS ]
```
aws ssm list-documents
```
------
#### [ Windows ]
```
aws ssm list-documents
```
------
#### [ PowerShell ]
```
Get-SSMDocumentList
```
------
**取得已與您共用的 SSM 文件的相關資訊**
------
#### [ Linux & macOS ]
```
aws ssm describe-document \
--name arn:aws:ssm:us-east-2:12345678912:document/documentName
```
------
#### [ Windows ]
```
aws ssm describe-document ^
--name arn:aws:ssm:us-east-2:12345678912:document/documentName
```
------
#### [ PowerShell ]
```
Get-SSMDocumentDescription `
–Name arn:aws:ssm:us-east-2:12345678912:document/documentName
```
------
**執行共用的 SSM 文件**
------
#### [ Linux & macOS ]
```
aws ssm send-command \
--document-name arn:aws:ssm:us-east-2:12345678912:document/documentName \
--instance-ids ID
```
------
#### [ Windows ]
```
aws ssm send-command ^
--document-name arn:aws:ssm:us-east-2:12345678912:document/documentName ^
--instance-ids ID
```
------
#### [ PowerShell ]
```
Send-SSMCommand `
–DocumentName arn:aws:ssm:us-east-2:12345678912:document/documentName `
–InstanceIds ID
```
------
# 搜尋 SSM 文件
您可以使用任意文字搜尋或以篩選條件為基礎的搜尋，在 AWS Systems Manager (SSM) 文件存放區中搜尋 SSM 文件。您可以收藏文件，以協助您尋找常用的 SSM 文件。下列各節說明如何使用這些功能。
## 使用任意文字搜尋
Systems Manager **文件**頁面中的搜尋方塊支援任意文字搜尋。任意文字搜尋會根據每個 SSM 文件中的文件名稱來比較搜尋詞語或您輸入的詞語。如果您輸入單個搜尋詞語，例如 **ansible**，則 Systems Manager 會傳回含有此詞語的所有 SSM 文件。如果您輸入多個搜尋詞語，則 Systems Manager 會使用 `OR` 陳述式進行搜尋。例如，如果您指定 **ansible** 和 **linux**，然後搜尋會傳回其名稱中含有*任何一個*關鍵字的所有文件。
如果您輸入任意文字搜尋詞語，並選擇搜尋選項，例如 **平台類型**，則搜尋會使用 `AND` 陳述式，並傳回名稱中包含關鍵字和指定平台類型的所有文件。
**注意**
請注意下列有關任意文字搜尋的詳細資訊。
任意文字搜尋*不*區分大小寫。
搜尋詞語要求最少三個字元，最多 20 個字元。
任意文字搜尋最多可接受五個搜尋詞語。
如果您在搜尋詞語之間輸入空格，系統會在搜尋時包含空格。
您可以將任意文字搜尋與其他搜尋選項 (例如**文件類型**或**平台類型**) 結合在一起。
**文件名稱字首**篩選條件和任意文字搜尋不能一起使用。它們相互排斥。
**若要搜尋 SSM 文件**
1. 在 https：//[https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/) 開啟 AWS Systems Manager 主控台。
1. 在導覽窗格中，選擇 **Documents (文件)**。
1. 在搜尋方塊中輸入您的搜尋詞語，然後按 Enter 鍵。
### 使用 執行任意文字文件搜尋 AWS CLI
**若要使用 CLI 執行任意文字文件搜尋**
1. 如果您尚未安裝並設定 AWS Command Line Interface (AWS CLI)，請安裝並設定 。
如需相關資訊，請參閱[安裝或更新最新版本的 AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)。
1. 若要使用單一詞語執行任意文字文件搜尋，請執行以下命令。在此命令中，用您自己的資訊取代 *search\$1term*。
```
aws ssm list-documents --filters Key="SearchKeyword",Values="search_term"
```
範例如下。
```
aws ssm list-documents --filters Key="SearchKeyword",Values="aws-asg" --region us-east-2
```
若要使用多個詞語進行搜尋 (建立 `AND` 陳述式)，執行下列命令。在此命令中，用您自己的資訊取代 *search\$1term\$11* 和 *search\$1term\$12*。
```
aws ssm list-documents --filters Key="SearchKeyword",Values="search_term_1","search_term_2","search_term_3" --region us-east-2
```
範例如下。
```
aws ssm list-documents --filters Key="SearchKeyword",Values="aws-asg","aws-ec2","restart" --region us-east-2
```
## 使用篩選條件
Systems Manager **文件**頁面會在您選擇搜尋方塊時自動顯示下列篩選條件。
+ 文件名稱字首
+ 平台類型
+ 文件類型
+ 標籤鍵
![\[SSM 文件頁面上的篩選條件選項。\]](http://docs.aws.amazon.com/zh_tw/systems-manager/latest/userguide/images/ssm-documents-filters-1.png)
您可以使用單一篩選條件來搜尋 SSM 文件。如果您想要傳回更具體的 SSM 文件集，可以套用多個篩選條件。以下是使用**平台類型**與**文件名稱字首**篩選條件的搜尋範例。
![\[在 SSM 文件頁面上套用多個篩選條件選項。\]](http://docs.aws.amazon.com/zh_tw/systems-manager/latest/userguide/images/ssm-documents-filters-2.png)
如果您套用多個篩選條件，Systems Manager 會根據您選擇的篩選條件建立不同的搜尋陳述式：
+ 如果您多次套用*相同*篩選條件，例如**文件名稱字首**，Systems Manager 會使用 `OR` 陳述式進行搜尋。例如，如果您指定的一個篩選條件為**文件名稱字首**=**AWS**，第二個篩選條件為**文件名稱字首**=**Lambda**，則搜尋會傳回字首為 "`AWS`" 的所有文件以及字首為 "`Lambda`" 的所有文件。
+ 如果套用*不同的*篩選條件，例如 **Document name prefix** (文件名稱字首) 和 **Platform types** (平台類型)，則 Systems Manager 會使用 `AND` 陳述式進行搜尋。例如，如果指定 **Document name prefix** (文件名稱字首) = **AWS** 篩選條件、**Platform types** (平台類型) = **Linux** 篩選條件，則搜尋會傳回特定於 Linux 平台且字首為「`AWS`」的所有文件。
**注意**
使用篩選條件的搜尋會區分大小寫。
## 將文件新增至收藏
為了協助您尋找常用的 SSM 文件，請將文件新增至收藏。每個 AWS 帳戶 和 每個文件類型最多可以收藏 20 個文件 AWS 區域。您可以從文件 AWS 管理主控台選擇、修改及檢視收藏。下列程序說明如何選擇、修改和檢視收藏。
**收藏 SSM 文件**
1. 在 https：//[https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/) 開啟 AWS Systems Manager 主控台。
1. 在導覽窗格中，選擇 **Documents (文件)**。
1. 選擇要收藏的文件名稱旁的星形圖示。
**從收藏移除 SSM 文件**
1. 在 https：//[https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/) 開啟 AWS Systems Manager 主控台。
1. 在導覽窗格中，選擇 **Documents (文件)**。
1. 取消選擇要移出收藏的文件名稱旁的星形圖示。
**從文件檢視您的最愛 AWS 管理主控台**
1. 在 https：//[https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/) 開啟 AWS Systems Manager 主控台。
1. 在導覽窗格中，選擇 **Documents (文件)**。
1. 選取**收藏**索引標籤。
# 對參數處理問題進行疑難排解
## 常見的參數處理問題
**執行期間無法使用的環境變數**
**問題：**由於找不到環境變數 (`SSM_parameter-name`)，命令失敗。
**可能原因：**
+ SSM Agent 版本不支援環境變數插補
+ `interpolationType` 未設定為 `ENV_VAR`
+ 參數名稱不符合預期的環境變數名稱
**解決方案**：
+ 驗證 SSM Agent 版本是否為 3.3.2746.0 或更新版本
+ 新增舊版 Agent 的備用邏輯：
```
if [ -z "${SSM_parameterName+x}" ]; then
export SSM_parameterName="{{parameterName}}"
fi
```
**參數值包含特殊字元**
**問題：**當參數值包含空格、引號或其他特殊字元時，命令失敗。
**解決方案**：
+ 引用環境變數時使用適當的引號：
```
# Correct
echo "$SSM_parameter-name"
# Incorrect
echo $SSM_parameter-name
```
+ 使用 `allowedPattern` 新增輸入驗證以限制特殊字元
**跨平台的不一致行為**
**問題：**參數處理在 Linux 和 Windows Server 系統上的運作方式不同。
**解決方案**：
+ 使用平台特定的環境變數語法：
```
# PowerShell
$env:SSM_parameter-name
# Bash
$SSM_parameter-name
```
+ 在您的文件中使用平台特定的先決條件檢查
**參數值未正確逸出**
**問題：**儘管使用了環境變數插補，仍存在命令注入漏洞。
**解決方案**：
+ 命令中包含參數值時，一律使用適當的逸出：
```
# Correct
mysql_command="mysql -u \"$SSM_username\" -p\"$SSM_password\""
# Incorrect
mysql_command="mysql -u $SSM_username -p$SSM_password"
```
## 參數驗證技巧
使用以下技巧來驗證參數處理：
1. 測試環境變數可用性：
```
#!/bin/bash
# Print all SSM_ environment variables
env | grep ^SSM_
# Test specific parameter
if [ -n "$SSM_parameter" ]; then
echo "Parameter is available"
else
echo "Parameter is not available"
fi
```
1. 驗證參數模式：
```
parameters:
myParameter:
type: String
allowedPattern: "^[a-zA-Z0-9_-]+$"
description: "Test this pattern with sample inputs"
```
1. 包含錯誤處理：
```
if [[ ! "$SSM_parameter" =~ ^[a-zA-Z0-9_-]+$ ]]; then
echo "Parameter validation failed"
exit 1
fi
```