API 文档

API 概览

PodOD 提供完整的 RESTful API，支持所有核心功能的编程访问。API 使用 JSON 格式进行数据交换，支持标准的 HTTP 状态码。

基础信息

  • Base URL: https://your-server:8080/api/v1
  • 协议: HTTPS
  • 数据格式: JSON
  • 认证方式: Bearer Token

HTTP 状态码

状态码 说明
200 请求成功
201 创建成功
400 请求参数错误
401 未授权
404 资源不存在
500 服务器内部错误

认证

POST /auth/login
用户登录，获取访问令牌

请求参数

参数 类型 必填 说明
username string 是 用户名
password string 是 密码

请求示例

{
  "username": "admin",
  "password": "admin123"
}

响应示例

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600
}

资产管理

GET /assets
获取资产列表，支持分页和筛选

查询参数

参数 类型 必填 说明
page int 否 页码，默认 1
limit int 否 每页数量，默认 20
status string 否 状态筛选：online, offline, risk
os_type string 否 操作系统类型

响应示例

{
  "success": true,
  "data": {
    "total": 150,
    "page": 1,
    "limit": 20,
    "assets": [
      {
        "id": 1,
        "hostname": "PC-001",
        "ip_address": "192.168.1.100",
        "os_name": "Windows 11 Pro",
        "status": "online",
        "last_seen": "2026-01-25T10:30:00Z"
      }
    ]
  }
}
GET /assets/{id}
获取指定资产的详细信息

响应示例

{
  "success": true,
  "data": {
    "id": 1,
    "hostname": "PC-001",
    "hardware": {
      "cpu": "Intel Core i7-12700K",
      "memory_gb": 32,
      "storage_gb": 1024
    },
    "software_count": 85,
    "security_status": "good"
  }
}

软件资产

GET /software
获取软件资产列表，支持按资产ID筛选

查询参数

参数 类型 必填 说明
asset_id int 否 资产ID，筛选特定资产的软件
name string 否 软件名称搜索
publisher string 否 发布商筛选

分组管理

POST /groups
创建新的资产分组

请求参数

参数 类型 必填 说明
name string 是 分组名称
description string 否 分组描述
rules array 否 自动分组规则

请求示例

{
  "name": "开发部门",
  "description": "开发部门的所有设备",
  "rules": [
    {
      "field": "hostname",
      "operator": "contains",
      "value": "DEV-"
    }
  ]
}

Webhook

PodOD 支持 Webhook，可以在特定事件发生时向您的应用程序发送通知。

支持的事件

  • asset.created - 新资产发现
  • asset.updated - 资产信息更新
  • asset.offline - 资产离线
  • security.alert - 安全告警
  • software.installed - 软件安装
  • software.uninstalled - 软件卸载
POST /webhooks
创建 Webhook 订阅

请求示例

{
  "url": "https://your-app.com/webhook",
  "events": ["asset.created", "security.alert"],
  "secret": "your-webhook-secret"
}