企业官网建设流程全解析

ntfy 如何用 X-Delay 头发送定时消息并取消已调度的通知

【免费下载链接】ntfySend push notifications to your phone or desktop using PUT/POST项目地址: https://gitcode.com/GitHub_Trending/nt/ntfy

ntfy 是一个通过 PUT/POST 请求向手机或桌面发送推送通知的服务。这篇文章针对一个具体任务：发送一条不在当前时刻、而是在将来某个时间点才投递的消息（例如提醒），并在投递之前反悔时从服务端取消它。定时投递在文档中说明适用于 Android、Apple（iOS）和 Firefox（Web/PWA）客户端。

如何发送一条定时消息

ntfy 通过X-Delay头指定投递时间，它有几个别名：Delay、X-At、At、X-In、In，任意一个都可以使用。取值支持三种格式（见 docs/publish.md）：

• Unix 时间戳，例如1639194738；
• 时长，例如30m、3h、2 days；
• 自然语言时间，例如10am、8:30pm、tomorrow, 3pm、Tuesday, 7am。

延迟范围有明确边界：最小延迟 10 秒，最大延迟 3 天，服务端可用message-delay-limit选项调整（见 docs/config.md）。

要让定时消息之后可以被取消，需要在发布时使用自定义 sequence ID，即直接发布到/<topic>/<sequence_id>，sequence ID 体现在 URL 路径里。以 docs/publish.md 中的示例为准：主题mytopic、sequence IDbreak-reminder、消息 2 小时后投递：

# Schedule a reminder for 2 hours from now curl -H "In: 2h" -d "Take a break!" ntfy.sh/mytopic/break-reminder

文档同时给出了三种取值形式的示例：

curl -H "At: tomorrow, 10am" -d "Good morning" ntfy.sh/hello curl -H "In: 30min" -d "It's 30 minutes later now" ntfy.sh/reminder curl -H "Delay: 1639194738" -d "Unix timestamps are awesome" ntfy.sh/itsaunixsystem

如果使用 ntfy CLI，对应的写法是：

ntfy publish --at="tomorrow, 10am" hello "Good morning" ntfy publish --in="2h" mytopic/break-reminder "Take a break!"

注意 ntfy CLI 不支持 DELETE 操作，取消定时消息仍需用 curl（见下节）。

文档给出一张头部取值与投递时间的对照表（文档示例，前提为当天是 12/10/2021、上午 9 点、Eastern Time Zone）：

这张表是文档示例，用于说明投递时间的推算规则，不是固定输出。判断要点：自然语言时间在当天已过时会顺延到第二天，时长则相对当前时间计算。

如何取消一条已调度的消息

在定时消息投递之前，向/<topic>/<sequence_id>端点发送 DELETE 请求即可取消；也可以向/<topic>/<sequence_id>/delete发送 GET 请求。这会把定时消息从服务端移除，使其永远不会被投递，并向所有订阅者发出一个message_delete事件——订阅端收到该事件即可作为取消生效的信号。

接着上一节的示例：

# Changed your mind? Cancel the scheduled message via DELETE curl -X DELETE ntfy.sh/mytopic/break-reminder # Or cancel it via GET curl ntfy.sh/mytopic/break-reminder/delete

如果使用 JavaScript 或 Python，文档给出的取消写法如下：

// Schedule a reminder for 2 hours from now await fetch('https://ntfy.sh/mytopic/break-reminder', { method: 'POST', body: 'Take a break!', headers: { 'In': '2h' } }); // Changed your mind? Cancel the scheduled message await fetch('https://ntfy.sh/mytopic/break-reminder', { method: 'DELETE' });

# Schedule a reminder for 2 hours from now requests.post( "https://ntfy.sh/mytopic/break-reminder", data="Take a break!", headers={"In": "2h"} ) # Changed your mind? Cancel the scheduled message requests.delete("https://ntfy.sh/mytopic/break-reminder")

可选分支：投递前修改定时消息

在定时消息投递前，用同一个 sequence ID 发布一条新消息，可以更新或替换它：原定时消息会从服务端被删除并替换为新消息。这与"投递后更新通知"不同——后者两条消息都保留在缓存中。

文档给出的一个用例是看门狗（dead man's switch / watchdog）：先调度一条 5 分钟后投递的消息，然后脚本每分钟更新一次，不断把投递时间推后；一旦脚本停止运行，这条消息最终就会作为告警投递出来：

# Dead man's switch: keeps pushing a scheduled message into the future # If this script stops, the alert will be delivered after 5 minutes while true; do curl -H "In: 5m" -d "Warning: Server heartbeat stopped!" \ ntfy.sh/mytopic/heartbeat-check sleep 60 # Update every minute done

验证方式与限制

以下是 docs/publish.md 中与定时消息直接相关的验证方式和边界：

• 取消是否生效：订阅者会收到message_delete事件，说明定时消息已从服务端移除、不会被投递。
• 缓存行为：定时消息在投递后保留在消息缓存中 12 小时。例如一条 3 天后投递的消息，会缓存 3 天 12 小时；因此关闭服务端缓存（turning off server-side caching）与定时投递功能无法组合使用。
• 延迟范围：最小 10 秒、最大 3 天，可用message-delay-limit配置。
• 客户端支持：定时投递标注为 Android、Apple、Firefox 客户端支持。
• 主题安全：ntfy 无需注册，主题名本质上就是密码，应选择不易猜测的主题名。
• CLI 限制：ntfy CLI 不支持 DELETE，取消定时消息需改用 curl 或其他 HTTP 客户端。

【免费下载链接】ntfySend push notifications to your phone or desktop using PUT/POST项目地址: https://gitcode.com/GitHub_Trending/nt/ntfy