• 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)。
本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 建立 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)。