ApsaraMQ for RocketMQ:Send and receive scheduled messages

Casos de uso

• Tratamento de timeout de pedidos: Envie uma mensagem agendada com o prazo limite de pagamento quando um usuário fizer um pedido. Caso o pedido continue sem pagamento no momento da entrega da mensagem, cancele-o automaticamente.

• Acionamento de tarefas periódicas: Agende operações como limpeza diária de arquivos ou sincronização periódica de dados enviando mensagens com horários de entrega futuros.

Funcionamento das mensagens agendadas

1. O produtor define um timestamp de entrega futuro na mensagem chamando msg.setStartDeliverTime(timestamp).

2. O broker retém a mensagem até o timestamp especificado.

3. No horário agendado, o broker entrega a mensagem aos consumidores inscritos.

Regras para definição de tempo:

Pré-requisitos

Antes de começar, verifique se você possui:

• O SDK para Java instalado. Consulte Preparar o ambiente

• Uma instância, um tópico e um grupo de consumidores do ApsaraMQ for RocketMQ criados no console do ApsaraMQ for RocketMQ

• Um par de AccessKey para sua conta Alibaba Cloud

• (Opcional) Configurações de log definidas

Enviar uma mensagem agendada

O exemplo abaixo envia uma mensagem com um timestamp de entrega futuro. O método msg.setStartDeliverTime(timestamp) informa ao broker quando entregar a mensagem.

Substitua os placeholders pelos valores reais:

import com.aliyun.openservices.ons.api.Message;
import com.aliyun.openservices.ons.api.ONSFactory;
import com.aliyun.openservices.ons.api.Producer;
import com.aliyun.openservices.ons.api.PropertyKeyConst;
import com.aliyun.openservices.ons.api.SendResult;
import java.text.SimpleDateFormat;
import java.util.Properties;

public class ProducerDelayTest {
    public static void main(String[] args) {
        Properties properties = new Properties();
        // Load AccessKey pair from environment variables
        properties.put(PropertyKeyConst.AccessKey, System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"));
        properties.put(PropertyKeyConst.SecretKey, System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        // TCP endpoint from the Instance Details page in the ApsaraMQ for RocketMQ console
        properties.put(PropertyKeyConst.NAMESRV_ADDR, "<your-tcp-endpoint>");

        Producer producer = ONSFactory.createProducer(properties);
        // Call start() once before sending any messages
        producer.start();

        Message msg = new Message(
                "<your-topic>",            // Topic
                "<your-tag>",              // Tag for consumer-side filtering
                "<your-message-body>".getBytes()  // Message body in bytes
        );

        // Optional: set a business key for message tracing in the console
        msg.setKey("<your-message-key>");

        try {
            // Set the delivery timestamp (milliseconds since epoch)
            // Example: deliver at 2026-03-15 10:30:00
            long deliverTime = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss")
                    .parse("2026-03-15 10:30:00")
                    .getTime();
            msg.setStartDeliverTime(deliverTime);

            SendResult sendResult = producer.send(msg);
            System.out.println("Message Id:" + sendResult.getMessageId());
        } catch (Exception e) {
            // Handle send failure: retry or persist the message
            System.out.println("Send failed. Topic: " + msg.getTopic());
            e.printStackTrace();
        }

        // Shut down the producer when the application exits.
        // To send messages frequently, keep the producer running instead of
        // shutting it down after each send.
        producer.shutdown();
    }
}

Pontos importantes:

• O método setStartDeliverTime(long timestamp) aceita um timestamp Unix em nível de milissegundos. O broker retém a mensagem até esse momento.

• Chame producer.start() apenas uma vez antes do envio. Em cenários de alto throughput, reutilize a mesma instância do produtor em vez de crie uma nova para cada mensagem.

• O uso de msg.setKey() é opcional, mas recomendado para rastrear mensagens por ID de negócio no console do ApsaraMQ for RocketMQ.

Para mais exemplos, consulte a biblioteca de códigos do ApsaraMQ for RocketMQ.

Inscrever-se em mensagens agendadas

A inscrição em mensagens agendadas segue o mesmo processo das mensagens normais. Nenhuma lógica especial de inscrição é necessária — o broker entrega a mensagem aos consumidores quando o timestamp agendado é atingido.

Para o código de inscrição, consulte Inscrever-se em mensagens.

Melhores práticas

• Defina chaves de mensagem únicas. Sempre que possível, a chave da mensagem (setKey) deve ser globalmente única. Utilize-a para localizar mensagens no console do ApsaraMQ for RocketMQ caso ocorram problemas de entrega.

• Reutilize a instância do produtor. Chame producer.shutdown() somente ao encerrar a aplicação. Criar e destruir produtores repetidamente desperdiça memória.

Tópicos relacionados

• Mensagens agendadas e mensagens atrasadas — Mecanismo de agendamento e restrições

• Inscrever-se em mensagens — Configurar consumo de mensagens

• Biblioteca de códigos do ApsaraMQ for RocketMQ — Mais exemplos do SDK para Java

• Projeto de demonstração — Projeto funcional completo