註冊維護時段任務時使用虛擬參數

在 Maintenance Windows (AWS Systems Manager 中的工具) 中註冊任務時，可以指定四種任務類型特有的參數。(在 CLI 命令中，這些都是使用 --task-invocation-parameters 選項提供。)

您也可以使用「虛擬參數」語法來參考特定的值，例如 {{RESOURCE_ID}}、{{TARGET_TYPE}} 和 {{WINDOW_TARGET_ID}}。維護時段任務執行時，它會傳遞正確的值，而不是虛擬參數預留位置。本主題後面的支援的虛擬參數中提供了您可以使用之虛擬參數的完整清單。

重要

對於目標類型 RESOURCE_GROUP，視任務所需的 ID 格式而定，您可以在任務執行時選擇使用 {{TARGET_ID}} 和 {{RESOURCE_ID}} 參考資源。{{TARGET_ID}} 會傳回資源的完整 ARN。{{RESOURCE_ID}} 只會傳回資源的較短名稱或 ID，如下列範例所示。

{{TARGET_ID}} 格式：arn:aws:ec2:us-east-1:123456789012:instance/i-02573cafcfEXAMPLE
{{RESOURCE_ID}} 格式：i-02573cafcfEXAMPLE

對於目標類型 INSTANCE，{{TARGET_ID}} 和 {{RESOURCE_ID}} 參數都只產生執行個體 ID。如需更多詳細資訊，請參閱支援的虛擬參數。

{{TARGET_ID}} 和 {{RESOURCE_ID}} 可以用來將 AWS 資源的 ID 僅傳遞給 Automation、Lambda 和 Step Functions 任務。這兩個虛擬參數不能與 Run Command 任務搭配使用。

虛擬參數範例

假設您 AWS Lambda 任務的酬載需要透過其 ID 來參考執行個體。

無論您是使用 INSTANCE 或 RESOURCE_GROUP 維護時段目標，都可以使用 {{RESOURCE_ID}} 虛擬參數加以實現。例如：


"TaskArn": "arn:aws:lambda:us-east-2:111122223333:function:SSMTestFunction",
    "TaskType": "LAMBDA",
    "TaskInvocationParameters": {
        "Lambda": {
            "ClientContext": "ew0KICAi--truncated--0KIEXAMPLE",
            "Payload": "{ \"instanceId\": \"{{RESOURCE_ID}}\" }",
            "Qualifier": "$LATEST"
        }
    }

如果除了 Amazon Elastic Compute Cloud (Amazon EC2) 執行個體之外，您的 Lambda 任務還要針對其他受支援的目標類型執行 (例如 Amazon DynamoDB 資料表)，則可以使用相同的語法，{{RESOURCE_ID}} 只會產生資料表的名稱。但是，如果您需要資料表的完整 ARN，請使用 {{TARGET_ID}}，如下列範例所示。


"TaskArn": "arn:aws:lambda:us-east-2:111122223333:function:SSMTestFunction",
    "TaskType": "LAMBDA",
    "TaskInvocationParameters": {
        "Lambda": {
            "ClientContext": "ew0KICAi--truncated--0KIEXAMPLE",
            "Payload": "{ \"tableArn\": \"{{TARGET_ID}}\" }",
            "Qualifier": "$LATEST"
        }
    }

相同的語法適用於定位執行個體或其他資源類型。已將多個資源類型新增至資源群組時，任務會針對每個適當的資源執行。

重要

並非資源群組中包含的所有資源類型都會產生 {{RESOURCE_ID}} 參數的值。如需支援的資源類型清單，請參閱支援的虛擬參數。

另一個例子是，若要執行可停止 EC2 執行個體的 Automation 任務，您可將 AWS-StopEC2Instance Systems Manager 文件 (SSM 文件) 指定為 TaskArn 值，並使用 {{RESOURCE_ID}} 虛擬參數：


"TaskArn": "AWS-StopEC2Instance",
    "TaskType": "AUTOMATION"
    "TaskInvocationParameters": {
        "Automation": {
            "DocumentVersion": "1",
            "Parameters": {
                "instanceId": [
                    "{{RESOURCE_ID}}"
                ]
            }
        }
    }

若要執行複製 Amazon Elastic Block Store (Amazon EBS)磁碟區快照的 Automation 任務，您可以將 AWS-CopySnapshot SSM 文件指定為 TaskArn 值，並使用 {{RESOURCE_ID}} 虛擬參數：


"TaskArn": "AWS-CopySnapshot",
    "TaskType": "AUTOMATION"
    "TaskInvocationParameters": {
        "Automation": {
            "DocumentVersion": "1",
            "Parameters": {
                "SourceRegion": "us-east-2",
                "targetType":"RESOURCE_GROUP",
                "SnapshotId": [
                    "{{RESOURCE_ID}}"
                ]
            }
        }
    }

支援的虛擬參數

以下清單說明您可以在 --task-invocation-parameters 選項中使用 {{PSEUDO_PARAMETER}} 語法指定的虛擬參數。

WINDOW_ID：目標維護時段 ID。
WINDOW_TASK_ID：正在執行的時段任務 ID。
WINDOW_TARGET_ID：包含目標的目標時段的 ID (目標 ID)。
WINDOW_EXECUTION_ID：目前執行時段的 ID。
TASK_EXECUTION_ID：目前執行任務的 ID。
INVOCATION_ID：目前呼叫的 ID。
TARGET_TYPE：目標類型。支援的類型包括 RESOURCE_GROUP 和 INSTANCE。

TARGET_ID:

如果您指定的目標類型為 INSTANCE，則 TARGET_ID 虛擬參數會由執行個體的 ID 取代。例如 i-078a280217EXAMPLE。

如果您指定的目標類型為 RESOURCE_GROUP，則任務執行所參考的值為資源的完整 ARN。例如：arn:aws:ec2:us-east-1:123456789012:instance/i-078a280217EXAMPLE。下表提供資源群組中特定資源類型的範例 TARGET_ID 值。

注意

TARGET_ID 不支援 Run Command 任務。

Resource Type (資源類型)	範例 TARGET_ID
`AWS::CloudWatch::Alarm`	`arn:aws:cloudwatch:us-east-1:123456789012:alarm:MyCloudWatchAlarmi-078a280217EXAMPLE`
`AWS::DynamoDB::Table`	`arn:aws:dynamodb:us-east-1:123456789012:table/MyTable`
`AWS::EC2::Instance`	`arn:aws:ec2:us-east-1:123456789012:instance/i-078a280217EXAMPLE`
`AWS::EC2::Image`	`arn:aws:ec2:us-east-1:123456789012:image/ami-02250b3732EXAMPLE`
`AWS::EC2::SecurityGroup`	`arn:aws:ec2:us-east-1:123456789012:security-group/sg-cEXAMPLE`
`AWS::EC2::Snapshot`	`arn:aws:ec2:us-east-1:123456789012:snapshot/snap-03866bf003EXAMPLE`
`AWS::EC2::Volume`	`arn:aws:ec2:us-east-1:123456789012:volume/vol-0912e04d78EXAMPLE`
`AWS::ECS::Service`	`arn:aws:ecs:us-east-1:123456789012:service/my-ecs-service`
`AWS::RDS::DBCluster`	`arn:aws:rds:us-east-2:123456789012:cluster:My-Cluster`
`AWS::RDS::DBInstance`	`arn:aws:rds:us-east-1:123456789012:db:My-SQL-Instance`
`AWS::S3::Bucket`	`arn:aws:s3:::amzn-s3-demo-bucket`
`AWS::SSM::ManagedInstance`	`arn:aws:ssm:us-east-1:123456789012:managed-instance/mi-0feadcf2d9EXAMPLE`

RESOURCE_ID：資源群組中所包含資源類型的簡短 ID。下表提供資源群組中特定資源類型的範例 RESOURCE_ID 值。

注意

RESOURCE_ID 不支援 Run Command 任務。

Resource Type (資源類型)	範例 RESOURCE_ID
`AWS::CloudWatch::Alarm`	`MyCloudWatchAlarm`
`AWS::DynamoDB::Table`	`MyTable`
`AWS::EC2::Instance`	`i-078a280217EXAMPLE`
`AWS::EC2::Image`	`ami-02250b3732EXAMPLE`
`AWS::EC2::SecurityGroup`	`sg-cEXAMPLE`
`AWS::EC2::Snapshot`	`snap-03866bf003EXAMPLE`
`AWS::EC2::Volume`	`vol-0912e04d78EXAMPLE`
`AWS::ECS::Service`	`my-ecs-service`
`AWS::RDS::DBCluster`	`My-Cluster`
`AWS::RDS::DBInstance`	`My-SQL-Instance`
`AWS::S3::Bucket`	`amzn-s3-demo-bucket`
`AWS::SSM::ManagedInstance`	`mi-0feadcf2d9EXAMPLE`

注意

如果您指定的 AWS 資源群組包含不會產生 RESOURCE_ID 值的資源類型，但未列在上表中，則不會填入 RESOURCE_ID 參數。該資源仍會發生執行呼叫。在這些情況下，請改用 TARGET_ID 虛擬參數，這將被取代為資源的完整 ARN。

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

使用維護時段進行修補的排程

維護時段排程與作用期間選項