Queries the information about consumer groups within the current account.

Note

This operation returns a consumer group list and does not return the details of consumer groups.

QPS limit

Each Alibaba Cloud account can call this operation up to 10 times per second. If the number of requests that you send to call this operation within a second exceeds the queries per second (QPS) limit, throttling is triggered. This may interrupt your business. For information about the QPS limit of each operation, see API rate limits.

Authorization

By default, Alibaba Cloud accounts can call this operation. A Resource Access Management (RAM) user can call this operation only after the RAM user is granted the required permissions. The following table describes the permissions that must be granted to a RAM user to call this operation.

API

Action

Resource

OnsGroupList

mq:QueryInstanceBaseInfo

acs:mq:*:*:{instanceId}

Note When you use the credential of a RAM user to call this operation, this operation returns only the information about the consumer groups on which the RAM user is granted the required permissions. Log on to the RAM console with your Alibaba Cloud account to grant the RAM user the required permissions on the consumer groups that you want to access. For information about how to grant permissions, see Policies.

Request parameters

Parameter Type Required Example Description
Action String Yes OnsGroupList

The operation that you want to perform. Set the value to OnsGroupList.

InstanceId String Yes MQ_INST_111111111111_DOxxxxxx

The ID of the Message Queue for Apache RocketMQ instance to which the consumer groups you want to query belong.

GroupId String No GID_test_group_id

This parameter is required only when you query specific consumer groups by using the fuzzy query method. If this parameter is not configured, the system queries all consumer groups that can be accessed by the current account.

If you set this parameter to GID_ABC, the information about the consumer groups whose IDs contain GID_ABC is returned. For example, the information about the GID_test_GID_ABC_123 and GID_ABC_356 consumer groups is returned.

GroupType String No tcp

The protocol over which the queried consumer groups consume messages. All clients in a consumer group communicate with the Message Queue for Apache RocketMQ broker over the same protocol. A consumer group cannot contain TCP clients and HTTP clients at the same time. You must create different consumer groups for TCP clients and HTTP clients. Valid values:

  • tcp: specifies the consumer groups that consume messages over TCP. This is the default value.
  • http: specifies the consumer groups that consume messages over HTTP.
Tag.N.Key String Yes CartService

The key of a tag that is attached to the consumer group. This parameter is not required. If you configure this parameter, you must configure the Tag.N.Value parameter. If you specify tags, the system filters consumer groups based on the specified tags. If you do not specify tags, the system queries all consumer groups that can be accessed by the current account.

  • Valid values of N: 1 to 20.
  • The parameter value cannot be an empty string.
  • The value can be up to 128 characters in length. The value cannot start with acs: or aliyun, or contain http:// or https://.
Tag.N.Value String Yes ServiceA

The value of the tag that is specified by the Tag.N.Key parameter. This parameter is not required. If you configure this parameter, you must configure the Tag.N.Value parameter. If you specify tags, the system filters consumer groups based on the specified tags. If you do not specify tags, the system queries all consumer groups that can be accessed by the current account.

  • Valid values of N: 1 to 20.
  • The parameter value can be an empty string.
  • The value can be up to 128 characters in length. The value cannot start with acs: or aliyun, or contain http:// or https://.

Response parameters

Parameter Type Example Description
RequestId String 16996623-AC4A-43AF-9248-FD9D2D75****

The ID of the request. The system generates a unique ID for each request. You can troubleshoot issues based on the request ID.

Data Array of SubscribeInfoDo

The data that is returned.

SubscribeInfoDo
Owner String 138015630679****

The ID of the user who created the consumer group.

UpdateTime Long 1570700979000

The most recent point in time when the consumer group was updated.

IndependentNaming Boolean true

Indicates whether a namespace is configured for the Message Queue for Apache RocketMQ instance to which the consumer group belong. Valid values:

  • true: A separate namespace is configured for the instance. The name of each resource must be unique in the instance. Resources across instances can use the same name.
  • false: No separate namespace is configured for the instance. The name of each resource must be unique across all instances.
GroupId String GID_test_group_id

The ID of the consumer group.

Remark String test

The description of the consumer group.

CreateTime Long 1568896605000

The point in time when the consumer group was created.

Tags Array of Tag

The tags that are attached to the consumer group.

Tag
Key String CartService

The key of the tag.

Value String ServiceA

The value of the tag.

InstanceId String MQ_INST_111111111111_DOxxxxxx

The ID of the instance.

GroupType String tcp

The protocol over which the queried consumer groups consume messages. All clients in a consumer group communicate with the Message Queue for Apache RocketMQ broker over the same protocol. A consumer group cannot contain TCP clients and HTTP clients at the same time. You must create different consumer groups for TCP clients and HTTP clients. Valid values:

  • tcp: indicates that the consumer group consumes messages over TCP.
  • http: indicates that the consumer group consumes messages over HTTP.

Examples

Sample requests

http(s)://ons.cn-hangzhou.aliyuncs.com/?Action=OnsGroupList
&InstanceId=MQ_INST_111111111111_DOxxxxxx
&Tag.1.Key=CartService
&Tag.1.Value=ServiceA
&<Common request parameters>

Sample success responses

XML format 

HTTP/1.1 200 OK
Content-Type:application/xml

<OnsGroupListResponse>
<RequestId>16996623-AC4A-43AF-9248-FD9D2D75****</RequestId>
<Data>
    <SubscribeInfoDo>
        <Owner>138015630679****</Owner>
        <GroupType>tcp</GroupType>
        <InstanceId>MQ_INST_111111111111_DOxxxxxx</InstanceId>
        <CreateTime>1568896605000</CreateTime>
        <UpdateTime>1570700979000</UpdateTime>
        <IndependentNaming>true</IndependentNaming>
        <GroupId>GID_test_group_id</GroupId>
        <Remark>test</Remark>
        <Tags>
            <Tag>
                <Value>ServiceA</Value>
                <Key>CartService</Key>
            </Tag>
        </Tags>
    </SubscribeInfoDo>
</Data>
</OnsGroupListResponse>

JSON format 

HTTP/1.1 200 OK
Content-Type:application/json

{
  "RequestId" : "16996623-AC4A-43AF-9248-FD9D2D75****",
  "Data" : {
    "SubscribeInfoDo" : [ {
      "Owner" : "138015630679****",
      "GroupType" : "tcp",
      "InstanceId" : "MQ_INST_111111111111_DOxxxxxx",
      "CreateTime" : 1568896605000,
      "UpdateTime" : 1570700979000,
      "IndependentNaming" : true,
      "GroupId" : "GID_test_group_id",
      "Remark" : "test",
      "Tags" : {
        "Tag" : [ {
          "Value" : "ServiceA",
          "Key" : "CartService"
        } ]
      }
    } ]
  }
}

Error codes

For a list of error codes, visit the API Error Center.