tencent cloud

PrevNext

文档反馈

请输入关键字

Recent Pages

文档
文档

ReceiveMessage

最后更新时间：2023-08-09 14:43:29

1. API Description

Domain name for API request: tdmq.tencentcloudapi.com.

Currently, the ReceiveMessage API only supports partitioned topics. It is used to receive messages sent to a specified partitioned topic. If it is called when there are no messages in the partitioned topic, the ReceiveTimeout exception will be reported.

Instructions on how to use BatchReceivePolicy:

BatchReceive has three parameters:

● MaxNumMessages: The maximum number of messages returned by Receive when BatchReceive is used.
● MaxNumBytes: The maximum size (in bytes) of the message returned by Receive when BatchReceive is used.
● Timeout: The maximum timeout period (in milliseconds) of calling Receive when BatchReceive is used.

By default, if you don’t specify any of the three parameters, the BatchReceive feature is disabled; if one of the three parameter values is above zero, BatchReceive is enabled. BatchReceive will be disabled when any of the three parameter values reaches the threshold you specify.

Note: The values of both MaxNumMessages and MaxNumBytes are subject to the value of ReceiveQueueSize. If the values of ReceiveQueueSize and MaxNumMessages are 5 and 10, respectively, you can receive up to five rather than 10 messages when BatchReceive is used.

The API configured with BatchReceivePolicy returns multiple messages at a time.

  1. These messages are separated by “###”. After receiving them, you can separate them with split tools in different languages.
  2. MessageIDs are separated by “###”. After receiving the messages, you can separate the MessageIDs with split tools in different languages, so that you can obtain the MessageID field information required for calling the AcknowledgeMessage API.

A maximum of 1000 requests can be initiated per second for this API.

We recommend you to use API Explorer
Try it
API Explorer provides a range of capabilities, including online call, signature authentication, SDK code generation, and API quick search. It enables you to view the request, response, and auto-generated examples.

2. Input Parameters

The following request parameter list only provides API request parameters and some common parameters. For the complete common parameter list, see Common Request Parameters.

Parameter Name Required Type Description
Action Yes String Common Params. The value used for this API: ReceiveMessage.
Version Yes String Common Params. The value used for this API: 2020-02-17.
Region No String Common Params. This parameter is not required for this API.
Topic Yes String Name of the topic which receives the message. It is better to be the full path of the topic, such as tenant/namespace/topic. If it is not specified, public/default will be used by default.
SubscriptionName Yes String Subscriber name
ReceiverQueueSize No Integer Default value: 1000. Messages received by the consumer will first be stored in the receiverQueueSize queue to tune the message receiving rate.
SubInitialPosition No String A parameter used to determine the position where the consumer initially receives messages. Valid values: Earliest (default), Latest.
MaxNumMessages No Integer This parameter is used to specify the maximum number of received messages in a batch for BatchReceivePolicy. The default value is 0, indicating that BatchReceivePolicy is disabled.
MaxNumBytes No Integer This parameter is used to specify the maximum body size (in bytes) of received messages in a batch for BatchReceivePolicy. The default value is 0, indicating that BatchReceivePolicy is disabled.
Timeout No Integer This parameter is used to specify the maximum wait timeout (in milliseconds) for receiving a batch of messages for BatchReceivePolicy. The default value is 0, indicating that BatchReceivePolicy is disabled.

3. Output Parameters

Parameter Name Type Description
MessageID String Unique primary key used to identify the message
MessagePayload String Content of the received message
AckTopic String Provided to the Ack API and used to acknowledge messages in the topic
ErrorMsg String Returned error message. If it is an empty string, no error occurred.
Note: this field may return null, indicating that no valid values can be obtained.
SubName String Returned subscriber name, which will be used when an acknowledgment consumer is created.
Note: this field may return null, indicating that no valid values can be obtained.
MessageIDList String MessageIDs returned by BatchReceivePolicy at a time, which are separated by “###”.
Note: This field may return null, indicating that no valid values can be obtained.
MessagesPayload String Message contents returned by BatchReceivePolicy at a time, which are separated by “###”.
Note: This field may return null, indicating that no valid values can be obtained.
RequestId String The unique request ID, which is returned for each request. RequestId is required for locating a problem.

4. Example

Example1 Receiving messages

Input Example

POST / HTTP/1.1
Host: tdmq.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: ReceiveMessage
<Common request parameters>

{
    "Topic": "tenant/namespace/topic",
    "SubscriptionName": "\"test-sub\""
}

Output Example

{
    "Response": {
        "RequestId": "36713f94-d07d-4b96-babf-42d139276f23",
        "MessageID": "71:12:0:0",
        "MessageIDList": "",
        "MessagesPayload": "",
        "MessagePayload": "hello TDMQ",
        "SubName": "xx",
        "AckTopic": "persistent://tenant/namespace/topic",
        "ErrorMsg": "xx"
    }
}

5. Developer Resources

SDK

TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call APIs.

Command Line Interface

6. Error Code

The following only lists the error codes related to the API business logic. For other error codes, see Common Error Codes.

Error Code Description
FailedOperation.CreateProducerError An error occurred while creating the producer.
FailedOperation.CreatePulsarClientError An error occurred while creating the TDMQ client.
FailedOperation.MaxMessageSizeError The message size exceeds the upper limit of 1 MB.
FailedOperation.MessageIDError The uploaded msgID is incorrect.
FailedOperation.ReceiveError An error occurred while receiving the message.
FailedOperation.ReceiveTimeout Message receiving timed out. Please try again.
FailedOperation.SendMessageTimeoutError Message sending timed out.
FailedOperation.TopicTypeError Please use a partition topic.
InvalidParameter.TenantNotFound The uploaded tenant name is incorrect.
InvalidParameter.TokenNotFound The correct token was not obtained.
InvalidParameterValue.TopicNotFound The uploaded topic name is incorrect.
Copyright © 2013-2024 Tencent Cloud. All Rights Reserved.
隐私条款服务条款缓存条款