GetInstance - ApsaraMQ for RocketMQ - Alibaba Cloud Documentation Center

Queries the detailed information about an instance.

Operation description

Note API operations provided by Alibaba Cloud are used to manage and query resources of Alibaba Cloud services. We recommend that you integrate these API operations only in management systems. Do not use these API operations in the core system of messaging services. Otherwise, system risks may occur.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer.

Debug

Authorization information

The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:

Operation: the value that you can use in the Action element to specify the operation on a resource.
Access level: the access level of each operation. The levels are read, write, and list.
Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
- The required resource types are displayed in bold characters.
- If the permissions cannot be granted at the resource level, All Resources is used in the Resource type column of the operation.
Condition Key: the condition key that is defined by the cloud service.
Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.

Operation	Access level	Resource type	Condition key	Associated operation
rocketmq:GetInstance	Read	Instance acs:rocketmq:{#regionId}:{#accountId}:instance/{#InstanceId}	none	none

Request syntax

GET /instances/{instanceId}

Request parameters

Parameter	Type	Required	Description	Example
instanceId	string	Yes	The ID of the instance that you want to query.	rmq-cn-7e22ody****

Response parameters

Parameter	Type	Description	Example
	object	The response parameters.
requestId	string	The ID of the request. Each request has a unique ID. You can use this ID to troubleshoot issues.	05AB7FBD-F1D3-5D87-BF78-BD782249****
success	boolean	Indicates whether the call was successful.	true
data	object	The returned data.
regionId	string	The ID of the region in which the instance resides.	cn-hangzhou
instanceId	string	The ID of the instance	rmq-cn-7e22ody****
instanceName	string	The name of the instance.	test instance
status	string	The status of the instance. Valid values: RELEASED RUNNING STOPPED CHANGING CREATING	RUNNING
startTime	string	The time when the instance was started.	2022-08-01 00:00:00
expireTime	string	The time when the instance expires.	2022-09-01 00:00:00
releaseTime	string	The time when the instance was released.	2022-09-07 00:00:00
userId	string	The ID of the user who owns the instance.	111111111111111
bid	string	The business ID (BID) of the commodity.	26842
commodityCode	string	The commodity code of the instance. The commodity code of a ApsaraMQ for RocketMQ 5.0 instance has a similar format as ons_rmqsub_public_cn.	ons_rmqsub_public_cn
serviceCode	string	The code of the service to which the instance belongs. The service code of ApsaraMQ for RocketMQ is rmq.	rmq
seriesCode	string	The primary edition of the instance. For information about the differences between primary edition instances, see Instance selection. Valid values: standard: Standard Edition ultimate: Enterprise Platinum Edition professional: Professional Edition	standard
subSeriesCode	string	The sub-category edition of the instance. For information about the differences between sub-category edition instances, see Instance selection. Valid values: cluster_ha: Cluster High-availability Edition single_node: Standalone Edition	cluster_ha
paymentType	string	The billing method of the instance. Valid values: PayAsYouGo: pay-as-you-go Subscription	Subscription
remark	string	The description of the instance.	This is remark for instance.
networkInfo	object	The network information.
vpcInfo	object	The virtual private cloud (VPC) information.
vpcId	string	The ID of the VPC with which the instance is associated.	vpc-uf6of9452b2pba82c****
vSwitchId	string	The ID of the vSwitch with which the instance is associated.	vsw-uf6gwtbn6etadpvz7****
securityGroupIds	string	The security group ID.	sg-hp35r2hc3a3sv8q2sb16
endpoints	object []	The information about endpoints.
endpointType	string	The type of the endpoint that is used to access the instance. Valid values: TCP_VPC: VPC endpoint TCP_INTERNET:public endpoint	TCP_INTERNET
endpointUrl	string	The endpoint that is used to access the instance.	rmq-cn-c4d2tbk****-vpc.cn-hangzhou.rmq.aliyuncs.com:8080
ipWhitelist	string	The whitelist that includes the IP addresses that are allowed to access the ApsaraMQ for RocketMQ broker over the Internet. This parameter can be configured only if you use the public endpoint to access the instance. If you do not configure an IP address whitelist, all CIDR blocks are allowed to access the ApsaraMQ for RocketMQ broker over the Internet. If you configure an IP address whitelist, only the IP addresses in the whitelist are allowed to access the ApsaraMQ for RocketMQ broker over the Internet. We recommend that you configure internetInfo.ipWhitelist instead of this parameter.	192.168.x.x/24
internetInfo	object	The information about the Internet.
internetSpec	string	Specifies whether to enable the Internet access feature. Valid values: enable disable By default, ApsaraMQ for RocketMQ instances are accessed in virtual private clouds (VPCs). If you enable the Internet access feature, you are charged for Internet outbound bandwidth. For more information, see Internet access fee.	enable
flowOutType	string	The metering method for Internet usage. Valid values: PayByBandwidth: pay-by-bandwidth. If the Internet access feature is enabled, specify this value for the parameter. uninvolved: N/A. If the Internet access feature is not enabled, specify this value for the parameter.	payByBandwidth
flowOutBandwidth	integer	The Internet bandwidth. Unit: MB/s.	1
ipWhitelist	array	The whitelist that includes the IP addresses that are allowed to access the ApsaraMQ for RocketMQ broker. If this parameter is not configured, all IP addresses are allowed to access the ApsaraMQ for RocketMQ broker over the Internet. If this parameter is configured, only the IP addresses that are included in the whitelist can access the ApsaraMQ for RocketMQ broker over the Internet.
	string	The whitelist that includes the IP addresses that are allowed to access the ApsaraMQ for RocketMQ broker over the Internet.	192.168.x.x/24
accountInfo	object	The account information.
username	string	The username of the instance. If you access a ApsaraMQ for RocketMQ instance over the Internet, you must configure the username and password of the instance in the SDK code for authentication.	6W0xz2uPfiwp****
instanceQuotas	object []	The instance quotas.
quotaName	string	The quota name. Valid value: TOPIC_COUNT: the number of topics that can be created on the instance	TOPIC_COUNT
usedCount	double	The number of used topics on the instance.	10
freeCount	double	The number of topics that are free of charge on the instance.	20
totalCount	double	The total number of topics on the instance.	100
createTime	string	The time when the instance was created.	2022-08-01 00:00:00
updateTime	string	The time when the instance was last modified.	2022-08-02 00:00:00
extConfig	object	The extended configurations. We recommend you configure productInfo, internetInfo, or aclInfo instead of this parameter.
aclType	string	The authentication type of the instance. Valid values: default: intelligent authentication	default
sendReceiveRatio	float	The ratio between sent messages and received messages in the instance.	0.5
autoScaling	boolean	Specifies whether to enable the elastic TPS feature for the instance. Valid values: true: enable false: disable This parameter is valid only when the supportAutoScaling parameter is set to enable.	true
messageRetentionTime	integer	The retention period of messages. Unit: hours. For information about the valid values of this parameter, see the "Limits on resource quotas" section in Usage limits. The storage of messages in ApsaraMQ for RocketMQ is serverless and scalable. You are charged for message storage based on your actual usage. You can change the retention period of messages to adjust storage capacity. For more information, see Storage fee.	72
supportAutoScaling	boolean	Specifies whether the elastic TPS feature is supported by the instance. Valid values: true: enable false: disable After you enable the elastic TPS feature for a ApsaraMQ for RocketMQ instance, you can use a specific amount of TPS that exceeds the specification limit. You are charged for the elastic TPS feature. For more information, see Computing fee. Note The elastic TPS feature is supported only by specific instance editions. For more information, see Instance specifications.	true
internetSpec	string	Specifies whether to enable the Internet access feature. Valid values: enable disable By default, ApsaraMQ for RocketMQ instances are accessed in virtual private clouds (VPCs). If you enable the Internet access feature, you are charged for Internet outbound bandwidth. For more information, see Internet access fee.	enable
flowOutType	string	The metering method for Internet usage. Valid values: PayByTraffic: pay-by-traffic paybybandwidth: pay-by-bandwidth uninvolved: N/A	payByBandwidth
flowOutBandwidth	integer	The Internet bandwidth. Unit: MB/s.	10
msgProcessSpec	string	The computing specification that is used to send and receive messages. For information about the upper limit of TPS, see Instance specifications.	rmq.s2.2xlarge
resourceGroupId	string	The ID of the resource group.	rg-acfm3tmjruyribi
productInfo	object	The extended configurations of the instance.
msgProcessSpec	string	The computing specification that is used to send and receive messages. For information about the upper limit of TPS, see Instance specifications.	rmq.s2.2xlarge
sendReceiveRatio	float	The ratio between sent messages and received messages in the instance.	0.5
autoScaling	boolean	Specifies whether to enable the elastic TPS feature for the instance. Valid values: true: enable false: disable This parameter is valid only when the supportAutoScaling parameter is set to enable.	true
messageRetentionTime	integer	The retention period of messages. Unit: hours. For information about the valid values of this parameter, see the "Limits on resource quotas" section in Usage limits. The storage of messages in ApsaraMQ for RocketMQ is serverless and scalable. You are charged for message storage based on your actual usage. You can change the retention period of messages to adjust storage capacity. For more information, see Storage fee.	72
supportAutoScaling	boolean	Specifies whether to enable the elastic TPS feature for the instance. Valid values: true: enable false: disable After you enable the elastic TPS feature for a ApsaraMQ for RocketMQ instance, you can use a specific amount of TPS that exceeds the specification limit. You are charged for the elastic TPS feature. For more information, see Computing fee. Note The elastic TPS feature is supported by only specific instance editions. For more information, see Instance specifications.	true
traceOn	boolean	Indicates whether the message trace feature is enabled. Valid values: true false This parameter is not in use. By default, the message trace feature is enabled for ApsaraMQ for RocketMQ instances, regardless of whether this parameter is configured.	true
aclInfo	object	The information about access control.
aclTypes	array	The authentication types of the instance.
	string	The authentication type of the instance. Valid values: default: intelligent identity authentication apache_acl:access control list (ACL) identity authentication	default
defaultVpcAuthFree	boolean	Indicates whether the authentication-free in VPCs feature is enabled. Valid values: true false	true
aclType	string	The authentication type of the instance. This parameter is no longer in use. We recommend that you configure aclTypes. Valid values: default: intelligent identity authentication apache_acl:access control list (ACL) identity authentication**	default
software	object	The instance software information.
softwareVersion	string	The version of software.	5.0-rmq-20230619-1
maintainTime	string	The period of upgrade time.	02:00-06:00
upgradeMethod	string	The upgrade method. Valid values: Auto: automatic upgrade Manual: manual upgrade	auto
topicCount	long	The number of topics.	10
groupCount	long	The number of groups.	10
tags	object []	The resource tags.
key	string	The tag key of the resource.	key
value	string	The tag value of the resource.	value
code	string	The error code returned if the call failed.	MissingInstanceId
message	string	The error message.	Parameter instanceId is mandatory for this action .
httpStatusCode	integer	The HTTP status code returned.	400
dynamicCode	string	The dynamic error code.	InstanceId
dynamicMessage	string	The dynamic error message.	instanceId

Examples

Sample success responses

JSONformat

{
  "requestId": "05AB7FBD-F1D3-5D87-BF78-BD782249****",
  "success": true,
  "data": {
    "regionId": "cn-hangzhou",
    "instanceId": "rmq-cn-7e22ody****",
    "instanceName": "test instance",
    "status": "RUNNING",
    "startTime": "2022-08-01 00:00:00",
    "expireTime": "2022-09-01 00:00:00",
    "releaseTime": "2022-09-07 00:00:00",
    "userId": "111111111111111",
    "bid": "26842",
    "commodityCode": "ons_rmqsub_public_cn",
    "serviceCode": "rmq",
    "seriesCode": "standard",
    "subSeriesCode": "cluster_ha",
    "paymentType": "Subscription",
    "remark": "This is remark for instance.",
    "networkInfo": {
      "vpcInfo": {
        "vpcId": "vpc-uf6of9452b2pba82c****",
        "vSwitchId": "vsw-uf6gwtbn6etadpvz7****",
        "securityGroupIds": "sg-hp35r2hc3a3sv8q2sb16"
      },
      "endpoints": [
        {
          "endpointType": "TCP_INTERNET",
          "endpointUrl": "rmq-cn-c4d2tbk****-vpc.cn-hangzhou.rmq.aliyuncs.com:8080",
          "ipWhitelist": "192.168.x.x/24"
        }
      ],
      "internetInfo": {
        "internetSpec": "enable",
        "flowOutType": "payByBandwidth",
        "flowOutBandwidth": 1,
        "ipWhitelist": [
          "192.168.x.x/24"
        ]
      }
    },
    "accountInfo": {
      "username": "6W0xz2uPfiwp****"
    },
    "instanceQuotas": [
      {
        "quotaName": "TOPIC_COUNT",
        "usedCount": 10,
        "freeCount": 20,
        "totalCount": 100
      }
    ],
    "createTime": "2022-08-01 00:00:00 ",
    "updateTime": "2022-08-02 00:00:00 ",
    "extConfig": {
      "aclType": "default",
      "sendReceiveRatio": 0.5,
      "autoScaling": true,
      "messageRetentionTime": 72,
      "supportAutoScaling": true,
      "internetSpec": "enable",
      "flowOutType": "payByBandwidth",
      "flowOutBandwidth": 10,
      "msgProcessSpec": "rmq.s2.2xlarge"
    },
    "resourceGroupId": "rg-acfm3tmjruyribi",
    "productInfo": {
      "msgProcessSpec": "rmq.s2.2xlarge",
      "sendReceiveRatio": 0.5,
      "autoScaling": true,
      "messageRetentionTime": 72,
      "supportAutoScaling": true,
      "traceOn": true
    },
    "aclInfo": {
      "aclTypes": [
        "default"
      ],
      "defaultVpcAuthFree": true,
      "aclType": "default"
    },
    "software": {
      "softwareVersion": "5.0-rmq-20230619-1",
      "maintainTime": "02:00-06:00",
      "upgradeMethod": "auto"
    },
    "topicCount": 10,
    "groupCount": 10,
    "tags": [
      {
        "key": "key",
        "value": "value"
      }
    ]
  },
  "code": "MissingInstanceId",
  "message": "Parameter instanceId is mandatory for this action .",
  "httpStatusCode": 400,
  "dynamicCode": "InstanceId",
  "dynamicMessage": "instanceId"
}

Error codes

For a list of error codes, visit the Service error codes.

Change history

Change time

Summary of changes

Operation

2024-03-29