註冊維護時段工作時使用虛擬參數

當您在中註冊任務時 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 傳遞給自動化、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 任務。

  資源類型	範例 TARGET_ID
  AWS::CloudWatch::Alarm	arn:aws:cloudwatch:us-east-1:123456789012:alarm:MyCloudWatchAlarmi-078a280217EXAMPLE
  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::DynamoDB::Table	arn:aws:dynamodb:us-east-1:123456789012:table/MyTable
  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::: DOC-EXAMPLE-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_ID
  AWS::CloudWatch::Alarm	MyCloudWatchAlarm
  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::DynamoDB::Table	MyTable
  AWS::RDS::DBCluster	My-Cluster
  AWS::RDS::DBInstance	My-SQL-Instance
  AWS::S3::Bucket	DOC-EXAMPLE-BUCKET
  AWS::SSM::ManagedInstance	mi-0feadcf2d9EXAMPLE

  注意

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