• 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)。

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 工作階段文件結構描述
<a name="session-manager-schema"></a>

下列資訊說明工作階段文件的結構描述元素。 AWS Systems Manager Session Manager使用工作階段文件來判斷要啟動的工作階段類型，例如標準工作階段、連接埠轉送工作階段或執行互動式命令的工作階段。

 [schemaVersion](#version)   
工作階段文件的結構描述版本。工作階段文件僅支援 1.0 版。  
類型：字串  
必要：是

 [description](#descript)   
您為工作階段文件指定的描述。例如，"Document to start port forwarding session with Session Manager" (使用 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 Simple Storage Service (Amazon S3) 儲存貯體時使用的字首。如需有關搭配使用公用字首與 Amazon Simple Storage Service (Amazon S3) 中存放的物件的詳細資訊，請參閱《*Amazon Simple Storage Service 使用者指南*》中的[如何使用 S3 儲存貯體中的資料夾？](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/using-folders.html)。  
類型：字串  
必要：否  
 [s3EncryptionEnabled](#s3Encrypt)   
如果設定為 `true`，則必須加密在 `s3BucketName` 輸入中指定的 Amazon Simple Storage Service (Amazon S3) 儲存貯體。  
類型：布林值  
必要：是  
 [cloudWatchLogGroupName](#logGroup)   
在工作階段結束時接收工作階段日誌的 Amazon CloudWatch Logs (CloudWatch Logs) 群組的名稱。  
類型：字串  
必要：否  
 [cloudWatchEncryptionEnabled](#cwEncrypt)   
如果設定為 `true`，則必須加密在 `cloudWatchLogGroupName` 輸入中指定的 日誌群組。  
類型：布林值  
必要：是  
 [cloudWatchStreamingEnabled](#cwStream)   
如果設定為 `true`，工作階段資料日誌的持續串流會傳送到您在 `cloudWatchLogGroupName` 輸入中指定的日誌群組。如果設定為 `false`，在工作階段結束時，工作階段日誌會傳送到您在 `cloudWatchLogGroupName` 輸入中指定的日誌群組。  
類型：布林值  
必要：是  
 [kmsKeyId](#kms)   
 AWS KMS key 您要用來進一步加密本機用戶端機器與連線的 Amazon Elastic Compute Cloud (Amazon EC2) 受管節點之間的資料 ID。  
類型：字串  
必要：否  
 [runAsEnabled](#run)   
如果設定為 `true`，則必須在 `runAsDefaultUser` 輸入中指定您將連線的受管節點上存在的使用者帳戶。否則，工作階段將無法啟動。根據預設，使用 AWS Systems Manager SSM Agent 建立的 `ssm-user` 帳戶來啟動工作階段。僅連線至 Linux 和 macOS 受管節點時才支援執行身分功能。  
類型：布林值  
必要：是  
 [runAsDefaultUser](#runUser)   
當 macOS 輸入設定為 `true` 時，在 Linux 和 `runAsEnabled` 受管節點上啟動工作階段的使用者帳戶名稱。您為此輸入指定的使用者帳戶必須存在於您要連線的受管節點上；否則，工作階段將無法啟動。決定要使用的作業系統使用者帳戶時， 會依下列順序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
      }
   }
}
```

------