Mensagens agendadas são entregues aos consumidores em um horário específico, em vez de imediatamente. Use-as para criar gatilhos baseados em tempo em aplicações distribuídas, como cancelamento de pedidos por timeout, notificações adiadas ou agendamento periódico de tarefas.
Mensagens agendadas e mensagens atrasadas funcionam da mesma forma: o broker retém ambas e as entrega no timestamp especificado. O termo "mensagens agendadas" a seguir abrange os dois tipos.
Antes de começar
Antes de enviar mensagens agendadas, verifique se:
O tópico tem o MessageType definido como
Delay. Mensagens agendadas só podem ser enviadas para tópicos do tipo Delay.O timestamp de entrega é posterior ao horário atual. Se o timestamp estiver no passado ou exceder o intervalo permitido, o broker entrega a mensagem imediatamente.
-
O timestamp de entrega está dentro da janela máxima de agendamento para o tipo da sua instância:
Tipo de instância
Janela máxima de agendamento
Standard Edition (assinatura, pagamento conforme o uso ou serverless) e Professional Edition serverless
7 dias
Professional Edition e Enterprise Platinum Edition (assinatura ou pagamento conforme o uso)
40 dias
Casos de uso
Agendamento de tarefas distribuídas
Agende mensagens com diferentes granularidades de tempo para substituir temporizadores tradicionais baseados em banco de dados. Por exemplo, acione uma tarefa diária de limpeza de arquivos em um horário fixo ou envie uma notificação de lembrete a cada 2 minutos. As mensagens agendadas eliminam a complexidade de gerenciar cron jobs distribuídos e oferecem maior escalabilidade.

Tratamento de timeout de tarefas
Adie uma ação até que um prazo expire. No comércio eletrônico, por exemplo, cancele um pedido não pago 30 minutos após a criação, em vez de consultar o banco de dados repetidamente para verificar o status do pagamento.

Em comparação com a consulta frequente ao banco de dados para buscar registros expirados, as mensagens agendadas oferecem:
Granularidade de tempo flexível: acione tarefas em qualquer intervalo, sem incrementos de tempo fixos e sem necessidade de lógica de deduplicação.
Maior desempenho: evite gargalos causados por varreduras frequentes no banco de dados. A infraestrutura de mensageria gerencia a concorrência e escala horizontalmente.
Como funciona o agendamento
Timestamp de entrega
O horário de entrega é expresso como um timestamp Unix em milissegundos. Defina-o na mensagem com setDeliveryTimestamp(). O broker retém a mensagem até que esse timestamp seja atingido.
Para mensagens agendadas, calcule o horário absoluto de entrega: se o horário atual for
2022-06-09 17:30:00e você desejar a entrega às19:20:00, defina o timestamp como1654773600000.Para mensagens atrasadas, adicione um deslocamento relativo ao horário atual: se o horário atual for
2022-06-09 17:30:00e você desejar a entrega após 1 hora, defina o timestamp como1654770600000.
Não é possível alterar ou cancelar o timestamp de entrega após o envio da mensagem.
Ciclo de vida da mensagem
Uma mensagem agendada passa por seis estágios, desde a produção até a exclusão:

|
Estágio |
O que acontece |
|
Inicialização |
O produtor constrói a mensagem e a envia ao broker. |
|
Agendada |
O broker armazena a mensagem em um sistema de armazenamento baseado em tempo. Nenhum índice visível para o consumidor é criado neste momento. |
|
Pronta para consumo |
No timestamp de entrega, a mensagem é movida para o mecanismo de armazenamento regular e torna-se visível para os consumidores. |
|
Em consumo |
Um consumidor recebe e processa a mensagem. Se nenhum reconhecimento chegar dentro do timeout, o broker tenta entregar novamente. Para mais informações, consulte Tentativa de consumo. |
|
Confirmada |
O consumidor reconhece a mensagem. O broker a marca como consumida, mas não a exclui imediatamente. |
|
Excluída |
O broker exclui a mensagem de forma rotativa quando o período de retenção expira ou o espaço de armazenamento fica escasso. Até a exclusão, a mensagem pode ser reconsumida. Para mais informações, consulte Armazenamento e limpeza de mensagens. |
Limites
|
Restrição |
Detalhe |
|
Tipo de tópico |
Apenas tópicos com MessageType definido como |
|
Precisão de tempo |
Precisão de milissegundos. A granularidade padrão é de 1.000 ms. |
|
Persistência |
Mensagens agendadas sobrevivem a reinicializações do broker. No entanto, exceções ou reinicializações do sistema de armazenamento podem causar breves atrasos na entrega. |
|
Cancelamento |
Não suportado. Após o envio, não é possível alterar ou revogar o timestamp de entrega. |
Enviar e consumir mensagens agendadas
Os exemplos abaixo usam o SDK Java do Apache RocketMQ 5.x. Cada exemplo de produtor define um timestamp de entrega com setDeliveryTimestamp(); essa é a única diferença em relação ao envio de uma mensagem normal. Para a referência completa do SDK, consulte SDKs do Apache RocketMQ 5.x.
Certifique-se de que seu tópico foi criado com MessageType definido como Delay antes de executar estes exemplos.
Melhores práticas
Distribua os horários de entrega. Evite agendar um grande lote de mensagens para exatamente o mesmo timestamp. Quando muitas mensagens compartilham o mesmo horário de entrega, o broker precisa processar todas simultaneamente, o que aumenta a carga e pode atrasar a entrega. Sempre que possível, espalhe os timestamps por um intervalo de tempo.
Implemente lógica de cancelamento nos consumidores. Como não é possível revogar ou reagendar uma mensagem após o envio, trate o cancelamento no lado do consumidor. Por exemplo, ao receber uma mensagem de "cancelar pedido não pago", verifique primeiro o status atual do pedido; se o usuário já tiver pago, ignore o cancelamento.
Perguntas frequentes
Posso cancelar ou reagendar uma mensagem após o envio?
Não. O timestamp de entrega é definitivo após o envio da mensagem. Para lidar com cenários em que uma ação agendada se torna desnecessária, implemente essa lógica no consumidor. Por exemplo, verifique o status atual do pedido antes de cancelar um pedido não pago.
O que acontece se eu definir um horário de entrega no passado?
O broker a entrega imediatamente, assim como uma mensagem normal.
Por que não consigo encontrar minha mensagem agendada no console?
Mensagens agendadas permanecem invisíveis até que o timestamp de entrega seja atingido. Verifique novamente após esse horário; a mensagem aparecerá e estará disponível para os consumidores.