Querying the Instance List

Function

This API is used to query the instances of an account by the specified conditions.

URI

GET /v2/{project_id}/instances

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Definition Project ID. For details about how to obtain it, see Obtaining a Project ID. Constraints N/A Range N/A Default Value N/A

**Table 2** Query Parameters
Parameter	Mandatory	Type	Description
engine	No	String	Definition Message engine type. Constraints N/A Range rocketmq: RocketMQ engine. reliability: RocketMQ engine alias. Default Value N/A
name	No	String	Definition Instance name. Constraints N/A Range N/A Default value N/A
instance_id	No	String	Definition Instance ID. You can call the API for querying all instances to obtain the instance ID. The instance ID is in the response body. Constraints N/A Range N/A Default Value N/A
status	No	String	Definition Instance status. Constraints N/A Range For details, see Instance Status. Default Value N/A
include_failure	No	String	Definition Whether to return the number of instances that fail to be created. Constraints N/A Range 'true': yes 'false': no Default value N/A
exact_match_name	No	String	Definition Whether to search for the instance that precisely matches a specified instance name. Constraints N/A Range 'true': yes 'false': no Default value 'false'
enterprise_project_id	No	String	Definition Enterprise project ID. Constraints N/A Range N/A Default value N/A
limit	No	Integer	Definition Number of returned instances of a query. Constraints N/A Range 1–50 Default Value 10
offset	No	Integer	Definition Offset where the query starts. Constraints N/A Range ≥ 0 Default value N/A

Request Parameters

None

Response Parameters

Status code: 200

**Table 3** Response body parameters
Parameter	Type	Description
instances	Array of InstanceDetail objects	Definition Instance list. Constraints N/A Range N/A Default Value N/A
instance_num	Integer	Definition Number of instances. Constraints N/A Range N/A Default Value N/A

**Table 4** InstanceDetail
Parameter	Type	Description
name	String	Definition Instance name. Constraints N/A Range N/A Default Value N/A
engine	String	Definition Message engine. Constraints N/A Range rocketmq: RocketMQ message engine. reliability: RocketMQ message engine alias. Default Value N/A
status	String	Definition Status. Constraints N/A Range For details, see Instance Status. Default Value N/A
description	String	Definition Message description. Constraints N/A Range N/A Default Value N/A
type	String	Definition Instance type. Constraints N/A Range single: 4.8.0 single-node cluster: 4.8.0 cluster single.basic: 5.x single-node basic edition cluster.basic: 5.x cluster basic edition single.professional: 5.x single-node professional edition cluster.professional: 5.x cluster professional edition Default Value N/A
specification	String	Definition Specification description. Constraints N/A Range For version 4.8.0, the value consists of the resource flavor and number of brokers, for example, *rocketmq.4u8g.cluster.small 1 broker. For the 5.x basic edition, the value consists of the resource flavor and instance TPS, for example, rocketmq.b2.large.4, 2000 tps. For the 5.x single-node professional edition, the value consists of the resource flavor and instance TPS, for example, rocketmq.p1.large.1, 500 tps. For the 5.x cluster professional edition, the value consists of the resource flavor, instance TPS, and elastic TPS, for example, rocketmq.p2.large.8, 4000 tps, 2000 elastic_tps. For details about resource flavors and other parameters, see the instance specification table of the corresponding version in Specifications Default Value** N/A
engine_version	String	Definition Instance version. Constraints N/A Range 4.8.0 5.x Default Value N/A
instance_id	String	Definition Instance ID. Constraints N/A Range N/A Default Value N/A
arch_type	String	Definition Architecture type. Range X86
charging_mode	Integer	Definition Billing mode. Constraints N/A Range 1 indicates pay-per-use.1: pay-per-use; 0: yearly/monthly. Default Value N/A
vpc_id	String	Definition VPC ID. Constraints N/A Range N/A Default Value N/A
vpc_name	String	Definition VPC name. Constraints N/A Range N/A Default Value N/A
created_at	String	Definition Time when creation is complete. The time is in the format of timestamp, that is, the offset milliseconds from 1970-01-01 00:00:00 UTC to the specified time. Constraints N/A Range N/A Default Value N/A
product_id	String	Definition RocketMQ instance flavors. Constraints N/A Range c6.4u8g.cluster.small: Max. 2,000 topics and 2,000 consumer groups per broker c6.4u8g.cluster: Max. 4,000 topics and 4,000 consumer groups per broker c6.8u16g.cluster: Max. 8,000 topics and 8,000 consumer groups per broker c6.12u24g.cluster: Max. 12,000 topics and 12,000 consumer groups per broker c6.16u32g.cluster: Max. 16,000 topics and 16,000 consumer groups per broker rocketmq.b1.large.1: RocketMQ 5.x basic edition single-node flavor, instance TPS 500 rocketmq.b2.large.4: RocketMQ 5.x basic edition cluster flavor, instance TPS 2,000 rocketmq.b2.large.8: RocketMQ 5.x basic edition cluster flavor, instance TPS 4,000 rocketmq.b2.large.12: RocketMQ 5.x basic edition cluster flavor, instance TPS 6,000 rocketmq.p1.large.1: RocketMQ 5.x professional edition single-node flavor, instance TPS 500 rocketmq.p2.large.8: RocketMQ 5.x professional edition cluster flavor, instance TPS 4,000 rocketmq.p2.large.12: RocketMQ 5.x professional edition cluster flavor, instance TPS 6,000 rocketmq.p2.large.20: RocketMQ 5.x professional edition cluster flavor, instance TPS 10,000 rocketmq.p2.large.40: RocketMQ 5.x professional edition cluster flavor, instance TPS 20,000 rocketmq.p2.large.100: RocketMQ 5.x professional edition cluster flavor, instance TPS 50,000 rocketmq.p2.large.150: RocketMQ 5.x professional edition cluster flavor, instance TPS 75,000 rocketmq.p2.large.200: RocketMQ 5.x professional edition cluster flavor, instance TPS 100,000 rocketmq.p2.large.300: RocketMQ 5.x professional edition cluster flavor, instance TPS 150,000 Default Value N/A
security_group_id	String	Definition Security group ID. Constraints N/A Range N/A Default Value N/A
security_group_name	String	Definition Security group name. Constraints N/A Range N/A Default Value N/A
subnet_id	String	Definition Subnet ID. Constraints N/A Range N/A Default Value N/A
subnet_cidr	String	Definition Subnet route. Constraints N/A Range N/A Default Value N/A
available_zones	Array of strings	Definition List of AZ IDs. Constraints N/A Range N/A Default Value N/A
available_zone_names	Array of strings	Definition List of AZ names. Constraints N/A Range N/A Default Value N/A
user_id	String	Definition User ID. Constraints N/A Range N/A Default Value N/A
user_name	String	Definition Username. Constraints N/A Range N/A Default Value N/A
maintain_begin	String	Definition Time at which the maintenance window starts. The format is HH:mm:ss. Constraints N/A Range N/A Default Value N/A
maintain_end	String	Definition Time at which the maintenance window ends. The format is HH:mm:ss. Constraints N/A Range N/A Default Value N/A
enable_log_collection	Boolean	Definition Whether log collection is enabled. Constraints N/A Range true: Yes false: No Default Value N/A
storage_space	Integer	Definition Storage space, in GB. Constraints N/A Range Different instance specifications support different storage configurations. Default Value N/A
used_storage_space	Integer	Definition Used message storage space, in GB. Constraints N/A Range N/A Default Value N/A
enable_publicip	Boolean	Definition Whether to enable public access. Constraints N/A Range true: Yes false: No Default Value N/A
publicip_id	String	Definition ID of the EIP bound to the instance. Use commas (,) to separate multiple EIP IDs. This parameter is mandatory if public access is enabled (that is, enable_publicip is set to true). Constraints N/A Range N/A Default Value N/A
publicip_address	String	Definition Public IP address. Constraints N/A Range N/A Default Value N/A
ssl_enable	Boolean	Definition Whether SSL is enabled. Range true: yes false: no
cross_vpc_info	String	Definition Cross-VPC access information. Constraints N/A Range N/A Default Value N/A
storage_resource_id	String	Definition Storage resource ID. Constraints N/A Range N/A Default Value N/A
storage_spec_code	String	Definition Storage specification code. Constraints N/A Range dms.physical.storage.high.v2: high I/O disk This value is not supported by RocketMQ 5.x professional edition. dms.physical.storage.ultra.v2: ultra-high I/O disk Default Value N/A
service_type	String	Definition Service type. Constraints N/A Range advanced: Service type. Default Value N/A
storage_type	String	Definition Storage type. Constraints N/A Range hec: Storage type. Default Value N/A
extend_times	Long	Definition Extension time. Constraints N/A Range N/A Default Value N/A
ipv6_enable	Boolean	Definition Whether IPv6 is enabled. Constraints N/A Range true: Yes false: No Default Value N/A
support_features	String	Definition Features supported by the instance. Constraints N/A Range N/A Default Value N/A
disk_encrypted	Boolean	Definition Whether disk encryption is enabled. Range true: yes false: no
disk_encrypted_key	String	Definition Disk encryption key. If disk encryption is not enabled, this parameter is left blank. Range N/A
ces_version	String	Definition Cloud Eye version. Constraints N/A Range N/A Default Value N/A
node_num	Integer	Definition Number of nodes. (This field is available only for RocketMQ 4.8.0 instances.) Constraints N/A Range N/A Default Value N/A
new_spec_billing_enable	Boolean	Definition Whether billing based on new specifications is enabled. Constraints N/A Range true: Yes false: No Default Value N/A
enable_acl	Boolean	Definition Whether to enable access control. Constraints N/A Range true: Yes false: No Default Value N/A
broker_num	Integer	Definition Number of brokers. Constraints N/A Range N/A Default Value N/A
dns_enable	Boolean	Definition Whether to enable domain name access to an instance. Constraints N/A Range true: Yes false: No Default Value N/A
namesrv_address	String	Definition Metadata address. Constraints N/A Range N/A Default Value N/A
namesrv_domain_name	String	Definition Metadata domain name. Constraints N/A Range N/A Default Value N/A
broker_address	String	Definition Service data address. Constraints N/A Range N/A Default Value N/A
public_namesrv_address	String	Definition Public network metadata address. Constraints N/A Range N/A Default Value N/A
public_namesrv_domain_name	String	Definition Public metadata domain name. Constraints N/A Range N/A Default Value N/A
public_broker_address	String	Definition Public network service data address. Constraints N/A Range N/A Default Value N/A
grpc_address	String	Definition gRPC connection address (displayed only for RocketMQ 5.x). Constraints N/A Range N/A Default Value N/A
grpc_domain_name	String	Definition gRPC connection domain name (displayed only for RocketMQ 5.x). Constraints N/A Range N/A Default Value N/A
public_grpc_address	String	Definition Public gRPC connection address (displayed only for RocketMQ 5.x). Constraints N/A Range N/A Default Value N/A
public_grpc_domain_name	String	Definition Public gRPC domain name (displayed only for RocketMQ 5.x). Constraints N/A Range N/A Default Value N/A
enterprise_project_id	String	Definition Enterprise project ID. Constraints N/A Range N/A Default Value N/A
tags	Array of TagEntity objects	Definition Tag list. Constraints N/A Range N/A Default Value N/A
total_storage_space	Integer	Definition Total storage space. Constraints N/A Range N/A Default Value N/A
resource_spec_code	String	Definition Resource specification. Constraints N/A Range N/A Default Value N/A
produce_portion	Integer	Definition Production TPS proportion. Constraints N/A Range N/A Default Value N/A
consume_portion	Integer	Definition Consumption TPS proportion. Constraints N/A Range N/A Default Value N/A
dr_enable	Boolean	Definition Whether the instance has disaster recovery (DR). Constraints N/A Range true: Yes false: No Default Value N/A
quota_address	String	Definition Quota address. Constraints N/A Range N/A Default Value N/A
max_msg_process_tps	Integer	Definition Maximum message TPS. Constraints N/A Range N/A Default Value N/A
config_ssl_need_restart_process	Boolean	Definition Whether a restart is required to configure SSL. Constraints N/A Range true: Yes false: No Default Value N/A
tls_mode	String	Definition Security protocol used by an instance. Constraints N/A Range N/A Default Value N/A
enable_elastic_tps	Boolean	Definition Elastic TPS switch status. Constraints N/A Range true: enabled false: disabled Default Value N/A

**Table 5** TagEntity
Parameter	Type	Description
key	String	Tag key. Must be specified. Must be unique for the same instance. Can contain 1 to 128 characters. Can contain letters, digits, spaces, and special characters _.:=+-@ Cannot start or end with a space.
value	String	Tag value. Can contain 0 to 255 characters. Can contain letters, digits, spaces, and special characters _.:=+-@ Cannot start or end with a space.

Example Requests

Querying the list of all instances

GET https://{endpoint}/v2/{project_id}/instances?engine=reliability

Example Responses

Status code: 200

Instance list queried successfully.

{
  "instances" : [ {
    "name" : "reliability-ztest",
    "engine" : "reliability",
    "status" : "RUNNING",
    "description" : "",
    "type" : "cluster",
    "specification" : "rocketmq.4u8g.cluster * 1 broker",
    "engine_version" : "4.8.0",
    "instance_id" : "68fdc9a8-805e-439d-8dd9-25adc1c58bf6",
    "resource_spec_code" : "",
    "charging_mode" : 1,
    "vpc_id" : "3db8490c-4d6d-4d8f-8d3f-047b0de4c5cf",
    "vpc_name" : "vpc-1101840",
    "created_at" : "1636699753874",
    "product_id" : "c6.4u8g.cluster",
    "security_group_id" : "23c5977f-ff33-4b95-a73e-08d8a0bc4e6c",
    "security_group_name" : "Sys-default",
    "subnet_id" : "0a0f1fcb-f019-458d-b9e5-301867394d50",
    "subnet_cidr" : "192.168.0.0/24",
    "available_zones" : [ "9f1c5806706d4c1fb0eb72f0a9b18c77" ],
    "available_zone_names" : [ "AZ3" ],
    "user_id" : "0b01fbb53600d4671fa8c00673c71260",
    "user_name" : "",
    "maintain_begin" : "02:00:00",
    "maintain_end" : "06:00:00",
    "enable_log_collection" : false,
    "storage_space" : 558,
    "total_storage_space" : 600,
    "used_storage_space" : 28,
    "enable_publicip" : false,
    "ssl_enable" : false,
    "arch_type" : "X86",
    "cross_vpc_info" : "{\"192.168.1.21\":{\"advertised_ip\":\"192.168.1.21\",\"broker_port\":\"-\",\"port_id\":\"fa020857-d899-497c-a5f8-8dd90ed67ff7\",\"namesrv_port\":\"8301\"},\"192.168.1.246\":{\"advertised_ip\":\"192.168.1.246\",\"broker_port\":\"10100\",\"port_id\":\"c0f0586f-a4ee-41b5-a7f1-b4e554bbf12d\",\"namesrv_port\":\"-\"},\"192.168.1.77\":{\"advertised_ip\":\"192.168.1.77\",\"broker_port\":\"10101\",\"port_id\":\"8eb1d144-4315-402f-8498-37c9a10b630c\",\"namesrv_port\":\"-\"},\"192.168.1.159\":{\"advertised_ip\":\"192.168.1.159\",\"broker_port\":\"-\",\"port_id\":\"d35b22af-a202-4329-bda4-26e1bdf2aa8e\",\"namesrv_port\":\"8300\"},\"192.168.1.14\":{\"advertised_ip\":\"192.168.1.14\",\"broker_port\":\"10102\",\"port_id\":\"5fcb50fd-3af5-4123-a455-a67f1b926026\",\"namesrv_port\":\"-\"}}",
    "storage_resource_id" : "164bdaef-2e67-4fd5-be8b-a18f91d455a2",
    "storage_spec_code" : "dms.physical.storage.ultra.v2",
    "service_type" : "advanced",
    "storage_type" : "hec",
    "enterprise_project_id" : "0",
    "extend_times" : 0,
    "ipv6_enable" : false,
    "support_features" : "features.log.collection",
    "disk_encrypted" : true,
    "disk_encrypted_key" : "********-b953-4875-a743-************",
    "enable_acl" : true,
    "ces_version" : "linux,v1,v2",
    "node_num" : 5,
    "new_spec_billing_enable" : true,
    "broker_num" : 1,
    "dr_enable" : false,
    "namesrv_address" : "***",
    "config_ssl_need_restart_process" : false,
    "broker_address" : "***",
    "public_namesrv_address" : "***",
    "public_broker_address" : "***",
    "grpc_address" : "***",
    "public_grpc_address" : "***"
  } ],
  "instance_num" : 1
}

Status Codes

Status Code	Description
200	Instance list queried successfully.

Error Codes

See Error Codes.

Parent Topic: Lifecycle Management

Previous topic: Creating a Pay-per-Use Instance

Next topic: Querying an Instance

Feedback

Was this page helpful?

Helpful Not helpful

Provide feedback

Thank you very much for your feedback. We will continue working to improve the documentation.

The system is busy. Please try again later.