Creates a trace query task based on a specified topic name and message key to obtain the ID of the query task.

Usage notes

If you have recorded the key of a message and need to query the delivery trace of the message based on the message ID, you can call this operation to create a query task. After the task ID is returned, you can call the OnsTraceGetResult operation to obtain the query results based on the task ID.

QPS limit

The queries-per-minute (QPM) limit on this operation is 30 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.

Operation

Action

Resource with a namespace

Resource without a namespace

OnsTraceQueryByMsgKey

mq:QueryTrace

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 OnsTraceQueryByMsgKey

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

BeginTime Long Yes 1570852800000

The timestamp that indicates the beginning of the time range to query. Unit: milliseconds.

EndTime Long Yes 1570968000000

The timestamp that indicates the end of the time range to query. Unit: milliseconds.

InstanceId String Yes MQ_INST_111111111111_DOxxxxxx

The ID of the Message Queue for Apache RocketMQ instance that corresponds to the message.

MsgKey String Yes ORDERID_100

The key of the messages that you want to query.

Topic String Yes test

The topic of the message that you want to query.

Response parameters

Parameter Type Example Description
QueryId String 272967562652883649157096685****

The ID of the query task. You can call the OnsTraceGetResult operation to query detailed results based on the task ID.

RequestId String F8654231-122A-4DBD-801F-38E35538****

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

Examples

Sample requests

http(s)://ons.cn-hangzhou.aliyuncs.com/?Action=OnsTraceQueryByMsgKey
&BeginTime=1570852800000
&EndTime=1570968000000
&InstanceId=MQ_INST_111111111111_DOxxxxxx
&MsgKey=ORDERID_100
&Topic=test
&<Common request parameters>

Sample success responses

XML format

<OnsTraceQueryByMsgKeyResponse>
  <RequestId>F8654231-122A-4DBD-801F-38E35538****</RequestId>
  <QueryId>272967562652883649157096685****</QueryId>
</OnsTraceQueryByMsgKeyResponse>

JSON format

{
	"RequestId": "F8654231-122A-4DBD-801F-38E35538****",
    "QueryId": "272967562652883649157096685****"
}

Error codes

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

Operations in the console

In addition to calling the OnsTraceQueryByMsgKey operation, you can create a trace query task in the Message Queue for Apache RocketMQ console. For more information, see Query messages.