Safeline开放平台报告管理API详解与使用指南

前言

Safeline开放平台提供了一套完整的报告管理API，允许开发者通过编程方式管理安全报告订阅、生成和查询。本文将深入解析这些API的功能和使用方法，帮助开发者快速集成报告管理功能到自己的系统中。

报告订阅管理API

获取报告订阅列表

通过GET请求可以获取当前所有的报告订阅配置，该API支持分页功能，适合处理大量订阅记录的情况。

响应示例：

{
    "data": [
        {
            "id": 5,
            "name": "foobar",
            "type": "day",
            "targets": ["https://foobar.com"],
            "create_time": "1544513554"
        }
    ]
}

关键字段说明：

• type：报告周期类型，支持day(日)、week(周)、month(月)
• targets：报告发送的目标地址列表
• create_time：订阅创建时间戳

创建报告订阅

使用POST请求可以创建新的报告订阅，需要提供必要的配置信息。

请求参数：

{
    "name": "foobar",
    "targets": ["https://foobar.com"],
    "type": "day"
}

参数验证规则：

• name：必填，字符串类型
• type：必填，必须是['day', 'week', 'month']中的一个
• targets：可选，默认为空列表，每个元素必须是有效的URL

最佳实践建议：

1. 为每个订阅设置具有描述性的name，便于后续管理
2. 定期检查targets的有效性，确保报告能正确送达
3. 根据实际需求选择合适的报告周期类型

删除报告订阅

DELETE请求用于删除不再需要的报告订阅，支持批量删除。

请求示例：

{
    "id": [4]
}

注意事项：

• 删除操作不可逆，请谨慎操作
• 支持一次删除多个订阅，只需在id数组中添加多个ID
• 删除成功后，系统将停止生成该订阅对应的报告

手动报告生成API

手动生成报告

POST请求允许用户手动触发报告生成过程，适用于需要即时报告的场景。

请求参数：

{
    "name": "foobar",
    "targets": [],
    "time_range": "1541001600-1541087999",
    "sync": true,
    "type": "day"
}

参数详解：

• time_range：必填，格式为"开始时间戳-结束时间戳"
• sync：可选，默认为false，设为true可同步等待报告生成完成
• type：支持['day', 'week', 'custom', 'month']四种类型

使用场景：

1. 紧急安全事件后需要立即生成分析报告
2. 自定义时间段的安全态势分析
3. 临时性的报告需求，无需创建长期订阅

报告结果管理API

查询报告结果

GET请求用于查询已生成的报告列表，支持多种过滤条件和分页。

请求示例：

{
    "type": ["custom", "day"],
    "name__like": ["f"]
}

过滤条件说明：

• type：按报告类型过滤
• name__like：按报告名称模糊匹配
• timestamp__range：按时间范围过滤

响应处理建议：

1. 检查state字段了解报告生成状态(Pending/Completed/Failed)
2. 对于大量报告结果，务必使用分页功能
3. 结合时间范围过滤可以提高查询效率

删除报告结果

DELETE请求用于清理不再需要的报告结果，释放存储空间。

请求示例：

{
    "id": [2]
}

存储管理建议：

1. 定期清理旧报告，保留重要时间节点的报告即可
2. 删除前确保报告已备份或不再需要
3. 可以考虑实现自动清理策略，如保留最近30天的报告

总结

Safeline开放平台的报告管理API提供了完整的报告生命周期管理能力，从订阅配置到生成查询再到清理维护。开发者可以根据实际业务需求，灵活组合使用这些API，构建自动化的安全报告管理系统。对于关键业务场景，建议实现适当的错误处理和重试机制，确保报告服务的可靠性。