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.

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
}