DescribeInvocations-阿里云帮助中心

Queries the execution list and status of Cloud Assistant commands.

Operation description

After you run a command, the command may not run successfully or produce the expected results. You must check the actual execution results based on the API response. The actual output prevails.
You can query the execution information of the last 30 days. A maximum of 10,000 execution records are retained.
You can subscribe to Cloud Assistant task status events to obtain task results through events. This prevents frequent polling and improves efficiency.
When paged query the first page, you only need to set MaxResults to limit the number of returned entries. The NextToken value in the response is used as the token to query the next page. When paged query the next page, set the NextToken parameter to the NextToken value obtained from the previous response, and set MaxResults to limit the number of returned entries.
Differences between DescribeInvocations and DescribeInvocationResults:
- When multiple instances are specified in a single RunCommand or InvokeCommand call:
  - You can use DescribeInvocations to obtain the execution status of the task on each instance and the aggregated status of the task across multiple instances.
  - You can use DescribeInvocationResults to obtain only the individual execution status on each instance, which does not include the aggregated status across multiple instances.
- When a single instance is specified in a single RunCommand or InvokeCommand call:
  - DescribeInvocations and DescribeInvocationResults have little difference and can be used interchangeably.
- When you need to view the execution details of each run for scheduled (periodic) tasks or tasks that run automatically on boot (RepeatMode=Period, EveryReboot), you can only use DescribeInvocationResults to query the historical execution records (you must set IncludeHistory=true). DescribeInvocations returns only the latest task status.
- When you need to view the command content and parameters, only DescribeInvocations returns CommandContent.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

ecs:DescribeInvocations

get

Instance

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

Command

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

None

Request parameters

Parameter	Type	Required	Description	Example
RegionId	string	Yes	The region ID. You can call the DescribeRegions operation to query the most recent region list.	cn-hangzhou
ResourceGroupId	string	No	The ID of the resource group to which the command execution belongs. If you specify this parameter, you must also specify ResourceGroupId when you run the command. This allows you to filter the corresponding command execution results.	rg-bp67acfmxazb4p****
InvokeId	string	No	The execution ID of the command.	t-hz0jdfwd9f****
CommandId	string	No	The command ID. You can call the DescribeCommands operation to query all available command IDs.	c-hz0jdfwcsr****
CommandName	string	No	The command name. This parameter does not take effect if the InstanceId parameter is also specified.	CommandTestName
CommandType	string	No	The command type. Valid values: RunBatScript: The command is a batch script that runs on a Windows instance. RunPowerShellScript: The command is a PowerShell script that runs on a Windows instance. RunShellScript: The command is a shell script that runs on a Linux instance.	RunShellScript
Timed	boolean	No	Specifies whether the queried command will be automatically run in the future. Valid values: true: Queries commands for which the RepeatMode parameter is set to Period, NextRebootOnly, or EveryReboot when you call RunCommand or InvokeCommand to run the commands. false: Queries commands in the following states: Commands for which the RepeatMode parameter is set to Once when you call RunCommand or InvokeCommand to run the commands. Commands that have been canceled, stopped, or completed. Default value: false.	true
InvokeStatus	string	No	The overall execution status of the command. The overall execution status depends on the combined execution status of one or more instances involved in the execution. Valid values: Running: Scheduled execution: The execution status remains Running until the scheduled command is manually stopped. One-time execution: The overall execution status is Running as long as a command process is running. Finished: Scheduled execution: The command process cannot be finished. One-time execution: All instances have completed the execution. Alternatively, the command processes on some instances are manually stopped, and the execution on the remaining instances is completed. Success: The command execution status on each instance is Stopped or Success, and the command execution status on at least one instance is Success. Immediately run tasks: The command execution is completed, and the exit code is 0. Scheduled tasks: The most recent execution is successful, the exit code is 0, and the specified schedule has ended. Failed: Scheduled execution: The command process cannot fail. One-time execution: The execution fails on all instances. Stopped: The command is stopped. Stopping: The command is being stopped. PartialFailed: The execution partially fails. This value does not take effect if the InstanceId parameter is also specified. Pending: The system is verifying or sending the command. The overall execution status is Pending if the command execution status on at least one instance is Pending. Scheduled: The scheduled command has been sent and is waiting to be run. The overall execution status is Scheduled if the command execution status on at least one instance is Scheduled.	Finished
InstanceId	string	No	The instance ID. If you specify this parameter, the system queries all command execution records of the instance.	i-bp1i7gg30r52z2em****
ContentEncoding	string	No	The encoding method of the CommandContent and Output fields in the response. Valid values: PlainText: returns the original command content and output. Base64: returns the Base64-encoded command content and output. Default value: Base64.	PlainText
IncludeOutput	boolean	No	Specifies whether to return the output of the command execution in the response. Valid values: true: The output is returned. In this case, you must specify at least the InvokeId or InstanceId parameter. false: The output is not returned. Default value: false.	false
PageNumber	integer	No	Note This parameter will soon be taken offline. We recommend that you use NextToken and MaxResults for paging and paged query operations.	1
PageSize	integer	No	Note This parameter will soon be taken offline. We recommend that you use NextToken and MaxResults for paging and paged query operations.	10
MaxResults	integer	No	The maximum number of entries per page for paging. Maximum value: 50. Default value: 10.	10
NextToken	string	No	The pagination token. Set the value to the NextToken value returned from the previous API call.	AAAAAdDWBF2
RepeatMode	string	No	The execution mode of the command. This parameter does not take effect if the InstanceId parameter is also specified. Valid values: Once: runs the command immediately. Period: runs the command on a schedule. NextRebootOnly: automatically runs the command the next time the instance starts. EveryReboot: automatically runs the command every time the instance starts. Default value: empty. An empty value indicates that all execution modes are queried.	Once
Tag	array<object>	No	The tags.
	object	No	The tags.
Key	string	No	The tag key of the command to execute. Valid values of N: 1 to 20. The tag key cannot be an empty string. If you use a single tag to filter resources, the resource count returned cannot exceed 1,000. If you use multiple tags to filter resources, the resource count of resources that have all the specified tags attached cannot exceed 1,000. If the resource count exceeds 1,000, use the ListTagResources operation to query the resources. The tag key can be up to 64 characters in length. It cannot start with aliyun or acs:, and cannot contain http:// or https://.	TestKey
Value	string	No	The tag value of the command execution. Valid values of N: 1 to 20. The tag value can be an empty string. The tag value can be up to 128 characters in length and cannot contain http:// or https://.	TestValue

Response elements

Element	Type	Description	Example
	object
Invocations	object
Invocation	array<object>	The array of command execution records.
	array<object>	The time when the task was created.
CommandContent	string	The command content. If ContentEncoding is set to PlainText, the original script content is returned. If ContentEncoding is set to Base64, the Base64-encoded script content is returned.	cnBtIC1xYSB8IGdyZXAgdnNm****
CommandDescription	string	The command description.	testDescription
CommandId	string	The command ID.	c-hz0jdfwcsr****
CommandName	string	The command name.	CommandTestName
CommandType	string	The command type.	RunShellScript
ContainerId	string	The container ID.	ab141ddfbacfe02d9dbc25966ed971536124527097398d419a6746873fea****
ContainerName	string	The container name.	test-container
CreationTime	string	The time when the task was created. The time follows the ISO 8601 standard in the UTC format.	2020-01-19T09:15:46Z
Frequency	string	The execution schedule of the command.	0 /20 * * *
InvocationStatus	string	The overall execution status of the command. The overall execution status depends on the combined execution status of all instances involved in the invocation. Valid values: Pending: The system is verifying or sending the command. The overall execution status is Pending if the command execution status on at least one instance is Pending. Scheduled: The scheduled command has been sent and is waiting to be run. The overall execution status is Scheduled if the command execution status on at least one instance is Scheduled. Running: The command is running on the instance. The overall execution status is Running if the command execution status on at least one instance is Running. Success: The command execution status on each instance is Stopped or Success, and the command execution status on at least one instance is Success. Immediately run tasks: The command execution is completed, and the exit code is 0. Scheduled tasks: The most recent execution is successful, the exit code is 0, and the specified schedule has ended. Failed: The command execution status on each instance is Stopped or Failed. The overall execution status is Failed if the command execution status on one or more instances is one of the following: Invalid: The command verification fails. Aborted: The command fails to be sent. Failed: The command execution is completed, but the exit code is not 0. Timeout: The command execution times out. Error: An exception occurs during command execution. Stopping: The task is being stopped. The overall execution status is Stopping if the command execution status on at least one instance is Stopping. Stopped: The task is stopped. The overall execution status is Stopped if the command execution status on all instances is Stopped. The overall execution status is Stopped if the command execution status on an instance is one of the following: Cancelled: The task is canceled. Terminated: The task is terminated. PartialFailed: The execution succeeds on some instances and fails on others. The overall execution status is PartialFailed if the command execution status on each instance is Success, Failed, or Stopped. Note The InvokeStatus response parameter has a similar meaning, but check this parameter instead.	Running
InvokeId	string	The execution ID of the command.	t-hz0jdfwd9f****
InvokeInstances	object
InvokeInstance	array<object>	The target instances of the execution.
	object	The execution status.
CreationTime	string	The start time of the command execution. The time follows the ISO 8601 standard in the UTC format.	2019-12-20T06:15:54Z
Dropped	integer	The length of the truncated and discarded text when the text length in the Output field exceeds 24 KB.	0
ErrorCode	string	The error code for the failure to send or run the command. Valid values: Empty: The command runs normally. InstanceNotExists: The specified instance does not exist or has been released. InstanceReleased: The instance was released during concurrent execution. InstanceNotRunning: The instance was not running when the concurrent execution started. CommandNotApplicable: The command is not applicable to the specified instance. AccountNotExists: The specified username for running the command does not exist. DirectoryNotExists: The specified directory does not exist. BadCronExpression: The specified cron expression is invalid. ClientNotRunning: The Cloud Assistant Agent is not running. ClientNotResponse: The Cloud Assistant Agent does not respond. ClientIsUpgrading: The Cloud Assistant Agent is being upgraded. ClientNeedUpgrade: The Cloud Assistant Agent needs to be upgraded. DeliveryTimeout: The command delivery timed out. ExecutionTimeout: The concurrent execution timed out. ExecutionException: An exception occurred during concurrent execution. ExecutionInterrupted: The concurrent execution task was interrupted. ExitCodeNonzero: The concurrent execution finished, but the exit code is not 0. SecurityGroupRuleDenied: The security group rules denied access to the Cloud Assistant service. TaskConcurrencyLimit: The number of concurrently executed tasks exceeds the limit.	InstanceNotExists
ErrorInfo	string	The error details for the failure to send or run the command. Valid values: Empty: The command runs normally. The security group rules denied access to the aliyun service: The security group rules denied access to the Cloud Assistant service. The specified instance does not exist: The specified instance does not exist or has been released. The specified instance was released during task execution: The instance was released during command execution. The specified instance was not running during task execution: The instance was not running when the command execution started. The OS type of the instance does not support the specified command type: The command is not applicable to the specified instance. The specified account does not exist: The specified account does not exist. The specified directory does not exist: The specified directory does not exist. The cron expression is invalid: The specified cron expression is invalid. The aliyun service is not running on the instance: The Cloud Assistant Agent is not running. The aliyun service in the instance does not response: The Cloud Assistant Agent does not respond. The aliyun service in the instance is upgrading during task execution: The Cloud Assistant Agent is being upgraded. The aliyun service in the instance need to be upgraded to at least version to support the feature: The Cloud Assistant Agent needs to be upgraded. is the minimum version that supports the feature, and is the specific feature. The command delivery has been timeout: The command delivery timed out. The command execution has been timeout: The command execution timed out. The command execution got an exception: An exception occurred during command execution. The command execution exit code is not zero: The command execution finished, but the exit code is not 0. The specified instance was released during task execution: The instance was released during file delivery.	the specified instance does not exists
ExitCode	integer	The exit code of the command process. Valid values: For Linux instances, the exit code of the shell process. For Windows instances, the exit code of the batch or PowerShell process.	0
FinishTime	string	The end time of the command process. The time follows the ISO 8601 standard in the UTC format.	2019-12-20T06:15:56Z
InstanceId	string	The instance ID.	i-bp1i7gg30r52z2em****
InstanceInvokeStatus	string	The command execution status on a single instance. Note Do not check this parameter. Check the InvocationStatus parameter instead.	Finished
InvocationStatus	string	The command execution status on a single instance. Valid values: Pending: The system is verifying or sending the command. Invalid: The specified command type or parameter is invalid. Aborted: The command fails to be sent to the instance. The instance must be running, and the command must be sent within 1 minute. Running: The command is running on the instance. Success: One-time execution: The command execution is completed, and the exit code is 0. Scheduled execution: The previous execution was successful, the exit code is 0, and the specified schedule has ended. Failed: One-time execution: The command execution is completed, but the exit code is not 0. Scheduled execution: The previous execution was successful, but the exit code is not 0, and the specified schedule will be terminated. Error: An exception occurred during command execution and the execution cannot continue. Timeout: The command execution timed out. Cancelled: The command execution is canceled, and the command was not started. Stopping: The task is being stopped. Terminated: The command was terminated during execution. Scheduled: One-time execution: Not applicable. This status does not occur. Scheduled execution: Waiting to be run.	Success
OssOutputErrorCode	string	The error code returned when the delivery fails. This parameter is returned only when OssOutputStatus is Failed. Valid values: CloudAssistant.UnsupportedInvocationStatus: The node status does not support delivery. CloudAssistant.ClientNeedUpgrade: The Cloud Assistant version does not support delivery. The Cloud Assistant version must be later than 2.2.4.1007 for Linux instances and later than 2.1.4.1007 for Windows instances. OSS.AccessDenied: You do not have access permissions to the bucket in Settings. OSS.NoSuchBucket: The bucket specified in Settings does not exist. OSS.FileImmutable: The data in the bucket is in the protection status. OSS.InvalidObjectName: The object name is invalid. This includes cases where the object name is not specified, the object name exceeds the length limit, or the specified object name is invalid.	CloudAssistant.UnsupportedInvocationStatus
OssOutputErrorInfo	string	The error details returned when the delivery fails. This parameter is returned only when OssOutputStatus is Failed.	The invocation status does not support output delivery.
OssOutputStatus	string	The delivery status of the command output. Valid values: InProgress: The delivery is in progress. Finished: The delivery is completed. Failed: The delivery fails.	Finished
OssOutputUri	string	The URI of the file to which the command output is delivered in OSS. This field is an empty string when the delivery fails or is in progress.	oss://testBucket/testPrefix/output.txt
Output	string	The command output. If ContentEncoding is set to PlainText, the original output is returned. If ContentEncoding is set to Base64, the Base64-encoded output is returned.	OutPutTestmsg
Repeats	integer	The number of times the command was run on the instance. For one-time execution, the value is 0 or 1. For scheduled execution, the value is the total number of executions.	0
StartTime	string	The time when the command started to run on the instance. The time follows the ISO 8601 standard in the UTC format.	2019-12-20T06:15:55Z
StopTime	string	The time when the StopInvocation operation was called to stop the command execution. The time follows the ISO 8601 standard in the UTC format.	2020-01-19T09:15:47Z
Timed	boolean	Specifies whether the queried command will be automatically run in the future.	false
UpdateTime	string	The time when the command status was updated. The time follows the ISO 8601 standard in the UTC format.	2020-01-19T09:15:47Z
InvokeStatus	string	The overall execution status of the command. Note Do not check this parameter. Check the InvocationStatus parameter instead.	Finished
Launcher	string	The launcher for script execution. The length cannot exceed 1 KB.	python3 -u {{ACS::ScriptFileName\|Ext(".py")}}
OssOutputDelivery	string	The OSS delivery configuration for the command output.	oss://testBucket/testPrefix
Parameters	string	The custom parameters in the command.	{}
RepeatMode	string	The execution mode of the command. Valid values: Once: runs the command immediately. Period: runs the command on a schedule. NextRebootOnly: automatically runs the command the next time the instance starts. EveryReboot: automatically runs the command every time the instance starts. DryRun: only performs a dry run on the request. The command execution does not take effect. The check items include request parameters, instance execution environment, and Cloud Assistant Agent running status.	Once
Tags	object
Tag	array<object>	The tags of the command execution.
	object	The tags of the command execution.
TagKey	string	The tag key of the command execution.	owner
TagValue	string	The tag value of the command execution.	zhangsan
TerminationMode	string	The mode used to stop the task, either manually or due to an execution timeout. Valid values: Process: stops the current script process. ProcessTree: stops the current process tree, which includes the script process and all its child processes.	ProcessTree
Timed	boolean	Specifies whether the queried command will be automatically run in the future.	false
Timeout	integer	The maximum timeout period for running the created command on the ECS instance. Unit: seconds. If the command cannot run for some reason, a timeout occurs. After the timeout, the command process is forcibly terminated, which means the PID of the command is canceled.	60
Username	string	The username used to run the command on the ECS instance.	test
WorkingDir	string	The execution path of the command.	/home/
NextToken	string	The pagination token returned by the current call.	AAAAAdDWBF2
PageNumber	integer	The page number of the query result.	1
PageSize	integer	The number of entries per page.	10
RequestId	string	The request ID.	473469C7-AA6F-4DC5-B3DB-A3DC0DE3****
TotalCount	integer	The total number of commands. Note The TotalCount parameter is meaningless when you use the MaxResults and NextToken parameters for paging.	1

Examples

Success response

JSON format

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

Error codes

HTTP status code	Error code	Error message	Description
400	RegionId.ApiNotSupported	The api is not supported in this region.	The API operation cannot be called in the specified region. Check whether the specified RegionId parameter is valid.
400	NumberExceed.Tags	The Tags parameter number is exceed.	The number of tags exceeds the maximum limit.
400	Duplicate.TagKey	The Tag.N.Key contain duplicate key.	The specified tag key already exists. Tag keys must be unique.
400	InvalidTagKey.Malformed	The specified Tag.n.Key is not valid.	The specified Tag.N.Key parameter is invalid.
400	InvalidTagValue.Malformed	The specified Tag.n.Value is not valid.	The specified tag value is invalid.
400	MissingParameter.TagKey	You must specify Tag.N.Key.	The tag key is not specified.
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.	The specified parameter NextToken is illegal.
400	InvalidParameter.MaxResults	The specified parameter MaxResults is not valid.	The specified parameter MaxResults is illegal.
500	InternalError.Dispatch	An error occurred when you dispatched the request.	An error occurred while the request is being sent. Try again later.
403	InvalidParameterCharacter	The specified parameter %s contains illegal characters.
403	Operation.Forbidden	The operation is not permitted.	The operation is not supported.
404	InvalidRegionId.NotFound	The RegionId provided does not exist in our records.	Region information error
404	InvalidCommandId.NotFound	The specified commandId does not exist

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.