DocsICP FilingConsole
Documentation

GetInstance

Updated at:
Copy as MD
Product
My Favorites

Retrieves the details of a specified instance.

Operation description

Important The OpenAPI operations provided by Alibaba Cloud are management APIs used to manage and query Alibaba Cloud service resources. Use them only in management and control workflows. Do not rely on OpenAPI in core data link workflows for message sending and receiving, as this may introduce risks to the data link.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

  • Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.

  • API: The API that you can call to perform the action.

  • Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.

  • Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.

    • For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.

    • For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.

  • Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.

  • Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

rocketmq:GetInstance

get

*Instance

acs:rocketmq:{#regionId}:{#accountId}:instance/{#InstanceId}

 None None

Request syntax

GET /instances/{instanceId} HTTP/1.1

Path Parameters

Parameter

Type

Required

Description

Example
instanceId

string

Yes

The ID of the instance to query.

rmq-cn-7e22ody****

Request parameters

Parameter

Type

Required

Description

Example

No parameters required.

Response elements

Element

Type

Description

Example

object

The response data.

requestId

string

The request ID. Each request has a unique ID, which you can use to troubleshoot and locate issues.

05AB7FBD-F1D3-5D87-BF78-BD782249****
success

boolean

Indicates whether the operation was successful.

true
data

object

The response result.

regionId

string

The ID of the region where the instance resides.

cn-hangzhou
instanceId

string

The instance ID.

rmq-cn-7e22ody****
instanceName

string

The instance name.

test instance
status

string

The instance status.

Valid values:

  • RELEASED :

    Released.

  • RUNNING :

    Running.

  • STOPPED :

    Stopped.

  • CHANGING :

    Changing.

  • CREATING :

    Creating.

RUNNING
startTime

string

The time when the instance was started. The format is YYYY-MM-DD HH:mm:ss.

2022-08-01 00:00:00
expireTime

string

The time when the instance expires. The format is YYYY-MM-DD HH:mm:ss.

2022-09-01 00:00:00
releaseTime

string

The time when the instance was released. The format is YYYY-MM-DD HH:mm:ss.

2022-09-07 00:00:00
userId

string

The ID of the user to whom the instance belongs.

111111111111111
bid

string

The BID of the sales channel for the commodity.

26842
commodityCode

string

The commodity code of an MSMQ for RocketMQ 5.x series instance, such as ons_rmqsub_public_cn.

ons_rmqsub_public_cn
serviceCode

string

The service code of the instance. The service code for MSMQ for RocketMQ is rmq.

rmq
seriesCode

string

The primary series code of the instance. For differences between primary series, see Product selection.

Valid values:

  • standard :

    Standard Edition.

  • shared :

    Shared Edition.

  • dedicated :

    Dedicated Edition.

  • ultimate :

    Platinum Edition.

  • professional :

    Professional Edition.

standard
subSeriesCode

string

The sub-series code of the instance. For differences between sub-series, see Product selection.

Valid values:

  • serverless :

    Serverless edition.

  • cluster_ha :

    Cluster high-availability edition.

  • single_node :

    Single-node edition.

cluster_ha
paymentType

string

The payment type of the instance.

Valid values:

  • PayAsYouGo :

    Pay-as-you-go (postpaid)

  • Subscription :

    Subscription (prepaid)

Subscription
remark

string

The remarks for the instance.

This is remark for instance.
networkInfo

object

The network information.

vpcInfo

object

The VPC information.

vpcId

string

The ID of the VPC associated with the instance.

vpc-uf6of9452b2pba82c****
vSwitchId deprecated

string

The ID of the vSwitch associated with the instance.

Important This field is not recommended. Use the vSwitches field instead. For compatibility, this field currently returns only one vSwitch.

vsw-uf6gwtbn6etadpvz7****
vSwitches

array<object>

The list of vSwitches.

object

vSwitchId

string

The vSwitch ID.

vsw-uf6gwtbn6etadpvz7****
zoneId

string

The zone ID.

cn-hangzhou
securityGroupIds

string

The security group ID.

sg-hp35r2hc3a3sv8q2sb16
endpoints

array<object>

The endpoint information.

object

The endpoint information.

endpointType

string

The endpoint type of the instance.

Valid values:

  • TCP_VPC :

    VPC endpoint.

  • TCP_INTERNET :

    Internet endpoint.

TCP_INTERNET
endpointUrl

string

The endpoint of the instance.

rmq-cn-c4d2tbk****-vpc.cn-hangzhou.rmq.aliyuncs.com:8080
ipWhitelist

array

The IP whitelist for public network access. IP whitelists are supported only for Internet endpoints and are not supported for VPC endpoints.

  • If no IP whitelist is configured, all IP address ranges are allowed to access the MSMQ for RocketMQ queue broker over the Internet by default.

  • If an IP whitelist is configured, only IP addresses in the whitelist are allowed to access the MSMQ for RocketMQ queue broker over the Internet.

This field is no longer recommended. Use the internetInfo.ipWhitelist field instead.

192.168.x.x/24

string

The IP whitelist for public network access.

192.168.x.x/24
endpointId

string

The associated PrivateLink endpoint instance.

ep-bpxxx
internetInfo

object

The public network information of the instance.

internetSpec

string

Indicates whether public network access is enabled.

The instance supports VPC access by default. If public network access is enabled, ApsaraMQ for RocketMQ charges fees for public downstream bandwidth. For more information about billing, see Public network access fees.

Valid values:

  • enable :

    Public network access is enabled.

  • disable :

    Public network access is disabled.

enable
flowOutType

string

The billing type for public network usage.

Valid values:

  • payByBandwidth :

    Fixed bandwidth billing. This value is returned when public network access is enabled.

  • uninvolved :

    Not applicable. This value is returned when public network access is not enabled.

payByBandwidth
flowOutBandwidth

integer

The Internet bandwidth specification. Unit: Mbit/s.

1
ipWhitelist

array

The IP whitelist for public network access.

  • If the IP whitelist is not configured, all IP address ranges are allowed to access the ApsaraMQ for RocketMQ broker over the public network by default.

  • If the IP whitelist is configured, only the IP addresses in the whitelist are allowed to access the ApsaraMQ for RocketMQ broker over the public network.

string

The IP address in the public network access whitelist.

192.168.x.x/24
accountInfo

object

The account information.

username

string

The username of the instance. When you use public network access, you must configure the username and password of the instance in the SDK code for identity verification.

6W0xz2uPfiwp****
instanceQuotas

array<object>

The capacity information.

object

The capacity information.

quotaName

string

The quota name of the instance.

Valid values:

  • TOPIC_COUNT :

    The topic creation quota of the instance.

TOPIC_COUNT
usedCount

number

The used quota. Unit: count.

10
freeCount

number

The free quota. Unit: count.

20
totalCount

number

The total quota. Unit: count.

100
createTime

string

The time when the instance was created. The value is in the YYYY-MM-DD HH:mm:ss format.

2022-08-01 00:00:00

updateTime

string

The time when the instance was last modified. The value is in the YYYY-MM-DD HH:mm:ss format.

2022-08-02 00:00:00

extConfig deprecated

object

[Deprecated] The extended configuration. This field is no longer recommended. Use the productInfo, internetInfo, and aclInfo fields instead.

aclType

string

The authentication type of the instance.

Valid values:

  • default :

    Intelligent identity recognition.

  • apache_acl :

    Apache RocketMQ ACL

default
sendReceiveRatio

number

The ratio of message sending to message receiving.

0.5
autoScaling

boolean

Indicates whether burstable elastic capacity beyond the base specification is enabled.

This parameter takes effect only when the value of supportAutoScaling is enable, which means the instance supports enabling elastic capacity.

Valid values:

  • true :

    Elastic capacity is enabled.

  • false :

    Elastic capacity is not enabled.

true
messageRetentionTime

integer

The message retention period. Unit: hours.

For the value range, see Limits > Resource Quotas > Message retention period.

The message storage of ApsaraMQ for RocketMQ is fully serverless and elastic. You are charged based on the actual storage space used. You can control the storage capacity by adjusting the message retention period. For more information, see Storage fees.

72
supportAutoScaling

boolean

Indicates whether the instance supports enabling burstable elastic capacity beyond the base specification.

After burstable elastic capacity is enabled, ApsaraMQ for RocketMQ allows the instance to exceed the TPS limit of the base specification within a certain range. Additional elastic specification fees are charged for the portion that exceeds the base specification. For more information about billing, see Computing fees.

Note

Only instances of specific specifications support burstable elastic capacity. For more information about supported instances, see Instance specifications.

Valid values:

  • true :

    Enabling elastic capacity is supported.

  • false :

    Enabling elastic capacity is not supported.

true
internetSpec

string

Indicates whether public network access is enabled.

The instance supports VPC access by default. If public network access is enabled, ApsaraMQ for RocketMQ charges fees for public downstream bandwidth. For more information about billing, see Public network access fees.

Valid values:

  • enable :

    Public network access is enabled.

  • disable :

    Public network access is disabled.

enable
flowOutType

string

The billing type for public network usage.

Valid values:

  • payByTraffic :

    Pay-by-traffic.

  • payByBandwidth :

    Pay-by-bandwidth.

  • uninvolved :

    Not applicable.

payByBandwidth
flowOutBandwidth

integer

The Internet bandwidth specification. Unit: Mbit/s.

10
msgProcessSpec

string

The message processing specification. For the TPS upper limit of message sending and receiving, see Instance specifications.

rmq.s2.2xlarge
resourceGroupId

string

The resource group ID.

rg-acfm3tmjruyribi
productInfo

object

The extended configuration of the instance.

msgProcessSpec

string

The message processing specification. For the TPS upper limit of message sending and receiving, see Instance specifications.

rmq.s2.2xlarge
sendReceiveRatio

number

The ratio of message sending to message receiving.

0.5
autoScaling

boolean

Indicates whether burstable elastic capacity beyond the base specification is enabled for seamless scaling.

This parameter takes effect only when the value of supportAutoScaling is enable, which means the instance supports enabling elastic capacity.

Valid values:

  • true :

    Elastic capacity is enabled.

  • false :

    Elastic capacity is not enabled.

true
messageRetentionTime

integer

The message retention period. Unit: hours.

For the value range, see Limits > Resource Quotas > Message retention period.

The message storage of ApsaraMQ for RocketMQ is fully serverless and elastic. You are charged based on the actual storage space used. You can control the storage capacity by adjusting the message retention period. For more information, see Storage fees.

72
supportAutoScaling

boolean

Indicates whether the burstable elastic capability beyond the base specification is enabled.

After the burstable elastic capability is enabled, ApsaraMQ for RocketMQ allows the instance to exceed the TPS limit of the base specification within a certain range. Additional elastic specification fees are charged for the portion that exceeds the base specification. For more information about billing, see Computing capability fees.

Note

Only instances of specific specifications support the burstable elastic capability. For more information about supported instances, see Instance specifications.

Valid values:

  • true :

    Enabling elastic capacity is supported.

  • false :

    Enabling elastic capacity is not supported.

true
traceOn

boolean

Indicates whether the message trace feature is enabled.

  • true: The message trace feature is enabled.

  • false: The message trace feature is disabled.

This parameter takes effect only for Serverless instances. If the message trace feature is enabled, message trace fees are incurred. For more information about billing, see Serverless billing.

For pay-as-you-go and subscription instances, this parameter does not take effect. The message trace feature is supported by default regardless of whether this parameter is enabled.

true
storageEncryption

boolean

Indicates whether storage encryption is enabled.

false
storageSecretKey

string

The storage encryption key.

xxxxx
capacityType

string

The capacity mode.

Valid values:

  • provisioned :

    provisioned + elastic.

  • ondemand :

    pay-as-you-go.

provisioned
provisionedCapacity

integer

The provisioned capacity.

3000
drReplicationMode

string

The cross-region replication mode.

async_cross_az
maxDelayTime

integer

The maximum interval for scheduled messages. Unit: seconds.

3456000
adaptiveElasticity

boolean

The adaptive elasticity.

false
aclInfo

object

The access control information.

aclTypes

array

The authentication types of the instance.

string

The authentication type of the instance.

Valid values:

  • default :

    Intelligent identity recognition.

  • apache_acl :

    ACL identity recognition.

default
defaultVpcAuthFree

boolean

Indicates whether the authentication-free in VPC feature is enabled.

Valid values:

  • true :

    Enabled.

  • false :

    Disabled.

true
aclType deprecated

string

The authentication type of the instance. This parameter is deprecated. Use the aclTypes parameter instead.

Valid values:

  • default :

    Intelligent identity recognition.

  • apache_acl :

    ACL identity recognition.

default
software

object

The instance software information.

softwareVersion

string

The software version.

5.0-rmq-20230619-1
maintainTime deprecated

string

The upgrade time window, in the format of HH:mm-HH:mm.

02:00-06:00
upgradeMethod

string

The upgrade method.

Valid values:

  • auto :

    Automatic upgrade.

  • maunal :

    Manual upgrade.

auto
topicCount

integer

The number of topics.

10
groupCount

integer

The number of consumer groups.

10
tags

array<object>

The resource tags.

object

The resource tag.

key

string

The key of the resource tag.

key
value

string

The value of the resource tag.

value
autoRenew

boolean

Indicates whether auto-renewal is enabled.

false
autoRenewPeriod

integer

Indicates whether auto-renewal is enabled.

false
code

string

The error code.

MissingInstanceId
message

string

The error message.

Parameter instanceId is mandatory for this action .
httpStatusCode

integer

The HTTP status code.

400
dynamicCode

string

The dynamic error code.

InstanceId
dynamicMessage

string

The dynamic error message.

instanceId

Examples

Success response

JSON format

{
  "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****",
        "vSwitches": [
          {
            "vSwitchId": "vsw-uf6gwtbn6etadpvz7****",
            "zoneId": "cn-hangzhou"
          }
        ],
        "securityGroupIds": "sg-hp35r2hc3a3sv8q2sb16"
      },
      "endpoints": [
        {
          "endpointType": "TCP_INTERNET",
          "endpointUrl": "rmq-cn-c4d2tbk****-vpc.cn-hangzhou.rmq.aliyuncs.com:8080",
          "ipWhitelist": [
            "192.168.x.x/24"
          ],
          "endpointId": "ep-bpxxx"
        }
      ],
      "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,
      "storageEncryption": false,
      "storageSecretKey": "xxxxx",
      "capacityType": "provisioned",
      "provisionedCapacity": 3000,
      "drReplicationMode": "async_cross_az",
      "maxDelayTime": 3456000,
      "adaptiveElasticity": false
    },
    "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"
      }
    ],
    "autoRenew": false,
    "autoRenewPeriod": 0
  },
  "code": "MissingInstanceId",
  "message": "Parameter instanceId is mandatory for this action .",
  "httpStatusCode": 400,
  "dynamicCode": "InstanceId",
  "dynamicMessage": "instanceId"
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.