变更 Event

title: "变更 Event"
description: "Flashduty 变更 Event API 文档。"
date: "2024-11-20T10:00:00+08:00"
url: "https://developer.flashcat.cloud/zh/flashduty/event-api/change-event"

通过标准 API 推送自有系统变更事件到快猫星云，大部分故障由变更导致，变更和告警事件联动有助于快速定位故障原因。

请求描述

请求方式

POST, Content-Type:"application/json"

请求参数：

QueryString 必须需要包含参数 integration_key，用于访问控制。

JsonBody 参数如下：

字段	必含	类型	释义
change_status	是	string	变更 event 状态，枚举值：Planned：已提单，Ready：即将（或计划）开始，Processing：进行中，Canceled：已取消（或回滚），Done：已完成。不要求全部状态都上报，可选择性上报
change_key	是	string	变更唯一 key，一般是变更单号。用于将不同的变更 event 合并至一个变更
title	是	string	变更 title
event_time	否	int64	变更 event 发生时间戳，单位“秒”，如果 change_status 为 Ready 状态，可以上报未来时间；如果不传，则使用当前时间
description	否	string	变更描述，不超过 2048 个字符
link	否	string	变更单地址，用于跳转到变更详情
labels	否	map	变更标签集合，key 为标签名称，value 为标签值。标签是事件的描述，用于后续的关联，非常重要。1. 标签的 key 和 value 均为 string 类型，区分大小写。2. 标签的 key 不要超过 128 个字符。3. 至多传入 50 个标签。`标签内容参考`最佳实践

请求响应

Body:

参数名称	必选	类型	描述
request_id	是	string	请求 trace id，用于问题追踪
error	否	Error	错误描述，仅当出现错误时返回

Error:

参数名称	可选	类型	描述
code	是	string	错误码
message	是	string	错误描述

Code:

错误码	HTTP Status	描述
InvalidParameter	400	参数错误
InvalidContentType	400	Conten-Type 不支持
MethodNotAllowed	400	http method 不支持
Unauthorized	401	登录认证失败
AccessDenied	403	权限认证失败
RequestTooFrequently	429	请求过于频繁
RouteNotFound	404	请求Method+Path未匹配
ResourceNotFound	400	账户未购买资源，前往费用中心线操作下单
InternalError	500	内部或未知错误

请求示例

请求：

curl -X POST 'https://api.flashcat.cloud/event/push/change/standard?integration_key=$key' \
-H 'Content-Type: application/json' \
-d '{
    "change_status": "Done",
    "change_key": "CHANGE-002",
    "description": "进度100%",
    "title": "双12活动",
    "labels": {
        "service": "flashcat",
        "cluster":"nj"
    },
    "link": "http://jira.flashcat.cloud/CHANGE-001"
}'

成功响应：

{
    "request_id": "0ace00116215ab4ca0ec5244b8fc54b0"
}

失败响应：

{
    "request_id": "0ace00116215abc0ba4e52449bd305b0",
    "error": {
        "code": "InvalidParameter",
        "message": "integration_key $key is not a valid one"
    }
}

最佳实践

标签是事件的描述，应尽量丰富标签内容，比如：

变更的应用范围，如 host，cluster 等
变更的归属信息，如 team，owner 等

最后修改时间： 13 小时前