Updated on 2025-05-06 GMT+08:00

Querying an Instance

Function

This API is used to query the details about an instance.

This API is out-of-date and may not be maintained in the future. Please use the API described in Querying an Instance.

Call Method

For details, see How to Call an API.

URI

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

Table 1 URI parameters

Parameter

Mandatory

Type

Description

engine

Yes

String

Indicates the message engine.

project_id

Yes

String

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

instance_id

Yes

String

Indicates the instance ID.

Request

None.

Response

Status code: 200

Table 2 Response body parameters

Parameter

Type

Description

name

String

Indicates the instance name.

engine

String

Indicates the message engine.

engine_version

String

Indicates the engine version.

description

String

Indicates the description of the instance.

specification

String

Indicates the instance specification.

storage_space

Integer

Indicates the message storage space. Unit: GB

partition_num

String

Number of partitions in a Kafka instance.

used_storage_space

Integer

Indicates the used message storage space. Unit: GB

dns_enable

Boolean

Whether to enable domain name access to an instance.

  • true: enable
  • false: disable

connect_address

String

Indicates the IP address of an instance.

port

Integer

Indicates the port number of an instance.

status

String

Indicates the status of an instance. See Instance statuses.

instance_id

String

Indicates the instance ID.

resource_spec_code

String

Indicates the resource specifications identifier.

  • dms.instance.kafka.cluster.c3.mini: Kafka instance, 100 MB/s reference bandwidth
  • dms.instance.kafka.cluster.c3.small.2: Kafka instance, 300 MB/s reference bandwidth
  • dms.instance.kafka.cluster.c3.middle.2: Kafka instance, 600 MB/s reference bandwidth
  • dms.instance.kafka.cluster.c3.high.2: Kafka instance, 1200 MB/s reference bandwidth

charging_mode

Integer

Indicates the billing mode. 1: pay-per-use mode; 0: yearly/monthly billing.

vpc_id

String

Indicates the ID of a VPC.

vpc_name

String

Indicates the name of a VPC.

created_at

String

Indicates the time when an instance is created.

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.

subnet_name

String

Indicates the subnet name.

subnet_cidr

String

Indicates the subnet CIDR block.

user_id

String

User ID.

user_name

String

Indicates the username.

access_user

String

Username for accessing an instance.

order_id

String

Indicates an order ID. This parameter has a value only when the billing mode is yearly/monthly mode.

maintain_begin

String

Time at which the maintenance time window starts. Format: HH:mm:ss.

maintain_end

String

Time at which the maintenance window ends. The format is HH:mm:ss.

enable_publicip

Boolean

Indicates whether to enable public access for an instance.

  • true: enable
  • false: disable

management_connect_address

String

Indicates the connection address of the Kafka Manager of a Kafka instance.

ssl_enable

Boolean

Indicates whether to enable security authentication.

  • true: enable
  • false: disable

broker_ssl_enable

Boolean

Indicates whether to enable encrypted replica transmission among brokers.

  • true: enable
  • false: disable

kafka_security_protocol

String

Security protocol used after SASL is enabled.

  • SASL_SSL: Data is encrypted with SSL certificates for high-security transmission.
  • SASL_PLAINTEXT: Data is transmitted in plaintext with username and password authentication. This protocol uses the SCRAM-SHA-512 mechanism to deliver better performance.

sasl_enabled_mechanisms

Array of strings

Authentication mechanism used after SASL is enabled.

  • PLAIN: simple username and password verification.
  • SCRAM-SHA-512: user credential verification, which is more secure than PLAIN.

ssl_two_way_enable

Boolean

Indicates whether to enable two-way authentication.

cert_replaced

Boolean

Whether the certificate can be replaced.

public_management_connect_address

String

Address for accessing Kafka Manager over public networks.

enterprise_project_id

String

Indicates the enterprise project ID.

is_logical_volume

Boolean

Distinguishes old instances from new instances during instance capacity expansion.

  • true: New instance, which allows dynamic disk capacity expansion without restarting the instance.
  • false: Old instance.

extend_times

Integer

Indicates the number of disk expansion times. If it exceeds 20, the disk cannot be expanded.

enable_auto_topic

Boolean

Indicates whether to enable automatic topic creation.

  • true: enable
  • false: disabled

type

String

Indicates the instance type. Value: cluster.

product_id

String

Indicates the product ID.

security_group_id

String

Indicates the security group ID.

security_group_name

String

Indicates the security group name.

subnet_id

String

Indicates the subnet ID.

available_zones

Array of strings

Indicates the ID of the AZ to which the instance node belongs. The AZ ID is returned.

available_zone_names

Array of strings

Indicates the AZ name to which the instance node belongs. The AZ name is returned.

total_storage_space

Integer

Indicates the message storage space. Unit: GB

public_connect_address

String

Indicates the instance IP address for public access. This parameter is displayed only when public access is enabled.

public_connect_domain_name

String

Domain name for public access to an instance. This parameter is displayed only when public access is enabled.

storage_resource_id

String

Indicates the storage resource ID.

storage_spec_code

String

Indicates the I/O specification.

service_type

String

Indicates the service type.

storage_type

String

Indicates the storage type.

retention_policy

String

Indicates the message retention policy.

kafka_public_status

String

Indicates whether Kafka public access is enabled.

public_bandwidth

Integer

Public network access bandwidth.

enable_log_collection

Boolean

Indicates whether log collection is enabled.

new_auth_cert

Boolean

Indicates whether to enable a new certificate.

cross_vpc_info

String

Indicates cross-VPC access information.

ipv6_enable

Boolean

Indicates whether IPv6 is enabled.

ipv6_connect_addresses

Array of strings

Indicates the IPv6 connection address.

connector_enable

Boolean

Indicates whether dumping is enabled. Dumping is not supported for the new specification type.

connector_node_num

Integer

Number of connectors.

connector_id

String

Indicates the ID of the dumping task.

rest_enable

Boolean

Indicates whether the Kafka REST function is enabled.

rest_connect_address

String

Indicates the Kafka REST connection address.

public_boundwidth

Integer

Public network access bandwidth. To be deleted.

message_query_inst_enable

Boolean

Indicates whether message query is enabled.

vpc_client_plain

Boolean

Indicates whether intra-VPC plaintext access is enabled.

support_features

String

Indicates the list of features supported by the Kafka instance.

trace_enable

Boolean

Indicates whether message tracing is enabled.

agent_enable

Boolean

Indicates whether the proxy is enabled.

pod_connect_address

String

Indicates the connection address on the tenant side.

disk_encrypted

Boolean

Indicates whether disk encryption is enabled.

disk_encrypted_key

String

Disk encryption key. If disk encryption is not enabled, this parameter is left blank.

kafka_private_connect_address

String

Indicates the private connection address of a Kafka instance.

kafka_private_connect_domain_name

String

Indicates the private domain name of a Kafka instance.

ces_version

String

Indicates the Cloud Eye version.

public_access_enabled

String

Time when public access was enabled for an instance.

Values:

  • true: Public access is enabled.
  • actived: Public access is enabled.
  • closed: Public access is disabled.
  • false: Public access is disabled.

node_num

Integer

Number of nodes.

port_protocols

PortProtocolsEntity object

Connection modes and addresses supported by an instance.

enable_acl

Boolean

Indicates whether access control is enabled.

new_spec_billing_enable

Boolean

Whether billing based on new specifications is enabled.

broker_num

Integer

Node quantity

tags

Array of TagEntity objects

Indicates the list of tags.

dr_enable

Boolean

Indicates whether DR is enabled.

Table 3 PortProtocolsEntity

Parameter

Type

Description

private_plain_enable

Boolean

Indicates whether private plaintext access is supported by an instance.

  • true: Yes
  • false: No

private_plain_address

String

Connection addresses of Kafka private plaintext access.

private_plain_domain_name

String

Private plaintext connection domain name.

private_sasl_ssl_enable

Boolean

Whether the instance supports private SASL_SSL access.

  • true: Yes
  • false: No

private_sasl_ssl_address

String

Connection addresses of the Kafka private SASL_SSL access mode.

private_sasl_ssl_domain_name

String

Private SASL_SSL connection domain name.

private_sasl_plaintext_enable

Boolean

Whether the instance supports private SASL_PLAINTEXT access.

  • true: Yes
  • false: No

private_sasl_plaintext_address

String

Connection addresses of the Kafka private SASL_PLAINTEXT access mode.

private_sasl_plaintext_domain_name

String

Private SASL_PLAINTEXT connection domain name.

public_plain_enable

Boolean

Whether the instance supports public plaintext access.

  • true: Yes
  • false: No

public_plain_address

String

Connection addresses of Kafka public plaintext access.

public_plain_domain_name

String

Public plaintext connection domain name.

public_sasl_ssl_enable

Boolean

Whether the instance supports public SASL_SSL access.

  • true: Yes
  • false: No

public_sasl_ssl_address

String

Connection addresses of the Kafka public SASL_SSL access mode.

public_sasl_ssl_domain_name

String

Public SASL_SSL connection domain name.

public_sasl_plaintext_enable

Boolean

Whether the instance supports public SASL_PLAINTEXT access.

  • true: Yes
  • false: No

public_sasl_plaintext_address

String

Connection addresses of the Kafka public SASL_PLAINTEXT access mode.

public_sasl_plaintext_domain_name

String

Public SASL_PLAINTEXT connection domain name.

Table 4 TagEntity

Parameter

Type

Description

key

String

Tag key, which:

  • Cannot be left blank.
  • Must be unique for the same instance.
  • Can contain 1 to 128 characters.
  • Can contain letters, digits, spaces, and special characters _.:=+-@
  • Cannot start with _sys_.
  • 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 _.:=+-@

Example Request

Querying a Specified Instance.

GET https://{endpoint}/v2/{engine}/{project_id}/instances/{instance_id}

Example Response

Status code: 200

Specified instance queried successfully.

{
  "name" : "kafka-2085975099",
  "engine" : "kafka",
  "port" : 9092,
  "status" : "RUNNING",
  "type" : "cluster",
  "specification" : "100MB",
  "engine_version" : "1.1.0",
  "connect_address" : "192.168.0.100,192.168.0.61,192.168.0.72",
  "instance_id" : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "resource_spec_code" : "dms.instance.kafka.cluster.c3.mini",
  "charging_mode" : 1,
  "vpc_id" : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "vpc_name" : "dms-test",
  "created_at" : "1585618587087",
  "product_id" : "00300-30308-0--0",
  "security_group_id" : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "security_group_name" : "Sys-default",
  "subnet_id" : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "available_zones" : [ "38b0f7a602344246bcb0da47b5d548e7" ],
  "available_zone_names" : [ "AZ1" ],
  "user_id" : "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "user_name" : "paas_dms",
  "access_user" : "root",
  "maintain_begin" : "02:00:00",
  "maintain_end" : "06:00:00",
  "enable_log_collection" : false,
  "new_auth_cert" : false,
  "storage_space" : 492,
  "total_storage_space" : 600,
  "used_storage_space" : 25,
  "partition_num" : "300",
  "enable_publicip" : false,
  "ssl_enable" : false,
  "broker_ssl_enable" : false,
  "cert_replaced" : false,
  "kafka_security_protocol" : "SASL_SSL",
  "management_connect_address" : "https://192.168.0.100:9999",
  "cross_vpc_info" : "{\"192.168.0.61\":{\"advertised_ip\":\"192.168.0.61\",\"port\":9011,\"port_id\":\"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"},\"192.168.0.72\":{\"advertised_ip\":\"192.168.0.72\",\"port\":9011,\"port_id\":\"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"},\"192.168.0.100\":{\"advertised_ip\":\"192.168.0.100\",\"port\":9011,\"port_id\":\"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"}}",
  "storage_resource_id" : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "storage_spec_code" : "dms.physical.storage.ultra",
  "service_type" : "advanced",
  "storage_type" : "hec",
  "enterprise_project_id" : "0",
  "retention_policy" : "produce_reject",
  "ipv6_enable" : false,
  "ipv6_connect_addresses" : [ ],
  "rest_enable" : false,
  "rest_connect_address" : "",
  "kafka_public_status" : "closed",
  "public_bandwidth" : 0,
  "trace_enable" : false,
  "agent_enable" : false,
  "pod_connect_address" : "100.86.75.15:9080,100.86.142.77:9080,100.86.250.167:9080",
  "disk_encrypted" : false,
  "kafka_private_connect_address" : "192.168.0.61:9092,192.168.0.100:9092,192.168.0.72:9092",
  "new_spec_billing_enable" : false,
  "ces_version" : "linux",
  "port_protocols" : "{\"private_plain_enable\": true,\"private_plain_address\": \"192.xxx.xxx.xxx:9092,192.xxx.xxx.xxx:9092,192.xxx.xxx.xxx:9092\",\"private_sasl_ssl_enable\": true,\"private_sasl_ssl_address\": \"192.xxx.xxx.xxx:9093,192.xxx.xxx.xxx:9093,192.xxx.xxx.xxx:9093\",\"private_sasl_plaintext_enable\": false,\"private_sasl_plaintext_address\": \"\",\"public_plain_enable\": true,\"public_plain_address\": \"100.xxx.xxx.xxx:9094,100.xxx.xxx.xxx:9094,100.xxx.xxx.xxx:9094\",\"public_sasl_ssl_enable\": true,\"public_sasl_ssl_address\": \"100.xxx.xxx.xxx:9095,100.xxx.xxx.xxx:9095,100.xxx.xxx.xxx:9095\",\"public_sasl_plaintext_enable\": false,\"public_sasl_plaintext_address\": \"\"}"
}

Status Code

Status Code

Description

200

Specified instance queried successfully.

Error Code

See Error Codes.