跳转到主要内容

​
一、功能概述

上报告警时，您可以在 标准告警 的 images 字段中携带图片，用于在前端及飞书、钉钉应用通知中展示告警相关截图。images 中每张图片的 src 支持两种取值：
  • http/https 开头的公网可访问图片链接；
  • 通过本接口上传图片后返回的 image_key。
当图片没有公网链接时，可先调用图片上传接口上传图片，拿到 image_key，再在上报告警时引用。工作流程如下：
  1. 调用图片上传接口，上传图片文件，获得 image_key；
  2. 上报标准告警时，将 image_key 填入 images[].src；
  3. Flashduty 在处理告警时解析 image_key，将图片关联到告警并持久化展示。
图片上传与标准告警上报共用同一个集成秘钥（integration_key）。请使用您在 标准告警 等集成中获取的推送秘钥，无需单独申请。

​
二、接口说明

​
请求方式

POST，Content-Type: multipart/form-data

​
请求地址

{api_host}/push/image/upload?integration_key={integration_key}
其中 {api_host} 为 Flashduty 的接入域名，公有云默认为 https://api.flashcat.cloud，与您的告警推送地址保持一致。

​
请求参数

Query 参数：
参数必含类型释义
integration_key是string集成秘钥，用于确定账户。添加集成后获得，与告警推送共用同一个秘钥。
Form-Data 参数：
参数必含类型释义
image是file待上传的图片文件，单文件最大 5MB。系统根据文件内容（而非扩展名）识别格式，支持的格式见下表。
支持的图片格式：
格式Content-Type
JPEGimage/jpeg、image/jpg
PNGimage/png
WebPimage/webp
GIFimage/gif
TIFFimage/tiff、image/tif
BMPimage/bmp
ICOimage/x-icon、image/vnd.microsoft.icon

​
请求响应

字段名称必选类型描述
request_id是string请求 ID，用于链路追踪
error否Error错误描述，仅当出现错误时返回
data否Data上传结果
Data：
字段名称必选类型描述
image_key是string图片标识，形如 img_<hash>。在上报标准告警时填入 images[].src 即可引用该图片。
Error：
字段名称必选类型描述
code是string错误码，枚举值参考 Code
message否string错误描述
Code：
错误码HTTP Status描述
InvalidParameter400参数错误，如缺少 image 文件、图片格式不支持或文件超过 5MB
Unauthorized401integration_key 缺失或无效，或集成、账户已被禁用
RequestTooFrequently429请求过于频繁，超过频率限制
InternalError500内部或未知错误

​
频率限制

为保护服务稳定，图片上传按账户限流：
  • 每账户每秒最多 5 次；
  • 每账户每分钟最多 50 次。
超过限制时返回 RequestTooFrequently（HTTP 429）。

​
三、请求示例

请求： 
curl -X POST '{api_host}/push/image/upload?integration_key={integration_key}' \
  -F 'image=@/path/to/screenshot.png'
成功响应： 
{
    "request_id": "0ace00116215ab4ca0ec5244b8fc54b0",
    "data": {
        "image_key": "img_8f3a9c2b1e4d5f6a7b8c9d0e1f2a3b4c"
    }
}

​
四、在告警中引用图片

拿到 image_key 后，在上报 标准告警 时，将其填入 images 数组中某张图片的 src 字段即可： 
{
    "event_status": "Warning",
    "title_rule": "cpu idle low than 20%",
    "labels": {
        "service": "engine"
    },
    "images": [
        {
            "alt": "CPU 使用率截图",
            "src": "img_8f3a9c2b1e4d5f6a7b8c9d0e1f2a3b4c"
        }
    ]
}
images 与 image 结构体的完整字段说明，请参考 标准告警 - image 结构体。
  • image_key 在 images[].src 中的长度限制为 256 字符，超长会被丢弃。
  • 上传后的图片先临时存储，被告警引用后才会转为长期存储。请在上传后及时将 image_key 用于告警上报。

​
五、常见问题

  1. 重复上传同一张图片会怎样？
    • 系统按图片内容去重。上传内容完全相同的图片会返回相同的 image_key，不会重复占用存储。
  2. 可以直接使用图片的公网链接吗？
    • 可以。如果图片已有 http/https 公网可访问链接，无需上传，直接将链接填入 images[].src 即可。图片上传接口仅用于没有公网链接的场景。
  3. image_key 可以跨账户使用吗？
    • 不可以。image_key 与上传时所用 integration_key 归属的账户绑定，仅在同一账户内有效。