Skip to content

api.md

Latest commit

 

History

History
302 lines (233 loc) · 6.68 KB

api.md

File metadata and controls

302 lines (233 loc) · 6.68 KB

API接口文档

概述

MCP Commute Assistant API 提供了完整的通勤信息服务接口，支持路线查询、定时任务管理和系统监控等功能。

基础信息

  • Base URL: http://localhost:8000
  • API版本: v1.0.0
  • 协议: HTTP/HTTPS
  • 数据格式: JSON

认证方式

当前版本API无需认证，但在生产环境中建议添加API密钥认证。

错误响应格式

{
  "error": "错误描述",
  "detail": "详细错误信息",
  "timestamp": "2024-01-01T12:00:00.000Z"
}

API端点详解

1. 健康检查

GET /health

检查服务健康状态

响应示例:

{
  "status": "healthy",
  "timestamp": "2024-01-01T12:00:00.000Z",
  "checks": {
    "amap_api": {
      "status": "healthy",
      "response_time": "normal"
    },
    "dingtalk_api": {
      "status": "healthy"
    }
  }
}

2. 通勤检查

POST /commute/check

手动触发通勤检查任务

请求示例:

curl -X POST http://localhost:8000/commute/check

响应示例:

{
  "message": "通勤检查任务已启动",
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "started",
  "timestamp": "2024-01-01T12:00:00.000Z"
}

3. 任务状态查询

GET /commute/status/{task_id}

查询指定任务的执行状态

路径参数:

  • task_id (string, required): 任务ID

响应示例:

{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "SUCCESS",
  "result": {
    "status": "success",
    "timestamp": "2024-01-01T12:05:00.000Z",
    "route_info": {
      "distance": 15000,
      "duration": 1800,
      "traffic_lights": 8
    },
    "notification_sent": true
  },
  "timestamp": "2024-01-01T12:05:01.000Z"
}

状态说明:

  • PENDING: 任务等待执行
  • STARTED: 任务正在执行
  • SUCCESS: 任务执行成功
  • FAILURE: 任务执行失败
  • REVOKED: 任务被撤销

4. 配置信息（开发环境）

GET /config/info

获取当前配置信息（仅开发环境可用）

响应示例:

{
  "config": {
    "app_env": "development",
    "debug": true,
    "log_level": "DEBUG",
    "amap_origin": "116.481485,39.990464",
    "amap_destination": "116.481485,39.990464",
    "redis_host": "localhost",
    "redis_port": 6379
  },
  "timestamp": "2024-01-01T12:00:00.000Z"
}

5. 测试通知（开发环境）

POST /test/notification

发送测试通知消息（仅开发环境可用）

响应示例:

{
  "message": "测试通知发送成功",
  "result": {
    "errcode": 0,
    "errmsg": "ok",
    "msgid": "test_message_id"
  },
  "timestamp": "2024-01-01T12:00:00.000Z"
}

WebSocket支持（可选）

实时通知订阅

const ws = new WebSocket('ws://localhost:8000/ws/notifications');

ws.onmessage = function(event) {
    const data = JSON.parse(event.data);
    console.log('收到通知:', data);
};

ws.onopen = function(event) {
    console.log('WebSocket连接已建立');
};

SDK使用示例

Python客户端

import requests
import time

class CommuteAssistantClient:
    def __init__(self, base_url="http://localhost:8000"):
        self.base_url = base_url
    
    def check_health(self):
        """检查服务健康状态"""
        response = requests.get(f"{self.base_url}/health")
        return response.json()
    
    def trigger_commute_check(self):
        """触发通勤检查"""
        response = requests.post(f"{self.base_url}/commute/check")
        return response.json()
    
    def get_task_status(self, task_id):
        """获取任务状态"""
        response = requests.get(f"{self.base_url}/commute/status/{task_id}")
        return response.json()
    
    def wait_for_completion(self, task_id, timeout=300):
        """等待任务完成"""
        start_time = time.time()
        while time.time() - start_time < timeout:
            status = self.get_task_status(task_id)
            if status['status'] in ['SUCCESS', 'FAILURE']:
                return status
            time.sleep(5)
        raise TimeoutError("任务执行超时")

# 使用示例
client = CommuteAssistantClient()

# 检查健康状态
health = client.check_health()
print(f"服务状态: {health['status']}")

# 触发通勤检查
result = client.trigger_commute_check()
task_id = result['task_id']
print(f"任务ID: {task_id}")

# 等待任务完成
final_status = client.wait_for_completion(task_id)
print(f"最终状态: {final_status['status']}")

JavaScript客户端

class CommuteAssistantClient {
    constructor(baseUrl = 'http://localhost:8000') {
        this.baseUrl = baseUrl;
    }
    
    async checkHealth() {
        const response = await fetch(`${this.baseUrl}/health`);
        return await response.json();
    }
    
    async triggerCommuteCheck() {
        const response = await fetch(`${this.baseUrl}/commute/check`, {
            method: 'POST'
        });
        return await response.json();
    }
    
    async getTaskStatus(taskId) {
        const response = await fetch(`${this.baseUrl}/commute/status/${taskId}`);
        return await response.json();
    }
    
    async waitForCompletion(taskId, timeout = 300000) {
        const startTime = Date.now();
        while (Date.now() - startTime < timeout) {
            const status = await this.getTaskStatus(taskId);
            if (['SUCCESS', 'FAILURE'].includes(status.status)) {
                return status;
            }
            await new Promise(resolve => setTimeout(resolve, 5000));
        }
        throw new Error('任务执行超时');
    }
}

// 使用示例
const client = new CommuteAssistantClient();

async function main() {
    try {
        // 检查健康状态
        const health = await client.checkHealth();
        console.log('服务状态:', health.status);
        
        // 触发通勤检查
        const result = await client.triggerCommuteCheck();
        const taskId = result.task_id;
        console.log('任务ID:', taskId);
        
        // 等待任务完成
        const finalStatus = await client.waitForCompletion(taskId);
        console.log('最终状态:', finalStatus.status);
        
    } catch (error) {
        console.error('操作失败:', error);
    }
}

main();

限流和配额

为了保证服务稳定性，API实施以下限制：

  • 健康检查: 无限制
  • 通勤检查: 每小时最多10次
  • 任务查询: 每分钟最多60次
  • 配置查询: 仅开发环境，无限制

超过限制的请求将返回429状态码。

版本兼容性

当前API版本为v1.0.0，后续版本将保持向后兼容性。重大变更将在文档中明确标注。

联系和支持

如有问题，请提交Issue或联系项目维护者。