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

# 会话文档架构
<a name="session-manager-schema"></a>

以下信息介绍了会话文档的架构元素。AWS Systems Manager Session Manager 使用会话文档来确定要启动哪些类型的会话，例如标准会话、端口转发会话或运行交互式命令的会话。

 [schemaVersion](#version)   
会话文档的架构版本。会话文档仅支持版本 1.0。  
类型：字符串  
是否必需：是

 [description](#descript)   
为会话文档指定的描述。例如，“用于启动与 Session Manager 的端口转发会话的文档”。  
类型：字符串  
必需：否

 [sessionType](#type)   
会话文档用于建立的会话类型。  
类型：字符串  
是否必需：是  
有效值：`InteractiveCommands` \| `NonInteractiveCommands` \| `Port` \| `Standard_Stream`

 [inputs](#in)   
用于使用此会话文档建立的会话的会话首选项。用于创建 `Standard_Stream` 会话的会话文档需要此元素。  
类型：StringMap  
必需：否    
 [s3BucketName](#bucket)   
您希望在会话结束时将会话日志发送到的 Amazon Simple Storage Service (Amazon S3) 存储桶。  
类型：字符串  
必需：否  
 [s3KeyPrefix](#prefix)   
将日志发送到您在输入 `s3BucketName` 时指定的 Amazon S3 存储桶时使用的前缀。有关对 Amazon S3 中存储的对象使用共享前缀的更多信息，请参阅 *Amazon Simple Storage Service 用户指南*中的[如何在 S3 存储桶中使用文件夹？](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/using-folders.html)。  
类型：字符串  
必需：否  
 [s3EncryptionEnabled](#s3Encrypt)   
如果设置为 `true`，则输入 `s3BucketName` 时指定的 Amazon S3 存储桶必须进行加密。  
类型：布尔值  
是否必需：是  
 [cloudWatchLogGroupName](#logGroup)   
您希望在会话结束时将会话日志发送到的 Amazon CloudWatch Logs (CloudWatch Logs) 组名称。  
类型：字符串  
必需：否  
 [cloudWatchEncryptionEnabled](#cwEncrypt)   
如果设置为 `true`，则输入 `cloudWatchLogGroupName` 时指定的日志组必须进行加密。  
类型：布尔值  
是否必需：是  
 [cloudWatchStreamingEnabled](#cwStream)   
如果设置为 `true`，会话数据日志流将持续发送到您在输入 `cloudWatchLogGroupName` 时指定的日志组。如果设置为 `false`，会话日志将在会话结束时发送到您在输入 `cloudWatchLogGroupName` 时指定的日志组。  
类型：布尔值  
是否必需：是  
 [kmsKeyId](#kms)   
您要用来进一步加密本地客户端与所连接的 Amazon Elastic Compute Cloud (Amazon EC2) 托管式节点之间数据的 AWS KMS key 的 ID。  
类型：字符串  
必需：否  
 [runAsEnabled](#run)   
如果设置为 `true`，则必须在 `runAsDefaultUser` 输入中指定一个存在于要连接的托管式节点上的用户账户。否则，会话将无法启动。默认情况下，会话使用 AWS Systems Manager SSM Agent 创建的 `ssm-user` 账户启动。只有连接到 Linux 和 macOS 托管节点才支持“运行身份”功能。  
类型：布尔值  
是否必需：是  
 [runAsDefaultUser](#runUser)   
当 `runAsEnabled` 输入设置为 `true` 时，用于在 Linux 和 macOS 托管节点上启动会话的用户账户的名称。您为此输入指定的用户账户必须存在于要连接的托管式节点上；否则，会话将无法启动。在确定要使用的操作系统用户账户时，Session Manager 会按以下顺序进行检查：IAM 用户的会话标签上的 `SSMSessionRunAs` 标签，然后是代入的 IAM 角色上的 `SSMSessionRunAs` 标签，最后是会话首选项中的此 `runAsDefaultUser` 值。有关更多信息，请参阅 [为 Linux 和 macOS 托管式节点开启“运行身份”支持](session-preferences-run-as.md)。  
类型：字符串  
必需：否  
 [idleSessionTimeout](#timeout)   
结束会话前允许处于非活动状态的时间长度。此输入以分钟为单位。  
类型：字符串  
有效值：1-60  
必需：否  
 [maxSessionDuration](#maxDuration)   
会话结束前允许的最长时间。此输入以分钟为单位。  
类型：字符串  
有效值：1-1440  
必需：否  
 [shellProfile](#shell)   
根据操作系统指定的要在会话中应用的首选项，例如 Shell 首选项、环境变量、工作目录以及在启动会话时运行多个命令。  
类型：StringMap  
必需：否    
 [windows](#win)   
为 Windows Server 托管式节点上的会话指定的 Shell 首选项、环境变量、工作目录和命令。  
类型：字符串  
必需：否  
 [linux](#lin)   
为 Linux 和 macOS 托管节点上的会话指定的 Shell 首选项、环境变量、工作目录和命令。  
类型：字符串  
必需：否

 [parameters](#param)   
定义文档接受的参数的对象。有关定义文档参数的更多信息，请参阅[顶级数据元素](documents-syntax-data-elements-parameters.md#top-level)中的**参数**。对于经常引用的参数，建议在 Systems Manager Parameter Store 中存储这些参数，以便进行引用。您可以在文档的这一部分引用 `String` 和 `StringList` Parameter Store 参数。您不能在文档的这一部分引用 `SecureString` Parameter Store 参数。您可以使用以下格式引用 Parameter Store 参数：  

```
{{ssm:{{parameter-name}}}}
```
有关 Parameter Store 的更多信息，请参阅 [AWS Systems Manager Parameter Store](systems-manager-parameter-store.md)。  
类型：StringMap  
必需：否

 [properties](#props)   
在 `StartSession` API 操作中使用的一个对象，其值由您指定。  
对于用于 `InteractiveCommands` 会话的会话文档，属性对象包含要在您指定的操作系统上运行的命令。您还可以 `runAsElevated` 布尔属性来确定命令是否作为 `root` 运行。有关更多信息，请参阅[限制对会话中命令的访问](session-manager-restrict-command-access.md)。  
对于用于 `Port` 会话的会话文档，属性对象包含应将流量重定向到的端口号。有关示例，请参阅本主题后文中的 `Port` 类型会话文档示例。  
类型：StringMap  
必需：否

`Standard_Stream` 类型会话文档示例

------
#### [ YAML ]

```
---
schemaVersion: '1.0'
description: Document to hold regional settings for Session Manager
sessionType: Standard_Stream
inputs:
  s3BucketName: ''
  s3KeyPrefix: ''
  s3EncryptionEnabled: true
  cloudWatchLogGroupName: ''
  cloudWatchEncryptionEnabled: true
  cloudWatchStreamingEnabled: true
  kmsKeyId: ''
  runAsEnabled: true
  runAsDefaultUser: ''
  idleSessionTimeout: '20'
  maxSessionDuration: '60'
  shellProfile:
    windows: ''
    linux: ''
```

------
#### [ JSON ]

```
{
    "schemaVersion": "1.0",
    "description": "Document to hold regional settings for Session Manager",
    "sessionType": "Standard_Stream",
    "inputs": {
        "s3BucketName": "",
        "s3KeyPrefix": "",
        "s3EncryptionEnabled": true,
        "cloudWatchLogGroupName": "",
        "cloudWatchEncryptionEnabled": true,
        "cloudWatchStreamingEnabled": true,
        "kmsKeyId": "",
        "runAsEnabled": true,
        "runAsDefaultUser": "",
        "idleSessionTimeout": "20",
        "maxSessionDuration": "60",
        "shellProfile": {
            "windows": "date",
            "linux": "pwd;ls"
        }
    }
}
```

------

`InteractiveCommands` 类型会话文档示例

------
#### [ YAML ]

```
---
schemaVersion: '1.0'
description: Document to view a log file on a Linux instance
sessionType: InteractiveCommands
parameters:
  logpath:
    type: String
    description: The log file path to read.
    default: "/var/log/amazon/ssm/amazon-ssm-agent.log"
    allowedPattern: "^[a-zA-Z0-9-_/]+(.log)$"
properties:
  linux:
    commands: "tail -f {{ logpath }}"
    runAsElevated: true
```

------
#### [ JSON ]

```
{
    "schemaVersion": "1.0",
    "description": "Document to view a log file on a Linux instance",
    "sessionType": "InteractiveCommands",
    "parameters": {
        "logpath": {
            "type": "String",
            "description": "The log file path to read.",
            "default": "/var/log/amazon/ssm/amazon-ssm-agent.log",
            "allowedPattern": "^[a-zA-Z0-9-_/]+(.log)$"
        }
    },
    "properties": {
        "linux": {
            "commands": "tail -f {{ logpath }}",
            "runAsElevated": true
        }
    }
}
```

------

`Port` 类型会话文档示例

------
#### [ YAML ]

```
---
schemaVersion: '1.0'
description: Document to open given port connection over Session Manager
sessionType: Port
parameters:
  paramExample:
    type: string
    description: document parameter
properties:
  portNumber: {{anyPortNumber}}
```

------
#### [ JSON ]

```
{
    "schemaVersion": "1.0",
    "description": "Document to open given port connection over Session Manager",
    "sessionType": "Port",
    "parameters": {
        "paramExample": {
            "type": "string",
            "description": "document parameter"
        }
    },
    "properties": {
        "portNumber": "anyPortNumber"
    }
}
```

------

包含特殊字符的会话文档示例

------
#### [ YAML ]

```
---
schemaVersion: '1.0'
description: Example document with quotation marks
sessionType: InteractiveCommands
parameters:
  Test:
    type: String
    description: Test Input
    maxChars: 32
properties:
  windows:
    commands: |
        $Test = '{{ Test }}'
        $myVariable = \"Computer name is $env:COMPUTERNAME\"
        Write-Host "Test variable: $myVariable`.`nInput parameter: $Test"
    runAsElevated: false
```

------
#### [ JSON ]

```
{
   "schemaVersion":"1.0",
   "description":"Test document with quotation marks",
   "sessionType":"InteractiveCommands",
   "parameters":{
      "Test":{
         "type":"String",
         "description":"Test Input",
         "maxChars":32
      }
   },
   "properties":{
      "windows":{
         "commands":[
            "$Test = '{{ Test }}'",
            "$myVariable = \\\"Computer name is $env:COMPUTERNAME\\\"",
            "Write-Host \"Test variable: $myVariable`.`nInput parameter: $Test\""
         ],
         "runAsElevated":false
      }
   }
}
```

------