Spaces:

fromozu
/

stock-analysis

Build error

App Files Files Community

stock-analysis / API_USAGE_GUIDE.md

fromozu

Auto-deploy from GitHub Actions - 6ea75c7

a105470 verified 11 months ago

preview code

raw

history blame contribute delete

8.98 kB

A newer version of the Gradio SDK is available: 6.16.0

Upgrade

股票分析系统 API 使用指南

概述

本指南详细介绍如何使用股票分析系统的RESTful API接口，包括认证、请求格式、响应处理和错误处理等。

快速开始

1. 获取API密钥

联系系统管理员获取API密钥，或使用默认测试密钥：

X-API-Key: UZXJfw3YNX80DLfN

2. 基础请求格式

所有API请求都需要包含以下头部：

Content-Type: application/json
X-API-Key: your_api_key_here

3. 基础URL

http://your-domain.com/api/v1

核心API端点

1. 投资组合分析

端点: POST /api/v1/portfolio/analyze

功能: 分析投资组合的整体表现和风险

请求示例:

curl -X POST "http://localhost:8888/api/v1/portfolio/analyze" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: UZXJfw3YNX80DLfN" \
  -d '{
    "stocks": [
      {
        "stock_code": "000001.SZ",
        "weight": 0.4,
        "market_type": "A"
      },
      {
        "stock_code": "600000.SH",
        "weight": 0.6,
        "market_type": "A"
      }
    ],
    "analysis_params": {
      "risk_preference": "moderate",
      "time_horizon": "medium"
    }
  }'

响应示例:

{
  "success": true,
  "data": {
    "portfolio_score": 75.5,
    "risk_level": "中等风险",
    "risk_analysis": {
      "volatility_risk": 65.2,
      "concentration_risk": 45.8,
      "correlation_risk": 55.3,
      "overall_risk_score": 55.4
    },
    "recommendations": [
      "投资组合表现良好，可适当调整优化",
      "根据您的保守风险偏好，建议降低组合风险"
    ],
    "individual_stocks": [
      {
        "stock_code": "000001.SZ",
        "stock_name": "平安银行",
        "score": 78.2,
        "weight": 0.4,
        "contribution": 31.28,
        "risk_level": "中等",
        "recommendation": "买入"
      }
    ]
  },
  "meta": {
    "analysis_time": "2025-01-03T10:30:00Z",
    "processing_time_ms": 1250,
    "cache_hit": false
  }
}

2. 个股分析

端点: POST /api/v1/stock/analyze

功能: 分析单只股票的详细信息

请求示例:

curl -X POST "http://localhost:8888/api/v1/stock/analyze" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: UZXJfw3YNX80DLfN" \
  -d '{
    "stock_code": "000001.SZ",
    "market_type": "A",
    "analysis_depth": "full",
    "include_ai_analysis": true
  }'

响应示例:

{
  "success": true,
  "data": {
    "stock_info": {
      "stock_code": "000001.SZ",
      "stock_name": "平安银行",
      "industry": "银行",
      "market_type": "A"
    },
    "analysis_result": {
      "overall_score": 78.5,
      "technical_score": 75.2,
      "fundamental_score": 82.1,
      "capital_flow_score": 77.8
    },
    "technical_analysis": {
      "trend": "上升",
      "support_levels": [12.50, 12.20],
      "resistance_levels": [13.80, 14.20],
      "indicators": {
        "rsi": 65.2,
        "macd_signal": "买入",
        "ma_trend": "多头排列"
      }
    },
    "fundamental_analysis": {
      "pe_ratio": 5.8,
      "pb_ratio": 0.65,
      "roe": 12.5,
      "debt_ratio": 45.2
    },
    "risk_assessment": {
      "risk_level": "中等",
      "volatility": 25.3,
      "total_risk_score": 45.2
    },
    "ai_analysis": {
      "summary": "该股票基本面良好，技术面呈现上升趋势...",
      "recommendation": "建议买入",
      "confidence": 0.85
    }
  }
}

3. 批量股票评分

端点: POST /api/v1/stocks/batch-score

功能: 批量分析多只股票的评分

请求示例:

curl -X POST "http://localhost:8888/api/v1/stocks/batch-score" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: UZXJfw3YNX80DLfN" \
  -d '{
    "stock_codes": ["000001.SZ", "600000.SH", "000002.SZ"],
    "market_type": "A",
    "min_score": 60,
    "sort_by": "score",
    "sort_order": "desc"
  }'

4. 异步任务管理

创建任务: POST /api/v1/tasks

curl -X POST "http://localhost:8888/api/v1/tasks" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: UZXJfw3YNX80DLfN" \
  -d '{
    "task_type": "portfolio_analysis",
    "params": {
      "stocks": [{"stock_code": "000001.SZ", "weight": 1.0}]
    }
  }'

查询任务状态: GET /api/v1/tasks/{task_id}

curl -X GET "http://localhost:8888/api/v1/tasks/your-task-id" \
  -H "X-API-Key: UZXJfw3YNX80DLfN"

获取任务结果: GET /api/v1/tasks/{task_id}/result

curl -X GET "http://localhost:8888/api/v1/tasks/your-task-id/result" \
  -H "X-API-Key: UZXJfw3YNX80DLfN"

认证机制

1. API密钥认证（基础）

在请求头中包含API密钥：

X-API-Key: your_api_key_here

2. HMAC签名认证（高安全级别）

对于敏感操作，使用HMAC签名：

X-API-Key: your_api_key_here
X-HMAC-Signature: hmac_sha256_signature
X-Timestamp: unix_timestamp

HMAC签名生成示例（Python）:

import hmac
import hashlib
import time
import json

def generate_hmac_signature(data, api_key, secret_key):
    timestamp = str(int(time.time()))
    
    # 构建签名数据
    sign_data = {**data, 'timestamp': timestamp, 'api_key': api_key}
    sign_string = '&'.join(f"{k}={v}" for k, v in sorted(sign_data.items()))
    
    # 生成HMAC签名
    signature = hmac.new(
        secret_key.encode(),
        sign_string.encode(),
        hashlib.sha256
    ).hexdigest()
    
    return signature, timestamp

错误处理

标准错误响应格式

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "错误描述",
    "details": {
      "additional_info": "详细信息"
    }
  },
  "meta": {
    "timestamp": "2025-01-03T10:30:00Z",
    "request_id": "req_123456789"
  }
}

常见错误代码

错误代码	HTTP状态码	描述
`MISSING_API_KEY`	401	缺少API密钥
`INVALID_API_KEY`	403	无效的API密钥
`RATE_LIMIT_EXCEEDED`	429	请求频率超限
`INVALID_STOCK_CODE`	400	无效的股票代码
`PORTFOLIO_TOO_LARGE`	400	投资组合过大
`ANALYSIS_FAILED`	500	分析失败
`TASK_NOT_FOUND`	404	任务不存在

限流策略

基础限流

免费用户: 100次/小时
付费用户: 1000次/小时
企业用户: 10000次/小时

端点特定限流

个股分析: 50次/小时
投资组合分析: 20次/小时
批量评分: 10次/小时

限流响应头

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1641024000

最佳实践

1. 错误重试

import time
import requests

def api_request_with_retry(url, data, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.post(url, json=data, headers=headers)
            
            if response.status_code == 429:  # 限流
                retry_after = int(response.headers.get('Retry-After', 60))
                time.sleep(retry_after)
                continue
            
            return response
            
        except requests.RequestException as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)  # 指数退避

2. 批量处理

def batch_analyze_stocks(stock_codes, batch_size=10):
    results = []
    
    for i in range(0, len(stock_codes), batch_size):
        batch = stock_codes[i:i + batch_size]
        
        response = requests.post(
            f"{base_url}/api/v1/stocks/batch-score",
            json={"stock_codes": batch},
            headers=headers
        )
        
        if response.status_code == 200:
            batch_results = response.json()['data']['results']
            results.extend(batch_results)
        
        time.sleep(1)  # 避免触发限流
    
    return results

3. 缓存利用

import hashlib
import json

def get_cache_key(request_data):
    data_str = json.dumps(request_data, sort_keys=True)
    return hashlib.md5(data_str.encode()).hexdigest()

def cached_api_request(url, data, cache_ttl=300):
    cache_key = get_cache_key(data)
    
    # 检查缓存
    cached_result = cache.get(cache_key)
    if cached_result:
        return cached_result
    
    # 发送请求
    response = requests.post(url, json=data, headers=headers)
    result = response.json()
    
    # 存储到缓存
    if response.status_code == 200:
        cache.set(cache_key, result, ttl=cache_ttl)
    
    return result

健康检查

端点: GET /api/v1/health

检查API服务状态：

curl -X GET "http://localhost:8888/api/v1/health" \
  -H "X-API-Key: UZXJfw3YNX80DLfN"

支持与反馈

如有问题或建议，请联系：

邮箱: support@example.com
文档: /api/docs (Swagger UI)
健康检查: /api/v1/health