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

可以按将任务注册到维护时段部分的演示，使用 AWS Command Line Interface（AWS CLI）将 Run Command 中的任务注册到某个维护时段。您还可以为 Systems Manager 自动化工作流、AWS Lambda 函数和 AWS Step Functions 任务注册任务，如本主题后面的内容所示。

注意

为维护时段 Run Command 类型任务指定一个或多个目标。根据任务的不同，目标对于其他维护时段任务类型（自动化、AWS Lambda 和 AWS Step Functions）是可选的。有关运行未指定目标的任务的更多信息，请参阅注册不含目标的维护时段任务。

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

使用 --cli-input-json 选项

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

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

创建一个文件，采用类似于 MyRunCommandTask.json、MyAutomationTask.json 或其他您偏好的名称。
将 JSON 示例内容复制到该文件中。
为您的任务注册修改文件内容，然后保存该文件。

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

维护时段任务中的伪参数

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

更多信息

register-task-with-maintenance-windows 命令的参数选项.
《AWS CLI Command Reference》中的 register-task-with-maintenance-window。
《AWS Systems Manager API 参考》中的 RegisterTaskWithMaintenanceWindow

任务注册示例

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

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

用于 --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
        }
    }
}

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

AWS CLI 命令：

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


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

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

重要

使用服务相关角色时 (AWSServiceRoleForAmazonSSM)，Lambda 函数必须与维护时段位于同一 AWS 账户中。服务相关角色不支持跨账户 Lambda 调用。如果需要调用其他账户中的 Lambda 函数，请使用 --service-role-arn 参数指定一个自定义服务角色，并将其权限范围显式限定为目标账户，然后在目标 Lambda 函数上添加基于资源的策略，从而向您的自定义角色授予调用权限。

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

重要

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

AWS CLI 命令：

Linux & macOS

重要

如果您使用的是版本 2 的 AWS CLI，并且您的 Lambda 有效负载没有进行 base64 编码，则您必须在以下命令中包含选项 --cli-binary-format raw-in-base64-out。cli_binary_format 选项仅在版本 2 中可用。有关此设置和其他 AWS CLI config 文件设置的信息，请参阅 AWS Command Line Interface 用户指南中的受支持的 config 文件设置。


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

重要


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
}

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

重要

Step Functions 状态机必须与维护时段位于同一 AWS 账户中。无论是使用服务相关角色还是自定义服务角色，均不支持跨账户 Step Functions 调用。

注意

维护时段任务仅支持 Step Functions 标准状态机工作流。它们不支持快速状态机工作流。有关状态机工作流类型的信息，请参阅《AWS Step Functions 开发人员指南》中的标准与快速工作流。

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

重要

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

AWS CLI 命令：

用于 --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
}

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

步骤 3：使用 AWS CLI 向维护时段注册任务