运维监控API集成说明结构化提示词

角色定义

你是一名系统运维架构师，具备API设计与技术文档编写经验。你的任务是基于运维监控系统（如Zabbix、Prometheus、Grafana等）的实际集成需求，生成一套结构清晰、符合业界规范的API集成说明提示词方案。输出需让开发者或运维人员能够直接理解接口调用方式、参数规则及错误处理逻辑，降低集成门槛。

适用场景

• 编写运维监控平台对外提供的RESTful API集成文档
• 为内部团队或第三方系统快速生成标准化接口接入指南
• 配合AI绘图工具（如Midjourney、DALL·E）生成API集成架构图或时序图的描述文本
• 作为提示词模板用于AI大模型（如ChatGPT、Claude）的持续调优和上下文管理

核心提示词

• “请以系统运维API集成说明文档的口气，描述一个用于获取监控告警列表的接口，包括：请求URL、HTTP方法、认证方式（API Key）、必填与可选参数、返回数据字段结构（JSON格式）、状态码含义（200, 400, 401, 500）以及限流说明（每分钟100次）。”
• “生成一段提示词，定义Prometheus Alertmanager API的集成步骤：配置Webhook接收器、设置告警路由规则、测试连通性，并附带一个curl示例。”
• “用结构化列表形式输出Zabbix API的token获取流程：请求地址 /api_jsonrpc.php，方法 user.login，参数 user/password，返回 result 中的 auth 令牌，以及后续请求中的 auth 必填字段。”
• “为运维监控系统的健康检查端点编写提示词：端点 /health，方法 GET，返回 { status: ‘ok’, version: ‘2.1.0’, uptime: 123456 }，并说明超时设置（5秒）与重试策略（3次，间隔1秒）。”

风格方向

• 技术文档体：客观、精确、无冗余，使用第三人称和被动语态（如“该接口需要携带Authorization头”）
• 结构化清单体：每个接口按“端点 → 方法 → 认证 → 参数 → 响应 → 错误码 → 示例”排列
• 干净代码风格：示例部分采用等宽字体（在提示词中可用反引号包裹），缩进清晰
• 避免口语化描述，所有说法均贴合RFC规范（如使用“HTTP Status 429 Too Many Requests”而非“访问太频繁”）

构图建议

• 若用于生成系统架构图，可提示：“绘制一张API集成拓扑图，左侧为外部监控系统（Grafana），中间为API Gateway，右侧为内部告警服务，标注数据流方向（请求 → 认证 → 路由 → 响应）。” 补充元素：防火墙、负载均衡、日志记录节点。
• 若用于生成时序图，提示词可写：“生成一个健康检查时序图，客户端依次发送GET /health请求，API Gateway校验Token，后端服务返回JSON响应，超时场景下显示504错误。” 注意使用PlantUML或Mermaid语法。
• 若用于生成数据模型图，提示词为：“以UML类图方式展示告警对象包含字段：id, severity, status, timestamp, source，标注字段类型和约束条件。”

细节强化

• 在认证部分，明确给出Header示例：Authorization: Bearer {your_api_key} 或 X-API-Key: 12345
• 在参数描述中，区分必填（required）与可选（optional），并列出默认值（如 page_size 默认20，最大100）
• 对每个错误码给出简短描述和调试建议，例如：“401 Unauthorized：请检查API Key是否过期或未在请求头中携带。500 Internal Server Error：请联系运维人员查看后端日志。”
• 限制说明要量化：“速率限制：每个API Key每分钟最多150次请求，超出后返回429状态码，响应头包含 Retry-After 字段。”
• 版本控制：在提示词中加入版本号字段（如 Accept: application/vnd.monitor.v1+json），便于向后兼容

使用建议

• 将以上核心提示词直接粘贴到AI绘画工具（如Midjourney、DALL·E）中，可配合附加词“architecture diagram, clean layout, blue and green color scheme”生成可视化集成图。
• 在AI对话工具（如ChatGPT、Claude）中，先用角色定义部分设定上下文，再逐条使用核心提示词，可获得结构统一、可直接复制粘贴的API说明文本。
• 若用于编写正式文档，建议将这些提示词作为Markdown或Notion模板的骨架，替换具体的接口名称和参数值后即可发布。
• 为保证提示词质量，每次使用时请在末尾添加“请用中文输出，并用表格形式展示请求参数”等追加约束，提升可读性。