能否根据 UptimeScout incidents 的响应,立即宣布某项服务发生故障?不能:该端点列出近期出现异常信号的服务,而规范明确指出,这些并非服务提供商确认的事件。实际结果是一个供进一步核查的简短信号列表,而不是对故障原因的定论。

对值班工程师和分析师来说,这一区别很重要:自动告警可以提示“检查 Y 地区的 X 服务”,但事实确认和原因解释仍应以服务提供商的官方状态或自行诊断为准。UptimeScout 规范记录了用于信号、当前状态和观测历史的不同路由。
信号列表具体返回什么
/v1/incidents 是一个 GET 端点,用于列出出现异常信号的服务目录。它支持按服务、地区、类别、搜索词和时间窗口筛选。响应需要许可证;API 文档说明使用 Bearer 令牌进行身份验证。地区字段接受两个字母的代码,而 hours 设置的时间窗口范围为 1 至 2160 小时。
路径中的“incident”容易被理解为“已确认的故障”,但文档对它的定义更窄:近期观测信号。因此,通知应依据响应数据来措辞,例如“收到可用性异常信号”,而不应声称服务提供商已经确认事件。
发送通知前的最低限度核查
首先,连同接收时间和请求参数保存原始响应。然后核对返回的服务和地区,并根据服务字段 observed_at 和 stale 判断数据是否及时。如果观测被标记为过时,应将其与当前信号区分开来,而不是作为“此刻”的状态展示。
curl -sS 'https://api.uptimescout.com/v1/incidents?region=US&hours=24' \
-H "Authorization: Bearer $UPTIMESCOUT_LICENSE_KEY"
这是一个查询美国地区、时间窗口为 24 小时的示例;密钥从环境变量读取,不会显示在命令行中。收到响应后,检查 HTTP 错误和 JSON 结构,再逐项处理返回的服务。模式中的状态值包括 operational、degraded、outage 和 unknown;如果字段或取值缺失,不要擅自补上解释。
对于需要采取行动的信号,请通过 /v1/status 查询相应服务的当前状态,并通过 /v1/history 查询历史记录。在历史数据中,建议将 resolution_seconds、samples、counts 和 effective_start 与数据序列一并保存:这样分析人员就能看出数据的时间粒度,以及实际可用数据所覆盖的时间范围。规范提醒,缺失的时间段状态未知;不能自动把空白区间视为可用或故障。
如何把响应整理成可核查的报告
为每条记录设置以下字段:服务 ID 和名称、请求地区、状态、观测时间、过时标记、响应接收时间,以及团队核查过的官方状态来源链接。最后一个字段由你的集成程序或操作人员填写:UptimeScout 规范并未承诺信号包含已确认的原因或服务提供商的声明。

将工作流程划分为三个状态。“收到信号”表示该记录出现在 /v1/incidents 的结果中;“正在核对状态”表示已查询当前状态和历史记录;“已确认”则只用于有外部官方公告或内部核查作为依据的结论。这样简单区分,可以避免仪表盘把汇总信号呈现为既定事实。
如果团队要生成涵盖多个地区的报告,请按所需地区代码分别发起请求,并将参数与结果一并保存。lang 字段用于设置服务说明的语言,不会改变观测地区。比较本地化目录和区域状态时,这一区分很重要。
结论的边界
这一流程产出的可核查结果,是一份明确标注时间、地区和时效的信号日志,并辅以单独的状态与历史核对。它有助于发现哪些事项需要关注,以及根据所选来源确认了哪些情况。/v1/incidents 响应本身报告的是观测信号升高;要宣布故障已获确认,还需要佐证数据。