API 文档 - AetherGate

认证方式

所有 API 请求需要在 HTTP Header 中携带 API Key 进行鉴权：

X-API-Key: your-api-key-here
Content-Type: application/json

💡 API Key 可在控制台「系统设置」页面获取

日志上传接口

POST /api/logs

上传单条日志记录到服务器

请求参数

参数	类型	必填	说明
device_id	string	是	设备唯一标识符（UUID）
category	string	是	分类：Runtime / Feature / Error / Performance
name	string	是	事件名称
data	object	否	附加数据（键值对）
timestamp	datetime	否	事件时间（默认服务器当前时间）
app_version	string	否	应用版本号
os_info	string	否	操作系统信息

请求示例

POST /api/logs HTTP/1.1
Host: your-domain.com
X-API-Key: abc123def456...
Content-Type: application/json

{
    "device_id": "6abf36f0-08fd-fc02-c7ed-d176e3335b28",
    "category": "Feature",
    "name": "UserLogin",
    "data": {
        "login_method": "cookie",
        "user_id": 12345,
        "success": true
    },
    "app_version": "1.2.0",
    "os_info": "Windows 11 Pro"
}

响应示例

{
    "code": 0,
    "msg": "success",
    "data": {
        "log_id": 1001
    }
}

批量日志上传

POST /api/logs/batch

批量上传多条日志（推荐，减少请求次数）

请求体格式

{
    "logs": [
        {
            "device_id": "6abf36f0-...",
            "category": "Runtime",
            "name": "Start",
            "data": { "boot_time": 120 }
        },
        {
            "device_id": "6abf36f0-...",
            "category": "Feature",
            "name": "GameLaunch",
            "data": { "game_id": "game001" }
        }
    ]
}

💡 单次批量请求建议不超过 100 条日志

心跳保活接口

POST /api/heartbeat

客户端定期上报心跳，用于在线设备统计

请求参数

参数	类型	必填	说明
device_id	string	是	设备唯一标识符
status	string	否	状态：running / idle / error

心跳间隔建议

建议每 5-10 秒发送一次心跳，服务器将在 30 秒内无心跳判定为离线。

错误码说明

状态码	HTTP Code	说明
0	200	请求成功
400	400	请求参数错误
403	403	API Key 无效或已禁用
429	429	请求过于频繁（触发限流）
500	500	服务器内部错误

C# 客户端示例

using System.Net.Http;
using System.Text.Json;

public class LogClient
{
    private readonly HttpClient _httpClient;
    private readonly string _apiKey;

    public LogClient(string baseUrl, string apiKey)
    {
        _httpClient = new HttpClient { BaseAddress = new Uri(baseUrl) };
        _httpClient.DefaultRequestHeaders.Add("X-API-Key", apiKey);
        _apiKey = apiKey;
    }

    public async Task TrackFeatureAsync(string deviceId, string featureName, object data = null)
    {
        var payload = new
        {
            device_id = deviceId,
            category = "Feature",
            name = featureName,
            data = data ?? new { }
        };

        var json = JsonSerializer.Serialize(payload);
        var content = new StringContent(json, Encoding.UTF8, "application/json");
        await _httpClient.PostAsync("/api/logs", content);
    }
}

🔌 API 文档

认证方式

日志上传接口

请求参数

请求示例

响应示例

批量日志上传

请求体格式

心跳保活接口

请求参数

心跳间隔建议

错误码说明

C# 客户端示例