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

# 示例：向维护时段注册任务


您可以使用 Amazon Command Line Interface（Amazon CLI）将 Run Command（Amazon Systems Manager 中的一项工具）中的任务注册到维护时段，如[向维护时段注册任务](mw-cli-tutorial-tasks.md)中所示。您还可以为 Systems Manager 自动化 工作流、Amazon Lambda 函数和 Amazon Step Functions 任务注册任务，如本主题后面的内容所示。

**注意**  
为维护时段 Run Command 类型任务指定一个或多个目标。根据任务的不同，目标对于其他维护时段任务类型（自动化、Amazon Lambda 和 Amazon Step Functions）是可选的。有关运行未指定目标的任务的更多信息，请参阅 [注册不含目标的维护时段任务](maintenance-windows-targetless-tasks.md)。

在本主题中，我们提供的示例演示了如何使用 Amazon Command Line Interface (Amazon CLI) 命令 `register-task-with-maintenance-window`，分别将四种支持的任务类型注册到维护时段。这些示例仅用于演示目的，不过您可以修改它们以创建工作任务注册命令。

**使用 --cli-input-json 选项**  
为了更好地管理任务选项，您可以使用命令选项 `--cli-input-json`，其选项值在 JSON 文件中引用。

要使用我们在下列示例中提供的示例 JSON 文件内容，请在您本地计算机上执行以下操作：

1. 创建一个文件，采用类似于 `MyRunCommandTask.json`、`MyAutomationTask.json` 或其他您偏好的名称。

1. 将 JSON 示例内容复制到该文件中。

1. 为您的任务注册修改文件内容，然后保存该文件。

1. 在存储文件的同一个目录中，运行以下命令：用您的文件名替换 *MyFile.json*。

------
#### [ Linux & macOS ]

   ```
   aws ssm register-task-with-maintenance-window \
       --cli-input-json file://MyFile.json
   ```

------
#### [ Windows ]

   ```
   aws ssm register-task-with-maintenance-window ^
       --cli-input-json file://MyFile.json
   ```

------

**维护时段任务中的伪参数**  
在某些示例中，我们使用*伪参数* 作为将 ID 信息传递到您任务的方法。例如，`{{TARGET_ID}}` 和 `{{RESOURCE_ID}}` 可用于将 Amazon 资源的 ID 传递到 自动化、Lambda 和 Step Functions 任务。有关 `--task-invocation-parameters` 内容中伪参数的更多信息，请参阅 [注册维护时段任务时使用伪参数](maintenance-window-tasks-pseudo-parameters.md)。

**更多信息**  
+ [register-task-with-maintenance-windows 命令的参数选项](mw-cli-task-options.md).
+ 《Amazon CLI Command Reference》**中的 [https://docs.amazonaws.cn/cli/latest/reference/ssm/register-task-with-maintenance-window.html](https://docs.amazonaws.cn/cli/latest/reference/ssm/register-task-with-maintenance-window.html)。
+ **《Amazon Systems Manager API 参考》中的 [https://docs.amazonaws.cn/systems-manager/latest/APIReference/API_RegisterTaskWithMaintenanceWindow.html](https://docs.amazonaws.cn/systems-manager/latest/APIReference/API_RegisterTaskWithMaintenanceWindow.html)

## 任务注册示例


以下部分提供了一个示例 Amazon CLI 命令，用于注册支持的任务类型和可与 `--cli-input-json` 选项一起使用的 JSON 示例。

### 注册 Systems Manager Run Command 任务


以下示例演示了如何使用 Amazon CLI 将 Systems Manager Run Command 任务注册到维护时段。

------
#### [ Linux & macOS ]

```
aws ssm register-task-with-maintenance-window \
    --window-id mw-0c50858d01EXAMPLE \
    --task-arn "AWS-RunShellScript" \
    --max-concurrency 1 --max-errors 1 --priority 10 \
    --targets "Key=InstanceIds,Values=i-02573cafcfEXAMPLE" \
    --task-type "RUN_COMMAND" \
    --task-invocation-parameters '{"RunCommand":{"Parameters":{"commands":["df"]}}}'
```

------
#### [ Windows ]

```
aws ssm register-task-with-maintenance-window ^
    --window-id mw-0c50858d01EXAMPLE ^
    --task-arn "AWS-RunShellScript" ^
    --max-concurrency 1 --max-errors 1 --priority 10 ^
    --targets "Key=InstanceIds,Values=i-02573cafcfEXAMPLE" ^
    --task-type "RUN_COMMAND" ^
    --task-invocation-parameters "{\"RunCommand\":{\"Parameters\":{\"commands\":[\"df\"]}}}"
```

------

**用于 `--cli-input-json` 文件选项的 JSON 内容：**

```
{
    "TaskType": "RUN_COMMAND",
    "WindowId": "mw-0c50858d01EXAMPLE",
    "Description": "My Run Command task to update SSM Agent on an instance",
    "MaxConcurrency": "1",
    "MaxErrors": "1",
    "Name": "My-Run-Command-Task",
    "Priority": 10,
    "Targets": [
        {
            "Key": "WindowTargetIds",
            "Values": [
                "e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE"
            ]
        }
    ],
    "TaskArn": "AWS-UpdateSSMAgent",
    "TaskInvocationParameters": {
        "RunCommand": {
            "Comment": "A TaskInvocationParameters test comment",
            "NotificationConfig": {
                "NotificationArn": "arn:aws:sns:region:123456789012:my-sns-topic-name",
                "NotificationEvents": [
                    "All"
                ],
                "NotificationType": "Invocation"
            },
            "OutputS3BucketName": "amzn-s3-demo-bucket",
            "OutputS3KeyPrefix": "S3-PREFIX",
            "TimeoutSeconds": 3600
        }
    }
}
```

### 注册 Systems Manager 自动化 任务


以下示例演示了如何使用 Amazon CLI 将 Systems Manager 自动化 任务注册到维护时段：

**Amazon CLI 命令：**

------
#### [ Linux & macOS ]

```
aws ssm register-task-with-maintenance-window \
    --window-id "mw-0c50858d01EXAMPLE" \
    --task-arn "AWS-RestartEC2Instance" \
    --service-role-arn arn:aws:iam::123456789012:role/MyMaintenanceWindowServiceRole \
    --task-type AUTOMATION \
    --task-invocation-parameters "Automation={DocumentVersion=5,Parameters={InstanceId='{{RESOURCE_ID}}'}}" \
    --priority 0 --name "My-Restart-EC2-Instances-Automation-Task" \
    --description "Automation task to restart EC2 instances"
```

------
#### [ Windows ]

```
aws ssm register-task-with-maintenance-window ^
    --window-id "mw-0c50858d01EXAMPLE" ^
    --task-arn "AWS-RestartEC2Instance" ^
    --service-role-arn arn:aws:iam::123456789012:role/MyMaintenanceWindowServiceRole ^
    --task-type AUTOMATION ^
    --task-invocation-parameters "Automation={DocumentVersion=5,Parameters={InstanceId='{{TARGET_ID}}'}}" ^
    --priority 0 --name "My-Restart-EC2-Instances-Automation-Task" ^
    --description "Automation task to restart EC2 instances"
```

------

**用于 `--cli-input-json` 文件选项的 JSON 内容：**

```
{
    "WindowId": "mw-0c50858d01EXAMPLE",
        "TaskArn": "AWS-PatchInstanceWithRollback",
    "TaskType": "AUTOMATION","TaskInvocationParameters": {
        "Automation": {
            "DocumentVersion": "1",
            "Parameters": {
                "instanceId": [
                    "{{RESOURCE_ID}}"
                ]
            }
        }
    }
}
```

### 注册 Amazon Lambda 任务


以下示例演示了如何使用 Amazon CLI 将 Lambda 函数任务注册到维护时段。

对于这些示例，创建 Lambda 函数的用户将其命名为 `SSMrestart-my-instances`，并创建了名为 `instanceId` 和 `targetType` 的两个参数。

**重要**  
Maintenance Windows 的 IAM policy 要求您将前缀 `SSM` 添加到 Lambda 函数（或别名）名称。继续注册此类型的任务之前，请在 Amazon Lambda 中更新其名称，以包含 `SSM`。例如，如果您的 Lambda 函数名称为 `MyLambdaFunction`，请将其更改为 `SSMMyLambdaFunction`。

**Amazon CLI 命令：**

------
#### [ Linux & macOS ]

**重要**  
如果您使用的是版本 2 的 Amazon CLI，并且您的 Lambda 有效负载没有进行 base64 编码，则您必须在以下命令中包含选项 `--cli-binary-format raw-in-base64-out`。`cli_binary_format` 选项仅在版本 2 中可用。有关此设置和其他 Amazon CLI `config` 文件设置的信息，请参阅 *Amazon Command Line Interface 用户指南*中的[受支持的 `config` 文件设置](https://docs.amazonaws.cn/cli/latest/userguide/cli-configure-files.html#cli-configure-files-settings)。

```
aws ssm register-task-with-maintenance-window \
    --window-id "mw-0c50858d01EXAMPLE" \
    --targets "Key=WindowTargetIds,Values=e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE" \
    --priority 2 --max-concurrency 10 --max-errors 5 --name "My-Lambda-Example" \
    --description "A description for my LAMBDA example task" --task-type "LAMBDA" \
    --task-arn "arn:aws:lambda:region:123456789012:function:serverlessrepo-SSMrestart-my-instances-C4JF9EXAMPLE" \
    --task-invocation-parameters '{"Lambda":{"Payload":"{\"InstanceId\":\"{{RESOURCE_ID}}\",\"targetType\":\"{{TARGET_TYPE}}\"}","Qualifier": "$LATEST"}}'
```

------
#### [ PowerShell ]

**重要**  
如果您使用的是版本 2 的 Amazon CLI，并且您的 Lambda 有效负载没有进行 base64 编码，则您必须在以下命令中包含选项 `--cli-binary-format raw-in-base64-out`。`cli_binary_format` 选项仅在版本 2 中可用。有关此设置和其他 Amazon CLI `config` 文件设置的信息，请参阅 *Amazon Command Line Interface 用户指南*中的[受支持的 `config` 文件设置](https://docs.amazonaws.cn/cli/latest/userguide/cli-configure-files.html#cli-configure-files-settings)。

```
aws ssm register-task-with-maintenance-window `
    --window-id "mw-0c50858d01EXAMPLE" `
    --targets "Key=WindowTargetIds,Values=e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE" `
    --priority 2 --max-concurrency 10 --max-errors 5 --name "My-Lambda-Example" `
    --description "A description for my LAMBDA example task" --task-type "LAMBDA" `
    --task-arn "arn:aws:lambda:region:123456789012:function:serverlessrepo-SSMrestart-my-instances-C4JF9EXAMPLE" `
    --task-invocation-parameters '{\"Lambda\":{\"Payload\":\"{\\\"InstanceId\\\":\\\"{{RESOURCE_ID}}\\\",\\\"targetType\\\":\\\"{{TARGET_TYPE}}\\\"}\",\"Qualifier\": \"$LATEST\"}}'
```

------

**用于 `--cli-input-json` 文件选项的 JSON 内容：**

```
{
    "WindowId": "mw-0c50858d01EXAMPLE",
    "Targets": [
        {
            "Key": "WindowTargetIds",
            "Values": [
                "e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE"
            ]
        }
    ],
    "TaskArn": "SSM_RestartMyInstances",
    "TaskType": "LAMBDA",
    "MaxConcurrency": "10",
    "MaxErrors": "10",
    "TaskInvocationParameters": {
        "Lambda": {
            "ClientContext": "ew0KICAi--truncated--0KIEXAMPLE",
            "Payload": "{ \"instanceId\": \"{{RESOURCE_ID}}\", \"targetType\": \"{{TARGET_TYPE}}\" }",
            "Qualifier": "$LATEST"
        }
    },
    "Name": "My-Lambda-Task",
    "Description": "A description for my LAMBDA task",
    "Priority": 5
}
```

### 注册 Step Functions 任务


以下示例演示了如何使用 Amazon CLI 将 Step Functions 状态机任务注册到维护时段。

**注意**  
维护时段任务仅支持 Step Functions 标准状态机工作流。它们不支持快速状态机工作流。有关状态机工作流类型的信息，请参阅《Amazon Step Functions 开发人员指南》**中的[标准与快速工作流](https://docs.amazonaws.cn/step-functions/latest/dg/concepts-standard-vs-express.html)。

对于这些示例，创建 Step Functions 状态机的用户使用名为 `instanceId` 的参数创建名为 `SSMMyStateMachine` 的状态机。

**重要**  
Maintenance Windows 的 Amazon Identity and Access Management （IAM）policy 要求您使用 `SSM` 作为 Step Functions 状态机名称的前缀。继续注册此类型的任务之前，您必须在 Amazon Step Functions 中更新此名称以包括 `SSM`。例如，如果您的状态机名为 `MyStateMachine`，则将其更改为 `SSMMyStateMachine`。

**Amazon CLI 命令：**

------
#### [ Linux & macOS ]

```
aws ssm register-task-with-maintenance-window \
    --window-id "mw-0c50858d01EXAMPLE" \
    --targets "Key=WindowTargetIds,Values=e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE" \
    --task-arn arn:aws:states:region:123456789012:stateMachine:SSMMyStateMachine-MggiqEXAMPLE \
    --task-type STEP_FUNCTIONS \
    --task-invocation-parameters '{"StepFunctions":{"Input":"{\"InstanceId\":\"{{RESOURCE_ID}}\"}", "Name":"{{INVOCATION_ID}}"}}' \
    --priority 0 --max-concurrency 10 --max-errors 5 \
    --name "My-Step-Functions-Task" --description "A description for my Step Functions task"
```

------
#### [ PowerShell ]

```
aws ssm register-task-with-maintenance-window `
    --window-id "mw-0c50858d01EXAMPLE" `
    --targets "Key=WindowTargetIds,Values=e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE" `
    --task-arn arn:aws:states:region:123456789012:stateMachine:SSMMyStateMachine-MggiqEXAMPLE `
    --task-type STEP_FUNCTIONS `
    --task-invocation-parameters '{\"StepFunctions\":{\"Input\":\"{\\\"InstanceId\\\":\\\"{{RESOURCE_ID}}\\\"}\", \"Name\":\"{{INVOCATION_ID}}\"}}' `
    --priority 0 --max-concurrency 10 --max-errors 5 `
    --name "My-Step-Functions-Task" --description "A description for my Step Functions task"
```

------

**用于 `--cli-input-json` 文件选项的 JSON 内容：**

```
{
    "WindowId": "mw-0c50858d01EXAMPLE",
    "Targets": [
        {
            "Key": "WindowTargetIds",
            "Values": [
                "e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE"
            ]
        }
    ],
    "TaskArn": "SSM_MyStateMachine",
    "TaskType": "STEP_FUNCTIONS",
    "MaxConcurrency": "10",
    "MaxErrors": "10",
    "TaskInvocationParameters": {
        "StepFunctions": {
            "Input": "{ \"instanceId\": \"{{TARGET_ID}}\" }",
            "Name": "{{INVOCATION_ID}}"
        }
    },
    "Name": "My-Step-Functions-Task",
    "Description": "A description for my Step Functions task",
    "Priority": 5
}
```