Queries all messages of a specified topic within a specified time range by page.

Usage notes

  • It is a range query to query messages based on a topic name. Query results are displayed to the caller by page. You can call this operation only when you do not know a specific message ID or message key.
  • We recommend that you minimize the time range to query messages. Otherwise, it will be difficult to locate problems due to an excessive number of matched messages. To call this operation, perform the following steps:

    1. Specify the topic, start time, end time, and number of entries to return on each page. If matched messages are found, the first page of the messages, total number of pages, and query task ID are returned by default.

    2. Query messages that are not displayed on the first page based on the returned query task ID for the first query. When you query the messages, specify the query task ID and current page number. The number of entries to return on each page, the start time, and the end time that you specify for subsequent queries do not take effect. By default, the values that you specified for the first query are used.

QPS limit

The queries-per-minute (QPM) limit on this operation is 10 per user. Throttling is triggered when the number of calls to this operation exceeds this limit. Throttling may affect your business. Therefore, call this operation based on your needs. For more information, see QPS limits.

Authorization information

By default, only Alibaba Cloud accounts can call this operation. Resource Access Management (RAM) users can call this operation only after they are authorized. The following table lists the authorization information of this operation. For more information, see Policies and examples.

API

Action

Resource with a namespace

Resource without a namespace

OnsMessagePageQueryByTopic

mq:QueryMessage

acs:mq:*:*:{instanceId}%{topic}

acs:mq:*:*:{topic}

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String Yes OnsMessagePageQueryByTopic

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

Topic String Yes test-mq_topic

The topic whose messages you want to query.

BeginTime Long Yes 1570723200000

The beginning of the time range to query. This value is a UNIX timestamp representing the number of milliseconds that have elapsed since the epoch time January 1, 1970, 00:00:00 UTC.

The value that you specify does not take effect if you query messages in subsequent queries based on the value of TaskId. By default, the start time that you specified for the first query is used.

EndTime Long Yes 1570809600000

The end of the time range to query. This value is a UNIX timestamp representing the number of milliseconds that have elapsed since the epoch time January 1, 1970, 00:00:00 UTC.

The value that you specify does not take effect if you query messages in subsequent queries based on the value of TaskId. By default, the end time that you specified for the first query is used.

TaskId String No 0BC1310300002A9F000021E4D7A48346

The ID of the query task. This parameter is not required for the first query but is required in subsequent queries for the messages. You can obtain the ID from the returned result of the first query.

CurrentPage Integer Yes 2

The number of the page to return. Pages start from page 1. Valid values: 1 to 50.

PageSize Integer No 5

The number of entries to return on each page. Valid values: 5 to 50. Default value: 20.

The value that you specify does not take effect if you query messages in subsequent queries based on the value of TaskId. By default, the number of entries to return on each page that you specified for the first query is used.

InstanceId String Yes MQ_INST_111111111111_DOxxxxxx

The ID of the Message Queue for Apache RocketMQ instance where the topic of the messages to be queried is created.

Note For more information about request parameters, see Common parameters and Make API requests.

Response parameters

Parameter Type Example Description
RequestId String 5DC2A47E-2B31-4722-96C8-FA59C9*****

The ID of the request. This parameter is a common parameter. Each request has a unique ID, which facilitates troubleshooting and problem locating.

MsgFoundDo Object

The query results.

CurrentPage Long 1

The page number of the returned page.

MsgFoundList Array of OnsRestMessageDo

A set of messages displayed on the current page. The results are the same as those returned for the call to the OnsMessageGetByMsgId operation.

OnsRestMessageDo
StoreSize Integer 406

The size of the message. Unit: KB.

ReconsumeTimes Integer 1

The number of retries after the message has failed to be consumed.

StoreTimestamp Long 1570760999811

The time when the Message Queue for Apache RocketMQ broker stored the message. This value is a UNIX timestamp representing the number of milliseconds that have elapsed since the epoch time January 1, 1970, 00:00:00 UTC.

InstanceId String MQ_INST_111111111111_DOxxxxxx

The ID of the Message Queue for Apache RocketMQ instance.

MsgId String 1E0578FE110F18B4AAC235C05F2*****

The ID of the message.

StoreHost String 11.193.***.***:10911

The Message Queue for Apache RocketMQ broker that stored the message.

Topic String test-mq_topic

The topic of the message.

PropertyList Array of MessageProperty

The returned properties of the message.

MessageProperty
Value String TagA

The value of the message property.

Name String TAGS

The property of the message. Valid values:

  • TRACE_ON: indicates whether a trace of the message exists.
  • KEYS: indicates the key property of the message.
  • TAGS: indicates the tag property of the message.
  • INSTANCE_ID: indicates the ID of the Message Queue for Apache RocketMQ instance that corresponds to the message.

For more information about the terms, see Terms.

BornTimestamp Long 1570760999721

The time when the message was generated. This value is a UNIX timestamp representing the number of milliseconds that have elapsed since the epoch time January 1, 1970, 00:00:00 UTC.

BodyCRC Integer 914112295

The cyclic redundancy check (CRC) value of the message body.

BornHost String 42.120.***.***:59270

The producer instance that generated the message.

MaxPageCount Long 400

The maximum number of returned pages.

TaskId String 0BC1310300002A9F000021E4D7A48346

The task ID returned for the first query task. The task ID is used to query messages in subsequent queries.

Examples

Sample requests

http(s)://ons.cn-hangzhou.aliyuncs.com/?Action=OnsMessagePageQueryByTopic
&BeginTime=1570723200000
&CurrentPage=2
&EndTime=1570809600000
&InstanceId=MQ_INST_111111111111_DOxxxxxx
&Topic=test-mq_topic
&<Common request parameters>

Sample success responses

XML format

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

<OnsMessagePageQueryByTopicResponse>
  <MsgFoundDo>
        <MaxPageCount>400</MaxPageCount>
        <MsgFoundList>
              <OnsRestMessageDo>
                    <MsgId>1E0578FE110F18B4AAC235C05F2*****</MsgId>
                    <InstanceId>MQ_INST_111111111111_DOxxxxxx</InstanceId>
                    <ReconsumeTimes>1</ReconsumeTimes>
                    <BornHost>42.120.***.***:59270</BornHost>
                    <StoreTimestamp>1570760999811</StoreTimestamp>
                    <StoreHost>11.193.***.***:10911</StoreHost>
                    <BodyCRC>914112295</BodyCRC>
                    <Topic>test-mq_topic</Topic>
                    <BornTimestamp>1570760999721</BornTimestamp>
                    <StoreSize>406</StoreSize>
                    <PropertyList>     
                          <MessageProperty>
                                <Name>TAGS</Name>
                                <Value>TagA</Value>
                          </MessageProperty>
                    </PropertyList>
              </OnsRestMessageDo>
        </MsgFoundList>
        <TaskId>0BC1310300002A9F000021E4D7A48346</TaskId>
        <CurrentPage>1</CurrentPage>
  </MsgFoundDo>
  <RequestId>5DC2A47E-2B31-4722-96C8-FA59C9*****</RequestId>
</OnsMessagePageQueryByTopicResponse>

JSON format

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

{
  "MsgFoundDo" : {
    "MaxPageCount" : 400,
    "MsgFoundList" : {
      "OnsRestMessageDo" : [ {
        "MsgId" : "1E0578FE110F18B4AAC235C05F2*****",
        "ReconsumeTimes" : 1,
        "BornHost" : "42.120.***.***:59270",
        "StoreTimestamp" : 1570760999811,
        "StoreHost" : "11.193.***.***:10911",
        "BodyCRC" : 914112295,
        "Topic" : "test-mq_topic",
        "BornTimestamp" : 1570760999721,
        "StoreSize" : 406,
        "PropertyList" : {
          "MessageProperty" : [ {
            "Name" : "TAGS",
            "Value" : "TagA"
          } ]
        }
      } ]
    },
    "TaskId" : "0BC1310300002A9F000021E4D7A48346",
    "CurrentPage" : 1
  },
  "RequestId" : "5DC2A47E-2B31-4722-96C8-FA59C9*****"
}

Error codes

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

Operations in the Message Queue for Apache RocketMQ console

In addition to calling the OnsMessagePageQueryByTopic operation, you can query the details about a message in the Message Queue for Apache RocketMQ console. For more information, see Query messages.