单个句子语法分析 API 文档

概述

该 API 端点用于分析单个句子的语法结构。它返回句子的语法成分，包括句子类型、主语、谓语、状语等详细信息。

输入JSON

{
    "type": "grammar_analysis",
    "text": "I am a student."
}

请求说明

• 请求方法: POST
• 请求URL: /analyze_sentence
• 请求头:
  • Content-Type: application/json
  • X-API-Key: 您的 API 密钥
  • X-Timestamp: 当前时间戳（秒）
  • X-Signature: 请求签名

签名生成

签名用于验证请求的完整性。生成方法如下：

1. 将 timestamp 和请求体的 JSON 字符串拼接。
2. 使用 HMAC-SHA256 算法和您的 API 密钥对拼接字符串进行加密。
3. 将结果转换为十六进制字符串。

响应JSON

{
    "step": "grammar_analysis",
    "data": {
        "sentence_analysis": [
            {
                "index": 1,
                "type": "简单句",
                "text": "I am a student.",
                "position": [0, 4],
                "elements": [
                    {
                        "type": "主语",
                        "text": "I",
                        "elements": []
                    },
                    {
                        "type": "谓语",
                        "text": "am",
                        "elements": []
                    },
                    {
                        "type": "表语",
                        "text": "a student",
                        "elements": [
                            {
                                "type": "限定词",
                                "text": "a",
                                "position": [2, 3]
                            }
                        ]
                    }
                ]
            }
        ]
    },
    "status": "success",
    "error": null
}

错误处理

• 如果请求缺少 text 字段，返回 400 错误。
• 如果请求超时（超过 15 秒），返回超时错误信息。
• 其他错误将返回通用错误信息。

注意事项

• 确保 API 密钥正确无误。
• 确保请求体格式正确。
• 确保服务器正在运行并可访问。

调用示例

Python 示例代码

import requests
import json
import time
import hmac
import hashlib
from typing import Dict, Any

# 测试用例数据
sentence_data = {
    "text": "The cat sleeps on the mat.",
    "type": "grammar_analysis"
}

def generate_signature(api_key: str, timestamp: str, body: str) -> str:
    """生成请求签名"""
    return hmac.new(
        api_key.encode('utf-8'),
        f"{timestamp}{body}".encode('utf-8'),
        hashlib.sha256
    ).hexdigest()

def analyze_sentence(input_data: Dict[str, Any]) -> None:
    """
    调用句子分析API并处理响应
    
    Args:
        input_data: 包含句子文本和类型的字典
    """
    # API配置
    url = 'https://hexeltsiting-fc-kuapjgzhvy.cn-hangzhou.fcapp.run/analyze_sentence'
    api_key = 'YOUR_API_KEY'  # 测试用API密钥
    timestamp = str(int(time.time()))
    
    # 使用确定的序列化方式
    body = json.dumps(input_data, ensure_ascii=False, separators=(',', ':'))
    
    # 生成签名
    signature = generate_signature(api_key, timestamp, body)
    
    headers = {
        'Content-Type': 'application/json',
        'X-API-Key': api_key,
        'X-Timestamp': timestamp,
        'X-Signature': signature
    }
    
    try:
        print("发送请求到服务器...")
        print(f"请求数据: {json.dumps(input_data, ensure_ascii=False, indent=2)}")
        
        # 发送请求
        response = requests.post(
            url=url,
            headers=headers,
            data=body.encode('utf-8'),
            stream=True
        )
        
        print(f"\n响应状态: {response.status_code}")
        
        if response.status_code == 200:
            print("\n处理响应流:")
            print("-" * 50)
            
            for line in response.iter_lines(decode_unicode=True):
                if line.startswith('data: '):
                    try:
                        # 解析SSE数据
                        json_data = line[6:]  # 移除 'data: ' 前缀
                        response_json = json.loads(json_data)
                        pretty_response = json.dumps(
                            response_json,
                            ensure_ascii=False,
                            indent=2
                        )
                        print(f"\n接收到的数据:\n{pretty_response}")
                        print("-" * 50)
                    except json.JSONDecodeError as e:
                        print(f"JSON解析错误: {e}")
                        print(f"原始数据: {json_data}")
        else:
            print(f"请求失败，状态码: {response.status_code}")
            print(f"错误信息: {response.text}")
            
    except requests.exceptions.ConnectionError:
        print("连接错误: 请确保服务器正在运行")
    except Exception as e:
        print(f"意外错误: {str(e)}")

def main():
    """主函数"""
    print("开始句子分析测试...")
    analyze_sentence(sentence_data)

if __name__ == "__main__":
    main()

cURL 示例

curl -X POST 'https://hexeltsiting-fc-kuapjgzhvy.cn-hangzhou.fcapp.run/analyze_sentence' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: your-api-key' \
-H "X-Timestamp: $TIMESTAMP" \
-H 'X-Signature: calculated-signature' \
-d '{
    "text": "The cat sleeps on the mat.",
    "type": "grammar_analysis"
}'

注意事项

1. 请求必须使用 HTTP/1.1 或更高版本
2. 客户端需要支持 SSE (Server-Sent Events) 接收流式响应
3. 建议设置合理的超时时间（15秒）
4. 签名计算时注意保持请求体的一致性
5. 所有文本内容必须使用 UTF-8 编码