Querying Messages

Function

Kafka instances support two message query modes. The query scope and result are as follows:

By creation time: If the creation time range of a message is known, use this mode. The message list and offset except the content are returned.
By offset: If the partition and offset of the topic in which the message belongs are known, use this mode. The message list and complete content are returned.

Calling Method

For details, see Calling APIs.

URI

GET /v2/{project_id}/instances/{instance_id}/messages

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Definition: Project ID. For details, see Obtaining a Project ID. Constraints: N/A Range: N/A Default Value: N/A
instance_id	Yes	String	Definition: Instance ID. You can call the API for querying all instances to obtain the instance ID. The instance ID is in the response body. Constraints: N/A Range: N/A Default Value: N/A

**Table 2** Query Parameters
Parameter	Mandatory	Type	Description
topic	Yes	String	Definition: Topic name. Constraints: A topic name must start with a letter and can only contain letters, hyphens (-), underscores (_), and digits. Range: N/A Default Value: N/A
asc	No	Boolean	Definition: Whether to sort messages by time. Constraints: N/A Range: true: Yes false: No Default Value: N/A
start_time	No	String	Definition Start time. The value is a Unix timestamp, in millisecond. Constraints Mandatory for query by creation time. Range N/A Default Value N/A
end_time	No	String	Definition End time. The value is a Unix timestamp, in millisecond. Constraints Mandatory for query by creation time. Range N/A Default Value N/A
limit	No	String	Definition: Number of messages displayed on each page. Constraints: N/A Range: N/A Default Value: N/A
offset	No	String	Definition: Page number. Constraints: N/A Range: N/A Default Value: N/A
download	No	Boolean	Definition: Whether to download messages to the local. Constraints: N/A Range: true: Yes false: No Default Value: N/A
message_offset	No	String	Definition Message offset. Constraints Mandatory for query by offset. If start_time and end_time are not empty, this parameter is invalid. Range N/A Default Value N/A
partition	No	String	Definition Partition. Constraints Mandatory for query by offset. If start_time and end_time are not empty, this parameter is invalid. Range N/A Default Value N/A
keyword	No	String	Definition: Keyword for querying messages. Constraints: N/A Range: 0 to 50 characters. Default Value: N/A
key	No	String	Definition Setting a message key and all messages containing it are queried. Constraints A maximum of 10,000 messages within 200 MB can be queried. The top 10 messages can be returned. Range N/A Default Value N/A
include	No	String	Definition Setting a keyword included in the message body. All messages including the keyword are queried. Constraints Multiple keywords are separated by commas (,). The commas (,) are URL-encoded as %2C. Range The total number of included and excluded keywords cannot exceed 20. Default Value N/A
exclude	No	String	Definition Setting a keyword excluded in the message body. All messages excluding the keyword are queried. Constraints Multiple keywords are separated by commas (,). The commas (,) are URL-encoded as %2C. Range The total number of included and excluded keywords cannot exceed 20. Default Value N/A

Request Parameters

None

Response Parameters

Status code: 200

**Table 3** Response body parameters
Parameter	Type	Description
messages	Array of MessagesEntity objects	Definition: Message list.
total	Long	Definition: Total number of messages. Range: N/A
size	Long	Definition: Number of records on each page. Range: N/A

**Table 4** MessagesEntity
Parameter	Type	Description
topic	String	Definition: Topic name. Range: N/A
partition	Integer	Definition: Partition where the message is located. Range: N/A
key	String	Definition: Message key. Range: N/A
value	String	Definition: Message content. Range: N/A
size	Integer	Definition: Message size. Range: N/A
timestamp	Long	Definition: Message production time. The value is a Unix timestamp. The unit is millisecond. Range: N/A
huge_message	Boolean	Definition: Big data flag. Range: N/A
message_offset	Long	Definition: Message offset. Range: N/A
message_id	String	Definition: Message ID. Range: N/A
app_id	String	Definition: Application ID. Range: N/A
tag	String	Definition: Message tag. Range: N/A

Status code: 400

**Table 5** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error description.

Status code: 403

**Table 6** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error description.

Example Requests

Querying the message offset.

GET https://{endpoint}/v2/{project_id}/instances/{instance_id}/messages?asc=false&end_time=1608609032042&limit=10&offset=0&start_time=1608608432042&topic=topic-test

Querying the message content.

GET https://{endpoint}/v2/{project_id}/instances/{instance_id}/messages?download=false&message_offset=0&partition=0&topic=topic-test

Example Responses

Status code: 200

The query is successful.

{
  "messages" : [ {
    "topic" : "topic-test",
    "partition" : 0,
    "value" : "hello world",
    "size" : 21,
    "timestamp" : 1607598463502,
    "huge_message" : false,
    "message_offset" : 4,
    "message_id" : "",
    "app_id" : "",
    "tag" : ""
  } ],
  "total" : 1,
  "size" : 1
}