Use DescribeInvocationResults to query Cloud Assistant command execution results - Elastic Compute Service - Alibaba Cloud - Elastic Compute Service

Queries the execution results of one or more Cloud Assistant commands, which are the actual execution results on ECS instances.

Operation description

After you run a command, the command may not be successfully executed or produce the expected results. You must call this operation paged query the actual execution results. The actual output prevails.
You can query the execution information of the last 30 days. A maximum of 10,000 execution records can be retained.
You can subscribe to Cloud Assistant task status events to obtain task results through events. This prevents frequent polling and improves efficiency.
When you 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 paged query the next page. When you 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 a RunCommand or InvokeCommand call specifies multiple instances:
  - 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 RunCommand or InvokeCommand call specifies a single instance:
  - DescribeInvocations and DescribeInvocationResults have little difference and can be used interchangeably.
- When you need to view each execution record of a scheduled task or a task that runs automatically on startup (RepeatMode=Period, EveryReboot), you can only use DescribeInvocationResults paged query the historical execution records (you must specify 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:DescribeInvocationResults

get

Command

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

Instance

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

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 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. You can call the DescribeInvocations operation to query the InvokeId value.	t-hz0jdfwd9f****
InstanceId	string	No	The instance ID.	i-bp1i7gg30r52z2em****
CommandId	string	No	The command ID.	c-hz0jdfwcsr****
InvokeRecordStatus	string	No	The execution status of the command. Valid values: Running: The command is 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: The command is completed. Scheduled execution: The command process cannot be in the Finished state. One-time execution: The command is completed on all instances, or the command process is manually stopped on some instances and completed on the remaining instances. Success: One-time execution: The command is completed and the exit code is 0. Scheduled execution: The last execution was successful with an exit code of 0, and the specified execution time has ended. Failed: The execution failed. Scheduled execution: The command process cannot be in the Failed state. One-time execution: The command failed on all instances. PartialFailed: The execution partially failed. Scheduled execution: The command process cannot be in the PartialFailed state. One-time execution: The command process failed on some instances, so the overall execution status is PartialFailed. Stopped: The command execution is stopped. Stopping: The command execution is being stopped.	Running
IncludeHistory	boolean	No	Specifies whether to return the history records of commands that execute on a schedule. Valid values: true: Returns the results of commands that execute on a schedule. If this parameter is set to true, the InvokeId parameter cannot be empty and must be the execution ID of a scheduled command (RepeatMode is Period) or a command that runs after each system startup (RepeatMode is EveryReboot). false: Does not return the history records. Default value: false.	false
ContentEncoding	string	No	The encoding method for the `CommandContent` and `Output` fields in the response. Valid values: PlainText: Returns the original command content and output information. Base64: Returns the Base64-encoded command content and output information. Default value: Base64.	PlainText
PageNumber	integer	No	Note This parameter will soon be deprecated. We recommend that you use NextToken and MaxResults for paging.	1
PageSize	integer	No	Note This parameter will soon be deprecated. We recommend that you use NextToken and MaxResults for paging.	1
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
Tag	array<object>	No	The list of tags.
	object	No	The list of tags.
Key	string	No	The tag key of the command that you execute. Valid values of N: 1 to 20. This parameter cannot be an empty string. If you use a single tag to filter resources, the resource count under the tag cannot exceed 1,000. If you use multiple tags to filter resources, the resource count of resources that are attached to all specified tags cannot exceed 1,000. If the resource count exceeds 1,000, you must call 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. This parameter 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
Invocation	object	The collection of command execution results.
InvocationResults	object
InvocationResult	array<object>	The set of command execution results.
	array<object>
CommandId	string	The command ID.	c-hz0jdfwcsr****
ContainerId	string	The container ID.	ab141ddfbacfe02d9dbc25966ed971536124527097398d419a6746873fea****
ContainerName	string	The container name.	test-container
Dropped	integer	The length of the text that is truncated and dropped when the text length in the `Output` field exceeds 24 KB.	0
ErrorCode	string	The error code for the failure to deliver or execute the command. Valid values: Empty: The command is executed 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 command was executed. CommandNotApplicable: The command is not applicable to the specified instance. AccountNotExists: The specified username for executing 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 is not responding. 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 was interrupted. ExitCodeNonzero: The concurrent execution finished with a non-zero exit code. SecurityGroupRuleDenied: Security group rules denied access to the Cloud Assistant service. TaskConcurrencyLimit: The number of concurrently executed tasks exceeds the maximum limit.	InstanceNotExists
ErrorInfo	string	The details of the failure to deliver or execute the command. Valid values: Empty: The command is running normally. The security group rules denied access to the aliyun service: 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 is not responding. 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 supported version for 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 with a non-zero exit code. 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. For Linux instances, it is the exit code of the shell command. For Windows instances, it is the exit code of the batch or PowerShell command.	0
FinishedTime	string	The completion time of the command execution. If the command execution times out, the completion time is calculated by adding the `Timeout` value to the `StartTime` value. The time follows the ISO 8601 standard and is displayed in UTC.	2019-12-20T06:15:56Z
InstanceId	string	The instance ID.	i-bp1i7gg30r52z2em****
InvocationStatus	string	The execution status of the command 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: Failed to send the command to the instance. The instance must be running, and the command must be sent within 1 minute. Running: The command is being executed on the instance. Success: One-time execution: The command is completed and the exit code is 0. Scheduled execution: The last execution was successful with an exit code of 0, and the specified execution time has ended. Failed: One-time execution: The command is completed and the exit code is not 0. Scheduled execution: The last execution finished with a non-zero exit code, and the specified execution time will be aborted. 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 command execution is being stopped. Terminated: The command execution was terminated. Scheduled: One-time execution: Not applicable. This status does not occur. Scheduled execution: Waiting to be executed.	Success
InvokeId	string	The execution ID of the command.	t-hz0jdfwd9f****
InvokeRecordStatus	string	The execution status of the command. Valid values: Running: The command is 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: The command is completed. Scheduled execution: The command process cannot be in the Finished state. One-time execution: The command is completed on all instances, or the command process is manually stopped on some instances and completed on the remaining instances. Failed: The execution failed. Scheduled execution: The command process cannot be in the Failed state. One-time execution: The command failed on all instances. PartialFailed: The execution partially failed. Scheduled execution: The command process cannot be in the PartialFailed state. One-time execution: The command process failed on some instances, so the overall execution status is PartialFailed. Stopped: The command execution is stopped. Stopping: The command execution is being stopped.	Running
Launcher	string	The bootstrap program for script execution. The length cannot exceed 1 KB.	python3 -u {{ACS::ScriptFileName\|Ext(".py")}}
OssOutputDelivery	string	The OSS delivery configuration for the command execution output.	oss://testBucket/testPrefix
OssOutputErrorCode	string	The error code returned when the delivery fails. This parameter is returned only when OssOutputStatus is Failed. Valid values: CloudAssistant.UnsupportedInvocationStatus: The task 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 on the specified bucket. OSS.NoSuchBucket: The specified bucket does not exist. OSS.FileImmutable: The data in the bucket is in a protected state. OSS.InvalidObjectName: The object name does not meet the specifications, including 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 execution output. Valid values: InProgress: The delivery is in progress. Finished: The delivery is completed. Failed: The delivery failed.	Finished
OssOutputUri	string	The URI of the file delivered to OSS for the command execution output. This field is an empty string when the delivery fails or is in progress.	oss://testBucket/testPrefix/output.txt
Output	string	The output information after the command is executed. If ContentEncoding is set to PlainText, the original output information is returned. If ContentEncoding is set to Base64, the Base64-encoded output information is returned.	MTU6MzA6MDEK
Repeats	integer	The number of times the command is executed on the instance. If the execution mode is immediate execution, the value is 0 or 1. If the execution mode is scheduled execution, the value is the number of times the command has been executed.	0
StartTime	string	The time when the command starts to be executed on the instance. The time follows the ISO 8601 standard and is displayed in UTC.	2019-12-20T06:15:55Z
StopTime	string	The time when the `StopInvocation` operation is called to stop the command execution. The time follows the ISO 8601 standard and is displayed in UTC.	2020-01-19T09:15:47Z
Tags	object
Tag	array<object>	The tag information of the command execution.
	object	The tag information 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 when the task is stopped (manually stopped or interrupted due to 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
Username	string	The username used to execute the command on the ECS instance.	test
NextToken	string	The pagination token returned by the current call.	AAAAAdDWBF2
PageNumber	integer	The current page number.	1
PageSize	integer	The number of rows per page for paging.	1
TotalCount	integer	The total number of commands. Note When you use the MaxResults and NextToken parameters for paging, the returned TotalCount value is meaningless.	1
RequestId	string	The request ID.	473469C7-AA6F-4DC5-B3DB-A3DC0DE*****

Examples

Success response

JSON format

{
  "Invocation": {
    "InvocationResults": {
      "InvocationResult": [
        {
          "CommandId": "c-hz0jdfwcsr****",
          "ContainerId": "ab141ddfbacfe02d9dbc25966ed971536124527097398d419a6746873fea****",
          "ContainerName": "test-container",
          "Dropped": 0,
          "ErrorCode": "InstanceNotExists",
          "ErrorInfo": "the specified instance does not exists",
          "ExitCode": 0,
          "FinishedTime": "2019-12-20T06:15:56Z",
          "InstanceId": "i-bp1i7gg30r52z2em****",
          "InvocationStatus": "Success",
          "InvokeId": "t-hz0jdfwd9f****",
          "InvokeRecordStatus": "Running",
          "Launcher": "python3 -u {{ACS::ScriptFileName|Ext(\".py\")}}",
          "OssOutputDelivery": "oss://testBucket/testPrefix",
          "OssOutputErrorCode": "CloudAssistant.UnsupportedInvocationStatus",
          "OssOutputErrorInfo": "The invocation status does not support output delivery.",
          "OssOutputStatus": "Finished",
          "OssOutputUri": "oss://testBucket/testPrefix/output.txt",
          "Output": "MTU6MzA6MDEK",
          "Repeats": 0,
          "StartTime": "2019-12-20T06:15:55Z",
          "StopTime": "2020-01-19T09:15:47Z",
          "Tags": {
            "Tag": [
              {
                "TagKey": "owner",
                "TagValue": "zhangsan"
              }
            ]
          },
          "TerminationMode": "ProcessTree",
          "Username": "test"
        }
      ]
    },
    "NextToken": "AAAAAdDWBF2",
    "PageNumber": 1,
    "PageSize": 1,
    "TotalCount": 1
  },
  "RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE*****"
}

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.
500	ServiceUnavailable	The request has failed due to a temporary failure of the server.
500	InternalError	The request processing has failed due to some unknown error.
403	InvalidParameterCharacter	The specified parameter %s contains illegal characters.
403	Operation.Forbidden	The operation is not permitted.	The operation is not supported.
403	RequestDenied.WAFIntercepted	Request denied by WAF security protection.	The request is blocked by WAF security protection.
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.