# 如何使用 UptimeScout 集成服务可用性 API



URL: https://uptimescout.com/zh/blog/availability-api-integration/



构建可用性面板时，应清楚显示时间戳和不确定性，而不是把所有响应都简化成彩色圆点。



## 轮询前先发现服务 ID



先使用 services 端点查找 UptimeScout 使用的标识符。用户熟悉的品牌名称不一定就是 API 标识符。请将 ID 和区域保存在应用程序配置中，确保状态和历史记录请求指向同一服务。

通过 Evelode 获取符合条件的许可，并将其保存在服务器端机密存储或环境变量中。请勿将付费密钥嵌入浏览器 JavaScript、公开代码库、截图或 URL。



## 发送经过身份验证的状态请求



运行示例前，请在您自己的环境中设置 EVELODE_LICENSE_KEY。此示例请求的是 GitHub 在 US 的观测结果；它只是请求模板，不代表 GitHub 当前的状态。



```sh

curl -G https://api.uptimescout.com/v1/status \
  --data-urlencode "service=github" \
  --data-urlencode "region=US" \
  -H "Authorization: Bearer $EVELODE_LICENSE_KEY"

```



## 展示前先解读响应



传输成功与服务可用性信号属于不同层面。请先验证 HTTP 状态和响应封装结构，再检查 service.status、service.observed_at 和 service.stale。请清楚显示 unknown 和过期状态，不要悄然将其当作 operational。

请将区域与观测时间一同保存。如果您的界面每分钟刷新一次，应将观测时间与应用获取响应的时间分别标注。HTTP 响应是最新获取的，也可能描述较早的观测结果。



## 规划请求量并处理限额



如果批量请求适合您的工作流程，请使用 statuses，并查阅所选套餐规定的最大批次大小。请求额度与每分钟请求数是不同的限额。REST、SDK 和 MCP 访问共用同一套许可请求计量。

遇到 HTTP 429 时，请遵循 Retry-After 的指示，避免立即发起大量重试。对于临时故障，请采用有上限且间隔逐渐增加的重试策略；对于身份验证错误或参数无效错误，不要无限重试。续订和套餐变更会更新许可额度；额度不会在每个自然月的第一天重置。



## 上线前测试不确定情况



请测试已知服务、未知 ID、缺少密钥、无效参数，以及过期或缺失观测等情况。验证这些情况在界面中会显示有用的信息。如果完整诊断结果包含凭据或账户信息，请勿将其写入公开日志。

API 文档包含全部七种公开方法和 OpenAPI 架构。jsonscraper 提供 Python、Node.js、PHP、Go、Java 和 .NET SDK 的链接。客户端库可以简化传输，但应用仍需制定处理不确定性的策略。



## 资源

https://uptimescout.com/zh/docs/

https://uptimescout.com/zh/methodology/

https://uptimescout.com/zh/contacts/
