# UptimeScout：如何检查用户所在地区的服务是否发生故障

https://jsonscraper.com/zh/blog/uptimescout-regional-service-outage-check

Author: Michael Johnson

Published: 2026-11-20T11:42:46+00:00

Updated: 2026-11-20T11:42:46+00:00

实用案例解析：汇总地区观测历史，区分最新信号与未知时段

当某个国家的用户报告问题，而团队看到服务运行正常时，最有用的做法是检查该地区的观测数据。UptimeScout API 可以按地区代码查询所选服务的历史记录，并返回时间段及测量次数。最终得到一张可核查的表格，用于分析用户反馈：包括时间段、分辨率、信号分布和样本数。



![文章：UptimeScout：如何检查用户所在地区的服务是否发生故障
摘要：地区可用性检查可以帮助判断用户遇到的问题是否与 UptimeScout 的观测相吻合。本文介绍一套可复现的流程：选择服务和地区、请求历史记录、检查数据的新鲜度与分辨率，然后连同原始响应一起保存结果。
图片用途：封面——核心主题
章节：
视觉主题：展示一张折叠的地区故障地图的编辑风格照片](https://jsonscraper.com/assets/uploads/journal/2026/11/1cd4023e50fafa3c2411a7c5fc1a0f4b.png.hero.webp)

地区和时间窗口共同界定可用性检查的范围。© jsonscraper · AI 生成

 

本文的实际场景是诊断疑似地区性故障。输入包括：UptimeScout 目录中的服务 ID、类似 US 或 GB 的地区代码，以及历史时间窗口。结果有助于将用户报告的时间与服务观测数据进行对照。API 将这些数据描述为可观测的可用性信号；服务检查有助于缩小排查范围，但不能替代对应用本身的检查。

 

## 首先确认服务和地区

 

从目录开始：按名称或搜索词找到所需服务，然后记录其准确 ID。[UptimeScout OpenAPI 规范](https://uptimescout.com/openapi.json)说明，可以通过 GET /v1/services 搜索，并使用 q、service、region、limit 和 offset 参数。诊断报告最好保存 ID，而不只是显示名称，这样重复查询时才能指向目录中的同一条目。

 

地区通过单独的两字母代码指定。务必将它与结果一同保存：查询 US 的响应与未设置地区筛选条件的响应回答的是不同问题。如果要以俄语显示说明，可用 lang=ru 参数控制说明文本的本地化；region 参数则用于选择观测数据。文档明确区分了这两种用途。

 

## 查询历史记录，而非只看单一状态

 

分析故障时，请使用 /v1/history，并提供必填参数 service 和所选 region。hours 参数用于设置历史窗口；规范允许的范围是 1 至 2160 小时。请求还支持 lang。根据 OpenAPI 规范，授权通过 Bearer 方案传递许可证。实际运行时，请将密钥保存在环境变量中，不要写入请求日志。

 

```
import os
import requests

response = requests.get(
    "https://api.uptimescout.com/v1/history",
    headers={"Authorization": f"Bearer {os.environ['UPTIMESCOUT_LICENSE_KEY']}"},
    params={"service": "github", "region": "GB", "hours": 24, "lang": "ru"},
    timeout=30,
)
response.raise_for_status()
data = response.json()
print(data)
```

 

这是一个最简请求示例，并非真实调查中发布的结果。github 服务 ID 和 GB 地区只是示例参数；使用前，请根据任务选择所需服务和地区。建议将完整响应保存为 JSON，并在审计系统的独立字段中添加获取时间和请求说明。这样便于重现分析，并确认使用的是哪一份数据快照。

 

## 分辨率和缺失时段也是结果的一部分

 

history 数组中值得关注的字段包括 observed_at、resolution_seconds、aggregated、samples 和 counts。分辨率表示时间区间的长度；samples 表示汇总中包含的观测次数，counts 则包含信号分布。应综合这些字段进行判断：样本数较少的一行，与包含大量观测的汇总记录，在分析中的权重并不相同。



![文章：UptimeScout：如何检查用户所在地区的服务是否发生故障
摘要：地区可用性检查可以帮助判断用户遇到的问题是否与 UptimeScout 的观测相吻合。本文介绍一套可复现的流程：选择服务和地区、请求历史记录、检查数据的新鲜度与分辨率，然后连同原始响应一起保存结果。
图片用途：辅助插图 2——展示另一个具体方面
章节：分辨率和缺失时段也是结果的一部分](https://jsonscraper.com/assets/uploads/journal/2026/11/a171063a93107bb525c54a0ee477e61a.png.hero.webp)

读取历史记录的顺序：地区、时间段、分辨率和缺失数据。© jsonscraper · AI 生成插图

 

UptimeScout 将历史记录描述为时间段，其步长会随所选窗口变化：较短时间段采用分钟或五分钟间隔，按天查看时采用小时间隔，较长时间段则采用日间隔。保存下来的旧汇总可能具有更粗的分辨率。因此，如果某一行代表小时或日级汇总，就不要断言“故障恰好在这一分钟开始”。请使用实际的 resolution_seconds 值，以及响应中的 effective_start 和 history_resolution 字段，明确说明可得结论的边界。

 

缺失的时间段应视为未知。规范明确要求将缺失数据作为未知区间处理：历史记录中的空白本身既不代表服务正常，也不代表发生故障。报告中遵循这一简单规则，可以避免用“正常”状态或零值错误填补缺失数据。

 

## 将历史记录与当前信号对照

 

如果需要核查用户反馈时的状态，请针对相同的 service 和 region 查询 /v1/status。在服务对象中，应结合查看 status、observed_at 和 stale；文档将这些字段列为判断状态与信号新鲜度的依据。顶层 status 对应 API 请求的结果，而 service.status 描述的是特定服务的可用性信号。在自动化报告中，这一区别尤其有用：HTTP 请求成功与外部服务的状态是两种不同的事物。

 

如果涉及多个依赖项，可以先查询 /v1/statuses，再仅针对出现异常的服务和地区查询历史记录。规范还提供 /v1/summary 和 /v1/incidents。诊断后一个端点时，应注意其准确用途：该端点返回最新的异常升高信号，而不是服务提供商确认的事故。因此，查询结果应作为进一步核查的线索，而非对故障原因的定论。

 

## 如何在不臆测的前提下总结结果

 

在报告条目中保存 service ID、region、查询时段、observed_at、resolution_seconds、samples、counts，以及是否存在缺失时段的标记。将支持请求或内部事故的链接作为 API 字段之外的信息单独添加。之后，将时间范围与应用日志、地区链路追踪和用户反馈进行对照。如果汇总记录的时间边界宽于故障时段，就应相应限定结论：在指定时间窗口内，该地区的观测包含这些信号，并具有相应的分辨率和样本数。

 

这样的分析能帮助值班人员确定下一步：检查外部服务的地区端，或继续排查自己的应用和用户网络。要确保分析可复现，必须保存请求参数和原始 JSON；要准确判断时间，则必须明确考虑分辨率、samples 和未知时段。对于可用性问题，这就是实际成果：得到一条同时限定地区和时间、同事可以复核的记录，而不只是一个当前状态标签。
