全部產品
Search

搜尋本產品

    Elastic Compute Service：命令中使用自訂參數

    文件中心

    Elastic Compute Service：命令中使用自訂參數

    更新時間：Nov 26, 2025

    雲助手支援使用自訂參數或內建環境參數來靈活調整命令內容，類似於模板變數的功能。同時，也可以在雲助手命令中結合OOS的參數倉庫功能，更為方便和安全地管理自訂參數。本文將詳細介紹其使用方法。

    前提條件

    • 執行個體的狀態必須為運行中（Running）。

    • 執行個體已安裝雲助手Agent，且雲助手Agent版本需要高於以下對應的版本。具體操作，請參見安裝雲助手Agent。

      • Linux：2.2.3.309

      • Windows：2.1.3.309

    使用說明

    • 通過API使用自訂參數執行雲助手命令。

      調用RunCommand或InvokeCommand執行雲助手命令時，可以通過指定參數EnableParameter=true啟用自訂參數功能，在CommandContent中使用{{}}方式定義自訂參數。在使用自訂參數時，存在以下限制：

      • 在{{}}內參數名前後的空格以及分行符號會被忽略。

      • 自訂參數個數不能超過20個。

      • 自訂參數名僅允許a-zA-Z0-9-_的組合，且不區分大小寫。

      • 不支援acs::首碼指定非內建參數，支援的內建環境參數，請參見內建環境參數。

      • 單個參數名不能超過64位元組。

    • 在ECS控制台雲助手中使用自訂參數。

      雲助手命令中自訂參數僅支援使用內建環境參數，且自訂參數個數不能超過20個。支援的內建環境參數，請參見內建環境參數。

    使用自訂參數

    在雲助手命令中使用自訂參數，可以更加靈活地編寫指令碼，提高命令的複用性。例如，在您的Linux執行個體中，存在一個定時執行的指令碼，該指令碼需要根據實際情況靈活地設定其執行頻率。

    import com.aliyun.ecs20140526.Client;
import com.aliyun.ecs20140526.models.RunCommandRequest;
import com.aliyun.teaopenapi.models.Config;

import java.util.Collections;
import java.util.List;


public class EcsService {

    /**
     * 從環境變數中擷取AccessKeyId、AccessKeySecret
     */
    private static final String ACCESS_KEY_ID = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID");
    private static final String ACCESS_KEY_SECRET = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET");

    public static void main(String[] args_) throws Exception {
        // 地區ID
        String regionId = "cn-hangzhou";
        Config config = new Config()
                .setAccessKeyId(ACCESS_KEY_ID)
                .setAccessKeySecret(ACCESS_KEY_SECRET)
                .setRegionId(regionId);
        Client ecsClient = new Client(config);
        List<String> instanceIds = Collections.singletonList("i-bp1h23xufsi8XXXXXXXX");
        // 待執行命令內容，其中/path/to/your/script.sh需要替換為待執行指令碼
        String commandContent = "#!/bin/bash\n " +
                "(crontab -l 2>/dev/null; echo \"{{cron}} /path/to/your/script.sh\") | crontab -";
        // 命令執行逾時時間
        long commandTimeOut = 60;
        RunCommandRequest request = new RunCommandRequest();
        request.setRegionId(regionId);
        request.setType("RunShellScript");
        // 開啟自訂參數功能
        request.setEnableParameter(true);
        // 設定自訂參數cron的值
        request.setParameters(Collections.singletonMap("cron", "0 2 * * *"));
        request.setCommandContent(commandContent);
        request.setInstanceId(instanceIds);
        request.setTimeout(commandTimeOut);
        ecsClient.runCommand(request);
    }
}

    import json
import os

from alibabacloud_ecs20140526 import models as ecs_20140526_models
from alibabacloud_ecs20140526.client import Client as Ecs20140526Client
from alibabacloud_tea_openapi import models as open_api_models

ACCESS_KEY_ID = os.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID")
ACCESS_KEY_SECRET = os.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")


def get_ecs_client(region_id):
    config = open_api_models.Config(
        access_key_id=ACCESS_KEY_ID,
        access_key_secret=ACCESS_KEY_SECRET,
        region_id=region_id
    )
    return Ecs20140526Client(config)


def main():
    # 地區ID
    region_id = "cn-hangzhou"
    client = get_ecs_client(region_id)
    # 要執行命令的ECS執行個體ID
    instance_ids = ["i-bp1h23xufsi8XXXXXXXX"]
    # 待執行命令內容，其中/path/to/your/script.sh為待執行指令碼
    command_content = "#!/bin/bash\n (crontab -l 2>/dev/null; echo \"{{cron}} /path/to/your/script.sh\") | crontab -"
    # 命令執行逾時時間，單位為秒
    command_timeout = 60
    # 適用於Linux執行個體的Shell命令：RunShellScript
    command_type = "RunShellScript"

    # 執行命令
    request = ecs_20140526_models.RunCommandRequest()
    request.region_id = region_id
    request.type = command_type
    # 開啟自訂參數功能
    request.enable_parameter = True
    # 設定自訂參數的值
    request.parameters = {"cron": "0 2 * * *"}
    request.command_content = command_content
    request.instance_id = instance_ids
    request.timeout = command_timeout
    response = client.run_command(request)
    print("execute_command result:", json.dumps(response.to_map()['body']))


if __name__ == "__main__":
    main()

    使用OOS參數

    CloudOps Orchestration ServiceOOS提供參數倉庫功能，支援普通參數和加密參數。您可以在雲助手命令中結合OOS的參數倉庫功能，更為方便和安全地管理自訂參數。使用CloudOps Orchestration ServiceOOS提供參數倉庫功能時，需要先開通CloudOps Orchestration ServiceOOS。更多資訊，請參見什麼是系統營運管理。

    使用普通參數

    如果您的命令不涉及敏感性資料，可以使用普通參數。以在Linux執行個體中增加新使用者為例，介紹如何在雲助手命令中使用OOS參數倉庫的普通參數。

    1. 通過CloudOps Orchestration ServiceOOS的參數倉庫建立普通參數。具體操作，請參見普通參數。

      以下樣本表示在普通參數中新增一個username參數，取值為user01，您可以根據實際情況修改。

      名稱

      樣本值

      參數名稱

      username

      參數類型

      String

      值

      user01

    2. 調用API執行雲助手命令。

      使用RAM使用者通過雲助手命令為Linux執行個體建立一個新使用者，命令內容為adduser {{oos:username}}。其中，{{oos:username}}表示新使用者名稱由OOS參數倉庫的普通參數username定義。

      說明

      為RAM使用者授予允許使用雲助手執行包含OSS普通參數的命令，具體權限原則資訊，請參見在命令中使用OSS普通參數。

      import com.aliyun.ecs20140526.Client;
import com.aliyun.ecs20140526.models.RunCommandRequest;
import com.aliyun.ecs20140526.models.RunCommandResponse;
import com.aliyun.teaopenapi.models.Config;

import java.util.Arrays;
import java.util.List;

public class EcsService {
    public static void main(String[] args_) throws Exception {
        // 地區ID
        String regionId = "cn-hangzhou";
        Config config = new Config()
                .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
                .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"))
                .setRegionId(regionId);
        Client ecsClient = new Client(config);
        RunCommandRequest request = new RunCommandRequest();
        request.setRegionId(regionId);
        request.setType("RunShellScript");
        // 開啟自訂參數功能
        request.setEnableParameter(true);
        // 待執行命令內容
        String commandContent = "adduser {{oos:username}}";
        request.setCommandContent(commandContent);
        List<String> instanceIds = Arrays.asList("i-bp1h23xufsi8XXXXXXXX");
        request.setInstanceId(instanceIds);
        // 命令執行逾時時間
        request.setTimeout(60L);
        RunCommandResponse response = ecsClient.runCommand(request);
        System.out.println(new Gson().toJson(response.getBody()));
    }
}

      import json
import os

from alibabacloud_ecs20140526 import models as ecs_20140526_models
from alibabacloud_ecs20140526.client import Client as Ecs20140526Client
from alibabacloud_tea_openapi import models as open_api_models

ACCESS_KEY_ID = os.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID")
ACCESS_KEY_SECRET = os.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")


def get_ecs_client(region_id):
    config = open_api_models.Config(
        access_key_id=ACCESS_KEY_ID,
        access_key_secret=ACCESS_KEY_SECRET,
        region_id=region_id
    )
    return Ecs20140526Client(config)


def main():
    # 地區ID
    region_id = "cn-hangzhou"
    client = get_ecs_client(region_id)
    # 要執行命令的ECS執行個體ID
    instance_ids = ["i-bp1h23xufsi8XXXXXXXX"]
    # 待執行命令內容
    command_content = "adduser {{oos:username}}"
    # 命令執行逾時時間，單位為秒
    command_timeout = 60
    # 適用於Linux執行個體的Shell命令：RunShellScript
    command_type = "RunShellScript"

    # 執行命令
    request = ecs_20140526_models.RunCommandRequest()
    request.region_id = region_id
    request.type = command_type
    # 開啟自訂參數功能
    request.enable_parameter = True
    request.command_content = command_content
    request.instance_id = instance_ids
    request.timeout = command_timeout
    response = client.run_command(request)
    print("execute_command result:", json.dumps(response.to_map()['body']))


if __name__ == "__main__":
    main()

    使用加密參數

    如果您的參數涉及敏感性資料（例如密碼等），建議使用加密參數。使用加密參數，需要開通Key Management Service（KMS）。更多資訊，請參見什麼是Key Management Service。

    1. 通過系統營運管理OOS的參數倉庫建立加密參數和普通參數。具體操作，請參見加密參數和普通參數。

      以下樣本表示在OOS參數倉庫中建立使用者名稱參數username和密碼參數password。

      • 在普通參數中新增一個使用者名稱參數username，取值為user01，您可以根據實際情況修改。

        名稱

        樣本值

        參數名稱

        username

        參數類型

        String

        值

        user01

      • 在加密參數中新增一個密碼參數password，取值為MyPassword01，您可以根據實際情況修改。

        名稱

        樣本值

        參數名稱

        password

        KMS密鑰ID

        Default Service CMK

        說明

        此處樣本值是由KMS產生的免費服務密鑰，請根據實際情況選擇。

        值

        MyPassword01

        說明

        此密碼僅做樣本，請不要在生產環境使用。

    2. 為目標ECS執行個體設定RAM角色。

      1. 建立RAM角色。具體操作，請參見建立可信實體為阿里雲服務的RAM角色。

        相關配置樣本如下所示。

        名稱

        樣本

        信任主體類型

        選擇雲端服務。

        信任主體名稱

        Elastic Compute Service / ECS。

        單擊確定，角色名稱設定為AxtParametersRamRole。

      2. 建立RAM角色相關權限原則。具體操作，請參見建立自訂權限原則。

        權限原則樣本

        策略名稱稱為AxtParametersRamPolicy，策略內容如下所示，表示允許調用KMS和OOS的相關API（GetSecretValue、GetParameters、GetSecretParameters、GetParameter和GetSecretParameter）。

        {
    "Version": "1",
    "Statement": [
        {
            "Action": [
                "kms:GetSecretValue",
                "oos:GetParameters",
                "oos:GetSecretParameters",
                "oos:GetParameter",
                "oos:GetSecretParameter"
            ],
            "Resource": "*",
            "Effect": "Allow"
        }
    ]
}

      3. 為RAM角色（AxtParametersRamRole）設定策略許可權（AxtParametersRamPolicy）。具體操作，請參見為RAM角色授權。

      4. 為目標ECS執行個體設定RAM角色（AxtParametersRamRole）。具體操作，請參見建立RAM角色並授予給ECS執行個體。

    3. 調用API執行雲助手命令。

      使用RAM使用者通過雲助手命令為Linux執行個體修改使用者密碼，命令內容如下所示：

       echo '{{oos-secret:password}}' | passwd '{{oos:username}}' --stdin

      其中，{{oos-secret:password}}表示使用者的新密碼，由OOS參數倉庫的加密參數password定義；{{oos:username}}表示使用者名稱，由OOS參數倉庫的普通參數username定義。

      說明

      為RAM使用者授予允許使用雲助手執行包含OSS加密參數的命令，具體權限原則資訊，請參見在命令中使用OSS加密參數。

      import com.aliyun.ecs20140526.Client;
import com.aliyun.ecs20140526.models.RunCommandRequest;
import com.aliyun.ecs20140526.models.RunCommandResponse;
import com.aliyun.teaopenapi.models.Config;
import com.google.gson.Gson;

import java.util.Arrays;
import java.util.List;

public class EcsService {
    public static void main(String[] args_) throws Exception {
        // 地區ID
        String regionId = "cn-hangzhou";
        Config config = new Config()
                .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
                .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"))
                .setRegionId(regionId);
        Client ecsClient = new Client(config);
        RunCommandRequest request = new RunCommandRequest();
        request.setRegionId(regionId);
        request.setType("RunShellScript");
        // 開啟自訂參數功能
        request.setEnableParameter(true);
        // 待執行命令內容
        String commandContent = "echo '{{oos-secret:password}}' | passwd '{{oos:username}}' --stdin";
        request.setCommandContent(commandContent);
        List<String> instanceIds = Arrays.asList("i-bp1h23xufsi8XXXXXXXX");
        request.setInstanceId(instanceIds);
        // 命令執行逾時時間
        request.setTimeout(60L);
        RunCommandResponse response = ecsClient.runCommand(request);
        System.out.println(new Gson().toJson(response.getBody()));
    }
}

      import json
import os

from alibabacloud_ecs20140526 import models as ecs_20140526_models
from alibabacloud_ecs20140526.client import Client as Ecs20140526Client
from alibabacloud_tea_openapi import models as open_api_models

ACCESS_KEY_ID = os.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID")
ACCESS_KEY_SECRET = os.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")


def get_ecs_client(region_id):
    config = open_api_models.Config(
        access_key_id=ACCESS_KEY_ID,
        access_key_secret=ACCESS_KEY_SECRET,
        region_id=region_id
    )
    return Ecs20140526Client(config)


def main():
    # 地區ID
    region_id = "cn-hangzhou"
    client = get_ecs_client(region_id)
    # 要執行命令的ECS執行個體ID
    instance_ids = ["i-bp1h23xufsi8XXXXXXXX"]
    # 待執行命令內容
    command_content = "echo '{{oos-secret:password}}' | passwd '{{oos:username}}' --stdin"
    # 命令執行逾時時間，單位為秒
    command_timeout = 60
    # 適用於Linux執行個體的Shell命令：RunShellScript
    command_type = "RunShellScript"

    # 執行命令
    request = ecs_20140526_models.RunCommandRequest()
    request.region_id = region_id
    request.type = command_type
    # 開啟自訂參數功能
    request.enable_parameter = True
    request.command_content = command_content
    request.instance_id = instance_ids
    request.timeout = command_timeout
    response = client.run_command(request)
    print("execute_command result:", json.dumps(response.to_map()['body']))


if __name__ == "__main__":
    main()

    內建環境參數介紹

    可以指定內建環境參數作為自訂參數，在執行命令時，無需手動為參數賦值，雲助手將自動替換為相應的值。

    內建環境參數

    說明

    {{ACS::RegionId}}

    地區ID。

    {{ACS::AccountId}}

    阿里雲主帳號UID。

    {{ACS::InstanceId}}

    執行個體 ID。命令下發到多個執行個體時，如需指定{{ACS::InstanceId}}作為內建環境參數，需確保雲助手 Agent 不低於以下版本：

    • Linux：2.2.3.309

    • Windows：2.1.3.309

    {{ACS::InstanceName}}

    執行個體名稱。命令下發到多個執行個體時，如需指定{{ACS::InstanceName}}作為內建環境參數，需確保雲助手 Agent 不低於以下版本：

    • Linux：2.2.3.344

    • Windows：2.1.3.344

    {{ACS::InvokeId}}

    命令執行ID。如需指定{{ACS::InvokeId}}作為內建環境參數，需確保雲助手 Agent 不低於以下版本：

    • Linux：2.2.3.309

    • Windows：2.1.3.309

    {{ACS::CommandId}}

    命令 ID。通過調用 RunCommand介面執行命令時，如需指定{{ACS::CommandId}}作為內建環境參數，需確保雲助手 Agent 不低於以下版本：

    • Linux：2.2.3.309

    • Windows：2.1.3.309