Você quer que seu bot do Discord envie um lembrete diário, execute um comando de limpeza a cada hora ou publique uma mensagem de boas-vindas em um horário específico. Sem um agendador, você precisaria manter o bot em execução constante e verificar a hora manualmente em um loop. APScheduler é uma biblioteca Python que permite agendar tarefas para executar em intervalos fixos, horários específicos ou após um atraso. Este artigo explica como integrar o APScheduler a um bot do Discord usando a biblioteca discord.py e mostra como criar, gerenciar e remover tarefas agendadas.
Principais Conclusões: Agendamento de Tarefas do Bot com APScheduler
- AsyncIOScheduler: O único agendador que funciona com código assíncrono do discord.py sem travar o bot.
- add_job() com tipos de gatilho: Use IntervalTrigger para tarefas recorrentes e CronTrigger para datas ou horários específicos.
- scheduler.start() antes de bot.run(): Sempre inicie o agendador antes do bot para evitar problemas de temporização.
O que o APScheduler Faz por um Bot do Discord
APScheduler, abreviação de Advanced Python Scheduler, é uma biblioteca de agendamento de tarefas. Ela executa funções Python em horários predeterminados sem precisar de agendadores externos como cron ou do sistema. Para um bot do Discord, o APScheduler lida com tarefas que devem ocorrer automaticamente: enviar anúncios, verificar APIs, limpar bancos de dados ou silenciar usuários após um tempo limite.
A biblioteca suporta quatro tipos de agendadores: BlockingScheduler, BackgroundScheduler, AsyncIOScheduler e GeventScheduler. Para bots do Discord construídos com discord.py, você deve usar AsyncIOScheduler. Este agendador se integra ao loop de eventos asyncio do Python, que o discord.py utiliza. Usar um agendador bloqueante congelaria o bot.
Antes de escrever código, instale o APScheduler e o discord.py. Use pip:
pip install apscheduler discord.py
Passos para Agendar Tarefas em um Bot do Discord com APScheduler
Os passos a seguir mostram como adicionar uma tarefa agendada que envia uma mensagem para um canal específico a cada 10 segundos. Você pode adaptar o gatilho e a função para suas próprias necessidades.
- Importe os módulos necessários
No script do seu bot, importe AsyncIOScheduler e os tipos de gatilho que você precisa. Também importe discord e commands de discord.ext.from apscheduler.schedulers.asyncio import AsyncIOScheduler
from apscheduler.triggers.interval import IntervalTrigger
from apscheduler.triggers.cron import CronTrigger
import discord
from discord.ext import commands - Crie a instância do agendador
Crie um objeto AsyncIOScheduler. Coloque-o após a inicialização do cliente do bot, mas antes de o bot ser executado.bot = commands.Bot(command_prefix='!', intents=discord.Intents.all())
scheduler = AsyncIOScheduler() - Defina a função da tarefa
Escreva uma função assíncrona que contenha o trabalho que você deseja agendar. A função deve ser async para funcionar com o loop de eventos. Ela pode receber argumentos como um ID de canal ou uma instância do bot.async def send_reminder(channel_id):
channel = bot.get_channel(channel_id)
if channel:
await channel.send("Este é um lembrete automático.") - Adicione a tarefa ao agendador
Use o método add_job. Forneça o nome da função, um objeto de gatilho e quaisquer argumentos. Faça isso dentro de um evento do bot como on_ready para garantir que o bot esteja conectado.@bot.event
async def on_ready():
scheduler.add_job(
send_reminder,
IntervalTrigger(seconds=10),
args=[123456789012345678], # Substitua pelo ID do seu canal
id="reminder_job"
)
print(f'{bot.user} conectou e o agendador está pronto.') - Inicie o agendador antes do bot
Chame scheduler.start() antes de bot.run(). Isso garante que o agendador comece a funcionar imediatamente.scheduler.start()
bot.run('SEU_TOKEN_DO_BOT')
O parâmetro job ID é opcional. Atribuir um ID permite modificar ou remover a tarefa posteriormente. Se você não fornecer um ID, o APScheduler gera um automaticamente.
Usando Diferentes Tipos de Gatilho
O APScheduler oferece vários tipos de gatilho. Os dois mais comuns para bots do Discord são IntervalTrigger e CronTrigger.
IntervalTrigger: Executa a tarefa em um intervalo fixo. Você pode especificar semanas, dias, horas, minutos, segundos e uma data de início.IntervalTrigger(hours=1, minutes=30) executa a cada 90 minutos.
CronTrigger: Executa a tarefa em horários específicos do calendário. Use campos semelhantes ao cron do Linux: year, month, day, week, day_of_week, hour, minute, second.CronTrigger(hour=9, minute=0, day_of_week='mon-fri') executa às 9h de segunda a sexta.
Para tarefas atrasadas de uma única vez, use DateTrigger com uma data de execução específica.
Erros Comuns e Limitações
O Bot Congela ao Usar o Tipo Errado de Agendador
Usar BlockingScheduler ou BackgroundScheduler com discord.py impede o bot de responder a comandos. Sempre use AsyncIOScheduler.
A Função da Tarefa Executa mas Não Envia Mensagens
A função da tarefa deve ser async e deve usar await para qualquer chamada à API do Discord. Se a função for um def comum em vez de async def, o agendador a executa, mas o bot não consegue enviar mensagens porque a corrotina nunca é aguardada. Mude a função para async def e use await.
A Tarefa Não Inicia Após Reconexão do Bot
Se o bot perder a conexão e reconectar, o agendador continua executando de forma independente. No entanto, se você parar o bot e reiniciá-lo, o agendador é redefinido. Para persistir tarefas entre reinicializações, armazene as configurações das tarefas em um banco de dados ou arquivo JSON e as readicione no on_ready.
Diferença de Fuso Horário
O APScheduler usa UTC por padrão. Se você agendar uma tarefa para um horário local, converta para UTC ou defina o fuso horário do agendador. Passe um argumento timezone ao criar o agendador:scheduler = AsyncIOScheduler(timezone='America/Sao_Paulo')
Tipos de Tarefa do APScheduler: Agendada vs Imediata vs Atrasada
| Característica | Agendada (CronTrigger) | Imediata (add_job sem gatilho) |
|---|---|---|
| Momento de execução | Data/hora específica ou padrão recorrente | Executa assim que o agendador inicia |
| Caso de uso | Relatórios diários, verificações por hora, limpeza semanal | Tarefas únicas de inicialização, como enviar uma mensagem de boot |
| Gatilho necessário | Sim, CronTrigger ou IntervalTrigger | Nenhum gatilho necessário, executa uma vez e se remove |
Agora você sabe como agendar tarefas em um bot do Discord usando APScheduler. Comece instalando a biblioteca e adicionando um AsyncIOScheduler ao seu bot. Defina suas funções de tarefa assíncronas e as associe com add_job usando IntervalTrigger ou CronTrigger. Para uso avançado, armazene as definições das tarefas em um banco de dados para que sobrevivam a reinicializações do bot. Experimente agendar uma mensagem diária que chame uma API externa para manter seu servidor informado.