• Amazon Systems Manager CloudWatch 控制面板在 2026 年 4 月 30 日之后将不再可用。客户可以像现在一样继续使用 Amazon CloudWatch 控制台来查看、创建和管理其 Amazon CloudWatch 控制面板。有关更多信息，请参阅 [Amazon CloudWatch 控制面板文档](https://docs.amazonaws.cn/AmazonCloudWatch/latest/monitoring/CloudWatch_Dashboards.html)。

# 创建 SSM 文档内容


如果 Amazon Systems Manager 公有文档不执行要对 Amazon 资源执行的所有操作，您可以创建自己的 SSM 文档。您还可以使用控制台克隆 SSM 文档。克隆文档将内容从现有文档复制到可以修改的新文档。创建或克隆文档时，文档的内容不得超过 64KB。此配额还包括在运行时指定的输入参数内容。创建新的 `Command` 或 `Policy` 文档时，我们建议您使用版本 2.2 或更高版本的架构，以便利用最新功能，例如文档编辑、自动版本控制、排序等。

## 编写 SSM 文档内容


要创建您自己的 SSM 文档内容，请务必了解可用于 SSM 文档的不同架构、功能、插件和语法。我们建议您熟悉以下资源。
+  [编写您自己的 Amazon Systems Manager 文档](https://www.amazonaws.cn/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-actions.md) 
+  [自动化系统变量](automation-variables.md) 
+  [其他运行手册示例](automation-document-examples.md) 
+  使用Amazon Toolkit for Visual Studio Code [处理 Systems Manager 自动化运行手册](https://docs.amazonaws.cn/toolkit-for-vscode/latest/userguide/systems-manager-automation-docs.html) 
+  [自动化运行手册的视觉对象设计体验](automation-visual-designer.md) 
+  [在运行手册中使用脚本](automation-document-script-considerations.md) 

Amazon 预定义的 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 访问的 Amazon 服务自有资源以及如何配置数据边界策略的信息，请参阅 [Amazon Systems Manager 中的数据边界](data-perimeters.md)。

## 克隆 SSM 文档


您可以克隆 Amazon Systems Manager 文档，使用 Systems Manager 文档控制台创建 SSM 文档。克隆 SSM 文档将内容从现有文档复制到可以修改的新文档中。无法克隆大于 64KB 的文档。

**克隆 SSM 文档**

1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.amazonaws.cn/systems-manager/)，打开 Amazon Systems Manager 控制台。

1. 在导航窗格中，选择**文档**。

1. 在搜索框中，输入要克隆的文档的名称。

1. 选择要克隆的文档的名称，然后选择**操作**下拉菜单中的**克隆文档**。

1. 根据需要修改文档，然后选择**创建文档**保存文档。

编写 SSM 文档内容后，您可以通过以下方法之一使用您的内容创建 SSM 文档。

**Topics**
+ [

## 编写 SSM 文档内容
](#writing-ssm-doc-content)
+ [

## 克隆 SSM 文档
](#cloning-ssm-document)
+ [

## 创建复合文档
](#documents-creating-composite)

## 创建复合文档


*复合* Amazon Systems Manager (SSM) 文档是自定义文档，可通过运行一个或多个次要 SSM 文档执行一系列操作。复合文档允许您为常见任务（例如引导软件或域加入实例）创建一组标准 SSM 文档，从而升级*基础设施代码*。您随后可以在同一个 Amazon Web Services 区域 中跨 Amazon Web Services 账户 共享这些文档，从而减少 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) 插件，可从 GitHub 公有存储库将 SSM 文档下载到名为 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)。