• 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 公有 Runbook 不支援您想要在 AWS 資源上執行的所有動作，您可以建立自己的 Runbook。若要建立自訂 Runbook，您可以利用適當的自動化動作來手動建立本機 YAML 或 JSON 格式檔案。或者，您可以使用 Systems Manager Automation 主控台中的文件建置器來建置自訂執行手冊。
使用文件建置器，您可以將自動化動作新增至自訂執行手冊，並提供必要的參數，而不需使用 JSON 或 YAML 語法。新增步驟並建立 Runbook 之後，系統會將您新增的動作轉換成 YAML 格式，以便 Systems Manager 可以用來執行自動化。
Runbook 支援使用 Markdown (一種標示語言)，可讓您新增維基樣式的描述至 Runbook 內，以及在 Runbook 內新增個別步驟。如需使用 Markdown 的相關資訊，請參閱[在 AWS中使用 Markdown](https://docs.aws.amazon.com/general/latest/gr/aws-markdown.html)。
## 使用文件建置器建立自訂執行手冊
**開始之前**
建議您了解可在執行手冊中使用的不同動作。如需詳細資訊，請參閱[Systems Manager Automation 動作參考](automation-actions.md)。
**使用文件建置器建立自訂 Runbook**
1. 在 https：//[https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/) 開啟 AWS Systems Manager 主控台。
1. 在導覽窗格中，選擇 **Documents (文件)**。
1. 選擇 **Create automation (建立自動化)**。
1. 對於 **Name** (名稱)，輸入 Runbook 的描述性名稱。
1. 對於 **Document description** (文件描述)，提供 Runbook 的 Markdown 樣式描述。您可以提供使用 Runbook、編號步驟或任何其他類型的資訊的指示來描述 Runbook。如需格式化內容的相關資訊，請參閱預設文字。
**提示**
在 **Hide preview (隱藏預覽)** 和 **Show preview (顯示預覽)** 之間切換，即可在撰寫時查看描述內容的外觀。
1. (選用) 對於 **Assume role (擔任角色)**，輸入要代表您執行動作的服務角色的名稱或 ARN。如果您未指定角色，自動化會使用執行自動化之使用者的存取許可。
**重要**
對於使用 `aws:executeScript` 動作的非 Amazon 擁有的 Runbook，必須指定角色。如需相關資訊，請參閱[使用 Runbook 的許可](automation-document-script-considerations.md#script-permissions)。
1. (選用) 對於 **Outputs** (輸出)，輸入用於此 Runbook 自動化以提供其他處理程序使用的任何輸出。
例如，如果您的 Runbook 建立了新的 AMI，您可以指定 ["CreateImage.ImageId"]，然後使用此輸出在後續的自動化中建立新的執行個體。
1. (選用) 展開 **Input parameters (輸入參數)** 區段，並執行下列動作。
1. 對於 **Parameter name** (參數名稱)，輸入您要建立的 Runbook 參數的描述性名稱。
1. 對於 **Type (類型)**，選擇參數的類型，例如 `String` 或 `MapList`。
1. 對於 **Required (必要)**，執行下列其中一項作業：
+ 如果必須在執行時間提供此 Runbook 參數的值，請選擇 **Yes** (是)。
+ 如果不需要參數，請選擇 **No** (否)，並 (選擇性地) 在 **Default value** (預設值) 中輸入預設參數值。
1. 對於 **Description** (描述)，輸入 Runbook 參數的描述。
**注意**
若要新增更多 Runbook 參數，請選擇 **Add a parameter** (新增參數)。若要移除 Runbook 參數，請選擇 **X** (移除) 按鈕。
1. (選用) 展開 **Target type** (目標類型) 區段，並選擇目標類型，以定義自動化可執行所在的資源類型。例如，若要在 EC2 執行個體上使用 Runbook，請選擇 `/AWS::EC2::Instance`。
**注意**
如果您指定 '`/`' 的值，則 Runbook 可以在所有類型的資源上執行。如需有效資源類型的清單，請參閱《*AWS CloudFormation 使用者指南*》 中的 [AWS 資源類型參考](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-template-resource-type-ref.html)。
1. (選用) 展開 **Document tags** (文件標籤) 區段，並輸入要套用至 Runbook 的一或多個標籤鍵值組。標籤可讓您更容易識別、組織和搜尋資源。
1. 在 **Step 1 (步驟 1)** 區段中，提供下列資訊。
+ 對於 **Step name** (步驟名稱)，輸入自動化第一個步驟的描述性名稱。
+ 對於 **Action type (動作類型)**，選取要用於此步驟的動作類型。
如需可用動作類型的清單和資訊，請參閱[Systems Manager Automation 動作參考](automation-actions.md)。
+ 對於 **Description (描述)**，輸入自動化步驟的描述。您可以使用 Markdown 來將文字格式化。
+ 根據選取的 **Action type (動作類型)**，在 **Step inputs (步驟輸入)** 區段中輸入動作類型的必要輸入。例如，如果您選取動作 `aws:approve`，則必須指定 `Approvers` 屬性的值。
如需步驟輸入欄位的相關資訊，請參閱 [Systems Manager Automation 動作參考](automation-actions.md) 中您所選動作類型的項目。例如：[`aws:executeStateMachine` – 執行 AWS Step Functions 狀態機器](automation-action-executeStateMachine.md)。
+ (選用) 對於 **Additional inputs** (其他輸入)，提供 Runbook 所需的任何其他輸入值。可用的輸入類型取決於您為步驟選取的動作類型。(請注意，某些動作類型需要輸入值。)
**注意**
若要新增更多輸入，請選擇 **Add optional input (新增選用輸入)**。若要移除輸入，請選擇 **X** (移除) 按鈕。
+ (選用) 對於 **Outputs** (輸出)，輸入用於此步驟以提供其他處理程序使用的任何輸出。
**注意**
**Outputs (輸出)** 不適用所有動作類型。
+ (選用) 展開 **Common properties** (一般屬性) 區段，並指定所有 Automation 動作通用的動作屬性。例如，對於 **Timeout seconds** (逾時秒)，您可以以秒為單位提供值，以指定步驟在停止之前可以執行的時間長度。
如需詳細資訊，請參閱[依所有動作共用的屬性](automation-actions.md#automation-common)。
**注意**
若要新增更多步驟，請選取 **Add step** (新增步驟)，然後重複建立步驟的程序。若要移除步驟，請選擇 **Remove step** (移除步驟)。
1. 選擇 **Create automation** (建立自動化) 以儲存 Runbook。
## 建立執行指令碼的執行手冊
下列程序顯示如何在 AWS Systems Manager Automation 主控台中使用文件建置器，以建立可執行指令碼的自訂執行手冊。
您建立 Runbook 的第一個步驟會執行指令碼來啟動 Amazon Elastic Compute Cloud (Amazon EC2) 執行個體。第二個步驟會執行另一個指令碼來監控要變更為 `ok` 的執行個體狀態檢查。然後，會報告自動化的 `Success` 整體狀態。
**開始之前**
請確認您已完成下列步驟：
+ 確認您具有管理員許可，或已獲授與適當的許可，才能存取 AWS Identity and Access Management (IAM) 中的 Systems Manager。
如需相關資訊，請參閱[驗證 Runbook 的使用者存取權](automation-setup.md#automation-setup-user-access)。
+ 確認您的 AWS 帳戶帳戶中具有用於自動化的 IAM 服務角色 (也稱為*擔任角色*)。此角色是必要的，因為此演練使用 `aws:executeScript` 動作。
如需建立此角色的詳細資訊，請參閱[設定自動化的服務角色 (擔任角色) 存取權](automation-setup.md#automation-setup-configure-role)。
如需執行 `aws:executeScript` 之 IAM 服務角色需求的相關資訊，請參閱 [使用 Runbook 的許可](automation-document-script-considerations.md#script-permissions)。
+ 確認您有啟動 EC2 執行個體的許可。
如需相關資訊，請參閱《Amazon EC2 使用者指南》**中的 [IAM 和 Amazon EC2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/UsingIAM.html#intro-to-iam)。
**使用文件建置器建立執行指令碼的自訂執行手冊**
1. 在 https：//[https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/) 開啟 AWS Systems Manager 主控台。
1. 在導覽窗格中，選擇 **Documents (文件)**。
1. 選擇 **Create automation (建立自動化)**。
1. 對於 **Name** (名稱)，輸入 Runbook 的描述性名稱：**LaunchInstanceAndCheckStatus**。
1. (選用) 對於 **Document description** (文件描述)，使用 Markdown，以此 Runbook 的描述取代預設文字。下列是 範例。
```
##Title: LaunchInstanceAndCheckState
-----
**Purpose**: This runbook first launches an EC2 instance using the AMI ID provided in the parameter ```imageId```. The second step of this runbook 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 2023 AMI ID available. | {{ ssm:/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-arm64 }}
```
1. 對於 **Assume role** (擔任角色)，輸入對於自動化執行，用於自動化 (擔任角色) 的 IAM 服務角色的 ARN，格式為 **arn:aws:iam::111122223333:role/AutomationServiceRole**。將您的 AWS 帳戶 ID 替換為 111122223333。
您指定的角色是用來提供開始自動化所需的許可。
**重要**
對於使用 `aws:executeScript` 動作的非 Amazon 擁有的 Runbook，必須指定角色。如需相關資訊，請參閱[使用 Runbook 的許可](automation-document-script-considerations.md#script-permissions)。
1. 展開 **Input parameters (輸入參數)**，然後執行下列動作。
1. 對於 **Parameter name (參數名稱)**，輸入 **imageId**。
1. 針對 **Type (類型)**，選擇 **String**。
1. 對於 **Required (必要)**，選擇 `No`。
1. 對於 **Default value (預設值)**，輸入以下內容。
```
{{ ssm:/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-arm64 }}
```
**注意**
此值會使用最新的 Amazon Linux 2023 Amazon Machine Image (AMI) ID 啟動 Amazon EC2 執行個體。如果您想使用不同的 AMI，請以您的 AMI ID 取代該值。
1. 對於 **Description (描述)**，輸入以下內容。
```
(Optional) The AMI ID to use for launching the instance. The default value uses the latest released Amazon Linux 2023 AMI ID.
```
1. 選擇 **Add a parameter (新增參數)** 來建立第二個參數 **tagValue**，然後輸入下列資訊。
1. 對於 **Parameter name (參數名稱)**，輸入 **tagValue**。
1. 針對 **Type (類型)**，選擇 **String**。
1. 對於 **Required (必要)**，選擇 `No`。
1. 對於 **Default value (預設值)**，輸入 **LaunchedBySsmAutomation**。這會將標籤金鑰對值 `Name:LaunchedBySsmAutomation` 新增至該執行個體。
1. 對於 **Description (描述)**，輸入以下內容。
```
(Optional) The tag value to add to the instance. The default value is LaunchedBySsmAutomation.
```
1. 選擇 **Add a parameter (新增參數)** 來建立第三個參數 **instanceType**，然後輸入下列資訊。
1. 對於 **Parameter name (參數名稱)**，輸入 **instanceType**。
1. 針對 **Type (類型)**，選擇 **String**。
1. 對於 **Required (必要)**，選擇 `No`。
1. 對於 **Default value (預設值)**，輸入 **t2.micro**。
1. 對於 **Parameter Description (參數描述)**，輸入以下內容。
```
(Optional) The instance type to use for the instance. The default value is t2.micro.
```
1. 展開 **Target type (目標類型)**，並選擇 **"/"**。
1. (選用) 展開 **Document tags** (文件標籤)，將資源標籤套用至您的 Runbook。對於 **Tag key (標籤鍵)**，輸入 **Purpose**，以及對於 **Tag value (標籤值)**，輸入 **LaunchInstanceAndCheckState**。
1. 在 **Step 1 (步驟 1)** 區段中，完成下列步驟。
1. 對於 **Step name** (步驟名稱)，輸入自動化第一個步驟的此描述性步驟名稱：**LaunchEc2Instance**。
1. 對於 **Action type (動作類型)**，選擇 **Run a script (執行指令碼)** (**aws:executeScript**)。
1. 對於 **Description (描述)**，輸入自動化步驟的描述，如下所示。
```
**About This Step**
This step first launches an EC2 instance using the ```aws:executeScript``` action and the provided script.
```
1. 展開 **Inputs (輸入)**。
1. 對於 **Runtime (執行時間)**，選擇用於執行所提供指令碼的執行時間語言。
1. 對於 **Handler (處理常式)**，輸入 **launch\_instance**。這是在以下指令碼中宣告的函數名稱。
**注意**
PowerShell 不需要用到。
1. 對於 **Script (指令碼)**，請以下列項目取代預設內容。請務必將指令碼與對應的執行時間值相符。
------
#### [ Python ]
```
def launch_instance(events, context):
import boto3
ec2 = boto3.client('ec2')
image_id = events['image_id']
tag_value = events['tag_value']
instance_type = events['instance_type']
tag_config = {'ResourceType': 'instance', 'Tags': [{'Key':'Name', 'Value':tag_value}]}
res = ec2.run_instances(ImageId=image_id, InstanceType=instance_type, MaxCount=1, MinCount=1, TagSpecifications=[tag_config])
instance_id = res['Instances'][0]['InstanceId']
print('[INFO] 1 EC2 instance is successfully launched', instance_id)
return { 'InstanceId' : instance_id }
```
------
#### [ PowerShell ]
```
Install-Module AWS.Tools.EC2 -Force
Import-Module AWS.Tools.EC2
$payload = $env:InputPayload | ConvertFrom-Json
$imageid = $payload.image_id
$tagvalue = $payload.tag_value
$instanceType = $payload.instance_type
$type = New-Object Amazon.EC2.InstanceType -ArgumentList $instanceType
$resource = New-Object Amazon.EC2.ResourceType -ArgumentList 'instance'
$tag = @{Key='Name';Value=$tagValue}
$tagSpecs = New-Object Amazon.EC2.Model.TagSpecification
$tagSpecs.ResourceType = $resource
$tagSpecs.Tags.Add($tag)
$res = New-EC2Instance -ImageId $imageId -MinCount 1 -MaxCount 1 -InstanceType $type -TagSpecification $tagSpecs
return @{'InstanceId'=$res.Instances.InstanceId}
```
------
1. 展開 **Additional inputs (其他輸入)**。
1. 對於 **Input name (輸入名稱)**，選擇 **InputPayload**。對於 **Input value (輸入值)**，輸入以下 YAML 資料。
```
image_id: "{{ imageId }}"
tag_value: "{{ tagValue }}"
instance_type: "{{ instanceType }}"
```
1. 展開 **Outputs (輸出)**，並執行下列動作：
+ 對於**名稱**，輸入 **payload**。
+ 對於 **Selector (選取器)**，輸入 **$.Payload**。
+ 針對 **Type (類型)**，選擇 `StringMap`。
1. 選擇 **Add step** (新增步驟)，將第二個步驟新增至 Runbook。第二個步驟會查詢在步驟 1 中啟動的執行個體狀態，並等候傳回的狀態為 `ok` 為止。
1. 在 **Step 2 (步驟 2)** 區段中，執行下列動作。
1. 對於 **Step name** (步驟名稱)，輸入自動化第二個步驟的此描述性名稱：**WaitForInstanceStatusOk**。
1. 對於 **Action type (動作類型)**，選擇 **Run a script (執行指令碼)** (**aws:executeScript**)。
1. 對於 **Description (描述)**，輸入自動化步驟的描述，如下所示。
```
**About This Step**
The script continuously polls the instance status check value for the instance launched in Step 1 until the ```ok``` status is returned.
```
1. 對於 **Runtime (執行時間)**，選擇用於執行所提供指令碼的執行時間語言。
1. 對於 **Handler (處理常式)**，輸入 **poll\_instance**。這是在以下指令碼中宣告的函數名稱。
**注意**
PowerShell 不需要用到。
1. 對於 **Script (指令碼)**，請以下列項目取代預設內容。請務必將指令碼與對應的執行時間值相符。
------
#### [ Python ]
```
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}
```
------
#### [ PowerShell ]
```
Install-Module AWS.Tools.EC2 -Force
$inputPayload = $env:InputPayload | ConvertFrom-Json
$instanceId = $inputPayload.payload.InstanceId
$status = Get-EC2InstanceStatus -InstanceId $instanceId
while ($status.Status.Status -ne 'ok'){
Write-Host 'Polling get status of the instance', $instanceId
Start-Sleep -Seconds 5
$status = Get-EC2InstanceStatus -InstanceId $instanceId
}
return @{Status = $status.Status.Status; InstanceId = $instanceId}
```
------
1. 展開 **Additional inputs (其他輸入)**。
1. 對於 **Input name (輸入名稱)**，選擇 **InputPayload**。對於 **Input value (輸入值)**，輸入以下內容：
```
{{ LaunchEc2Instance.payload }}
```
1. 選擇 **Create automation** (建立自動化) 以儲存 Runbook。