# Amazon商品数据爬虫使用说明

## 概述

这是一个使用万邦API爬取亚马逊商品数据的Python脚本。脚本会读取查询列表文件，逐个请求API，并将结果保存为JSON文件。

## 文件说明

- `amazon_crawler.py` - 基础版爬虫脚本
- `amazon_crawler_v2.py` - 增强版爬虫脚本（推荐使用）
- `config.example.py` - 配置文件示例
- `queries.txt` - 搜索关键词列表（每行一个）
- `amazon_results/` - 结果保存目录（自动创建）
- `amazon_crawler.log` - 运行日志文件

## 快速开始

### 1. 安装依赖

```bash
pip install requests
```

### 2. 配置API密钥

有三种方式配置API密钥：

#### 方式1：使用配置文件（推荐）

```bash
cd data_crawling
cp config.example.py config.py
# 编辑 config.py，填入真实的API密钥
```

#### 方式2：使用命令行参数

```bash
python amazon_crawler_v2.py --key YOUR_KEY --secret YOUR_SECRET
```

#### 方式3：使用环境变量

```bash
export ONEBOUND_API_KEY="your_key_here"
export ONEBOUND_API_SECRET="your_secret_here"
python amazon_crawler_v2.py
```

### 3. 运行爬虫

#### 基础版运行

```bash
# 编辑 amazon_crawler.py，填入API密钥
python amazon_crawler.py
```

#### 增强版运行

```bash
# 使用默认配置
python amazon_crawler_v2.py

# 自定义参数
python amazon_crawler_v2.py \
  --key YOUR_KEY \
  --secret YOUR_SECRET \
  --queries queries.txt \
  --delay 2.0 \
  --start 0 \
  --max 100 \
  --output amazon_results
```

## 命令行参数说明

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--key` | API Key | 从配置文件或环境变量读取 |
| `--secret` | API Secret | 从配置文件或环境变量读取 |
| `--queries` | 查询文件路径 | `data_crawling/queries.txt` |
| `--delay` | 请求间隔（秒） | 2.0 |
| `--start` | 起始索引（断点续爬） | 0 |
| `--max` | 最大爬取数量 | None（全部） |
| `--output` | 结果保存目录 | `data_crawling/amazon_results` |

## 使用示例

### 示例1：测试前10个查询

```bash
python amazon_crawler_v2.py --max 10
```

### 示例2：从第100个查询开始继续爬取

```bash
python amazon_crawler_v2.py --start 100
```

### 示例3：加快爬取速度（减少延迟）

```bash
python amazon_crawler_v2.py --delay 1.0
```

### 示例4：使用自定义查询文件

```bash
python amazon_crawler_v2.py --queries my_queries.txt
```

### 示例5：完整参数示例

```bash
python amazon_crawler_v2.py \
  --key "your_api_key" \
  --secret "your_api_secret" \
  --queries queries.txt \
  --delay 2.0 \
  --start 0 \
  --max 100 \
  --output my_results
```

## API参数说明

根据万邦API文档，支持以下搜索参数：

| 参数 | 说明 | 示例 |
|------|------|------|
| `q` | 搜索关键字 | "Mobile Phone Holder" |
| `start_price` | 开始价格 | 10 |
| `end_price` | 结束价格 | 100 |
| `page` | 页码 | 1 |
| `cat` | 分类ID | - |
| `discount_only` | 仅折扣商品 | yes/no |
| `sort` | 排序方式 | - |
| `page_size` | 每页数量 | 100 |
| `cache` | 使用缓存 | yes/no |
| `result_type` | 返回格式 | json |
| `lang` | 语言 | cn/en |

## 结果文件格式

每个查询的结果保存为单独的JSON文件，文件名格式：

```
0001_Bohemian_Maxi_Dress.json
0002_Vintage_Denim_Jacket.json
...
```

JSON文件结构示例：

```json
{
  "items": {
    "item": [
      {
        "detail_url": "https://www.amazon.com/...",
        "num_iid": "B07F8S18D5",
        "pic_url": "https://...",
        "price": "9.99",
        "reviews": "53812",
        "sales": 10000,
        "stars": "4.7",
        "title": "商品标题"
      }
    ],
    "page": "1",
    "page_size": 100,
    "real_total_results": 700,
    "q": "搜索词"
  },
  "error_code": "0000",
  "reason": "ok"
}
```

## 日志文件

运行日志保存在 `amazon_crawler.log`，包含：

- 每个请求的状态
- 成功/失败统计
- 错误信息
- 爬取进度

示例日志：

```
2025-01-07 10:00:00 - INFO - Amazon爬虫启动
2025-01-07 10:00:01 - INFO - [1/5024] (0.0%) - Bohemian Maxi Dress
2025-01-07 10:00:02 - INFO - ✓ 成功: Bohemian Maxi Dress - 获得 700 个结果
```

## 注意事项

### 1. API限制

- 注意API的请求限制（每日/每月配额）
- 建议设置适当的延迟时间（--delay参数）
- 从API响应中可以查看配额信息：`api_info` 字段

### 2. 断点续爬

如果爬取中断，可以使用 `--start` 参数从指定索引继续：

```bash
# 从第1000个查询继续
python amazon_crawler_v2.py --start 1000
```

### 3. 查询文件格式

`queries.txt` 文件要求：
- UTF-8 编码
- 每行一个查询关键词
- 空行会被自动跳过

### 4. 错误处理

- 请求失败的查询会保存错误信息到JSON文件
- 所有错误都会记录在日志文件中
- 可以通过日志文件查找失败的查询并重新爬取

### 5. 结果分析

可以编写脚本统计和分析爬取结果：

```python
import json
from pathlib import Path

results_dir = Path("amazon_results")
total_items = 0

for json_file in results_dir.glob("*.json"):
    with open(json_file) as f:
        data = json.load(f)
        if data.get('error_code') == '0000':
            items = data.get('items', {}).get('item', [])
            total_items += len(items)

print(f"共爬取 {total_items} 个商品")
```

## 性能优化

### 1. 并发爬取

当前脚本是串行爬取，如果需要提高速度，可以：
- 将查询列表分割成多个文件
- 使用多个进程同时运行
- 或修改脚本支持多线程/异步请求

### 2. 内存优化

如果查询数量很大（如5024个），建议：
- 使用 `--max` 参数分批爬取
- 定期清理日志文件

### 3. 网络优化

- 选择网络稳定的环境运行
- 可以增加重试机制
- 使用代理（如有需要）

## 故障排除

### 问题1：API密钥错误

```
错误: 未配置API密钥！
```

**解决**：检查配置文件、命令行参数或环境变量是否正确设置

### 问题2：请求超时

```
请求失败: timeout
```

**解决**：
- 检查网络连接
- 增加超时时间（修改脚本中的 `timeout` 参数）
- 检查API服务是否正常

### 问题3：API配额耗尽

```
API返回错误: quota exceeded
```

**解决**：
- 等待配额重置
- 升级API套餐
- 使用 `--max` 参数限制爬取数量

### 问题4：文件编码错误

```
UnicodeDecodeError
```

**解决**：确保 `queries.txt` 是 UTF-8 编码

## 扩展功能

如果需要扩展功能，可以修改脚本添加：

1. **多页爬取**：每个查询爬取多页结果
2. **数据过滤**：按价格、评分等条件过滤商品
3. **数据库存储**：将结果存入数据库而非JSON文件
4. **重试机制**：失败的请求自动重试
5. **代理支持**：通过代理服务器发送请求
6. **异步请求**：使用 aiohttp 实现并发爬取

## 联系方式

如有问题，请查看：
- 万邦API文档：`万邦API_亚马逊.md`
- 项目README：`README.md`
- 日志文件：`amazon_crawler.log`