All Products
Search

This Product

    ApsaraMQ for RocketMQ:SDK reference overview

    Document Center

    ApsaraMQ for RocketMQ:SDK reference overview

    Last Updated:Sep 24, 2025

    ApsaraMQ for RocketMQ provides multi-language software development kits (SDKs) for the TCP and HTTP protocols. This topic describes the differences between the SDKs and explains how to use them.

    SDK versions

    The following table describes the features supported by different versions of ApsaraMQ for RocketMQ SDKs.

    In the following table, ✅ indicates that the feature is supported, and ❌ indicates that the feature is not supported.

    Item

    RocketMQ 5.x gRPC SDK

    RocketMQ 5.x Remoting SDK

    RocketMQ 4.x/3.x SDK

    RocketMQ ONS TCP 1.x SDK

    RocketMQ ONS TCP 2.x SDK

    RocketMQ ONS HTTP SDK

    Protocol

    gRPC protocol v2

    Remoting protocol

    Remoting protocol

    Remoting protocol

    gRPC protocol v1

    HTTP protocol

    Accessible instances

    5.x series instances

    • 5.x series instances

    • 4.x series instances

    • 5.x series instances

    • 4.x series instances

    • 5.x series instances

    • 4.x series instances

    4.x series instances

    4.x series instances

    Recommendations

    Use the 5.x gRPC SDK.

    • It provides comprehensive support for multiple languages.

    • All new features and optimizations will be supported on the 5.x gRPC SDK.

    • If some features of the 5.x gRPC SDK do not meet your requirements, you can use the 5.x Remoting SDK.

    • If your services already use clients of these versions, you can continue to use them.

    • 5.x series instances are compatible with these SDK versions.

    • Do not use clients of these versions. These SDK versions do not support new features and optimizations.

    • You can only access 4.x series instances.

    Sending normal, ordered, transactional, and scheduled messages

    ✅

    ✅

    ✅

    ✅

    ✅

    ✅

    Concurrent consumption

    ✅

    ✅

    ✅

    ✅

    ✅

    ✅

    Ordered consumption

    ✅

    ✅

    ✅

    ✅

    ✅

    ✅

    Consumption concurrency optimization for ordered consumption

    ✅

    ❌

    ❌

    ❌

    ❌

    ❌

    Broadcasting consumption

    ❌

    ✅

    ✅

    ✅

    ❌

    ❌

    Stream consumption (connecting to services such as Flink)

    ❌

    ✅

    ✅

    ❌

    ❌

    ❌

    Message trace

    ✅

    ✅

    Supported in versions 4.5.2 and later

    ✅

    ✅

    ❌

    Producer and consumer client metrics

    ✅

    ❌

    ❌

    ❌

    ❌

    ❌

    Graceful shutdown

    ✅

    Supported only for 5.x series instances

    ❌

    ❌

    ❌

    ❌

    SDK limits

    • All consumers in the same consumer group must use clients that support the same protocol.

    • When you perform a grayscale upgrade from a Remoting protocol SDK to a gRPC protocol SDK for the same consumer group, note the following:

      • Upgrades are not supported for consumer groups that deliver ordered messages.

      • Consumer groups that deliver messages concurrently support smooth upgrades. A small number of messages may be duplicated during the upgrade.

    • The consumer offset for ordered messages may be rolled back if you perform the following steps for a consumer group that delivers ordered messages:

      1. The consumer group for ordered messages initially uses a Remoting protocol SDK.

      2. You then upgrade the SDK to a gRPC protocol SDK.

      3. You roll back the SDK to the Remoting protocol SDK.

    • The RocketMQ ONS TCP 2.x SDK is available only in some regions. For more information, see Limits.

    TCP protocol

    Important

    Use the Community Edition SDK only when you migrate open source RocketMQ to the cloud and do not want to modify your code. For all other scenarios, use the Enterprise Edition SDK provided by ApsaraMQ for RocketMQ. Compared with the Community Edition SDK, the Enterprise Edition SDK provides more features and ensures higher stability.

    Enterprise Edition TCP protocol SDKs (ONS 1.x/2.x SDKs)

    Java SDK

    C/C++ SDK

    .NET SDK

    HTTP protocol

    Enterprise Edition HTTP protocol SDKs (recommended for multi-language support)

    Java SDK

    PHP SDK

    Go SDK

    Python SDK

    Node.js SDK

    C# SDK

    C++ SDK

    Comparison between TCP and HTTP protocol SDKs

    TCP and HTTP protocol SDKs support different features. Evaluate which protocol type best suits your requirements.

    SDK protocol type

    TCP protocol SDK

    HTTP protocol SDK

    Recommendation

    Recommended choice

    • Provides high transport performance and is suitable for high-concurrency scenarios.

    • Provides more complete message features and supports fast iteration.

    • Provides more observability metrics and more complete features such as message accumulation and consumer offset resetting.

    Alternative choice

    • A supplement for multi-language access. You can choose the HTTP protocol if the TCP protocol does not support a specific language.

    • Provides lightweight access with fewer feature concepts and is suitable for simple scenarios.

    Normal messages

    Supported

    Supported

    Ordered messages

    Supported

    Supported

    Scheduled and delayed messages

    Supported

    Supported

    Transactional messages

    Supported

    Supported

    PushConsumer

    Supported

    Not supported

    PullConsumer

    Supported

    Not supported

    Batch consumption

    Supported

    Not supported

    Broadcasting consumption

    Supported

    Not supported

    Clustering consumption

    Supported

    Supported

    Message retry

    Supported

    Supported

    Query message traces

    Supported

    Supported

    Dead-letter queues

    Supported

    Supported

    Reset consumer offsets

    Supported

    Unsupported

    SDK usage notes

    • Each type of endpoint can be used only by clients of the same protocol type. For example, if you want to use a TCP client SDK to send and receive messages, you must use the TCP endpoint of your ApsaraMQ for RocketMQ instance to access the ApsaraMQ for RocketMQ broker.

    • ApsaraMQ for RocketMQ supports group IDs for the HTTP and TCP protocols. Group IDs for different protocols cannot be used interchangeably. For example, if you use a TCP protocol SDK to send and receive messages, you must create a TCP protocol group ID.

    • Clients that use the TCP protocol and clients that use the HTTP protocol can send messages to and receive messages from each other. However, the HTTP protocol uses XML to serialize messages. Therefore, message properties, content, tags, and keys must comply with XML specifications. Otherwise, messages may fail to be sent or consumed.

      You can use Base64 to encode and decode messages that do not comply with XML specifications.

      Note

      For more information about XML specifications, see XML syntax. You can also use a third-party tool, such as xml_validator, to check whether the XML syntax is valid.

    • Public and private endpoints for TCP and HTTP clients are provided in all regions. In production environments, we recommend that you access ApsaraMQ for RocketMQ in virtual private clouds (VPCs). If you want to access ApsaraMQ for RocketMQ across regions, from on-premises data centers, or over the Internet while Cloud Enterprise Network (CEN) is unavailable, you can use public endpoints to access ApsaraMQ for RocketMQ instances. If you use public endpoints to access ApsaraMQ for RocketMQ instances, you are charged for outbound Internet traffic. For more information, see Billing of Internet traffic.