From 705c3ba69ef70eb3928f2dc7bf89604cd3e51d71 Mon Sep 17 00:00:00 2001 From: pijiang <419471640@qq.com> Date: Mon, 21 Sep 2026 11:06:34 +0800 Subject: [PATCH 1/2] docs: add Checkly alert integration --- docs.json | 2 + .../alert-sources/checkly.mdx | 133 ++++++++++++++++ integration-docs/src/doc-map.mjs | 1 + .../alert-sources/checkly.mdx | 147 ++++++++++++++++++ 4 files changed, 283 insertions(+) create mode 100644 en/on-call/integration/alert-integration/alert-sources/checkly.mdx create mode 100644 zh/on-call/integration/alert-integration/alert-sources/checkly.mdx diff --git a/docs.json b/docs.json index 1520dfe8..2ebfaa80 100644 --- a/docs.json +++ b/docs.json @@ -1682,6 +1682,7 @@ "zh/on-call/integration/alert-integration/alert-sources/datadog", "zh/on-call/integration/alert-integration/alert-sources/new-relic", "zh/on-call/integration/alert-integration/alert-sources/sumo-logic", + "zh/on-call/integration/alert-integration/alert-sources/checkly", "zh/on-call/integration/alert-integration/alert-sources/zabbix", "zh/on-call/integration/alert-integration/alert-sources/flashcat", "zh/on-call/integration/alert-integration/alert-sources/open-falcon", @@ -3053,6 +3054,7 @@ "en/on-call/integration/alert-integration/alert-sources/datadog", "en/on-call/integration/alert-integration/alert-sources/new-relic", "en/on-call/integration/alert-integration/alert-sources/sumo-logic", + "en/on-call/integration/alert-integration/alert-sources/checkly", "en/on-call/integration/alert-integration/alert-sources/zabbix", "en/on-call/integration/alert-integration/alert-sources/flashcat", "en/on-call/integration/alert-integration/alert-sources/open-falcon", diff --git a/en/on-call/integration/alert-integration/alert-sources/checkly.mdx b/en/on-call/integration/alert-integration/alert-sources/checkly.mdx new file mode 100644 index 00000000..916c3be8 --- /dev/null +++ b/en/on-call/integration/alert-integration/alert-sources/checkly.mdx @@ -0,0 +1,133 @@ +--- +title: "Checkly alert integration" +description: "Send Checkly failure, degradation, recovery, and SSL certificate alerts to Flashduty On-call through a Webhook Alert Channel." +keywords: ["alert integration", "Checkly", "webhook", "synthetic monitoring", "API monitoring"] +--- + +Use a Checkly Webhook Alert Channel to send check-state changes to Flashduty On-call. Failure, degradation, continued failure, and recovery notifications for one Check update the same Flashduty alert. + +
+ +## In Flashduty On-call +--- + +Create either a dedicated or shared **Checkly** alert integration and copy its complete Push URL. + +
+ +## Configure Checkly +--- + + + + +1. In Checkly, open **Alert Settings** +2. Click **Add more channels** and select **Webhook** +3. Enter `Flashduty` as the name +4. Select `POST` as the method +5. Paste the complete Flashduty integration Push URL into URL +6. Add `Content-Type: application/json` under Headers + + + + + +1. Enable **Failure**, **Degradation**, and **Recovery** under **Notification events** +2. Optionally enable **SSL certificate expirations** +3. Subscribe the Checks or Check Groups that should send notifications to Flashduty + +Recovery must be enabled. Otherwise, a recovered Check cannot recover its existing Flashduty alert. + + + + + +Replace Body with this complete JSON template: + +```json +{ + "alert_type": "{{ALERT_TYPE}}", + "alert_title": "{{ALERT_TITLE}}", + "check_id": "{{CHECK_ID}}", + "check_result_id": "{{CHECK_RESULT_ID}}", + "check_name": "{{CHECK_NAME}}", + "check_type": "{{CHECK_TYPE}}", + "group_name": "{{GROUP_NAME}}", + "is_reminder": "{{IS_REMINDER}}", + "reminder_sequence": "{{REMINDER_SEQUENCE}}", + "region": "{{REGION}}", + "run_location": "{{RUN_LOCATION}}", + "started_at": "{{STARTED_AT}}", + "response_time": "{{RESPONSE_TIME}}", + "response_status_code": "{{API_CHECK_RESPONSE_STATUS_CODE}}", + "response_status_text": "{{API_CHECK_RESPONSE_STATUS_TEXT}}", + "result_link": "{{RESULT_LINK}}", + "error_message": "{{CHECK_ERROR_MESSAGE}}", + "tags": [{{#each TAGS}}"{{this}}"{{#unless @last}},{{/unless}}{{/each}}] +} +``` + +Keep `alert_type` and `check_id`. Never add API keys, tokens, passwords, cookies, or other secrets to the payload. + + + + + +Move one subscribed Check through failure, degradation, and recovery. Confirm that one Flashduty alert is triggered, updated, and recovered. + +A Checkly test notification or webhook HTTP 200 proves connectivity only. Use real Check state changes to verify Alert Key correlation and recovery. + + + + +## Alert Key +--- + +Normal check-state notifications use the trimmed `check_id` (Checkly variable `CHECK_ID`) as the Alert Key. Titles, errors, run locations, response times, result IDs, and alert-state changes do not affect it. + + +If `check_id` is missing or empty, Flashduty accepts the request and generates a random UUID for that notification. These notifications cannot correlate: a later update or recovery without `check_id` cannot find the earlier alert. + + +`ALERT_SSL` is an independent one-shot Warning event. It always receives a new random UUID, even when the payload includes `check_id`, and does not update or recover the Check's normal state alert. + +## Status and severity +--- + +| Checkly `ALERT_TYPE` | Flashduty status | Flashduty severity | +| :--- | :--- | :--- | +| `ALERT_FAILURE`, `ALERT_FAILURE_REMAIN`, `ALERT_DEGRADED_FAILURE` | Active | Critical | +| `ALERT_DEGRADED`, `ALERT_DEGRADED_REMAIN`, `ALERT_FAILURE_DEGRADED` | Active | Warning | +| `ALERT_RECOVERY` | Recovered | Critical | +| `ALERT_DEGRADED_RECOVERY` | Recovered | Warning | +| `ALERT_SSL` | Active, one-shot | Warning | +| `NO_ALERT` | Ignored; no event is created | - | + +An empty or unknown `alert_type` returns an invalid-parameter response. Recovery is determined only by `alert_type`, not by the title or error text. + +## Labels and description +--- + +Flashduty creates these labels: + +- `check` and `source=checkly` +- `check_id` and `checkly_alert_type` +- `check_name`, `check_type`, and `group_name` +- `region` and `run_location` +- `is_reminder` and `reminder_sequence` +- JSON-encoded `tags` + +`check_result_id` is a high-cardinality per-run value and is not stored as a label. The bounded alert description contains the error, response status, response time, start time, and result link. + +## Delivery and troubleshooting +--- + +Checkly retries a failed webhook delivery up to five times at approximately 20-second intervals. Use Checkly's Alert Notification Log to inspect the final delivery result. + +- **Flashduty returns an invalid-parameter error**: verify that Body is valid JSON, matches the complete template, and contains a supported `alert_type` +- **One Check creates multiple alerts**: confirm that every notification carries the same non-empty `check_id` +- **The alert does not recover**: enable Recovery and confirm that the recovery payload has the same `check_id` as the trigger +- **No degradation alert arrives**: enable Degradation and configure a degradation condition on the Check +- **No notification arrives**: confirm that the Check or Check Group subscribes to this Webhook Channel, then inspect the Alert Notification Log + +See [Alerting With Checkly](https://www.checklyhq.com/docs/alerting-and-retries/custom-alerts/) for Checkly's state-transition model. diff --git a/integration-docs/src/doc-map.mjs b/integration-docs/src/doc-map.mjs index 32eb494e..e39ad1ca 100644 --- a/integration-docs/src/doc-map.mjs +++ b/integration-docs/src/doc-map.mjs @@ -66,6 +66,7 @@ export const docMap = { Datadog: `${alertBase}/datadog.mdx`, NewRelic: `${alertBase}/new-relic.mdx`, SumoLogic: `${alertBase}/sumo-logic.mdx`, + Checkly: `${alertBase}/checkly.mdx`, AliyunPrometheus: `${alertBase}/aliyun-prometheus.mdx`, AliyunDataWorksOp: `${alertBase}/aliyun-dataworks-op.mdx`, HttpPull: `${alertBase}/http-pull.mdx`, diff --git a/zh/on-call/integration/alert-integration/alert-sources/checkly.mdx b/zh/on-call/integration/alert-integration/alert-sources/checkly.mdx new file mode 100644 index 00000000..f3c8059b --- /dev/null +++ b/zh/on-call/integration/alert-integration/alert-sources/checkly.mdx @@ -0,0 +1,147 @@ +--- +title: "Checkly 告警集成" +description: "通过 Webhook Alert Channel 将 Checkly 的失败、性能降级、恢复和 SSL 证书告警同步到 Flashduty On-call。" +keywords: ["告警集成", "Checkly", "Webhook", "合成监控", "API 监控"] +--- + +通过 Checkly Webhook Alert Channel 将检查状态同步到 Flashduty On-call。同一个 Check 的失败、降级、持续异常和恢复通知会更新同一条 Flashduty 告警。 + +
+ +## 在 Flashduty On-call +--- + +您可通过以下两种方式获取集成推送地址，任选其一即可。 + +### 使用专属集成 + +1. 进入 Flashduty 控制台，选择 **协作空间**，打开一个协作空间 +2. 选择 **集成数据**，点击 **添加一个集成** +3. 选择 **Checkly**，点击 **保存** +4. 打开生成的集成卡片，复制 **推送地址** + +### 使用共享集成 + +1. 进入 Flashduty 控制台，选择 **集成中心 → 告警事件** +2. 选择 **Checkly**，填写集成名称 +3. 配置默认路由并选择协作空间；创建后可在 **路由** 中增加更多规则 +4. 点击 **保存**，复制生成的 **推送地址** + +
+ +## 在 Checkly 中配置 +--- + + + + +1. 登录 Checkly，进入 **Alert Settings** +2. 点击 **Add more channels**，选择 **Webhook** +3. 名称填写 `Flashduty` +4. Method 选择 `POST` +5. 将 Flashduty 集成的完整推送地址粘贴到 URL +6. 在 Headers 中增加 `Content-Type: application/json` + + + + + +1. 在 **Notification events** 中启用 **Failure**、**Degradation** 和 **Recovery** +2. 如需接收证书到期提醒，再启用 **SSL certificate expirations** +3. 在订阅范围中选择需要发送到 Flashduty 的 Checks 或 Check Groups + +必须启用 Recovery，否则 Checkly 恢复后，Flashduty 中的原告警不会自动恢复。 + + + + + +将 Body 替换为以下完整 JSON 模板： + +```json +{ + "alert_type": "{{ALERT_TYPE}}", + "alert_title": "{{ALERT_TITLE}}", + "check_id": "{{CHECK_ID}}", + "check_result_id": "{{CHECK_RESULT_ID}}", + "check_name": "{{CHECK_NAME}}", + "check_type": "{{CHECK_TYPE}}", + "group_name": "{{GROUP_NAME}}", + "is_reminder": "{{IS_REMINDER}}", + "reminder_sequence": "{{REMINDER_SEQUENCE}}", + "region": "{{REGION}}", + "run_location": "{{RUN_LOCATION}}", + "started_at": "{{STARTED_AT}}", + "response_time": "{{RESPONSE_TIME}}", + "response_status_code": "{{API_CHECK_RESPONSE_STATUS_CODE}}", + "response_status_text": "{{API_CHECK_RESPONSE_STATUS_TEXT}}", + "result_link": "{{RESULT_LINK}}", + "error_message": "{{CHECK_ERROR_MESSAGE}}", + "tags": [{{#each TAGS}}"{{this}}"{{#unless @last}},{{/unless}}{{/each}}] +} +``` + +请保留 `alert_type` 和 `check_id`。不要在 Payload 中加入 API Key、Token、密码、Cookie 或其他敏感信息。 + + + + + +让一个已订阅的 Check 依次进入失败、降级和恢复状态，确认 Flashduty 中同一条告警依次触发、更新并恢复。 + +Checkly 的测试发送或 Webhook HTTP 200 只能证明地址可达，不能证明 Alert Key 关联和恢复行为。请使用真实 Check 状态变化完成验证。 + + + + +## Alert Key +--- + +普通检查状态通知使用去除首尾空格后的 `check_id`（Checkly 变量 `CHECK_ID`）作为 Alert Key。标题、错误、执行区域、响应时间、结果 ID 和告警状态变化都不会改变 Alert Key。 + + +当 `check_id` 缺失或为空时，Flashduty 不会拒绝请求，而是为本次通知生成随机 UUID。此时不同通知无法关联：后续更新或恢复不能命中之前同样缺少 `check_id` 的告警。 + + +`ALERT_SSL` 是独立的单次 Warning 事件，即使 Payload 中有 `check_id`，也会使用新的随机 UUID。它不会更新或恢复该 Check 的普通状态告警。 + +## 状态和告警等级 +--- + +| Checkly `ALERT_TYPE` | Flashduty 状态 | Flashduty 等级 | +| :--- | :--- | :--- | +| `ALERT_FAILURE`、`ALERT_FAILURE_REMAIN`、`ALERT_DEGRADED_FAILURE` | 活动 | Critical | +| `ALERT_DEGRADED`、`ALERT_DEGRADED_REMAIN`、`ALERT_FAILURE_DEGRADED` | 活动 | Warning | +| `ALERT_RECOVERY` | 恢复 | Critical | +| `ALERT_DEGRADED_RECOVERY` | 恢复 | Warning | +| `ALERT_SSL` | 活动、单次事件 | Warning | +| `NO_ALERT` | 忽略，不创建事件 | - | + +空值或未知的 `alert_type` 会返回参数错误。恢复只根据 `alert_type` 判断，与标题或错误文本无关。 + +## 标签和描述 +--- + +Flashduty 会生成以下标签： + +- `check`、`source=checkly` +- `check_id`、`checkly_alert_type` +- `check_name`、`check_type`、`group_name` +- `region`、`run_location` +- `is_reminder`、`reminder_sequence` +- JSON 编码后的 `tags` + +`check_result_id` 是每次执行产生的高基数字段，不会写入标签。错误信息、响应状态、响应时间、开始时间和结果链接会进入有长度限制的告警描述。 + +## 投递和排查 +--- + +Checkly 对失败的 Webhook 投递最多重试 5 次，每次间隔约 20 秒。可在 Checkly 的 Alert Notification Log 中查看最终投递结果。 + +- **Flashduty 返回参数错误**：确认 Body 是有效 JSON，并使用上面的完整模板；检查 `alert_type` 是否为支持值 +- **同一个 Check 产生多条告警**：确认每次通知都带有相同且非空的 `check_id` +- **告警没有恢复**：确认 Notification events 已启用 Recovery，且恢复 Payload 的 `check_id` 与触发时一致 +- **没有降级告警**：确认已启用 Degradation，并为 Check 配置了降级条件 +- **没有收到通知**：确认目标 Check 或 Check Group 已订阅该 Webhook Channel，并在 Alert Notification Log 中检查投递状态 + +Checkly 的状态转换说明请参阅 [Alerting With Checkly](https://www.checklyhq.com/docs/alerting-and-retries/custom-alerts/)。 From a6db6044815f1774a529006cb144225327f67bcc Mon Sep 17 00:00:00 2001 From: debidong <1953531014@qq.com> Date: Wed, 23 Sep 2026 16:07:52 +0800 Subject: [PATCH 2/2] docs(api): add AI SRE assignee fields to the work-item OpenAPI spec Create and reset take assignees ({type, id?}) beside the legacy assignee_ids alias. List can filter with assignee_type. Work item responses include structured assignees and the AI session id and venue. --- api-reference/openapi.en.json | 184 ++++++++++++++++++++++++++++++++-- api-reference/openapi.zh.json | 184 ++++++++++++++++++++++++++++++++-- 2 files changed, 352 insertions(+), 16 deletions(-) diff --git a/api-reference/openapi.en.json b/api-reference/openapi.en.json index 9ea6dd53..36e2edaf 100644 --- a/api-reference/openapi.en.json +++ b/api-reference/openapi.en.json @@ -6592,13 +6592,21 @@ "description": "Parameters for creating an incident work item.", "properties": { "assignee_ids": { - "description": "Initial assignee member IDs. Assignees must be active members who can already read the anchor; assignment never grants access.", + "description": "Legacy alias for the initial assignees. Equivalent to `assignees` with every entry `type` `person`. Mutually exclusive with `assignees`: sending both returns an error. Assignees must be active members who can already read the anchor; assignment never grants access.", "items": { "format": "int64", "type": "integer" }, "type": "array" }, + "assignees": { + "description": "Initial assignees. Each entry is `{type, id?}`. `type` is `person` or `ai_sre`; an `ai_sre` entry omits `id`. Mutually exclusive with `assignee_ids`: sending both returns an error. `assignee_ids` is the legacy alias and is equivalent to an all-`person` list. At most 20 entries. Person assignees must be active members who can already read the anchor; assignment never grants access.", + "items": { + "$ref": "#/components/schemas/WorkItemAssignee" + }, + "maxItems": 20, + "type": "array" + }, "description": { "description": "Optional longer description (max 65,535 characters).", "maxLength": 65535, @@ -14456,13 +14464,21 @@ "type": "object" }, "ListWorkItemRequest": { - "description": "Filters for listing work items. At least one of `incident_id`, `post_mortem_id`, or `assignee_id` is required.", + "description": "Filters for listing work items. At least one of `incident_id`, `post_mortem_id`, `assignee_id`, or `assignee_type` = `ai_sre` is required.", "properties": { "assignee_id": { - "description": "Restrict results to items assigned to this member ID. Listing by assignee alone requires being that assignee or an account admin.", + "description": "Restrict results to items assigned to this member ID. Listing by assignee alone requires being that assignee or an account admin. Ignored when `assignee_type` is `ai_sre`.", "format": "int64", "type": "integer" }, + "assignee_type": { + "description": "Filter by assignee type: `person` or `ai_sre`. `ai_sre` returns items assigned to AI SRE (an AI caller uses this to list its own tasks) and does not require `assignee_id`. `person` together with `assignee_id` restricts results to that member. Omitted with a positive `assignee_id` means `person`.", + "enum": [ + "person", + "ai_sre" + ], + "type": "string" + }, "cursor": { "description": "Pagination cursor from a previous response's `next_cursor`.", "type": "string" @@ -18130,13 +18146,21 @@ "description": "Full replacement of a work item's assignee set.", "properties": { "assignee_ids": { - "description": "New assignee member IDs, replacing the current set. An empty array clears all assignees.", + "description": "Legacy alias for the replacement assignee set. Equivalent to `assignees` with every entry `type` `person`. Mutually exclusive with `assignees`: sending both returns an error. An empty array clears all assignees.", "items": { "format": "int64", "type": "integer" }, "type": "array" }, + "assignees": { + "description": "Replacement assignee set. Each entry is `{type, id?}`. `type` is `person` or `ai_sre`; an `ai_sre` entry omits `id`. Mutually exclusive with `assignee_ids`: sending both returns an error. `assignee_ids` is the legacy alias and is equivalent to an all-`person` list. At most 20 entries. An empty array clears all assignees.", + "items": { + "$ref": "#/components/schemas/WorkItemAssignee" + }, + "maxItems": 20, + "type": "array" + }, "version": { "description": "Current item version for optimistic locking. Must match the stored version.", "format": "int64", @@ -28429,6 +28453,28 @@ ], "type": "object" }, + "WorkItemAssignee": { + "description": "One assignee on a work item.", + "properties": { + "id": { + "description": "Member ID. Required when `type` is `person`. Omitted when `type` is `ai_sre`.", + "format": "int64", + "type": "integer" + }, + "type": { + "description": "Assignee kind: `person` (a member) or `ai_sre` (the account AI SRE).", + "enum": [ + "person", + "ai_sre" + ], + "type": "string" + } + }, + "required": [ + "type" + ], + "type": "object" + }, "WorkItemCreateResult": { "description": "Result of creating a work item.", "properties": { @@ -28456,14 +28502,33 @@ "WorkItemItem": { "description": "A structured incident work item (action or post-mortem follow-up) with its assignees.", "properties": { + "agent_session_id": { + "description": "ID of the AI SRE session executing this item. Omitted when no session is recorded.", + "type": "string" + }, + "agent_session_venue": { + "description": "Where that AI SRE session runs: `web` or `im`. Omitted when no session is recorded.", + "enum": [ + "web", + "im" + ], + "type": "string" + }, "assignee_ids": { - "description": "Member IDs of the current assignees. Never null; an empty array means unassigned.", + "description": "Member IDs of the current person assignees. AI SRE is not included. Never null; an empty array means no person assignee.", "items": { "format": "int64", "type": "integer" }, "type": "array" }, + "assignees": { + "description": "Current assignees. Each entry is `{type, id?}`. `type` is `person` or `ai_sre`; an `ai_sre` entry omits `id`. Never null; an empty array means unassigned. `assignee_ids` is the person-only subset of this list.", + "items": { + "$ref": "#/components/schemas/WorkItemAssignee" + }, + "type": "array" + }, "converted_at_seconds": { "description": "Conversion time as a Unix timestamp in seconds. Present only after conversion.", "format": "int64", @@ -28563,6 +28628,7 @@ "source_kind", "version", "assignee_ids", + "assignees", "created_by", "updated_by", "created_at_seconds", @@ -40265,6 +40331,20 @@ 4756301322131, 5068740052131 ], + "assignees": [ + { + "id": 3790925372131, + "type": "person" + }, + { + "id": 4756301322131, + "type": "person" + }, + { + "id": 5068740052131, + "type": "person" + } + ], "created_at_seconds": 1785495329, "created_by": 5329873302131, "incident_id": "6a5f1e28807515413b384bce", @@ -40321,7 +40401,7 @@ "On-call/Incidents" ], "x-mint": { - "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- Requires the On-call Pro license.\n- Full replacement of the assignee set — an empty array clears all assignees.\n- Only newly added assignees are notified; removals never notify.\n- Audited — changes are recorded in the audit log.", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- Requires the On-call Pro license.\n- Full replacement of the assignee set — an empty array clears all assignees.\n- Set either `assignees` or the legacy `assignee_ids`, not both (sending both returns an error). An `ai_sre` entry omits `id`.\n- Only newly added assignees are notified; removals never notify.\n- Audited — changes are recorded in the audit log.", "href": "/en/api-reference/on-call/incidents/incident-work-item-reset-assignees", "metadata": { "sidebarTitle": "Reset work item assignees" @@ -40361,6 +40441,20 @@ 4756301322131, 5068740052131 ], + "assignees": [ + { + "id": 3790925372131, + "type": "person" + }, + { + "id": 4756301322131, + "type": "person" + }, + { + "id": 5068740052131, + "type": "person" + } + ], "created_at_seconds": 1785495329, "created_by": 5329873302131, "incident_id": "6a5f1e28807515413b384bce", @@ -40454,6 +40548,20 @@ 4756301322131, 5068740052131 ], + "assignees": [ + { + "id": 3790925372131, + "type": "person" + }, + { + "id": 4756301322131, + "type": "person" + }, + { + "id": 5068740052131, + "type": "person" + } + ], "created_at_seconds": 1785495329, "created_by": 5329873302131, "incident_id": "6a5f1e28807515413b384bce", @@ -40554,6 +40662,12 @@ "assignee_ids": [ 3790925372131 ], + "assignees": [ + { + "id": 3790925372131, + "type": "person" + } + ], "created_at_seconds": 1785496400, "created_by": 3790925372131, "incident_id": "6a5f1e28807515413b384bce", @@ -40606,7 +40720,7 @@ "On-call/Incidents" ], "x-mint": { - "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- Requires the On-call Pro license.\n- An `action` anchors to an active incident and must NOT set `post_mortem_id`; a `follow_up` REQUIRES the `post_mortem_id` of a post-mortem linked to `incident_id`.\n- Assignees must be active members who can already read the anchor incident or post-mortem — assignment never grants access.\n- Newly added assignees are notified.\n- Retrying with the same (`creator`, `idempotency_key`) replays the original item with `idempotent_replay: true` instead of creating a duplicate.\n- Audited — changes are recorded in the audit log.", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- Requires the On-call Pro license.\n- An `action` anchors to an active incident and must NOT set `post_mortem_id`; a `follow_up` REQUIRES the `post_mortem_id` of a post-mortem linked to `incident_id`.\n- Set either `assignees` or the legacy `assignee_ids`, not both. `assignees` entries are `{type, id?}` with `type` `person` or `ai_sre`; an `ai_sre` entry omits `id`. `assignee_ids` is equivalent to an all-`person` list. Sending both returns an error.\n- Person assignees must be active members who can already read the anchor incident or post-mortem — assignment never grants access.\n- Newly added assignees are notified.\n- Retrying with the same (`creator`, `idempotency_key`) replays the original item with `idempotent_replay: true` instead of creating a duplicate.\n- Audited — changes are recorded in the audit log.", "href": "/en/api-reference/on-call/incidents/incident-work-item-create", "metadata": { "sidebarTitle": "Create a work item" @@ -40717,6 +40831,20 @@ 4756301322131, 5068740052131 ], + "assignees": [ + { + "id": 3790925372131, + "type": "person" + }, + { + "id": 4756301322131, + "type": "person" + }, + { + "id": 5068740052131, + "type": "person" + } + ], "created_at_seconds": 1785495329, "created_by": 5329873302131, "incident_id": "6a5f1e28807515413b384bce", @@ -40734,6 +40862,12 @@ "assignee_ids": [ 5068740052131 ], + "assignees": [ + { + "id": 5068740052131, + "type": "person" + } + ], "created_at_seconds": 1785495164, "created_by": 3790925372131, "incident_id": "6a5f1e28807515413b384bce", @@ -40789,7 +40923,7 @@ "On-call/Incidents" ], "x-mint": { - "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** (`on-call`) |\n\n## Usage\n\n- At least one of `incident_id`, `post_mortem_id`, or `assignee_id` is required.\n- Cursor pagination sorted by `updated_at_seconds` descending — pass the previous response's `next_cursor` as `cursor` until `has_more` is false.\n- Listing by `incident_id` also includes follow-ups anchored on the incident's post-mortem.\n- Listing by `assignee_id` alone requires being that assignee or an account admin.", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** (`on-call`) |\n\n## Usage\n\n- At least one of `incident_id`, `post_mortem_id`, `assignee_id`, or `assignee_type` = `ai_sre` is required.\n- `assignee_type` = `ai_sre` lists items assigned to AI SRE and can be used on its own.\n- Cursor pagination sorted by `updated_at_seconds` descending — pass the previous response's `next_cursor` as `cursor` until `has_more` is false.\n- Listing by `incident_id` also includes follow-ups anchored on the incident's post-mortem.\n- Listing by `assignee_id` alone requires being that assignee or an account admin.", "href": "/en/api-reference/on-call/incidents/incident-work-item-list", "metadata": { "sidebarTitle": "List work items" @@ -40830,6 +40964,20 @@ 4756301322131, 5068740052131 ], + "assignees": [ + { + "id": 3790925372131, + "type": "person" + }, + { + "id": 4756301322131, + "type": "person" + }, + { + "id": 5068740052131, + "type": "person" + } + ], "created_at_seconds": 1785495329, "created_by": 5329873302131, "incident_id": "6a5f1e28807515413b384bce", @@ -40847,6 +40995,12 @@ "assignee_ids": [ 5068740052131 ], + "assignees": [ + { + "id": 5068740052131, + "type": "person" + } + ], "created_at_seconds": 1785495164, "created_by": 3790925372131, "incident_id": "6a5f1e28807515413b384bce", @@ -40941,6 +41095,20 @@ 4756301322131, 5068740052131 ], + "assignees": [ + { + "id": 3790925372131, + "type": "person" + }, + { + "id": 4756301322131, + "type": "person" + }, + { + "id": 5068740052131, + "type": "person" + } + ], "created_at_seconds": 1785495329, "created_by": 5329873302131, "incident_id": "6a5f1e28807515413b384bce", diff --git a/api-reference/openapi.zh.json b/api-reference/openapi.zh.json index 0f9564bb..25cbdfae 100644 --- a/api-reference/openapi.zh.json +++ b/api-reference/openapi.zh.json @@ -6592,13 +6592,21 @@ "description": "创建故障跟进事项的参数。", "properties": { "assignee_ids": { - "description": "初始负责人成员 ID 列表。负责人须为已能查看锚定对象的活跃成员；指派不会授予访问权限。", + "description": "初始负责人的旧版别名，等价于全部为 `person` 的 `assignees`。与 `assignees` 互斥，同时出现会报错。负责人须为已能查看锚定对象的活跃成员；指派不会授予访问权限。", "items": { "format": "int64", "type": "integer" }, "type": "array" }, + "assignees": { + "description": "初始负责人列表。每项为 `{type, id?}`。`type` 取 `person` 或 `ai_sre`；`ai_sre` 不带 `id`。与 `assignee_ids` 互斥，同时出现会报错。`assignee_ids` 是旧版别名，等价于全部为 `person`。最多 20 项。`person` 须为已能查看锚定对象的活跃成员；指派不会授予访问权限。", + "items": { + "$ref": "#/components/schemas/WorkItemAssignee" + }, + "maxItems": 20, + "type": "array" + }, "description": { "description": "可选的详细描述（最长 65,535 字符）。", "maxLength": 65535, @@ -14456,13 +14464,21 @@ "type": "object" }, "ListWorkItemRequest": { - "description": "查询跟进事项的过滤条件。`incident_id`、`post_mortem_id`、`assignee_id` 至少提供一个。", + "description": "查询跟进事项的过滤条件。`incident_id`、`post_mortem_id`、`assignee_id`，或 `assignee_type` 为 `ai_sre`，至少满足一个。", "properties": { "assignee_id": { - "description": "按负责人成员 ID 过滤结果。仅按负责人查询时，须为本人或账户管理员。", + "description": "按负责人成员 ID 过滤结果。仅按负责人查询时，须为本人或账户管理员。`assignee_type` 为 `ai_sre` 时忽略本字段。", "format": "int64", "type": "integer" }, + "assignee_type": { + "description": "按负责人类型过滤：`person` 或 `ai_sre`。`ai_sre` 返回指派给 AI SRE 的事项（AI 用它查询自己的任务），不需要 `assignee_id`。`person` 与 `assignee_id` 一起使用时，只返回该成员负责的事项。省略本字段且 `assignee_id` 为正数时，按 `person` 过滤。", + "enum": [ + "person", + "ai_sre" + ], + "type": "string" + }, "cursor": { "description": "分页游标，取自上一次响应的 `next_cursor`。", "type": "string" @@ -18130,13 +18146,21 @@ "description": "整体替换跟进事项的负责人集合。", "properties": { "assignee_ids": { - "description": "新的负责人成员 ID 列表，整体替换当前集合。空数组表示清空所有负责人。", + "description": "替换后负责人集合的旧版别名，等价于全部为 `person` 的 `assignees`。与 `assignees` 互斥，同时出现会报错。空数组表示清空所有负责人。", "items": { "format": "int64", "type": "integer" }, "type": "array" }, + "assignees": { + "description": "替换后的负责人集合。每项为 `{type, id?}`。`type` 取 `person` 或 `ai_sre`；`ai_sre` 不带 `id`。与 `assignee_ids` 互斥，同时出现会报错。`assignee_ids` 是旧版别名，等价于全部为 `person`。最多 20 项。空数组表示清空所有负责人。", + "items": { + "$ref": "#/components/schemas/WorkItemAssignee" + }, + "maxItems": 20, + "type": "array" + }, "version": { "description": "事项当前版本号，用于乐观锁。必须与存储的版本一致。", "format": "int64", @@ -28429,6 +28453,28 @@ ], "type": "object" }, + "WorkItemAssignee": { + "description": "跟进事项的一名负责人。", + "properties": { + "id": { + "description": "成员 ID。`type` 为 `person` 时必填；`type` 为 `ai_sre` 时省略。", + "format": "int64", + "type": "integer" + }, + "type": { + "description": "负责人类型：`person` 为成员，`ai_sre` 为账户的 AI SRE。", + "enum": [ + "person", + "ai_sre" + ], + "type": "string" + } + }, + "required": [ + "type" + ], + "type": "object" + }, "WorkItemCreateResult": { "description": "创建跟进事项的结果。", "properties": { @@ -28456,14 +28502,33 @@ "WorkItemItem": { "description": "结构化的故障跟进事项（行动项或复盘后续行动）及其负责人。", "properties": { + "agent_session_id": { + "description": "执行该事项的 AI SRE 会话 ID。没有会话时省略。", + "type": "string" + }, + "agent_session_venue": { + "description": "该 AI SRE 会话所在位置：`web` 或 `im`。没有会话时省略。", + "enum": [ + "web", + "im" + ], + "type": "string" + }, "assignee_ids": { - "description": "当前负责人的成员 ID 列表。不会为 null；空数组表示未指派。", + "description": "当前人员负责人的成员 ID。不含 AI SRE。不会为 null；空数组表示没有人员负责人。", "items": { "format": "int64", "type": "integer" }, "type": "array" }, + "assignees": { + "description": "当前负责人。每项为 `{type, id?}`。`type` 取 `person` 或 `ai_sre`；`ai_sre` 不带 `id`。不会为 null；空数组表示未指派。`assignee_ids` 是其中仅含 `person` 的子集。", + "items": { + "$ref": "#/components/schemas/WorkItemAssignee" + }, + "type": "array" + }, "converted_at_seconds": { "description": "转化时间，Unix 秒级时间戳。仅转化后返回。", "format": "int64", @@ -28563,6 +28628,7 @@ "source_kind", "version", "assignee_ids", + "assignees", "created_by", "updated_by", "created_at_seconds", @@ -40265,6 +40331,20 @@ 4756301322131, 5068740052131 ], + "assignees": [ + { + "id": 3790925372131, + "type": "person" + }, + { + "id": 4756301322131, + "type": "person" + }, + { + "id": 5068740052131, + "type": "person" + } + ], "created_at_seconds": 1785495329, "created_by": 5329873302131, "incident_id": "6a5f1e28807515413b384bce", @@ -40321,7 +40401,7 @@ "On-call/故障管理" ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- 整体替换负责人集合 —— 空数组表示清空所有负责人。\n- 仅新添加的负责人会收到通知；移除不通知。\n- 已审计 —— 变更会记录到审计日志。", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- 整体替换负责人集合 —— 空数组表示清空所有负责人。\n- 使用 `assignees` 或旧版 `assignee_ids`。两者同时出现会报错。`ai_sre` 条目不带 `id`。\n- 仅新添加的负责人会收到通知；移除不通知。\n- 已审计 —— 变更会记录到审计日志。", "href": "/zh/api-reference/on-call/incidents/incident-work-item-reset-assignees", "metadata": { "sidebarTitle": "重置跟进事项负责人" @@ -40361,6 +40441,20 @@ 4756301322131, 5068740052131 ], + "assignees": [ + { + "id": 3790925372131, + "type": "person" + }, + { + "id": 4756301322131, + "type": "person" + }, + { + "id": 5068740052131, + "type": "person" + } + ], "created_at_seconds": 1785495329, "created_by": 5329873302131, "incident_id": "6a5f1e28807515413b384bce", @@ -40454,6 +40548,20 @@ 4756301322131, 5068740052131 ], + "assignees": [ + { + "id": 3790925372131, + "type": "person" + }, + { + "id": 4756301322131, + "type": "person" + }, + { + "id": 5068740052131, + "type": "person" + } + ], "created_at_seconds": 1785495329, "created_by": 5329873302131, "incident_id": "6a5f1e28807515413b384bce", @@ -40554,6 +40662,12 @@ "assignee_ids": [ 3790925372131 ], + "assignees": [ + { + "id": 3790925372131, + "type": "person" + } + ], "created_at_seconds": 1785496400, "created_by": 3790925372131, "incident_id": "6a5f1e28807515413b384bce", @@ -40606,7 +40720,7 @@ "On-call/故障管理" ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- `action` 锚定活动故障，且不得设置 `post_mortem_id`；`follow_up` 必须设置为关联到 `incident_id` 的故障复盘 ID。\n- 负责人须为已能查看锚定故障或复盘的活跃成员 —— 指派不会授予访问权限。\n- 新添加的负责人会收到通知。\n- 以相同的（`creator`、`idempotency_key`）重试时，返回原事项并标记 `idempotent_replay: true`，不会创建重复事项。\n- 已审计 —— 变更会记录到审计日志。", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- `action` 锚定活动故障，且不得设置 `post_mortem_id`；`follow_up` 必须设置为关联到 `incident_id` 的故障复盘 ID。\n- 使用 `assignees`（`person` 带 `id`，或 `ai_sre` 不带 `id`），或使用旧版 `assignee_ids`（全部为 `person`）。两者同时出现会报错。\n- 人员负责人须为已能查看锚定故障或复盘的活跃成员 —— 指派不会授予访问权限。\n- 新添加的负责人会收到通知。\n- 以相同的（`creator`、`idempotency_key`）重试时，返回原事项并标记 `idempotent_replay: true`，不会创建重复事项。\n- 已审计 —— 变更会记录到审计日志。", "href": "/zh/api-reference/on-call/incidents/incident-work-item-create", "metadata": { "sidebarTitle": "创建跟进事项" @@ -40717,6 +40831,20 @@ 4756301322131, 5068740052131 ], + "assignees": [ + { + "id": 3790925372131, + "type": "person" + }, + { + "id": 4756301322131, + "type": "person" + }, + { + "id": 5068740052131, + "type": "person" + } + ], "created_at_seconds": 1785495329, "created_by": 5329873302131, "incident_id": "6a5f1e28807515413b384bce", @@ -40734,6 +40862,12 @@ "assignee_ids": [ 5068740052131 ], + "assignees": [ + { + "id": 5068740052131, + "type": "person" + } + ], "created_at_seconds": 1785495164, "created_by": 3790925372131, "incident_id": "6a5f1e28807515413b384bce", @@ -40789,7 +40923,7 @@ "On-call/故障管理" ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障查看**（`on-call`） |\n\n## 使用说明\n\n- `incident_id`、`post_mortem_id`、`assignee_id` 至少提供一个。\n- 按 `updated_at_seconds` 倒序的游标分页 —— 将上一次响应的 `next_cursor` 作为 `cursor` 传入，直到 `has_more` 为 false。\n- 按 `incident_id` 查询时，同时包含锚定在该故障复盘上的后续行动。\n- 仅按 `assignee_id` 查询时，须为本人或账户管理员。", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障查看**（`on-call`） |\n\n## 使用说明\n\n- `incident_id`、`post_mortem_id`、`assignee_id`，或 `assignee_type` 为 `ai_sre`，至少满足一个。\n- `assignee_type` 为 `ai_sre` 时返回指派给 AI SRE 的事项，可单独作为查询条件。\n- 按 `updated_at_seconds` 倒序的游标分页 —— 将上一次响应的 `next_cursor` 作为 `cursor` 传入，直到 `has_more` 为 false。\n- 按 `incident_id` 查询时，同时包含锚定在该故障复盘上的后续行动。\n- 仅按 `assignee_id` 查询时，须为本人或账户管理员。", "href": "/zh/api-reference/on-call/incidents/incident-work-item-list", "metadata": { "sidebarTitle": "查询跟进事项列表" @@ -40830,6 +40964,20 @@ 4756301322131, 5068740052131 ], + "assignees": [ + { + "id": 3790925372131, + "type": "person" + }, + { + "id": 4756301322131, + "type": "person" + }, + { + "id": 5068740052131, + "type": "person" + } + ], "created_at_seconds": 1785495329, "created_by": 5329873302131, "incident_id": "6a5f1e28807515413b384bce", @@ -40847,6 +40995,12 @@ "assignee_ids": [ 5068740052131 ], + "assignees": [ + { + "id": 5068740052131, + "type": "person" + } + ], "created_at_seconds": 1785495164, "created_by": 3790925372131, "incident_id": "6a5f1e28807515413b384bce", @@ -40941,6 +41095,20 @@ 4756301322131, 5068740052131 ], + "assignees": [ + { + "id": 3790925372131, + "type": "person" + }, + { + "id": 4756301322131, + "type": "person" + }, + { + "id": 5068740052131, + "type": "person" + } + ], "created_at_seconds": 1785495329, "created_by": 5329873302131, "incident_id": "6a5f1e28807515413b384bce",