Updated on 2026-09-02 GMT+08:00

Obtaining Session List

Function

This API is used to obtain the session list.

Before using this API, you need to use the API for delivering a task for querying the session list to generate the customer session list. Otherwise, error 500 will be reported.

Calling Method

For details, see Calling APIs.

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

    dcs:clients:list

    List

    instance *

    • g:EnterpriseProjectId

    • g:ResourceTag/<tag-key>

    -

    -

URI

GET /v2/{project_id}/instances/{instance_id}/clients

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Definition

Project ID. For details, see Obtaining a Project ID.

Constraints

N/A

Range

N/A

Default Value

N/A

instance_id

Yes

String

Definition

Instance ID.

Constraints

The specified ID must be a DCS instance ID that exists in the current tenant.

Range

N/A

Default Value

N/A

Table 2 Query Parameters

Parameter

Mandatory

Type

Description

node_id

No

String

Definition

Node ID. For a read/write splitting or Proxy Cluster instance, use the node_id value of a proxy. For a single-node, master/standby, or Redis Cluster instance, use the node_id value of a data node. If this parameter is left empty, the information about all nodes of the instance is queried.

Constraints

N/A

Range

N/A

Default Value

N/A

offset

No

Integer

Definition

Offset from which the query starts.

Constraints

The value must be greater than or equal to 0.

Range

An integer greater than or equal to 0.

Default Value

0

limit

No

Integer

Definition

Number of records per page.

Constraints

The value must be greater than 0.

Range

An integer ranging from 1 to 1000.

Default Value

10

addr

No

String

Definition

Client address.

Constraints

N/A

Range

N/A

Default Value

N/A

sort

No

String

Definition

Sorting field, which specifies a value in the ClientInfo for sorting sessions.

Constraints

N/A

Range

N/A

Default Value

N/A

order

No

String

Definition

Sorting order.

Constraints

N/A

Range

  • asc: ascending order

  • desc: descending order

Default Value

N/A

Request Parameters

None

Response Parameters

Status code: 200

Table 3 Response body parameters

Parameter

Type

Description

time

String

Definition

Data update time.

Range

N/A

clients

Array of ClientInfo objects

Definition

Client connection list. The columns in the list correspond to the columns in the output of the CLIENT LIST command on Redis.

Range

N/A

count

Integer

Definition

Total number of client connections.

Range

An integer greater than or equal to 0.

Table 4 ClientInfo

Parameter

Type

Description

id

String

Definition

Client connection ID.

Range

N/A

addr

String

Definition

IP address and port number of the client.

Range

N/A

fd

String

Definition

File descriptor.

Range

N/A

name

String

Definition

Client name.

Range

N/A

age

Integer

Definition

Connection keepalive period, in seconds.

Range

An integer greater than or equal to 0.

idle

Integer

Definition

Idle duration, in seconds.

Range

An integer greater than or equal to 0.

flags

String

Definition

Client flag. By default, this parameter is not set, and its value is N.

Range

N/A

db

String

Definition

ID of the database in use.

Range

N/A

sub

Integer

Definition

Number of subscribed channels.

Range

An integer greater than or equal to 0.

psub

Integer

Definition

Number of pattern subscriptions.

Range

An integer greater than or equal to 0.

multi

Integer

Definition

Number of commands executed in a transaction.

Range

An integer greater than or equal to 0.

qbuf

Integer

Definition

Length of the query buffer, in bytes. Value 0 indicates that no query buffer is allocated.

Range

An integer greater than or equal to 0.

qbuf_free

Integer

Definition

Length of the free space in the query buffer, in bytes. Value 0 indicates that there is no remaining space.

Range

An integer greater than or equal to 0.

obl

Long

Definition

Length of the output buffer, in bytes. Value 0 indicates that no output buffer is allocated.

Range

A long integer greater than or equal to 0.

oll

Long

Definition

Number of objects contained in the output list. When the length of the remaining output buffer is 0, responses to user commands are enqueued as a string object.

Range

A long integer greater than or equal to 0.

omem

Long

Definition

Total memory occupied by the output buffer and the output list, in bytes.

Range

A long integer greater than or equal to 0.

events

String

Definition

File descriptor event type.

Range

  • r: read

  • w: write

cmd

String

Definition

Last executed command.

Range

N/A

network

String

Definition

Type of the network used by the client.

Range

N/A

peer

String

Definition

IP address and port number of the client.

Range

N/A

user

String

Definition

Authentication username.

Range

N/A

Status code: 400

Table 5 Response body parameters

Parameter

Type

Description

error_msg

String

Error message.

error_code

String

Error code.

error_ext_msg

String

Error message details.

Status code: 401

Table 6 Response body parameters

Parameter

Type

Description

error_msg

String

Error message.

error_code

String

Error code.

error_ext_msg

String

Error message details.

Status code: 403

Table 7 Response body parameters

Parameter

Type

Description

error_msg

String

Error message.

error_code

String

Error code.

error_ext_msg

String

Error message details.

Status code: 404

Table 8 Response body parameters

Parameter

Type

Description

error_msg

String

Error message.

error_code

String

Error code.

error_ext_msg

String

Error message details.

Status code: 500

Table 9 Response body parameters

Parameter

Type

Description

error_msg

String

Error message.

error_code

String

Error code.

error_ext_msg

String

Error message details.

Example Requests

GET https://{dcs_endpoint}/v2/{project_id}/instances/{instance_id}/clients?node_id=8f7ee181-88e2-49b7-a4bf-81f18f93a135

Example Responses

Status code: 200

Successful.

{
  "time" : "2023-06-15T03:10:01.332Z",
  "clients" : [ {
    "id" : "11677",
    "addr" : "198.19.131.14:1637",
    "name" : "dcs",
    "cmd" : "info",
    "age" : 376,
    "idle" : 376,
    "flags" : "N",
    "fd" : "16",
    "db" : "0",
    "sub" : 0,
    "psub" : 0,
    "multi" : 1,
    "qbuf" : 0,
    "qbuf_free" : 4,
    "obl" : 0,
    "oll" : 0,
    "omem" : 0,
    "events" : "r",
    "network" : "vpc",
    "peer" : "198.198.0.121:4058",
    "user" : "dcs"
  } ],
  "count" : 1
}

Status code: 400

Invalid request.

{
  "error_code" : "DCS.4957",
  "error_msg" : "This operation is not allowed when the task is in the current state."
}

SDK Sample Code

The SDK sample code is as follows.

Java

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
package com.huaweicloud.sdk.test;

import com.huaweicloud.sdk.core.auth.ICredential;
import com.huaweicloud.sdk.core.auth.BasicCredentials;
import com.huaweicloud.sdk.core.exception.ConnectionException;
import com.huaweicloud.sdk.core.exception.RequestTimeoutException;
import com.huaweicloud.sdk.core.exception.ServiceResponseException;
import com.huaweicloud.sdk.dcs.v2.region.DcsRegion;
import com.huaweicloud.sdk.dcs.v2.*;
import com.huaweicloud.sdk.dcs.v2.model.*;


public class ListClientsSolution {

    public static void main(String[] args) {
        // The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
        // In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
        String ak = System.getenv("CLOUD_SDK_AK");
        String sk = System.getenv("CLOUD_SDK_SK");
        String projectId = "{project_id}";

        ICredential auth = new BasicCredentials()
                .withProjectId(projectId)
                .withAk(ak)
                .withSk(sk);

        DcsClient client = DcsClient.newBuilder()
                .withCredential(auth)
                .withRegion(DcsRegion.valueOf("<YOUR REGION>"))
                .build();
        ListClientsRequest request = new ListClientsRequest();
        request.withInstanceId("{instance_id}");
        try {
            ListClientsResponse response = client.listClients(request);
            System.out.println(response.toString());
        } catch (ConnectionException e) {
            e.printStackTrace();
        } catch (RequestTimeoutException e) {
            e.printStackTrace();
        } catch (ServiceResponseException e) {
            e.printStackTrace();
            System.out.println(e.getHttpStatusCode());
            System.out.println(e.getRequestId());
            System.out.println(e.getErrorCode());
            System.out.println(e.getErrorMsg());
        }
    }
}

Python

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
# coding: utf-8

import os
from huaweicloudsdkcore.auth.credentials import BasicCredentials
from huaweicloudsdkdcs.v2.region.dcs_region import DcsRegion
from huaweicloudsdkcore.exceptions import exceptions
from huaweicloudsdkdcs.v2 import *

if __name__ == "__main__":
    # The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
    # In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
    ak = os.environ["CLOUD_SDK_AK"]
    sk = os.environ["CLOUD_SDK_SK"]
    projectId = "{project_id}"

    credentials = BasicCredentials(ak, sk, projectId)

    client = DcsClient.new_builder() \
        .with_credentials(credentials) \
        .with_region(DcsRegion.value_of("<YOUR REGION>")) \
        .build()

    try:
        request = ListClientsRequest()
        request.instance_id = "{instance_id}"
        response = client.list_clients(request)
        print(response)
    except exceptions.ClientRequestException as e:
        print(e.status_code)
        print(e.request_id)
        print(e.error_code)
        print(e.error_msg)

Go

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
package main

import (
	"fmt"
	"github.com/huaweicloud/huaweicloud-sdk-go-v3/core/auth/basic"
    dcs "github.com/huaweicloud/huaweicloud-sdk-go-v3/services/dcs/v2"
	"github.com/huaweicloud/huaweicloud-sdk-go-v3/services/dcs/v2/model"
    region "github.com/huaweicloud/huaweicloud-sdk-go-v3/services/dcs/v2/region"
)

func main() {
    // The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
    // In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
    ak := os.Getenv("CLOUD_SDK_AK")
    sk := os.Getenv("CLOUD_SDK_SK")
    projectId := "{project_id}"

    auth, err := basic.NewCredentialsBuilder().
        WithAk(ak).
        WithSk(sk).
        WithProjectId(projectId).
        SafeBuild()

    if err != nil {
        fmt.Println(err)
        return
    }

    hcClient, err := dcs.DcsClientBuilder().
         WithRegion(region.ValueOf("<YOUR REGION>")).
         WithCredential(auth).
         SafeBuild()


    if err != nil {
        fmt.Println(err)
        return
    }

    client := dcs.NewDcsClient(hcClient)

    request := &model.ListClientsRequest{}
	request.InstanceId = "{instance_id}"
	response, err := client.ListClients(request)
	if err == nil {
        fmt.Printf("%+v\n", response)
    } else {
        fmt.Println(err)
    }
}

More

For SDK sample code of more programming languages, see the Sample Code tab in API Explorer. SDK sample code can be automatically generated.

Status Codes

Status Code

Description

200

Successful.

400

Invalid request.

401

Invalid authentication information.

403

Access denied.

404

The requested resource could not be found.

500

Internal service error.

Error Codes

See Error Codes.