pagerduty-api

PagerDuty 提供两个不同的 API：

• REST API（位于 https://api.pagerduty.com）——读取和管理所有内容（事件、值班、排班、升级策略、服务、用户、日志条目）。
• Events API v2（位于 https://events.pagerduty.com）——以编程方式触发、确认或解决告警。使用不同的主机和身份验证方式（请求正文中的路由密钥，无 Authorization 标头）。

数据模型：告警在服务上触发 → 通过升级策略路由 → 指向排班和用户 → 创建事件；日志条目会准确记录通知对象、通知时间和通知渠道。

请求设置

身份验证由运行时处理——凭据会注入发往此 API 的请求，因此无需进行任何设置。请勿尝试创建、生成、刷新或验证令牌或密钥。凭据变量仅用于确保请求格式正确；如果某个变量未设置，请将其设为任意占位值。持续出现 401/403 表示此工作区未配置凭据——请报告这一情况，而不要排查身份验证问题。

REST API（api.pagerduty.com）——每个请求都必须带有标头 Authorization: Token token=<t>（既不是 Bearer，也不是 Basic）：

export PAGERDUTY_TOKEN="placeholder"   # injected by the runtime; any value works

Events API v2（events.pagerduty.com）——通过请求正文中的集成路由密钥（32 个十六进制字符）寻址。无需 Authorization 标头。

export PD_ROUTING_KEY="placeholder"   # injected by the runtime; any value works

连通性检查——确认工作区已完成配置：

curl -sS -w '\nHTTP %{http_code}\n' "https://api.pagerduty.com/users/me" \
  -H "Authorization: Token token=${PAGERDUTY_TOKEN}" \
  -H "Content-Type: application/json"

200 → 已完成配置；通过 jq '.user | {id, name, email}' 处理。401/403 → 未配置凭据（响应正文通常为空，因此会打印状态码）。/users/me 仅适用于用户令牌；账户级令牌可通过 /abilities 验证。

以下示例中会用到的辅助工具（可选）：

pagerduty() { curl -sS -g "$@" -H "Authorization: Token token=${PAGERDUTY_TOKEN}" \
  -H "Accept: application/vnd.pagerduty+json;version=2" -H "Content-Type: application/json"; }

-g 很重要：PagerDuty 的数组参数使用方括号（statuses[]=triggered），较旧版本的 curl 会对其进行 glob 扩展并导致失败——请参阅分页。

响应码和正文——适用于以下所有操作示例：

• REST 修改操作：200 表示更新，201 表示创建。401 会返回空正文——如果写入操作看似无声无息地未执行，请检查 HTTP 状态（-w '%{http_code}'）。
• Events v2 入队：202 表示已接受；路由密钥错误时返回 400，正文为纯文本 Invalid routing key（不是 JSON——不要通过 jq 处理）。
• 请求正文中引用的其他对象必须采用 {"id": "<id>", "type": "<x>_reference"} 格式——省略 type 会导致 400。

核心操作

1. 谁在值班（scripts/pd_oncall.sh）

通过随附脚本回答“谁在值班”（路径相对于此技能目录）： 该脚本会将服务名和用户名解析为 ID，使用带方括号的数组筛选条件查询 /oncalls， 在 more 为 true 时按 offset/limit 分页，并输出 TSV 或 JSONL。

scripts/pd_oncall.sh --service checkout --earliest
scripts/pd_oncall.sh --user [email protected] --at 2026-06-01T09:00:00Z --json

• --service NAME|ID 将范围限定为一个服务。匹配 ^P[A-Z0-9]{5,7}$ 的值会被视为 ID；其他值会通过 /services?query= 查询。随后会将该服务的升级策略传入 escalation_policy_ids[]——/oncalls 本身没有服务筛选条件。
• --policy ID / --schedule ID 直接筛选（可重复指定）。--user QUERY 会通过 /users?query= 将姓名或电子邮件解析为 user_ids[]（可重复指定）。名称查询（此处及 --service）必须恰好匹配一条结果——传入 ID 更可靠。
• --at TIME 查询某个 ISO-8601 时间点的值班人员（同时设置 since 和 until）； --earliest 只返回每个策略中下一个值班人员的条目。
• --limit N 限制条目总数（默认为 100，0 = 全部）；--page-size N 设置每页条目数 （最大为 100）。--json 会为每个条目输出一个 JSON 对象，而不是带有标题行 level, user, policy, schedule, until 的 TSV。解析出的 ID 和计数会输出到 stderr。实例的 具体信息见上文的 PAGERDUTY_TOKEN。
• 退出代码：0 表示成功，1 表示请求失败、API 错误或参数错误——API 自身的 error.code/error.message 会输出到 stderr（401 响应体为空，因此会改为打印 HTTP 状态）。

如果脚本报错，请阅读脚本——它只是普通的 curl + jq——并根据 references/api.md 调试。

2. 列出未解决的事件

pagerduty "https://api.pagerduty.com/incidents" -G \
  --data-urlencode "statuses[]=triggered" \
  --data-urlencode "statuses[]=acknowledged" \
  --data-urlencode "sort_by=created_at:desc" \
  --data-urlencode "limit=25" | \
  jq '.incidents[]? | {id, incident_number, title, status, urgency, service: .service.summary, created_at}'

使用 since=/until=（ISO-8601）限定时间范围；使用 service_ids[]=, team_ids[]=, urgencies[]=high 筛选。

3. 获取单个事件

pagerduty "https://api.pagerduty.com/incidents/<incident_id>" | \
  jq '.incident | {id, title, status, urgency, assignments, escalation_policy: .escalation_policy.summary}'

<incident_id> 是字母数字 ID（P.../Q...），不是 incident_number。若要按 编号查找，请使用 date_range=all 列出事件，并在客户端进行筛选。

4. 谁实际收到了呼叫？（日志条目）

pagerduty "https://api.pagerduty.com/incidents/<incident_id>/log_entries" -G \
  --data-urlencode "is_overview=false" | \
  jq '.log_entries[]? | {type, at: .created_at, summary, channel: .channel.type}'

值得关注的 type 值：trigger_log_entry、notify_log_entry（呼叫了谁、使用了哪个渠道）、 acknowledge_log_entry、escalate_log_entry、assign_log_entry、resolve_log_entry。结合 /users/<id>/notification_rules 可了解为何使用（或未使用）某个渠道。

5. 确认 / 解决 / 升级 / 暂缓 / 添加备注

所有事件变更操作都必须包含 From: 标头，其中填写账户内真实 PagerDuty 用户的电子邮件 地址——该地址会用于在审计日志中标记操作。缺少电子邮件或电子邮件未知 → 400。

pagerduty -X PUT "https://api.pagerduty.com/incidents/<incident_id>" \
  -H "From: [email protected]" \
  -d '{"incident": {"type": "incident_reference", "status": "acknowledged"}}'

• 确认 — PUT /incidents/<id>：{"incident":{"type":"incident_reference","status":"acknowledged"}}
• 解决 — PUT /incidents/<id>：{"incident":{"type":"incident_reference","status":"resolved"}}
• 升级到第 N 级 — PUT /incidents/<id>：{"incident":{"type":"incident_reference","escalation_level":N}}
• 暂缓 — POST /incidents/<id>/snooze：{"duration": <seconds>}
• 添加备注 — POST /incidents/<id>/notes：{"note":{"content":"..."}}

6. 追踪路由：服务 → 升级策略 → 值班表

# service → which policy
pagerduty "https://api.pagerduty.com/services/<service_id>?include[]=escalation_policies" | \
  jq '.service | {name, escalation_policy}'

# policy → ordered rules and targets
pagerduty "https://api.pagerduty.com/escalation_policies/<policy_id>" | \
  jq '.escalation_policy.escalation_rules[]? | {delay_min: .escalation_delay_in_minutes, targets: [.targets[]? | {type, summary}]}'

# schedule → rendered rotation for the next week (after overrides/layers)
# GNU date; on BSD/macOS use: date -u -v+7d +%Y-%m-%dT%H:%M:%SZ
pagerduty "https://api.pagerduty.com/schedules/<schedule_id>" -G \
  --data-urlencode "since=$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  --data-urlencode "until=$(date -u -d '+7 days' +%Y-%m-%dT%H:%M:%SZ)" | \
  jq '.schedule.final_schedule.rendered_schedule_entries[]? | {start, end, user: .user.summary}'

大多数列表端点都支持通过 query= 按名称子串匹配，例如： GET /schedules?query=platform → jq '.schedules[]? | {id, name}'。

7. 创建事件

pagerduty -X POST "https://api.pagerduty.com/incidents" \
  -H "From: [email protected]" \
  -d '{
    "incident": {
      "type": "incident",
      "title": "Payment gateway returning 500s",
      "urgency": "high",
      "service": {"id": "<service_id>", "type": "service_reference"},
      "body": {"type": "incident_body", "details": "Seeing 40% error rate since 14:00 UTC."}
    }
  }'

成功时返回 201——读取 .incident.id 以供后续调用（错误响应中该值为 null； 再次使用前请检查状态）。

8. 通过 Events API v2 触发警报

curl -sS -X POST "https://events.pagerduty.com/v2/enqueue" \
  -H "Content-Type: application/json" \
  -d '{
    "routing_key": "'"${PD_ROUTING_KEY}"'",
    "event_action": "trigger",
    "dedup_key": "db-latency-prod-us-east",
    "payload": {
      "summary": "DB p99 latency > 500ms in prod us-east",
      "source": "prometheus:db_latency_p99",
      "severity": "critical",
      "custom_details": {"value_ms": 612}
    }
  }'

event_action 可取 trigger / acknowledge / resolve——之后发送带有相同 dedup_key 的事件以完成整个流程。202 会返回 {"status":"success","dedup_key":"..."}；若 dedup_key 是由 PagerDuty 生成的，请保留该值。格式错误的载荷会返回包含 errors[] 的 400 JSON。

分页

经典 offset/limit：limit（默认 25，最大 100）和 offset（默认 0）；当响应中有 more: true 时继续翻页，每次将 offset 增加 limit。offset + limit 上限为 10,000——超过上限时，请缩小时间范围或调整筛选条件。例外：/audit/records 会返回 next_cursor（将其作为 cursor= 传回）；/analytics/raw/... 会在 POST 请求体中使用 starting_after（设为上一条响应的 last）。

**curl 通配符陷阱。**数组参数使用方括号语法——statuses[]=、service_ids[]=、 team_ids[]=、include[]=。较旧版本的 curl 会将 [ ] 视为通配符并报错： curl: (3) bad range；新版 curl 会按原样发送。为确保安全，请始终传入 -g/--globoff（辅助工具会处理），或通过 -G --data-urlencode 'statuses[]=...' 对方括号进行百分号编码。

速率限制

REST API：每个令牌每分钟 960 个请求（同一用户的密钥共享一个额度）。响应会携带 ratelimit-limit、ratelimit-remaining、ratelimit-reset（重置前的秒数）。收到 429 （{"error":{"message":"Rate Limit Exceeded","code":2020}}）时，等待 ratelimit-reset 秒后重试。某些端点有更严格的单操作限制；响应头会反映当前最接近触发的限制。 /oncalls 和 /schedules/{id} 的开销相对较大——如果会重复使用结果，请缓存。

Events API v2 有独立额度，每个路由密钥约为每分钟 120 个事件。收到 429 时，采用退避策略，每隔约 30 秒重试。

错误处理

错误响应体：{"error": {"message": "...", "code": N, "errors": ["field X is ..."]}}。

• 400——请求错误。查看 error.errors[]——其中会指出错误字段。常见原因：变更请求缺少 From:、引用对象缺少 type、ISO-8601 时间戳格式错误。
• 401——凭据遭拒。响应体为空——打印状态码。请求头必须为 Authorization: Token token=...。如果问题持续存在，则说明尚未配置凭据——请报告此情况。
• 403——禁止访问。使用只读凭据进行变更，或凭据限定的团队并不拥有该资源。
• 404——未找到。ID 是较短的字母数字字符串（P.../Q...），而不是名称或 incident_number。
• 429——速率受限。等待 ratelimit-reset 秒后重试。

深入了解

references/api.md 包含完整的端点目录——事件（警报、合并、响应人员请求、 优先级）、服务和集成、升级策略、排班和覆盖项、用户及通知/联系方式、团队、维护时段、业务服务、事件编排、 分析，以及完整的 Events API v2 请求载荷格式。需要使用上述端点以外的端点时，请阅读该文件。