All Products
Search

This Product

    ApsaraMQ for RocketMQ:SDK reference overview

    Document Center

    ApsaraMQ for RocketMQ:SDK reference overview

    Last Updated:Oct 08, 2026

    ApsaraMQ for RocketMQ provides SDKs for the TCP and HTTP protocols across multiple programming languages. Choose an SDK based on your instance version, required features, and preferred protocol.

    Choose an SDK version

    The 5.x gRPC SDK is the recommended starting point. It supports all new features and receives ongoing optimizations. If the gRPC SDK does not cover a specific feature, fall back to the 5.x Remoting SDK.

    The following table compares all available SDK versions. ✅ = supported, ❌ = not supported.

    Feature

    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

    Compatible instances

    5.x series instances

    5.x and 4.x series instances

    5.x and 4.x series instances

    5.x and 4.x series instances

    4.x series instances

    4.x series instances

    When to use

    Recommended. Supports multiple languages. All new features and optimizations target this SDK.

    Fall back to the Remoting SDK if the 5.x gRPC SDK does not meet specific requirements.

    Use only if your services already run on these clients. 5.x instances are backward-compatible.

    Use only if your services already run on these clients. 5.x instances are backward-compatible.

    Legacy SDK. No new features. Only accesses 4.x instances.

    Legacy SDK. No new features. Only accesses 4.x instances.

    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

    ❌

    ❌

    ❌

    ❌

    Limitations

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

    • When performing a grayscale upgrade from a Remoting protocol SDK to a gRPC protocol SDK within the same consumer group:

      • Consumer groups that deliver ordered messages do not support this upgrade.

      • 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 a consumer group follows this sequence: starts with a Remoting protocol SDK, upgrades to a gRPC protocol SDK, and then rolls back 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 SDKs

    Important

    Use the Community Edition SDK only when migrating open source RocketMQ to the cloud without code changes. For all other cases, use the Enterprise Edition SDK provided by ApsaraMQ for RocketMQ. The Enterprise Edition SDK provides more features and higher stability.

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

    Java

    C/C++

    .NET

    HTTP protocol SDKs

    The HTTP protocol SDKs (Enterprise Edition) are recommended for multi-language support, covering additional programming languages not available through the TCP protocol.

    Enterprise Edition HTTP protocol SDKs

    Java

    PHP

    Go

    Python

    Node.js

    C#

    C++

    TCP vs. HTTP feature comparison

    TCP is the recommended protocol. It offers high transport performance, supports more messaging features, and provides richer observability, including message accumulation and consumer offset resetting. Use HTTP when TCP does not support your programming language or when lightweight access is enough.

    Feature

    TCP

    HTTP

    Normal messages

    ✅

    ✅

    Ordered messages

    ✅

    ✅

    Scheduled and delayed messages

    ✅

    ✅

    Transactional messages

    ✅

    ✅

    PushConsumer

    ✅

    ❌

    PullConsumer

    ✅

    ❌

    Batch consumption

    ✅

    ❌

    Broadcasting consumption

    ✅

    ❌

    Clustering consumption

    ✅

    ✅

    Message retry

    ✅

    ✅

    Query message traces

    ✅

    ✅

    Dead-letter queues

    ✅

    ✅

    Reset consumer offsets

    ✅

    ❌

    Usage notes

    • Match the endpoint type to the SDK protocol. A TCP SDK requires the TCP endpoint of the ApsaraMQ for RocketMQ instance; an HTTP SDK requires the HTTP endpoint.

    • Group IDs are protocol-specific and cannot be shared across protocols. Create a TCP group ID for TCP SDKs and an HTTP group ID for HTTP SDKs.

    • TCP and HTTP clients can exchange messages with each other. However, HTTP uses XML serialization, so message properties, content, tags, and keys must conform to XML specifications. Encode non-compliant messages with Base64.

      Note

      For XML specifications, see XML syntax. To validate XML, use a third-party tool such as xml_validator.

    • Public and private endpoints are available in all regions for both TCP and HTTP. For production workloads, access ApsaraMQ for RocketMQ through a virtual private cloud (VPC). For cross-region access, on-premises access, or Internet access when Cloud Enterprise Network (CEN) is unavailable, use a public endpoint. Public endpoint traffic incurs outbound Internet traffic charges. For more information, see Internet traffic pricing details.