# Xiyou Auth SDK
Xiyou OpenAPI Python认证SDK，提供完整的加签认证功能。
## 特性
- ✅ **纯Python标准库实现** - 无需外部依赖
- ✅ **HMAC-SHA256签名** - 安全可靠的签名算法
- ✅ **简单易用** - 几行代码即可完成认证
- ✅ **灵活集成** - 可与任何HTTP客户端库配合使用
## 安装
```bash
pip install -e .
```
## 快速开始
### 1. 基本使用
```python
from xiyou_sdk import XiyouAuth
# 初始化认证对象
auth = XiyouAuth(
client_id="your_client_id",
secret_key="your_secret_key"
)
# 获取认证头部
headers = auth.get_auth_headers(
method="POST",
path="/v1/asins/traffic",
body='{"entities":[{"country":"US","asin":"B09PCSR9SX"}]}'
)
print(headers)
# 输出:
# {
# 'X-Client-Id': 'your_client_id',
# 'X-Timestamp': '1753776583',
# 'X-Sign': '5572ae2572e2aef8fa23623a3f56fa245f2f74950b533fe63100ad8f688b254f',
# 'Content-Type': 'application/json'
# }
```
### 2. 与requests库结合使用
```python
import requests
import json
from xiyou_sdk import XiyouAuth
auth = XiyouAuth("your_client_id", "your_secret_key")
# 构建请求数据
data = {"entities": [{"country": "US", "asin": "B09PCSR9SX"}]}
body = json.dumps(data, ensure_ascii=False, separators=(',', ':'))
# 获取认证头部
headers = auth.get_auth_headers(
method="POST",
path="/v1/asins/traffic",
body=body
)
# 发起请求
response = requests.post(
"https://api.xiyou.com/v1/asins/traffic",
headers=headers,
data=body
)
```
### 3. 与urllib结合使用
```python
import urllib.request
import json
from xiyou_sdk import XiyouAuth
auth = XiyouAuth("your_client_id", "your_secret_key")
# 构建请求数据
data = {"entities": [{"country": "US", "asin": "B09PCSR9SX"}]}
body = json.dumps(data, ensure_ascii=False, separators=(',', ':'))
# 获取认证头部
headers = auth.get_auth_headers(
method="POST",
path="/v1/asins/traffic",
body=body
)
# 发起请求
req = urllib.request.Request(
"https://api.xiyou.com/v1/asins/traffic",
data=body.encode(),
headers=headers
)
response = urllib.request.urlopen(req)
```
## API参考
### XiyouAuth
#### 构造函数
```python
XiyouAuth(client_id: str, secret_key: str)
```
**参数:**
- `client_id`: 客户端ID
- `secret_key`: 密钥
#### 方法
##### get_auth_headers()
```python
get_auth_headers(
method: str = "POST",
path: str = "",
body: str = "",
timestamp: Optional[str] = None
) -> Dict[str, str]
```
生成包含认证信息的完整头部。
**参数:**
- `method`: HTTP方法 (GET, POST, PUT, DELETE等)
- `path`: API路径 (如: /v1/asins/traffic)
- `body`: 请求体内容
- `timestamp`: 自定义时间戳，默认使用当前时间
**返回:** 包含认证头部的字典
##### generate_signature()
```python
generate_signature(
timestamp: str,
method: str = "POST",
path: str = "",
body: str = ""
) -> str
```
生成API请求签名。
**参数:**
- `timestamp`: 时间戳字符串
- `method`: HTTP方法
- `path`: API路径
- `body`: 请求体内容
**返回:** 签名字符串
## 签名算法
签名使用HMAC-SHA256算法，签名字符串格式为：
```
client_id + timestamp + method + path + body
```
## 支持的API
该SDK适用于所有Xiyou OpenAPI接口，包括：
- `/v1/asins/traffic` - ASIN流量得分
- `/v1/asins/infoChange/trends/daily` - ASIN基础信息变动趋势（天）
- `/v1/asins/trafficScore/trend/daily` - ASIN流量得分趋势（天）
- `/v1/asins/trafficScore/trend/weekly` - ASIN流量得分趋势（周）
- `/v1/asins/trafficScore/trend/monthly` - ASIN流量得分趋势（月）
- 以及其他所有API接口
## 示例
查看 `examples/` 目录中的示例代码：
- `basic_usage.py` - 基本使用示例
- `signature_test.py` - 签名验证测试
运行示例：
```bash
PYTHONPATH=. python examples/basic_usage.py
PYTHONPATH=. python examples/signature_test.py
```
## 许可证
MIT License
Raw data
{
"_id": null,
"home_page": "https://github.com/xiyou/xiyou-python-auth-sdk",
"name": "xiyou-auth-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "xiyou, api, auth, signature, hmac, authentication",
"author": "Xiyou SDK Team",
"author_email": "Xiyou SDK Team <support@xiyou.com>",
"download_url": "https://files.pythonhosted.org/packages/ec/7a/d48e527e4ff375f75a085009c572c61cf5073e4deabd3dbe6165ffd17a45/xiyou_auth_sdk-1.0.0.tar.gz",
"platform": null,
"description": "# Xiyou Auth SDK\n\nXiyou OpenAPI Python\u8ba4\u8bc1SDK\uff0c\u63d0\u4f9b\u5b8c\u6574\u7684\u52a0\u7b7e\u8ba4\u8bc1\u529f\u80fd\u3002\n\n## \u7279\u6027\n\n- \u2705 **\u7eafPython\u6807\u51c6\u5e93\u5b9e\u73b0** - \u65e0\u9700\u5916\u90e8\u4f9d\u8d56\n- \u2705 **HMAC-SHA256\u7b7e\u540d** - \u5b89\u5168\u53ef\u9760\u7684\u7b7e\u540d\u7b97\u6cd5\n- \u2705 **\u7b80\u5355\u6613\u7528** - \u51e0\u884c\u4ee3\u7801\u5373\u53ef\u5b8c\u6210\u8ba4\u8bc1\n- \u2705 **\u7075\u6d3b\u96c6\u6210** - \u53ef\u4e0e\u4efb\u4f55HTTP\u5ba2\u6237\u7aef\u5e93\u914d\u5408\u4f7f\u7528\n\n## \u5b89\u88c5\n\n```bash\npip install -e .\n```\n\n## \u5feb\u901f\u5f00\u59cb\n\n### 1. \u57fa\u672c\u4f7f\u7528\n\n```python\nfrom xiyou_sdk import XiyouAuth\n\n# \u521d\u59cb\u5316\u8ba4\u8bc1\u5bf9\u8c61\nauth = XiyouAuth(\n client_id=\"your_client_id\",\n secret_key=\"your_secret_key\"\n)\n\n# \u83b7\u53d6\u8ba4\u8bc1\u5934\u90e8\nheaders = auth.get_auth_headers(\n method=\"POST\",\n path=\"/v1/asins/traffic\",\n body='{\"entities\":[{\"country\":\"US\",\"asin\":\"B09PCSR9SX\"}]}'\n)\n\nprint(headers)\n# \u8f93\u51fa:\n# {\n# 'X-Client-Id': 'your_client_id',\n# 'X-Timestamp': '1753776583',\n# 'X-Sign': '5572ae2572e2aef8fa23623a3f56fa245f2f74950b533fe63100ad8f688b254f',\n# 'Content-Type': 'application/json'\n# }\n```\n\n### 2. \u4e0erequests\u5e93\u7ed3\u5408\u4f7f\u7528\n\n```python\nimport requests\nimport json\nfrom xiyou_sdk import XiyouAuth\n\nauth = XiyouAuth(\"your_client_id\", \"your_secret_key\")\n\n# \u6784\u5efa\u8bf7\u6c42\u6570\u636e\ndata = {\"entities\": [{\"country\": \"US\", \"asin\": \"B09PCSR9SX\"}]}\nbody = json.dumps(data, ensure_ascii=False, separators=(',', ':'))\n\n# \u83b7\u53d6\u8ba4\u8bc1\u5934\u90e8\nheaders = auth.get_auth_headers(\n method=\"POST\",\n path=\"/v1/asins/traffic\",\n body=body\n)\n\n# \u53d1\u8d77\u8bf7\u6c42\nresponse = requests.post(\n \"https://api.xiyou.com/v1/asins/traffic\",\n headers=headers,\n data=body\n)\n```\n\n### 3. \u4e0eurllib\u7ed3\u5408\u4f7f\u7528\n\n```python\nimport urllib.request\nimport json\nfrom xiyou_sdk import XiyouAuth\n\nauth = XiyouAuth(\"your_client_id\", \"your_secret_key\")\n\n# \u6784\u5efa\u8bf7\u6c42\u6570\u636e\ndata = {\"entities\": [{\"country\": \"US\", \"asin\": \"B09PCSR9SX\"}]}\nbody = json.dumps(data, ensure_ascii=False, separators=(',', ':'))\n\n# \u83b7\u53d6\u8ba4\u8bc1\u5934\u90e8\nheaders = auth.get_auth_headers(\n method=\"POST\",\n path=\"/v1/asins/traffic\",\n body=body\n)\n\n# \u53d1\u8d77\u8bf7\u6c42\nreq = urllib.request.Request(\n \"https://api.xiyou.com/v1/asins/traffic\",\n data=body.encode(),\n headers=headers\n)\nresponse = urllib.request.urlopen(req)\n```\n\n## API\u53c2\u8003\n\n### XiyouAuth\n\n#### \u6784\u9020\u51fd\u6570\n\n```python\nXiyouAuth(client_id: str, secret_key: str)\n```\n\n**\u53c2\u6570:**\n- `client_id`: \u5ba2\u6237\u7aefID\n- `secret_key`: \u5bc6\u94a5\n\n#### \u65b9\u6cd5\n\n##### get_auth_headers()\n\n```python\nget_auth_headers(\n method: str = \"POST\",\n path: str = \"\",\n body: str = \"\",\n timestamp: Optional[str] = None\n) -> Dict[str, str]\n```\n\n\u751f\u6210\u5305\u542b\u8ba4\u8bc1\u4fe1\u606f\u7684\u5b8c\u6574\u5934\u90e8\u3002\n\n**\u53c2\u6570:**\n- `method`: HTTP\u65b9\u6cd5 (GET, POST, PUT, DELETE\u7b49)\n- `path`: API\u8def\u5f84 (\u5982: /v1/asins/traffic)\n- `body`: \u8bf7\u6c42\u4f53\u5185\u5bb9\n- `timestamp`: \u81ea\u5b9a\u4e49\u65f6\u95f4\u6233\uff0c\u9ed8\u8ba4\u4f7f\u7528\u5f53\u524d\u65f6\u95f4\n\n**\u8fd4\u56de:** \u5305\u542b\u8ba4\u8bc1\u5934\u90e8\u7684\u5b57\u5178\n\n##### generate_signature()\n\n```python\ngenerate_signature(\n timestamp: str,\n method: str = \"POST\",\n path: str = \"\",\n body: str = \"\"\n) -> str\n```\n\n\u751f\u6210API\u8bf7\u6c42\u7b7e\u540d\u3002\n\n**\u53c2\u6570:**\n- `timestamp`: \u65f6\u95f4\u6233\u5b57\u7b26\u4e32\n- `method`: HTTP\u65b9\u6cd5\n- `path`: API\u8def\u5f84\n- `body`: \u8bf7\u6c42\u4f53\u5185\u5bb9\n\n**\u8fd4\u56de:** \u7b7e\u540d\u5b57\u7b26\u4e32\n\n## \u7b7e\u540d\u7b97\u6cd5\n\n\u7b7e\u540d\u4f7f\u7528HMAC-SHA256\u7b97\u6cd5\uff0c\u7b7e\u540d\u5b57\u7b26\u4e32\u683c\u5f0f\u4e3a\uff1a\n\n```\nclient_id + timestamp + method + path + body\n```\n\n## \u652f\u6301\u7684API\n\n\u8be5SDK\u9002\u7528\u4e8e\u6240\u6709Xiyou OpenAPI\u63a5\u53e3\uff0c\u5305\u62ec\uff1a\n\n- `/v1/asins/traffic` - ASIN\u6d41\u91cf\u5f97\u5206\n- `/v1/asins/infoChange/trends/daily` - ASIN\u57fa\u7840\u4fe1\u606f\u53d8\u52a8\u8d8b\u52bf\uff08\u5929\uff09\n- `/v1/asins/trafficScore/trend/daily` - ASIN\u6d41\u91cf\u5f97\u5206\u8d8b\u52bf\uff08\u5929\uff09\n- `/v1/asins/trafficScore/trend/weekly` - ASIN\u6d41\u91cf\u5f97\u5206\u8d8b\u52bf\uff08\u5468\uff09\n- `/v1/asins/trafficScore/trend/monthly` - ASIN\u6d41\u91cf\u5f97\u5206\u8d8b\u52bf\uff08\u6708\uff09\n- \u4ee5\u53ca\u5176\u4ed6\u6240\u6709API\u63a5\u53e3\n\n## \u793a\u4f8b\n\n\u67e5\u770b `examples/` \u76ee\u5f55\u4e2d\u7684\u793a\u4f8b\u4ee3\u7801\uff1a\n\n- `basic_usage.py` - \u57fa\u672c\u4f7f\u7528\u793a\u4f8b\n- `signature_test.py` - \u7b7e\u540d\u9a8c\u8bc1\u6d4b\u8bd5\n\n\u8fd0\u884c\u793a\u4f8b\uff1a\n\n```bash\nPYTHONPATH=. python examples/basic_usage.py\nPYTHONPATH=. python examples/signature_test.py\n```\n\n## \u8bb8\u53ef\u8bc1\n\nMIT License \n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Xiyou OpenAPI Python\u8ba4\u8bc1SDK - \u63d0\u4f9b\u5b8c\u6574\u7684\u52a0\u7b7e\u8ba4\u8bc1\u529f\u80fd",
"version": "1.0.0",
"project_urls": {
"Bug Reports": "https://github.com/xiyou/xiyou-python-auth-sdk/issues",
"Documentation": "https://docs.xiyou.com",
"Homepage": "https://github.com/xiyou/xiyou-python-auth-sdk",
"Source": "https://github.com/xiyou/xiyou-python-auth-sdk"
},
"split_keywords": [
"xiyou",
" api",
" auth",
" signature",
" hmac",
" authentication"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "accc9c72a9f1c9e1c4f01619695e2f496cfb63662bf0d0d00f0a27922125d0ad",
"md5": "edb8acd1180b82756aa15fb9b7d2fd61",
"sha256": "c9000d66209a9634568f680a438506dea9f0353b8fc590bac22d4b3f98aed8fe"
},
"downloads": -1,
"filename": "xiyou_auth_sdk-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "edb8acd1180b82756aa15fb9b7d2fd61",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 5319,
"upload_time": "2025-07-29T08:30:50",
"upload_time_iso_8601": "2025-07-29T08:30:50.351027Z",
"url": "https://files.pythonhosted.org/packages/ac/cc/9c72a9f1c9e1c4f01619695e2f496cfb63662bf0d0d00f0a27922125d0ad/xiyou_auth_sdk-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ec7ad48e527e4ff375f75a085009c572c61cf5073e4deabd3dbe6165ffd17a45",
"md5": "adf7b63ce0a1a5b6dd6440eb9c2c9040",
"sha256": "415ceff251c95d8edc7371367b7c089d341d1aeea6022222b3bd94f60edbf88c"
},
"downloads": -1,
"filename": "xiyou_auth_sdk-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "adf7b63ce0a1a5b6dd6440eb9c2c9040",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 7615,
"upload_time": "2025-07-29T08:30:51",
"upload_time_iso_8601": "2025-07-29T08:30:51.967248Z",
"url": "https://files.pythonhosted.org/packages/ec/7a/d48e527e4ff375f75a085009c572c61cf5073e4deabd3dbe6165ffd17a45/xiyou_auth_sdk-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-29 08:30:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "xiyou",
"github_project": "xiyou-python-auth-sdk",
"github_not_found": true,
"lcname": "xiyou-auth-sdk"
}
JSON
