Querying Desktop Usage Statistics

Function

Queries desktop usage statistics.

The cloud service performs aggregation calculation at 02:00 every day to calculate the usage duration from 00:00:00 to 23:59:59 of the previous day, and aggregates data within the period range to the period boundary.

Cross-day records are calculated based on the statistical period.

Assume that you have logged in to the desktop multiple times in a day, for example, 09:00–12:00, 13:00–21:00, and 22:00–01:00 (next day).

The accumulated usage duration of the current day is aggregated to 23:59:59. The total usage duration is 3 hours (09:00–12:00) + 8 hours (13:00–21:00) + 2 hours (22:00–00:00).

Only aggregation calculation data in the last 180 days can be queried.

Debugging

You can debug this API through automatic authentication in API Explorer or use the SDK sample code generated by API Explorer.

Authorization Information

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

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

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
workspace:statistics:listDesktopMetrics	List	-	-	-	-

URI

GET /v2/{project_id}/statistics/metrics/desktops

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Project ID.

**Table 2** Query Parameters
Parameter	Mandatory	Type	Description
start_time	Yes	String	Query start time (GMT) The cloud service performs aggregation calculation at 02:00 every day to calculate the usage duration from 00:00:00 to 23:59:59 of the previous day, and aggregates data within the period range to the period boundary. Cross-day records are calculated based on the statistical period. Assume that you have logged in to the desktop multiple times in a day, for example, 09:00–12:00, 13:00–21:00, and 22:00–01:00 (next day). The accumulated usage duration of the current day is aggregated to 23:59:59. The total usage duration is 3 hours (09:00–12:00) + 8 hours (13:00–21:00) + 2 hours (22:00–00:00). If the value of from-to is less than one period, the queried data may be empty.
end_time	Yes	String	Query end time (GMT).
resource_name	No	String	Resource name (fuzzy match).
min_idle_days	No	Integer	Minimum number of days when the desktop is idle.
max_idle_days	No	Integer	Maximum number of days when the desktop is idle. If both min_idle_days and max_idle_days are not empty, the value of max_idle_days must be greater than or equal to that of min_idle_days. Otherwise, no data can be queried.
usage_min_hours	No	Integer	Minimum usage duration (in hour).
usage_max_hours	No	Integer	Maximum usage duration (in hour). The value must be greater than or equal to usage_min_hours.
enterprise_project_id	No	String	Enterprise project ID.
sort_field	No	String	Sorts desktops by metric. desktop_usage - Sorts desktops by desktop usage duration. desktop_idle_duration - Sorts desktops by idle period.
sort_type	No	String	Direction of sorting by metric. This parameter must be used together with sort_field. DESC - Returns data in descending order. ASC - Returns data in ascending order.
offset	No	Integer	Query offset. The default value is 0.
limit	No	Integer	The value of limit ranges from 1 to 100 and defaults to 10.

Request Parameters

None

Response Parameters

Status code: 200

**Table 3** Response body parameters
Parameter	Type	Description
count	Integer	Total number.
items	Array of DesktopMetric objects	Desktop metric.

**Table 4** DesktopMetric
Parameter	Type	Description
resource_id	String	Desktop ID.
resource_pool_id	String	Desktop pool ID. This parameter is available only for desktops in a desktop pool.
resource_name	String	Desktop name.
enterprise_project_id	String	Enterprise project ID.
metric	Array of Metric objects	Statistics desktop_usage - Desktop usage duration (unit: second) desktop_idle_duration - Desktop idle duration (unit: second)

**Table 5** Metric
Parameter	Type	Description
metric_name	String	Metric name.
metric_value	Double	Metric value.

Status code: 400

**Table 6** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error message.

Status code: 401

**Table 7** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error message.

Status code: 500

**Table 8** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error message.

Example Requests

None

Example Responses

Status code: 200

Succeeded.

{
  "count" : 0,
  "items" : [ {
    "resource_id" : "xxx-xxx-xxx",
    "resource_pool_id" : "xxx-xxx-xxx",
    "resource_name" : "xxxx",
    "metric" : [ {
      "metric_name" : "desktop_state",
      "metric_value" : 10
    } ]
  } ]
}