メンテナンスウィンドウのタスクを登録する際の疑似パラメータの使用 - AWS Systems Manager
擬似パラメータの例サポートされる擬似パラメータ

メンテナンスウィンドウのタスクを登録する際の疑似パラメータの使用

AWS Systems Manager の一機能である Maintenance Windows でタスクを登録する際、4 つのタスクタイプのそれぞれに固有のパラメータを指定します。(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 のタスクにのみ渡すことができます。これら 2 つの擬似パラメータは、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"
        }
    }

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}} パラメータの値を生成するわけではありません。サポートされているリソースタイプの一覧については、「サポートされる擬似パラメータ」を参照してください。

別の例として、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}}"
                ]
            }
        }
    }

サポートされる擬似パラメータ

以下のリストでは、{{PSEUDO_PARAMETER}} オプションの --task-invocation-parameters 構文を使用して指定できる疑似パラメータについて説明しています。

  • 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 に置き換えられます。