Help Center/ Distributed Cache Service/ API Reference/ API V2/ Managing an Instance/ Querying the Topology of a Cluster Instance
Updated on 2025-08-05 GMT+08:00
Online Debugging
CLI Examples
View PDF
Share

Querying the Topology of a Cluster Instance

Function

This API is used to query the topology of a cluster instance.

Calling Method

For details, see Calling APIs.

URI

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

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. It can be viewed on the instance details page on the DCS console.

Constraints:

N/A

Range:

N/A

Default Value:

N/A
Table 2 Query Parameters

Parameter

Mandatory

Type

Description

start

No

Integer

Definition:

Offset, which indicates that the generated list is displayed from this offset. For example, if the offset is 3, the generated list is displayed from the fourth record.

Constraints:

N/A

Range:

≥ 0

Default Value:

0

limit

No

Integer

Definition:

Number of records displayed on each page.

Constraints:

N/A

Range:

1–1000

Default Value:

10

Request Parameters

None

Response Parameters

Status code: 200

Table 3 Response body parameters

Parameter

Type

Description

redis_server

Array of TopologyInfo objects

Definition:

Cluster role: Redis-server instance topology.

cluster_lvs

Array of TopologyInfo objects

Definition:

Cluster role: LVS instance topology (currently discontinued), which applies only to Redis 3.0 instances.

cluster_admin

Array of TopologyInfo objects

Definition:

Cluster role: admin instance topology (currently discontinued), which applies only to Redis 3.0 instances.

cluster_proxy

Array of TopologyInfo objects

Definition:

Cluster role: proxy instance topology.

master

Array of TopologyInfo objects

Definition:

Redis role: master instance topology, which applies only to Redis 3.0 instances.

vpcendpoint

Array of TopologyInfo objects

Definition:

Cluster role: VPC Endpoint service instance topology, which applies to Redis 4.0 and later instances.

elb

Array of TopologyInfo objects

Definition:

Cluster role: ELB service instance topology, which applies to Redis 4.0 and later instances.
Table 4 TopologyInfo

Parameter

Type

Description

node_id

String

Definition:

Node ID.

Range:

N/A

node_name

String

Definition:

Node name.

Range:

N/A

ip

String

Definition:

Node IP address.

Range:

N/A

port

String

Definition:

Node port.

Range:

N/A

node_type

String

Definition:

Node master/standby role.

Range:

master: master node

slave: standby node

proxy: proxy node

max_memory

String

Definition:

Total memory size in MB.

Range:

N/A

used_memory

String

Definition:

Used memory size in MB.

Range:

N/A

qps

String

Definition:

Query rate per second.

Range:

N/A

bandwidth

BandWidth object

Definition:

Bandwidth information.

db_num

String

Definition:

Number of databases in the instance.

Range:

N/A

dbs

KeySpace object

Definition:

Key information.

relation_ip

String

Definition:

Associated IP address.

Range:

N/A

relation_port

String

Definition:

Associated port.

Range:

N/A

group_id

String

Definition:

Shard ID.

Range:

N/A

status

String

Definition:

Node status.

Range:

N/A

dims

DimsInfo object

Definition:

Cloud Eye monitoring maintenance information.
Table 5 BandWidth

Parameter

Type

Description

input

String

Definition:

Uplink bandwidth, in Kbit/s.

Range:

N/A

output

String

Definition:

Downlink bandwidth, in Kbit/s.

Range:

N/A
Table 6 KeySpace

Parameter

Type

Description

db_idx

String

Definition:

Database index.

Range:

N/A

keys

String

Definition:

Number of node keys.

Range:

N/A

expires

String

Definition:

Number of expired node keys.

Range:

N/A

avg_ttl

String

Definition:

Average expiration time of node keys.

Range:

N/A
Table 7 DimsInfo

Parameter

Type

Description

dim_k

String

Definition:

Cloud Eye monitoring dimension route.

Range:

N/A

dim_v

String

Definition:

Cloud Eye monitoring dimension ID.

Range:

N/A

Status code: 400

Table 8 Response body parameters

Parameter

Type

Description

error_msg

String

Parameter description:

Error message.

Value range:

N/A.

error_code

String

Parameter description:

Error code.

Value range:

For details, see Error Codes.

error_ext_msg

String

Parameter description:

Extended error information. This parameter is not used currently and is set to null.

Value range:

N/A.

Status code: 401

Table 9 Response body parameters

Parameter

Type

Description

error_msg

String

Parameter description:

Error message.

Value range:

N/A.

error_code

String

Parameter description:

Error code.

Value range:

For details, see Error Codes.

error_ext_msg

String

Parameter description:

Extended error information. This parameter is not used currently and is set to null.

Value range:

N/A.

Status code: 403

Table 10 Response body parameters

Parameter

Type

Description

error_msg

String

Parameter description:

Error message.

Value range:

N/A.

error_code

String

Parameter description:

Error code.

Value range:

For details, see Error Codes.

error_ext_msg

String

Parameter description:

Extended error information. This parameter is not used currently and is set to null.

Value range:

N/A.

Status code: 404

Table 11 Response body parameters

Parameter

Type

Description

error_msg

String

Parameter description:

Error message.

Value range:

N/A.

error_code

String

Parameter description:

Error code.

Value range:

For details, see Error Codes.

error_ext_msg

String

Parameter description:

Extended error information. This parameter is not used currently and is set to null.

Value range:

N/A.

Status code: 500

Table 12 Response body parameters

Parameter

Type

Description

error_msg

String

Parameter description:

Error message.

Value range:

N/A.

error_code

String

Parameter description:

Error code.

Value range:

For details, see Error Codes.

error_ext_msg

String

Parameter description:

Extended error information. This parameter is not used currently and is set to null.

Value range:

N/A.

Example Requests

GET https://{dcs_endpoint}/v2/{project_id}/instances/{instance_id}/nodes

Example Responses

Status code: 200

Instance topology queried.

{
  "cluster_proxy" : [ {
    "node_id" : "ff80808188b4aeb60188b4b234ea0144",
    "node_name" : "dcs-bare-vm-x86-cn-north-7c-1657002433-0",
    "ip" : "192.168.60.32",
    "port" : "2892",
    "node_type" : "proxy",
    "max_memory" : null,
    "used_memory" : null,
    "qps" : null,
    "bandwidth" : null,
    "db_num" : null,
    "dbs" : null,
    "relation_ip" : null,
    "relation_port" : null,
    "group_id" : null,
    "status" : "Active",
    "dims" : {
      "dim_k" : "dcs_instance_id",
      "dim_v" : "3b76eb20-70cd-4083-be96-266a29de6e52"
    }
  }, {
    "node_id" : "ff80808188b4aeb60188b4b234ea0143",
    "node_name" : "dcs-bare-vm-x86-cn-north-7c-1684760402-1",
    "ip" : "192.168.5.105",
    "port" : "3048",
    "node_type" : "proxy",
    "max_memory" : null,
    "used_memory" : null,
    "qps" : null,
    "bandwidth" : null,
    "db_num" : null,
    "dbs" : null,
    "relation_ip" : null,
    "relation_port" : null,
    "group_id" : null,
    "status" : "Active",
    "dims" : {
      "dim_k" : "dcs_instance_id",
      "dim_v" : "3b76eb20-70cd-4083-be96-266a29de6e52"
    }
  }, {
    "node_id" : "ff80808188b4aeb60188b4b234ea0145",
    "node_name" : "dcs-bare-vm-x86-cn-north-7c-1660116188-2",
    "ip" : "192.168.53.35",
    "port" : "3834",
    "node_type" : "proxy",
    "max_memory" : null,
    "used_memory" : null,
    "qps" : null,
    "bandwidth" : null,
    "db_num" : null,
    "dbs" : null,
    "relation_ip" : null,
    "relation_port" : null,
    "group_id" : null,
    "status" : "Active",
    "dims" : {
      "dim_k" : "dcs_instance_id",
      "dim_v" : "3b76eb20-70cd-4083-be96-266a29de6e52"
    }
  } ],
  "vpcendpoint" : [ {
    "node_id" : "e50c0fda-1870-4bbc-ba4c-ace69504e305",
    "node_name" : "",
    "ip" : "192.168.74.33",
    "port" : "6379",
    "node_type" : "vpcendpoint",
    "max_memory" : null,
    "used_memory" : null,
    "qps" : null,
    "bandwidth" : null,
    "db_num" : null,
    "dbs" : null,
    "relation_ip" : null,
    "relation_port" : null,
    "group_id" : null,
    "status" : "Active",
    "dims" : null
  } ],
  "elb" : [ {
    "node_id" : "af04b606-241e-4099-8ae2-194e2b61ef63",
    "node_name" : "",
    "ip" : "192.168.20.137",
    "port" : "6379",
    "node_type" : "elb",
    "max_memory" : null,
    "used_memory" : null,
    "qps" : null,
    "bandwidth" : null,
    "db_num" : null,
    "dbs" : null,
    "relation_ip" : null,
    "relation_port" : null,
    "group_id" : null,
    "status" : "Active",
    "dims" : null
  } ],
  "redis_server" : [ {
    "node_id" : "ff80808188b4aeb60188b4b234e4013d",
    "node_name" : "dcs-bare-vm-x86-cn-north-7c-1684823334-0",
    "ip" : "192.168.22.138",
    "port" : "2076",
    "node_type" : "master",
    "max_memory" : "1365",
    "used_memory" : "3",
    "qps" : "4",
    "bandwidth" : {
      "input" : "0.10",
      "output" : "0.30"
    },
    "db_num" : "0",
    "dbs" : {
      "db_idx" : "0",
      "keys" : "0",
      "expires" : "0",
      "avg_ttl" : "0"
    },
    "relation_ip" : "192.168.60.32",
    "relation_port" : "2984",
    "group_id" : null,
    "status" : "Active",
    "dims" : {
      "dim_k" : "dcs_instance_id",
      "dim_v" : "3b76eb20-70cd-4083-be96-266a29de6e52"
    }
  }, {
    "node_id" : "ff80808188b4aeb60188b4b234ea0141",
    "node_name" : "dcs-bare-vm-x86-cn-north-7c-1657800431-0",
    "ip" : "192.168.33.181",
    "port" : "3694",
    "node_type" : "master",
    "max_memory" : "1365",
    "used_memory" : "3",
    "qps" : "8",
    "bandwidth" : {
      "input" : "0.20",
      "output" : "3.31"
    },
    "db_num" : "0",
    "dbs" : {
      "db_idx" : "0",
      "keys" : "0",
      "expires" : "0",
      "avg_ttl" : "0"
    },
    "relation_ip" : "192.168.46.161",
    "relation_port" : "3600",
    "group_id" : null,
    "status" : "Active",
    "dims" : {
      "dim_k" : "dcs_instance_id",
      "dim_v" : "3b76eb20-70cd-4083-be96-266a29de6e52"
    }
  }, {
    "node_id" : "ff80808188b4aeb60188b4b234ea013f",
    "node_name" : "dcs-bare-vm-x86-cn-north-7c-1657002433-0",
    "ip" : "192.168.60.32",
    "port" : "2476",
    "node_type" : "master",
    "max_memory" : "1365",
    "used_memory" : "3",
    "qps" : "3",
    "bandwidth" : {
      "input" : "0.12",
      "output" : "2.30"
    },
    "db_num" : "0",
    "dbs" : {
      "db_idx" : "0",
      "keys" : "0",
      "expires" : "0",
      "avg_ttl" : "0"
    },
    "relation_ip" : "192.168.53.35",
    "relation_port" : "3704",
    "group_id" : null,
    "status" : "Active",
    "dims" : {
      "dim_k" : "dcs_instance_id",
      "dim_v" : "3b76eb20-70cd-4083-be96-266a29de6e52"
    }
  } ]
}

Status code: 400

Invalid request.

{
  "error_code" : "111400063",
  "error_msg" : "Invalid {0} parameter in the request."
}

SDK Sample Code

The SDK sample code is as follows.

 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 ShowInstanceTopologySolution {

    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();
        ShowInstanceTopologyRequest request = new ShowInstanceTopologyRequest();
        request.withInstanceId("{instance_id}");
        try {
            ShowInstanceTopologyResponse response = client.showInstanceTopology(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());
        }
    }
}

 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 = ShowInstanceTopologyRequest()
        request.instance_id = "{instance_id}"
        response = client.show_instance_topology(request)
        print(response)
    except exceptions.ClientRequestException as e:
        print(e.status_code)
        print(e.request_id)
        print(e.error_code)
        print(e.error_msg)

 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
 
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 := basic.NewCredentialsBuilder().
        WithAk(ak).
        WithSk(sk).
        WithProjectId(projectId).
        Build()

    client := dcs.NewDcsClient(
        dcs.DcsClientBuilder().
            WithRegion(region.ValueOf("<YOUR REGION>")).
            WithCredential(auth).
            Build())

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

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

Instance topology queried.

400

Invalid request.

401

Invalid authentication information.

403

Rejected request.

404

The requested resource could not be found.

500

Internal service error.

Error Codes

See Error Codes.

Parent Topic: Managing an Instance