关于虚拟参数 - Amazon Systems Manager
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 Amazon Web Services 服务入门

关于虚拟参数

当您在 Amazon Systems Manager 的功能 Maintenance Windows 中注册任务时,可以使用 --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}} 可用于将 Amazon 资源的 ID 仅传递到 自动化、Lambda 和 Step Functions 任务。这两个伪参数不能用于 Run Command 任务。

伪参数示例

假设 Amazon 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" } }

如果您的 Lambda 任务旨在针对 Amazon Elastic Compute Cloud (Amazon EC2) 实例之外的其他受支持的目标类型运行(如 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}} 参数生成值。有关受支持的资源类型的列表,请参阅 支持的伪参数

另一个例子是,要运行停止您的 Amazon EC2 实例的 自动化 任务,请指定 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) 卷的快照的 自动化 任务,请将 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_GROUPINSTANCE

  • TARGET_ID:

    如果您指定的目标类型为 INSTANCE,则 TARGET_ID 伪参数将被替换为实例的 ID。例如:i-078a280217EXAMPLE

    如果您指定的目标类型为 RESOURCE_GROUP,则为任务执行引用的值将是资源的完整 ARN。例如:arn:aws:ec2:us-east-1:123456789012:instance/i-078a280217EXAMPLE。下表提供资源组中特定资源类型的示例 TARGET_ID 值。

    注意

    对于 Run Command 任务,TARGET_ID 不受支持。

    资源类型 示例 TARGET_ID
    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 值。

    注意

    对于 Run Command 任务,RESOURCE_ID 不受支持。

    资源类型 示例 RESOURCE_ID
    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
    注意

    如果您指定的 Amazon 资源组包含的资源类型不会生成 RESOURCE_ID 值,并且这些资源类型未在上表中列出,则不会填充 RESOURCE_ID 参数。对于该资源仍会发生执行调用。在这些情况下,请改用 TARGET_ID 伪参数,该参数将替换为资源的完整 ARN。