Querying Tasks and Details

Function

This API is used to query tasks (by default) and details.

Authorization Information

Each account has permissions to call all APIs, but IAM users must have the required permissions specifically assigned.

If you are using role/policy-based authorization, see the required permissions in Permissions and Supported Actions.

If you are using identity policy-based authorization, the following identity policy-based permissions are required.

Action	Access Level	Resource Type (*: required)	Condition Key	Alias	Dependencies
gaussdbfornosql:task:list	List	instance *	g:ResourceTag/<tag-key> g:EnterpriseProjectId	nosql:task:list	-

URI

GET /v3/{project_id}/jobs

**Table 1** URI parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Definition Project ID of a tenant in a region. To obtain this value, see Obtaining a Project ID. Constraints N/A Range The value contains 32 characters. Only letters and digits are allowed. Default Value N/A

**Table 2** Query parameters
Parameter	Mandatory	Type	Description
id	No	String	Definition Task ID. Constraints N/A Range N/A Default Value N/A
start_time	No	String	Definition Query start time. Constraints The value is in the yyyy-mm-ddThh:mm:ssZ format. T is the separator between the calendar and the hourly notation of time. Z indicates the time zone offset. Range N/A Default Value The default value is 30 days before the current time.
end_time	No	String	Definition Query end time. Constraints The value is in the yyyy-mm-ddThh:mm:ssZ format. The end time must be later than the start time, and the time span cannot be longer than 30 days. T is the separator between the calendar and the hourly notation of time. Z indicates the time zone offset. Range N/A Default Value The default value is the current time.
status	No	String	Definition Task status. Constraints N/A Range Running: The task is in progress. Completed: The task is successfully executed. Failed: The task fails to be executed. Default Value N/A
name	No	String	Definition Task name. Constraints N/A Range CreateInstance: Create an instance. RestoreNewInstance: Restore data to a new instance. EnlargeInstance: Scale out an instance. ReduceInstance: Scale in an instance. RestartInstance: Restart an instance. RestartNode: Restart a node. EnlargeInstanceVolume: Scale up storage space of an instance. ReduceInstanceVolume: Scale down storage space of an instance. ResizeInstance: Change the specifications of an instance. UpgradeDbVersion: Upgrade the database version. BindPublicIP: Bind an EIP to an instance. UnbindPublicIP: Unbind an EIP from an instance. DeleteInstance: Delete an instance. EnlargeInstanceColdVolume: Scale up cold storage of an instance. AddInstanceColdVolume: Enable cold storage for an instance. ModifySecurityGroup: Modify a security group. ModifyCcmCert: Modify a CCM certificate. ModifyPort: Change a port. ConstructDisasterRecovery: Establish a DR relationship. DeConstructDisasterRecovery: Remove a DR relationship. SwitchOverDisasterRecovery: Switch a DR relationship. BuildBiActiveInstance: Create an active-active relationship between two instances. ReleaseBiActiveInstance: Remove an active-active relationship from two instances. BackupInstance: Back up an instance. Default Value N/A
offset	No	Integer	Definition Index offset. Constraints The value must be a non-negative integer. Range N/A Default Value 0: The query starts from the first data record.
limit	No	Integer	Definition Number of records returned by a query. Constraints The value must be a non-negative integer. Range 10 20 50 Default Value 50

Request Parameters

**Table 3** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	Definition User token You can obtain the token by calling the IAM API by following Obtaining a User Token Through Password Authentication. Constraints N/A Range N/A Default Value N/A

Response Parameters

Status code: 200

**Table 4** Response body parameters
Parameter	Type	Description
jobs	Array of objects (Table 5)	Definition Task list.
total_count	Integer	Definition Total number of tasks in the task list. Range N/A

**Table 5** JobDetail
Parameter	Type	Description
id	String	Definition Task ID. Range N/A
name	String	Definition Task name. Range N/A
status	String	Definition Task execution status. Range Running: The task is in progress. Completed: The task is successfully executed. Failed: The task fails to be executed.
start_time	String	Definition Creation time in the yyyy-mm-ddThh:mm:ssZ format. T is the separator between the calendar and the hourly notation of time. Z indicates the time zone offset. Range N/A
end_time	String	Definition End time in the yyyy-mm-ddThh:mm:ssZ format. Range N/A
progress	String	Definition Task execution progress. The execution progress (such as "60%", indicating the task execution progress is 60%) is displayed only when the task is being executed. Otherwise, "" is returned. Range N/A
instance	Objects in Table 6	Definition Details of the instance associated with the task.
fail_reason	String	Definition Task failure information. Range N/A

**Table 6** JobInstanceInfo
Parameter	Type	Description
id	String	Definition Instance ID. Range N/A
name	String	Definition Instance name. Range N/A

Example Requests

URI example

GET https://{endpoint}/v3/0549b4a43100d4f32f51c01c2fe4acdb/jobs?id=89a0cde6-9c46-4b89-a92c-573e1083ff23

Example Responses

Status code: 200

Success

{ 
  "total_count" : 1, 
  "jobs" : [ { 
    "id" : "6f85e061-04dd-42e7-86d6-d3b1e40aac2e", 
    "name" : "CreateCassandra", 
    "status" : "Running", 
    "start_time" : "2023-09-12T06:44:01+0000", 
    "end_time" : "2023-09-12T06:44:03+0000", 
    "progress" : "14%", 
    "instance" : { 
      "id" : "27a045b6bf9e46f691f81366d398cb04in06", 
      "name" : "nosql-12f5" 
    }, 
    "fail_reason" : "" 
  } ] 
}

Status Codes

For details, see Status Codes.

Error Codes

For details, see Error Codes.

Parent topic: Task Management

Previous topic: Task Management

Next topic: Querying the Maintenance Period of an Instance