Elastic Compute Service：RunCommand - 建立並執行雲助手命令

地區 ID。您可以調用 DescribeRegions 查看最新的阿里雲地區列表。

命令執行的資源群組 ID，當指定該參數時：

• 當 InstanceId 對應的 ECS 執行個體屬於非預設資源群組時，該 ECS 執行個體必須屬於該資源群組。

• 支援通過指定該參數篩選出對應的命令執行結果（通過調用 DescribeInvocations 或 DescribeInvocationResults ）。

地區 ID。您可以調用 DescribeRegions 查看最新的阿里雲地區列表。

命令名稱。支援全字元集，長度不得超過 128 個字元。

命令描述。支援全字元集，長度不得超過 512 個字元。

命令類型。取值範圍：

• RunBatScript：適用於 Windows 執行個體的 Bat 命令。

• RunPowerShellScript：適用於 Windows 執行個體的 PowerShell 命令。

• RunShellScript：適用於 Linux 執行個體的 Shell 命令。

命令內容。命令內容可以是明文內容或 Base 64 編碼後的內容。您需要注意：

• 若儲存命令，命令內容在 Base 64 編碼後的大小不能超過 18 KB；若不儲存命令，命令內容在 Base 64 編碼後的大小不能超過 24 KB。您可通過KeepCommand設定是否保留命令。

• 如果您的命令內容是 Base 64 編碼後的內容，則必須設定ContentEncoding=Base64。

• 指定參數EnableParameter=true可在命令內容中啟用自訂參數功能：

  • 用{{}}包含的方式定義自訂參數，在{{}}內參數名前後的空格以及分行符號會被忽略。

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

  • 自訂參數名允許 a-zA-Z0-9-_的組合，不支援 acs::首碼指定非內建環境參數，不支援其餘字元，參數名不區分大小寫。

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

• 您可以指定內建環境參數作為自訂參數，執行命令時無需手動對參數賦值，雲助手將為您自動替換為環境中對應的值。支援指定以下內建環境參數：

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

    • Linux：2.2.3.309

    • Windows：2.1.3.309

命令在 ECS 執行個體中的運行目錄。長度不得超過 200 個字元。

預設值：

• Linux 系統執行個體預設在管理員（root 使用者）的 home 目錄下，即/root。

• Windows 系統執行個體預設在雲助手 Agent 進程所在目錄，例如C:\Windows\System32。

執行命令的逾時時間，單位：秒。

當因為進程原因、缺失模組、缺失雲助手 Agent 等原因無法運行命令時，會出現逾時現象。逾時後，會強制終止命令進程。

預設值：60。

命令中是否包含自訂參數。

預設值：false。

設定命令執行的方式。取值範圍：

• Once：立即執行命令。

• Period：定時執行命令。當該參數取值為Period時，必須同時指定Frequency參數。

• NextRebootOnly：當執行個體下一次啟動時，自動執行命令。

• EveryReboot：執行個體每一次啟動都將自動執行命令。

• DryRun：只預檢此次請求，命令執行不會實際生效，檢查項包括請求參數、執行個體執行環境、雲助手 Agent 運行狀態等。

預設值：

• 當不指定Frequency參數時，預設值為Once。

• 當指定Frequency參數時，無論是否已設定了該參數值，都將按照Period處理。

注意事項：

• 您可以調用 StopInvocation 停止待執行的命令或定時執行的命令。

• 當該參數取值Period或者EveryReboot時，您可以調用 DescribeInvocationResults ，然後指定IncludeHistory=true查看命令定時執行的記錄。

定時執行命令的執行時間。目前支援三種定時執行方式：固定時間間隔執行（基於 Rate 運算式）、僅在指定時間執行一次、基於時鐘定時執行（基於 Cron 運算式）。

• 固定時間間隔執行：基於 Rate 運算式，按照設定的時間間隔執行命令。時間間隔支援按秒（s） 、分鐘（m） 、小時（h）和天（d）來選擇，適用於在固定時間間隔執行任務的情境。格式為rate(<執行間隔數值><執行間隔單位>)，如 5 分鐘執行一次，格式為rate(5m)。使用固定時間間隔執行有以下限制：

  • 設定的時間間隔不大於 7 天、不小於 60 秒，且需大於定時任務的逾時時間。

  • 執行間隔只基於固定頻率，與任務實際執行需要的時間無關。例如設定每 5 分鐘執行一次命令，任務需要 2 分鐘執行完成，則在任務完成 3 分鐘後繼續執行下一輪。

  • 建立任務時不會立即執行。例如設定每 5 分鐘執行一次命令，建立任務時不會立即執行一次命令，而是在任務建立完成後的 5 分鐘後開始執行。

• 僅在指定時間執行一次：按照設定的時區和執行時間點執行一次命令。格式為at(yyyy-MM-dd HH:mm:ss <時區>)，即at(年-月-日 時:分:秒 <時區>)。如果不指定時區，預設為 UTC 時區。時區支援以下三種形式：

  • 時區全稱： 如Asia/Shanghai（中國/上海時間）、America/Los_Angeles（美國/洛杉磯時間）等。

  • 時區相對于格林威治時間的位移量： 如GMT+8:00（東八區）、GMT-7:00（西七區）等。使用 GMT 格式時，小時位不支援添加前置字元為零。

  • 時區縮寫： 僅支援 UTC（國際標準時間間）。

  如果指定在中國/上海時間 2022 年 06 月 06 日 13 時 15 分 30 秒執行一次，格式為：at(2022-06-06 13:15:30 Asia/Shanghai)；如果指定在西七區 2022 年 06 月 06 日 13 時 15 分 30 秒執行一次，格式為：at(2022-06-06 13:15:30 GMT-7:00)。

• 基於時鐘定時執行（基於 Cron 運算式）：基於 Cron 運算式，按照設定的定時任務執行命令。格式為<秒> <分鐘> <小時> <日期> <月份> <星期> <年份（可選）> <時區>，即<Cron 運算式> <時區>。在指定的時區下，根據 Cron 運算式推算定時任務執行時間並執行。若不指定時區，預設為執行定時任務執行個體的系統內部時區。關於 Cron 運算式的更多資訊，請參見 Cron 運算式。時區支援以下三種形式：

  • 時區全稱： 如Asia/Shanghai（中國/上海時間）、America/Los_Angeles（美國/洛杉磯時間）等。

  • 時區相對于格林威治時間的位移量： 如GMT+8:00（東八區）、GMT-7:00（西七區）等。使用 GMT 格式時，小時位不支援添加前置字元為零。

  • 時區縮寫： 僅支援 UTC（國際標準時間間）。 例如，在中國/上海時間，2022 年每天上午 10:15 執行一次命令，格式為0 15 10 ? * * 2022 Asia/Shanghai；在東八區時間，2022 年每天上午 10:00 到 11:30 每隔半小時執行，格式為0 0/30 10-11 * * ? 2022 GMT+8:00；在 UTC 時間，從 2022 年開始，每隔兩年的 10 月每天下午 14:00 到下午 14:55 時間段內每隔 5 分鐘執行，格式為0 0/5 14 * 10 ? 2022/2 UTC。

  說明

  設定的最小時間間隔需大於或等於定時任務的逾時時間，且不小於 10 秒。

命令中包含自訂參數時，執行命令時傳入的自訂參數的索引值對。例如，命令內容為echo {{name}}，則可以通過Parameter參數傳入索引值對{"name":"Jack"}。自訂參數將自動替換變數值name，得到一條新的命令，實際執行的是echo Jack。

自訂參數的個數範圍為 0~10，且您需要注意：

• 鍵不允許為空白字串，最多支援 64 個字元。

• 值允許為空白字串。

• 自訂參數與原始命令內容在 Base 64 編碼後，若儲存命令，命令內容在 Base 64 編碼後的大小不能超過 18 KB；若不儲存命令，命令內容在 Base 64 編碼後的大小不能超過 24 KB。您可通過KeepCommand設定是否保留命令。

• 設定的自訂參數名集合必須為建立命令時定義的參數集的子集。對於未傳入的參數，您可以使用Null 字元串代替。

預設值為空白，表示取消設定該參數從而禁用自訂參數。

執行完該命令後，是否保留下來。取值範圍：

• true：保留。可以通過 InvokeCommand 再次執行。會佔用雲助手命令的保有量配額。

• false：不保留。執行完成後自動刪除，不佔用雲助手命令的保有量配額。

預設值：false。

命令內容（CommandContent）的編碼方式。取值範圍（不區分大小寫）：

• PlainText：不編碼，採用明文傳輸。

• Base64：Base 64 編碼。

預設值：PlainText，亂填或錯填該取值會當作 PlainText 處理。

在 ECS 執行個體中執行命令的使用者名稱稱。長度不得超過 255 個字元。

• Linux 系統的 ECS 執行個體，預設以 root 使用者執行命令。

• Windows 系統的 ECS 執行個體，預設以 System 使用者執行命令。

您也可以指定執行個體中已存在的其他使用者執行命令，以普通使用者執行雲助手命令更加安全。更多資訊，請參見設定普通使用者執行雲助手命令。

在 Windows 執行個體中執行命令的使用者的密碼名稱。長度不得超過 255 個字元。

當您希望以非預設使用者（System）在 Windows 執行個體中執行命令時，需要同時傳入Username和該參數。為降低密碼泄露的風險，需要將密碼明文託管在系統營運管理的參數倉庫中，此處僅傳入密碼的名稱。更多資訊，請參見加密參數以及設定普通使用者執行雲助手命令。

容器 ID。僅支援 64 位元 16 進位字串，允許存在docker://、containerd://或者cri-o://首碼來明確指定的容器運行。

注意事項：

• 如果指定了該參數，雲助手將在執行個體的指定容器內執行指令碼。

• 如果指定了該參數，僅支援在雲助手 Agent 版本不低於 2.2.3.344 的 Linux 執行個體內運行。

• 如果指定了該參數，已指定的Username參數和WorkingDir參數將不會生效。僅支援通過容器預設使用者在容器的預設工作目錄下執行命令。詳細資料，請參見使用雲助手在容器內執行命令。

容器名稱。

注意事項：

• 如果指定了該參數，雲助手將在執行個體的指定容器內執行指令碼。

• 如果指定了該參數，僅支援在雲助手 Agent 版本不低於 2.2.3.344 的 Linux 執行個體內運行。

• 如果指定了該參數，已指定的Username參數和WorkingDir參數將不會生效。僅支援通過容器預設使用者在容器的預設工作目錄下執行命令。詳細資料，請參見使用雲助手在容器內執行命令。

保證請求等冪性。從您的用戶端產生一個參數值，確保不同請求間該參數值唯一。ClientToken 只支援 ASCII 字元，且不能超過 64 個字元。更多資訊，請參見如何保證等冪性。

命令執行 Output OSS 投遞配置。

• 格式：oss://${BucketName}/${Prefix}，${BucketName}為待投遞到的 OSS Bucket 名稱，${Prefix}為待投遞到的目錄首碼。

停止任務（手動停止或執行逾時打斷）時的模式。可能值：

• Process：停止當前指令碼進程。

• ProcessTree：停止當前進程樹（指令碼進程以及它建立的所有子進程的集合）。

指令碼執行的引導程式。長度不能超過 1 KB。