DescribeInvocations - Elastic Compute Service

呼叫 DescribeInvocations 查詢雲端助手命令的執行列表和狀態。

介面說明

當您執行命令後，不代表命令一定成功運行，並且一定有預期的命令效果。您需要透過介面返回值查看實際執行結果，以實際輸出結果為準。
您可以查詢最近 30 天的執行資訊，執行資訊的保留上限為 1 萬條。
您可以透過雲端助手任務狀態事件訂閱的方式，透過事件取得任務結果，避免頻繁輪詢，用以提升效率。
分頁查詢首頁時，僅需設定MaxResults以限制返回資訊的條目數，返回結果中的NextToken將作為查詢後續頁的憑證。查詢後續頁時，將NextToken參數設定為上一次返回結果中取得到的NextToken作為查詢憑證，並設定MaxResults限制返回條目數。
DescribeInvocations和DescribeInvocationResults差異點：
- 當一次RunCommand/InvokeCommand呼叫指定有多個執行個體時：
  - 使用DescribeInvocations可以取得任務在各個執行個體上的執行狀態、多個執行個體任務狀態的聚合狀態；
  - 使用DescribeInvocationResults僅能取得各個執行個體上的單獨的執行狀態，不包含多執行個體的聚合狀態；
- 當一次RunCommand/InvokeCommand呼叫指定有一個執行個體時：
  - DescribeInvocations與DescribeInvocationResults區別不大，完全可以互相替換。
- 當需要查看定時性（週期性）任務、開機自動執行任務（RepeatMode=Period, EveryReboot）的每一次執行情況時，僅能用DescribeInvocationResults可以查詢取得執行的過往歷史記錄（需指定IncludeHistory=true），而DescribeInvocations僅支援返回最新的任務狀態。
- 當需要查看命令的內容、參數時，僅有DescribeInvocations返回CommandContent。

調試

您可以在OpenAPI Explorer中直接運行該介面，免去您計算簽名的困擾。運行成功後，OpenAPI Explorer可以自動產生SDK程式碼範例。

調試

授權資訊

下表是API對應的授權資訊，可以在RAM權限原則語句的Action元素中使用，用來給RAM使用者或RAM角色授予調用此API的許可權。具體說明如下：

操作：是指具體的許可權點。
存取層級：是指每個操作的存取層級，取值為寫入（Write）、讀取（Read）或列出（List）。
資源類型：是指操作中支援授權的資源類型。具體說明如下：
- 對於必選的資源類型，用前面加 * 表示。
- 對於不支援資源級授權的操作，用全部資源表示。
條件關鍵字：是指雲產品自身定義的條件關鍵字。
關聯操作：是指成功執行操作所需要的其他許可權。操作者必須同時具備關聯操作的許可權，操作才能成功。

操作

存取層級

資源類型

條件關鍵字

關聯操作

ecs:DescribeInvocations

get

Instance

acs:ecs:{#regionId}:{#accountId}:instance/{#instanceId}

Command

acs:ecs:{#regionId}:{#accountId}:command/{#commandId}

無

請求參數

名稱	類型	必填	描述	樣本值
RegionId	string	是	地域 ID。您可以呼叫 DescribeRegions 查看最新的阿里雲地域列表。	cn-hangzhou
ResourceGroupId	string	否	命令執行的資源群組 ID。傳入該參數後，需要在執行命令時指定 ResourceGroupId，支援篩選出對應的命令執行結果。	rg-bp67acfmxazb4p****
RegionId	string	是	地域 ID。您可以呼叫 DescribeRegions 查看最新的阿里雲地域列表。	cn-hangzhou
InvokeId	string	否	命令執行 ID。	t-hz0jdfwd9f****
CommandId	string	否	命令 ID。您可以透過介面 DescribeCommands 查詢所有可用的 CommandId。	c-hz0jdfwcsr****
CommandName	string	否	命令名稱。如果同時設定了`InstanceId`參數，則該參數不生效。	CommandTestName
CommandType	string	否	命令類型。取值範圍： RunBatScript：命令為在 Windows 執行個體中運行的 Bat 指令碼。 RunPowerShellScript：命令為在 Windows 執行個體中運行的 PowerShell 指令碼。 RunShellScript：命令為在 Linux 執行個體中運行的 Shell 指令碼。	RunShellScript
Timed	boolean	否	查詢的命令是否在將來會自動執行。取值範圍： true：查詢在呼叫`RunCommand`或`InvokeCommand`執行命令時，`RepeatMode`參數取值為`Period`、`NextRebootOnly`或者`EveryReboot`。 false：查詢以下兩種狀態的命令。在呼叫`RunCommand`或`InvokeCommand`執行命令時，`RepeatMode`參數取值為`Once`。已被取消、被停止或者已完成執行的命令。預設值：false。	true
InvokeStatus	string	否	命令執行的總執行狀態。總執行狀態取決於建立執行中的一台或多台執行個體的共同執行狀態。取值範圍： Running：定時執行：未手動停止定時執行命令前，執行狀態一直為進行中。單次執行：一旦有進行中的命令處理程序，總的執行狀態就為進行中。 Finished：定時執行：命令處理程序不可能為執行完成。單次執行：所有執行個體全部完成執行。或者手動停止部分執行個體的命令處理程序，其餘執行個體全部執行完成。 Success：各個執行個體上的命令執行狀態均為 Stopped 或 Success，且至少一個執行個體的命令執行狀態是 Success，則總執行狀態為 Success。立即運行的任務：命令執行完成，且退出碼為 0。定時運行的任務：最近一次執行成功且退出碼為 0，且指定的時間已全部完成。 Failed：定時執行：命令處理程序不可能為執行失敗。單次執行：所有執行個體全部執行失敗。 Stopped：停止命令。 Stopping：停止中。 PartialFailed：部分失敗；如果同時設定了`InstanceId`參數，則不生效。 Pending：系統正在校驗或傳送命令。存在至少一台執行個體的命令執行狀態為 Pending，則總執行狀態為 Pending。 Scheduled：定時執行的命令已傳送，等待運行。存在至少一台執行個體的命令執行狀態為 Scheduled，則總執行狀態為 Scheduled。	Finished
InstanceId	string	否	執行個體 ID。當您傳入了該參數，將查詢該執行個體所有的命令執行記錄。	i-bp1i7gg30r52z2em****
ContentEncoding	string	否	設定返回資料中`CommandContent`欄位和`Output`欄位的編碼方式。取值範圍： PlainText：返回原始命令內容和輸出資訊。 Base64：返回 Base64 編碼後的命令內容和輸出資訊。預設值：Base64。	PlainText
IncludeOutput	boolean	否	是否在結果中返回命令運行的輸出資訊。 true：返回。此時，您至少指定參數`InvokeId`或`InstanceId`。 false：不返回。預設值：false。	false
PageNumber	integer	否	說明該參數即將下線，推薦您使用 NextToken 與 MaxResults 完成分頁查詢操作。	1
PageSize	integer	否	說明該參數即將下線，推薦您使用 NextToken 與 MaxResults 完成分頁查詢操作。	10
MaxResults	integer	否	分頁查詢時每頁的最大條目數。最大值為 50。預設值為 10。	10
NextToken	string	否	查詢憑證（Token），取值為上一次 API 呼叫返回的 NextToken 參數值。	AAAAAdDWBF2
RepeatMode	string	否	命令執行的方式。如果同時設定了`InstanceId`參數，則不生效。取值範圍： Once：立即執行命令。 Period：定時執行命令。 NextRebootOnly：當執行個體下一次啟動時，自動執行命令。 EveryReboot：執行個體每一次啟動都將自動執行命令。預設值為空，表示查詢全部。	Once
Tag	array<object>	否	標籤列表。
	object	否	標籤列表。
Value	string	否	命令執行的標籤值。N 的取值範圍為 1~20。該值可以為空字串。最多支援 128 個字元，不能包含`http://`或`https://`。	TestValue
Key	string	否	命令執行的標籤鍵。N 的取值範圍為 1~20。一旦傳入該值，則不允許為空字串。使用一個標籤過濾資源，查詢到該標籤下的資源數量不能超過 1000 個；使用多個標籤過濾資源，查詢到同時繫結了多個標籤的資源數量不能超過 1000 個。如果資源數量超過 1000 個，您需要使用 ListTagResources 介面進行查詢。最多支援 64 個字元，不能以`aliyun`或`acs:`開頭，不能包含`http://`或`https://`。	TestKey

返回參數

名稱	類型	描述	樣本值
	object
PageSize	integer	每頁行數。	10
RequestId	string	請求 ID。	473469C7-AA6F-4DC5-B3DB-A3DC0DE3****
PageNumber	integer	查詢結果的頁碼。	1
TotalCount	integer	命令總個數。	1
NextToken	string	本次呼叫返回的查詢憑證值。	AAAAAdDWBF2
Invocations	object
Invocation	array<object>	命令執行記錄組成的陣列。
	array<object>	任務建立的時間。
OssOutputDelivery	string	命令執行 Output OSS 投遞配置。	oss://testBucket/testPrefix
InvocationStatus	string	命令執行的總執行狀態，總執行狀態取決於本次呼叫的全部執行個體的共同執行狀態，可能值： Pending：系統正在校驗或傳送命令。存在至少一台執行個體的命令執行狀態為 Pending，則總執行狀態為 Pending。 Scheduled：定時執行的命令已傳送，等待運行。存在至少一台執行個體的命令執行狀態為 Scheduled，則總執行狀態為 Scheduled。 Running：命令正在執行個體上運行。存在至少一台執行個體的命令執行狀態為 Running，則總執行狀態為 Running。 Success：各個執行個體上的命令執行狀態均為 Stopped 或 Success，且至少一個執行個體的命令執行狀態是 Success，則總執行狀態為 Success。立即運行的任務：命令執行完成，且退出碼為 0。定時運行的任務：最近一次執行成功且退出碼為 0，且指定的時間已全部完成。 Failed：各個執行個體上的命令執行狀態均為 Stopped 或 Failed，則總執行狀態為 Failed。執行個體上的命令執行狀態一項或多項為以下狀態時，返回值均為 Failed 狀態：命令校驗失敗（Invalid）。命令傳送失敗（Aborted）。命令執行完成但退出碼非 0（Failed）。命令執行逾時（Timeout）。命令執行異常（Error）。 Stopping：正在停止任務。存在至少一台執行個體的命令執行狀態為 Stopping，則總執行狀態為 Stopping。 Stopped：任務已停止。所有執行個體的命令執行狀態是 Stopped，則總執行狀態為 Stopped。執行個體上的命令執行狀態為以下狀態時，返回值均為 Stopped 狀態：任務已取消（Cancelled）。任務已終止（Terminated）。 PartialFailed：部分執行個體執行成功且部分執行個體執行失敗。各個執行個體的命令執行狀態均為 Success、Failed 或 Stopped，則總執行狀態為 PartialFailed。說明返回參數中的`InvokeStatus`與該參數意義相似，但建議您查看該返回值。	Running
Parameters	string	命令中的自訂參數。	{}
Timed	boolean	查詢的命令是否在將來會自動執行。	false
CommandDescription	string	命令描述。	testDescription
Timeout	integer	您建立的命令在 ECS 執行個體中執行時最大的逾時時間，單位：秒。當因為某種原因無法運行您建立的命令時，會出現逾時現象。逾時後，會強制終止命令處理程序，即取消命令的 PID。	60
InvokeInstances	object
InvokeInstance	array<object>	執行目標執行個體集類型。
	object	執行狀態列表。
Dropped	integer	Output 欄位中文字長度超出 24 KB 後，截斷丟棄的文字長度。	0
InvocationStatus	string	單台執行個體的命令進度狀態，可能值： Pending：系統正在校驗或傳送命令。 Invalid：指定命令類型或參數有誤。 Aborted：向執行個體傳送命令失敗。執行個體必須在運行中，且命令可以 1 分鐘內傳送完成。 Running：命令正在執行個體上運行。 Success：單次執行的命令：命令執行完成，且退出碼為 0。定時執行的命令：上一次運行成功且退出碼為 0，且指定的時間已結束。 Failed：單次執行的命令：命令執行完成，且退出碼非 0。定時執行的命令：上一次運行成功且退出碼非 0，且指定的時間將中止。 Error：命令執行時發生異常無法繼續。 Timeout：命令執行逾時。 Cancelled：命令的執行動作已經取消，命令未曾啟動。 Stopping：正在停止任務。 Terminated：命令運行時被終止。 Scheduled：單次執行的命令：不適用，不會出現。定時執行的命令：等待運行。	Success
InstanceId	string	執行個體 ID。	i-bp1i7gg30r52z2em****
Timed	boolean	查詢的命令是否在將來會自動執行。	false
InstanceInvokeStatus	string	單台執行個體的命令進度狀態。說明不推薦查看該返回值，推薦您查看`InvocationStatus`的返回值。	Finished
ExitCode	integer	命令處理程序的退出代碼。可能值： Linux 執行個體為 Shell 處理程序的退出碼。 Windows 執行個體為 Bat 或者 PowerShell 處理程序的退出碼。	0
ErrorInfo	string	命令的下發失敗或執行失敗原因的詳情，可能值：空：命令運行正常。 The security group rules denied access to the aliyun service：安全性群組規則拒絕存取雲端助手服務。 The specified instance does not exist：指定的執行個體不存在或已釋放。 The specified instance was released during task execution：執行命令期間，該執行個體被釋放。 The specified instance was not running during task execution：開始執行命令時，該執行個體不在運行中。 The OS type of the instance does not support the specified command type：命令不適用於指定的執行個體。 The specified account does not exist：指定的帳號不存在。 The specified directory does not exist：指定的目錄不存在。 The cron expression is invalid：指定的執行時間運算式不合法。 The aliyun service is not running on the instance：雲端助手 Agent 未運行。 The aliyun service in the instance does not response：雲端助手 Agent 無回應。 The aliyun service in the instance is upgrading during task execution：雲端助手 Agent 正在升級中。 The aliyun service in the instance need to be upgraded to at least version to support the feature：雲端助手 Agent 需要升級。為該特性最低支援版本號，為具體特性。 The command delivery has been timeout：傳送命令逾時。 The command execution has been timeout：命令執行逾時。 The command execution got an exception：命令執行發生異常。 The command execution exit code is not zero：命令執行結束，退出碼非 0。 The specified instance was released during task execution：下發檔案期間，該執行個體被釋放。	the specified instance does not exists
StartTime	string	命令在執行個體中開始執行的時間。	2019-12-20T06:15:55Z
Repeats	integer	命令在該執行個體上執行的次數。若執行方式為單次執行，則值為 0 或 1。若執行方式為定時執行，則值為執行過多少次。	0
OssOutputUri	string	命令執行 Output 投遞到 OSS 的檔案 URI 位址，當投遞失敗/投遞中時該欄位為空字串。	oss://testBucket/testPrefix/output.txt
OssOutputStatus	string	命令執行 Output 投遞狀態。列舉值： InProgress：投遞中。 Finished：投遞完成。 Failed：投遞失敗。	Finished
OssOutputErrorCode	string	投遞失敗時的錯誤碼，僅在 OssOutputStatus 為 Failed 時返回。取值範圍： CloudAssistant.UnsupportedInvocationStatus：任務狀態不支援投遞。 CloudAssistant.ClientNeedUpgrade：雲端助手版本不支援投遞。Linux 執行個體雲端助手版本需大於 2.2.4.1007，Windows 執行個體雲端助手版本需大於 2.1.4.1007。 OSS.AccessDenied：使用者對設定的 Bucket 沒有存取權限。 OSS.NoSuchBucket：設定的 Bucket 不存在。 OSS.FileImmutable：Bucket 中的資料處於被保護狀態。 OSS.InvalidObjectName：Object 名稱不符合規範，包括未指定 Object 名稱、Object 名稱超出長度限制、指定的 Object 名稱無效。	CloudAssistant.UnsupportedInvocationStatus
OssOutputErrorInfo	string	投遞失敗時的錯誤詳情，僅在 OssOutputStatus 為 Failed 時返回。	The invocation status does not support output delivery.
FinishTime	string	命令處理程序的結束時間。	2019-12-20T06:15:56Z
Output	string	命令的輸出資訊。若 ContentEncoding 指定 PlainText，返回原始輸出資訊。若 ContentEncoding 指定 Base64，返回 Base64 編碼後的輸出資訊。	OutPutTestmsg
CreationTime	string	命令執行的開始時間。	2019-12-20T06:15:54Z
UpdateTime	string	命令狀態的更新時間。	2020-01-19T09:15:47Z
ErrorCode	string	命令的下發失敗或執行失敗原因的代碼，可能值：空：命令運行正常。 InstanceNotExists：指定的執行個體不存在或已釋放。 InstanceReleased：執行命令期間，該執行個體被釋放。 InstanceNotRunning：開始執行命令時，該執行個體不在運行中。 CommandNotApplicable：命令不適用於指定的執行個體。 AccountNotExists：指定的執行命令的使用者名稱不存在。 DirectoryNotExists：指定的目錄不存在。 BadCronExpression：指定的執行時間運算式不合法。 ClientNotRunning：雲端助手 Agent 未運行。 ClientNotResponse：雲端助手 Agent 無回應。 ClientIsUpgrading：雲端助手 Agent 正在升級中。 ClientNeedUpgrade：雲端助手 Agent 需要升級。 DeliveryTimeout：傳送命令逾時。 ExecutionTimeout：命令執行逾時。 ExecutionException：命令執行發生異常。 ExecutionInterrupted：命令執行任務中斷。 ExitCodeNonzero：命令執行結束，退出碼非 0。 SecurityGroupRuleDenied：安全性群組規則拒絕存取雲端助手服務。 TaskConcurrencyLimit：任務並行執行數量超過最大額度。	InstanceNotExists
StopTime	string	若呼叫了`StopInvocation`以停止命令執行，表示呼叫的時間。	2020-01-19T09:15:47Z
CommandContent	string	命令內容。若 ContentEncoding 指定 PlainText，返回原始指令碼內容。若 ContentEncoding 指定 Base64，返回 Base64 編碼後的指令碼內容。	cnBtIC1xYSB8IGdyZXAgdnNm****
WorkingDir	string	命令執行路徑。	/home/
RepeatMode	string	命令執行的方式。可能值： Once：立即執行命令。 Period：定時執行命令。 NextRebootOnly：當執行個體下一次啟動時，自動執行命令。 EveryReboot：執行個體每一次啟動都將自動執行命令。 DryRun：只預檢此次請求，命令執行不會實際生效，檢查項包括請求參數、執行個體執行環境、雲端助手 Agent 運行狀態等。	Once
InvokeStatus	string	命令總的執行狀態。說明不推薦查看該返回值，推薦您查看`InvocationStatus`的返回值。	Finished
CommandType	string	命令類型。	RunShellScript
Username	string	ECS 執行個體中執行命令的使用者名稱。	test
ContainerId	string	容器 ID。	ab141ddfbacfe02d9dbc25966ed971536124527097398d419a6746873fea****
ContainerName	string	容器名稱。	test-container
CreationTime	string	任務的建立時間。	2020-01-19T09:15:46Z
Frequency	string	定時執行命令的執行時間。	0 /20 * * *
Launcher	string	指令碼執行的引導程式。長度不能超過 1 KB。	python3 -u {{ACS::ScriptFileName\|Ext(".py")}}
CommandId	string	命令 ID。	c-hz0jdfwcsr****
CommandName	string	命令名稱。	CommandTestName
InvokeId	string	命令執行 ID。	t-hz0jdfwd9f****
TerminationMode	string	停止任務（手動停止或執行逾時打斷）時的模式。可能值： Process：停止當前指令碼處理程序。 ProcessTree：停止當前處理程序樹（指令碼處理程序以及它建立的所有子處理程序的集合）。	ProcessTree
Tags	object
Tag	array<object>	命令執行的標籤資訊。
	object	命令執行的標籤資訊。
TagKey	string	命令執行的標籤鍵。	owner
TagValue	string	命令執行的標籤值。	zhangsan

樣本

正常返回樣本

JSON格式

{
  "PageSize": 10,
  "RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3****",
  "PageNumber": 1,
  "TotalCount": 1,
  "NextToken": "AAAAAdDWBF2",
  "Invocations": {
    "Invocation": [
      {
        "OssOutputDelivery": "oss://testBucket/testPrefix",
        "InvocationStatus": "Running",
        "Parameters": "{}",
        "Timed": false,
        "CommandDescription": "testDescription",
        "Timeout": 60,
        "InvokeInstances": {
          "InvokeInstance": [
            {
              "Dropped": 0,
              "InvocationStatus": "Success",
              "InstanceId": "i-bp1i7gg30r52z2em****",
              "Timed": false,
              "InstanceInvokeStatus": "Finished",
              "ExitCode": 0,
              "ErrorInfo": "the specified instance does not exists",
              "StartTime": "2019-12-20T06:15:55Z",
              "Repeats": 0,
              "OssOutputUri": "oss://testBucket/testPrefix/output.txt",
              "OssOutputStatus": "Finished",
              "OssOutputErrorCode": "CloudAssistant.UnsupportedInvocationStatus",
              "OssOutputErrorInfo": "The invocation status does not support output delivery.",
              "FinishTime": "2019-12-20T06:15:56Z",
              "Output": "OutPutTestmsg",
              "CreationTime": "2019-12-20T06:15:54Z",
              "UpdateTime": "2020-01-19T09:15:47Z",
              "ErrorCode": "InstanceNotExists",
              "StopTime": "2020-01-19T09:15:47Z"
            }
          ]
        },
        "CommandContent": "cnBtIC1xYSB8IGdyZXAgdnNm****",
        "WorkingDir": "/home/",
        "RepeatMode": "Once",
        "InvokeStatus": "Finished",
        "CommandType": "RunShellScript",
        "Username": "test",
        "ContainerId": "ab141ddfbacfe02d9dbc25966ed971536124527097398d419a6746873fea****",
        "ContainerName": "test-container",
        "CreationTime": "2020-01-19T09:15:46Z",
        "Frequency": "0 */20 * * * *",
        "Launcher": "python3 -u {{ACS::ScriptFileName|Ext(\".py\")}}",
        "CommandId": "c-hz0jdfwcsr****",
        "CommandName": "CommandTestName",
        "InvokeId": "t-hz0jdfwd9f****",
        "TerminationMode": "ProcessTree",
        "Tags": {
          "Tag": [
            {
              "TagKey": "owner",
              "TagValue": "zhangsan"
            }
          ]
        }
      }
    ]
  }
}

錯誤碼

HTTP status code	錯誤碼	錯誤資訊
400	RegionId.ApiNotSupported	The api is not supported in this region.
400	NumberExceed.Tags	The Tags parameter number is exceed.
400	Duplicate.TagKey	The Tag.N.Key contain duplicate key.
400	InvalidTagKey.Malformed	The specified Tag.n.Key is not valid.
400	InvalidTagValue.Malformed	The specified Tag.n.Value is not valid.
400	MissingParameter.TagKey	You must specify Tag.N.Key.
400	InvalidParam.PageNumber	The specified parameter is invalid.
400	InvalidParam.PageSize	The specified parameter is invalid.
400	InvalidParameter.NextToken	The specified parameter NextToken is not valid.
400	InvalidParameter.MaxResults	The specified parameter MaxResults is not valid.
500	InternalError.Dispatch	An error occurred when you dispatched the request.
403	Operation.Forbidden	The operation is not permitted.
404	InvalidRegionId.NotFound	The RegionId provided does not exist in our records.

訪問錯誤中心查看更多錯誤碼。

變更歷史

更多資訊，參考變更詳情。