REST API

EnerOS REST API 遵循 RESTful 规范，使用标准 HTTP 方法语义，所有响应体为 JSON。端点由 eneros-api crate 提供，经 eneros-gateway 校验后转发至内核。每个端点都经过完整的鉴权、限流、审计链路。

通用约定

HTTP 方法语义

端点列表

分页、过滤、排序

分页参数

列表端点统一支持以下分页参数：

分页响应：

{
  "data": [/* ... */],
  "meta": {
    "page": 1,
    "page_size": 20,
    "total": 137,
    "total_pages": 7,
    "next_cursor": "eyJpZCI6Im5ldF94eHgifQ=="
  }
}

过滤参数

各端点支持的过滤字段示例：

排序参数

示例：?sort=-created_at&page=2&page_size=50

端点详解

健康检查

GET /api/v1/health 检查服务可用性，无需鉴权。

请求参数：无

响应字段：

cURL 示例：

curl http://localhost:8080/api/v1/health

响应示例：

{
  "data": {
    "status": "ok",
    "version": "0.47.0",
    "uptime_seconds": 86400,
    "checks": {
      "database": "ok",
      "timeseries": "ok",
      "eventbus": "ok",
      "realtime": "ok"
    }
  },
  "request_id": "req_20260706_001",
  "timestamp": "2026-07-06T08:30:00Z"
}

获取 Token

POST /api/v1/auth/token 通过用户名密码换取 Bearer Token。

请求参数：

cURL 示例：

curl -X POST http://localhost:8080/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin"}'

响应示例：

{
  "data": {
    "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "rft_20260706_abc123",
    "expires_in": 3600,
    "token_type": "Bearer"
  },
  "request_id": "req_20260706_002",
  "timestamp": "2026-07-06T08:30:00Z"
}

创建电网

POST /api/v1/networks 创建一个新的电网模型。

请求参数：

cURL 示例：

curl -X POST http://localhost:8080/api/v1/networks \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "IEEE-14",
    "base_kv": 110.0,
    "base_mva": 100.0,
    "buses": [
      {"id": 1, "type": "slack", "v": 1.05, "theta": 0.0},
      {"id": 2, "type": "pv", "v": 1.04},
      {"id": 3, "type": "pq"}
    ],
    "branches": [
      {"from": 1, "to": 2, "r": 0.01938, "x": 0.05917, "b": 0.0528}
    ],
    "generators": [
      {"bus": 1, "mw": 50.0, "mvar": 0.0}
    ],
    "loads": [
      {"bus": 3, "mw": 94.2, "mvar": 19.0}
    ],
    "tags": {"owner": "ieee", "scenario": "summer"}
  }'

Rust 示例：

use eneros_sdk::{ApiClient, models::NetworkInput};
use serde_json::json;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let client = ApiClient::builder()
        .endpoint("http://localhost:8080")
        .token("<bearer-token>")
        .build()?;

    let input = NetworkInput {
        name: "IEEE-14".to_string(),
        base_kv: Some(110.0),
        base_mva: Some(100.0),
        buses: vec![
            json!({"id": 1, "type": "slack", "v": 1.05, "theta": 0.0}),
            json!({"id": 2, "type": "pv", "v": 1.04}),
            json!({"id": 3, "type": "pq"}),
        ],
        branches: vec![
            json!({"from": 1, "to": 2, "r": 0.01938, "x": 0.05917, "b": 0.0528}),
        ],
        generators: vec![json!({"bus": 1, "mw": 50.0, "mvar": 0.0})],
        loads: vec![json!({"bus": 3, "mw": 94.2, "mvar": 19.0})],
        tags: json!({"owner": "ieee", "scenario": "summer"}),
        ..Default::default()
    };

    let network = client.networks().create(&input).await?;
    println!("created network: {}", network.id);
    Ok(())
}

Python 示例：

from eneros_sdk import ApiClient

client = ApiClient(
    endpoint="http://localhost:8080",
    token="<bearer-token>",
)

network = client.networks.create({
    "name": "IEEE-14",
    "base_kv": 110.0,
    "base_mva": 100.0,
    "buses": [
        {"id": 1, "type": "slack", "v": 1.05, "theta": 0.0},
        {"id": 2, "type": "pv", "v": 1.04},
        {"id": 3, "type": "pq"},
    ],
    "branches": [
        {"from": 1, "to": 2, "r": 0.01938, "x": 0.05917, "b": 0.0528},
    ],
    "generators": [{"bus": 1, "mw": 50.0, "mvar": 0.0}],
    "loads": [{"bus": 3, "mw": 94.2, "mvar": 19.0}],
    "tags": {"owner": "ieee", "scenario": "summer"},
})
print(f"created network: {network.id}")

响应示例：

{
  "data": {
    "id": "net_8f3a2b",
    "name": "IEEE-14",
    "description": "",
    "base_kv": 110.0,
    "base_mva": 100.0,
    "bus_count": 14,
    "branch_count": 20,
    "generator_count": 5,
    "load_count": 11,
    "status": "ready",
    "tags": {"owner": "ieee", "scenario": "summer"},
    "created_at": "2026-07-06T08:30:00Z",
    "updated_at": "2026-07-06T08:30:00Z"
  },
  "request_id": "req_20260706_003",
  "timestamp": "2026-07-06T08:30:00Z"
}

获取电网列表

GET /api/v1/networks 返回当前租户下的电网列表。

请求参数（Query）：

响应示例：

{
  "data": [
    {
      "id": "net_8f3a2b",
      "name": "IEEE-14",
      "bus_count": 14,
      "status": "ready",
      "created_at": "2026-07-06T08:30:00Z"
    },
    {
      "id": "net_9c4d1e",
      "name": "IEEE-30",
      "bus_count": 30,
      "status": "ready",
      "created_at": "2026-07-05T10:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "page_size": 20,
    "total": 2,
    "total_pages": 1
  },
  "request_id": "req_20260706_004",
  "timestamp": "2026-07-06T08:30:00Z"
}

触发潮流计算

POST /api/v1/networks/{id}/powerflow 触发一次潮流计算任务。

路径参数：

请求参数：

cURL 示例：

curl -X POST http://localhost:8080/api/v1/networks/net_8f3a2b/powerflow \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"method": "newton_raphson", "tolerance": 1e-8, "max_iterations": 50}'

响应示例（同步模式）：

{
  "data": {
    "task_id": "pf_20260706_001",
    "network_id": "net_8f3a2b",
    "status": "converged",
    "method": "newton_raphson",
    "iterations": 4,
    "duration_ms": 12,
    "tolerance": 1e-8,
    "buses": [
      {"id": 1, "v": 1.05, "theta": 0.0, "p_gen": 50.0, "q_gen": 12.5},
      {"id": 2, "v": 1.04, "theta": -0.039, "p_gen": 0.0, "q_gen": 0.0}
    ],
    "branches": [
      {"from": 1, "to": 2, "p_from": 50.0, "q_from": 12.5, "loading": 0.45}
    ],
    "losses": {"p_mw": 1.23, "q_mvar": 5.67},
    "started_at": "2026-07-06T08:30:00Z",
    "completed_at": "2026-07-06T08:30:00.012Z"
  },
  "request_id": "req_20260706_005",
  "timestamp": "2026-07-06T08:30:00Z"
}

响应示例（异步模式）：

{
  "data": {
    "task_id": "pf_20260706_002",
    "network_id": "net_8f3a2b",
    "status": "queued",
    "poll_url": "/api/v1/tasks/pf_20260706_002"
  },
  "request_id": "req_20260706_006",
  "timestamp": "2026-07-06T08:30:00Z"
}

创建 Agent

POST /api/v1/agents 创建并注册一个新的 Agent。

请求参数：

cURL 示例：

curl -X POST http://localhost:8080/api/v1/agents \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "DispatchAgent-01",
    "type": "dispatch",
    "network_id": "net_8f3a2b",
    "config": {"objective": "economic", "horizon_minutes": 15},
    "tools": ["powerflow", "topology", "forecast"],
    "reasoning_model": "default",
    "max_actions_per_minute": 30,
    "auto_start": true
  }'

JavaScript 示例：

import { ApiClient } from '@eneros/sdk';

const client = new ApiClient({
  endpoint: 'http://localhost:8080',
  token: '<bearer-token>',
});

const agent = await client.agents.create({
  name: 'DispatchAgent-01',
  type: 'dispatch',
  networkId: 'net_8f3a2b',
  config: { objective: 'economic', horizonMinutes: 15 },
  tools: ['powerflow', 'topology', 'forecast'],
  reasoningModel: 'default',
  maxActionsPerMinute: 30,
  autoStart: true,
});
console.log('created agent:', agent.id);

响应示例：

{
  "data": {
    "id": "agent_dispatch_01",
    "name": "DispatchAgent-01",
    "type": "dispatch",
    "network_id": "net_8f3a2b",
    "status": "running",
    "config": {"objective": "economic", "horizon_minutes": 15},
    "tools": ["powerflow", "topology", "forecast"],
    "reasoning_model": "default",
    "max_actions_per_minute": 30,
    "created_at": "2026-07-06T08:30:00Z",
    "started_at": "2026-07-06T08:30:01Z"
  },
  "request_id": "req_20260706_007",
  "timestamp": "2026-07-06T08:30:00Z"
}

下发 Agent 指令

POST /api/v1/agents/{id}/command 向 Agent 下发一条指令。

请求参数：

cURL 示例：

curl -X POST http://localhost:8080/api/v1/agents/agent_dispatch_01/command \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "set_generation",
    "params": {"bus": 2, "mw": 50.0},
    "priority": "normal",
    "timeout_ms": 5000,
    "await_result": true
  }'

响应示例：

{
  "data": {
    "command_id": "cmd_20260706_001",
    "agent_id": "agent_dispatch_01",
    "command": "set_generation",
    "status": "success",
    "result": {
      "bus": 2,
      "mw_set": 50.0,
      "constraint_checked": true,
      "audit_id": "aud_20260706_001"
    },
    "duration_ms": 12,
    "executed_at": "2026-07-06T08:30:00Z"
  },
  "request_id": "req_20260706_008",
  "timestamp": "2026-07-06T08:30:00Z"
}

时序数据查询

GET /api/v1/timeseries 查询时序数据，支持聚合与降采样。

请求参数（Query）：

cURL 示例：

curl -G http://localhost:8080/api/v1/timeseries \
  -H "Authorization: Bearer <token>" \
  --data-urlencode "metric=branch_loading" \
  --data-urlencode "tags=network:net_8f3a2b,branch:1-2" \
  --data-urlencode "from=2026-07-06T00:00:00Z" \
  --data-urlencode "to=2026-07-06T08:00:00Z" \
  --data-urlencode "aggregation=avg" \
  --data-urlencode "interval=5m"

Python 示例：

from eneros_sdk import ApiClient
from datetime import datetime, timezone, timedelta

client = ApiClient(endpoint="http://localhost:8080", token="<bearer-token>")

result = client.timeseries.query(
    metric="branch_loading",
    tags={"network": "net_8f3a2b", "branch": "1-2"},
    from_=datetime.now(timezone.utc) - timedelta(hours=8),
    to=datetime.now(timezone.utc),
    aggregation="avg",
    interval="5m",
)
for point in result.points:
    print(f"{point.timestamp} -> {point.value}")

响应示例：

{
  "data": {
    "metric": "branch_loading",
    "tags": {"network": "net_8f3a2b", "branch": "1-2"},
    "aggregation": "avg",
    "interval": "5m",
    "points": [
      {"timestamp": "2026-07-06T00:00:00Z", "value": 0.42},
      {"timestamp": "2026-07-06T00:05:00Z", "value": 0.45},
      {"timestamp": "2026-07-06T00:10:00Z", "value": 0.48}
    ],
    "count": 96
  },
  "request_id": "req_20260706_009",
  "timestamp": "2026-07-06T08:30:00Z"
}

批量写入时序

POST /api/v1/timeseries/batch 批量写入时序数据点，单次最多 10000 点。

请求参数：

cURL 示例：

curl -X POST http://localhost:8080/api/v1/timeseries/batch \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "points": [
      {"metric": "branch_loading", "timestamp": "2026-07-06T08:30:00Z", "value": 0.42, "tags": {"network": "net_8f3a2b", "branch": "1-2"}},
      {"metric": "bus_voltage", "timestamp": "2026-07-06T08:30:00Z", "value": 1.05, "tags": {"network": "net_8f3a2b", "bus": "1"}}
    ]
  }'

响应示例：

{
  "data": {
    "accepted": 2,
    "rejected": 0,
    "errors": []
  },
  "request_id": "req_20260706_010",
  "timestamp": "2026-07-06T08:30:00Z"
}

告警列表与确认

GET /api/v1/alarms 获取告警列表，PATCH /api/v1/alarms/{id}/ack 确认告警。

列表请求参数：

确认告警请求参数：

响应示例（列表）：

{
  "data": [
    {
      "id": "alm_001",
      "severity": "critical",
      "status": "active",
      "type": "BRANCH_OVERLOAD",
      "message": "Branch 1-2 overload: 105% of limit",
      "network_id": "net_8f3a2b",
      "source": {"type": "constraint_engine", "id": "ce_01"},
      "details": {"branch_id": "1-2", "loading": 1.05, "limit": 1.0},
      "raised_at": "2026-07-06T08:30:00Z",
      "acknowledged_at": null,
      "cleared_at": null
    }
  ],
  "meta": {"page": 1, "page_size": 20, "total": 1, "total_pages": 1},
  "request_id": "req_20260706_011",
  "timestamp": "2026-07-06T08:30:00Z"
}

审计日志查询

GET /api/v1/audit 查询操作审计日志，需要审计权限。

请求参数：

响应示例：

{
  "data": [
    {
      "id": "aud_20260706_001",
      "timestamp": "2026-07-06T08:30:00Z",
      "actor": {"type": "user", "id": "admin", "tenant": "default"},
      "action": "agent.command",
      "resource": {"type": "agent", "id": "agent_dispatch_01"},
      "request_id": "req_20260706_008",
      "ip": "192.168.1.10",
      "user_agent": "curl/7.88.1",
      "result": "success",
      "details": {"command": "set_generation", "params": {"bus": 2, "mw": 50.0}}
    }
  ],
  "meta": {"page": 1, "page_size": 50, "total": 1, "total_pages": 1},
  "request_id": "req_20260706_012",
  "timestamp": "2026-07-06T08:30:00Z"
}

错误码

通用错误码

业务错误码

错误响应体统一格式：

{
  "error": {
    "code": "CONSTRAINT_VIOLATION",
    "message": "Branch 1-2 overload: 105% of limit",
    "details": {"branch_id": "1-2", "loading": 1.05, "limit": 1.0},
    "trace_id": "trace_abc123",
    "doc_url": "https://docs.openeneros.com/api-reference/rest#错误码"
  },
  "request_id": "req_20260706_008"
}

字段枚举值说明

NetworkStatus

AgentType

AgentStatus

PowerFlowMethod

BusType

DeviceType

批量操作

除时序写入外，REST API 还支持以下批量端点：

批量请求统一返回每个条目的独立结果：

{
  "data": {
    "succeeded": [{"index": 0, "id": "net_a"}, {"index": 1, "id": "net_b"}],
    "failed": [{"index": 2, "error": {"code": "VALIDATION_FAILED", "message": "invalid bus"}}]
  }
}

相关文档

• API 总览 — 四种 API 对比
• GraphQL — 灵活查询替代方案
• 限流与配额 — 速率限制策略
• 版本管理 — API 版本演进
• eneros-api crate — API 服务实现