313 lines
8.8 KiB
Markdown
313 lines
8.8 KiB
Markdown
# Woocommerce API 配置指南
|
||
|
||
## 1. 认证方式配置
|
||
|
||
Woocommerce API 支持两种认证方式：Basic Auth 和 OAuth 1.0a。对于使用 `customer_key` 和 `customer_secret` 的情况，我们需要使用 OAuth 1.0a 认证。
|
||
|
||
### 1.1 OAuth 1.0a 认证配置
|
||
|
||
在 DataX 的 RESTful Reader 中，我们可以通过自定义请求参数和签名来实现 OAuth 1.0a 认证。以下是配置示例：
|
||
|
||
```json
|
||
{
|
||
"reader": {
|
||
"name": "restfulreader",
|
||
"parameter": {
|
||
"url": "https://your-woocommerce-site.com/wp-json/wc/v3/products",
|
||
"method": "GET",
|
||
"headers": {
|
||
"Accept": "application/json"
|
||
},
|
||
"requestParams": {
|
||
"consumer_key": "your_consumer_key",
|
||
"consumer_secret": "your_consumer_secret"
|
||
},
|
||
"pagination": {
|
||
"type": "page",
|
||
"pageSize": 100,
|
||
"pageNum": 1,
|
||
"totalCount": 1000
|
||
},
|
||
"dataPath": "$.*",
|
||
"column": [
|
||
// 列配置
|
||
]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 1.2 认证参数说明
|
||
|
||
- `consumer_key`: Woocommerce 后台生成的消费者密钥
|
||
- `consumer_secret`: Woocommerce 后台生成的消费者密钥密码
|
||
|
||
### 1.3 获取消费者密钥
|
||
|
||
1. 登录 Woocommerce 后台
|
||
2. 进入 `WooCommerce > 设置 > 高级 > REST API`
|
||
3. 点击 `添加密钥` 按钮
|
||
4. 填写描述，选择用户和权限
|
||
5. 点击 `生成 API 密钥`
|
||
6. 保存生成的 `consumer_key` 和 `consumer_secret`
|
||
|
||
## 2. 分页获取全部数据
|
||
|
||
Woocommerce API 默认一次最多返回 100 条数据，要获取全部数据，我们需要使用分页机制。DataX 的 RESTful Reader 支持多种分页方式，这里我们使用基于页码的分页。
|
||
|
||
### 2.1 分页配置示例
|
||
|
||
```json
|
||
{
|
||
"pagination": {
|
||
"type": "page",
|
||
"pageSize": 100,
|
||
"pageNum": 1,
|
||
"totalCount": 1000,
|
||
"pageToken": {
|
||
"offset": 0,
|
||
"limit": 100
|
||
},
|
||
"pageUrlTemplate": "${url}?page=${pageNum}&per_page=${pageSize}"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2.2 分页参数说明
|
||
|
||
| 参数名 | 说明 | 默认值 |
|
||
|--------|------|--------|
|
||
| `type` | 分页类型，支持 `page`（基于页码）、`offset`（基于偏移量）、`cursor`（基于游标） | 无 |
|
||
| `pageSize` | 每页数据条数 | 100 |
|
||
| `pageNum` | 起始页码 | 1 |
|
||
| `totalCount` | 预估总数据量，用于计算总页数 | 1000 |
|
||
| `pageUrlTemplate` | 分页 URL 模板，用于构建请求 URL | 无 |
|
||
|
||
### 2.3 动态获取总数据量
|
||
|
||
为了确保获取全部数据，我们可以先请求一次 API 获取总数据量，然后再进行分页请求。以下是实现思路：
|
||
|
||
1. 首先发送一次请求，获取总数据量
|
||
2. 根据总数据量和每页条数计算总页数
|
||
3. 遍历所有页码，获取全部数据
|
||
|
||
### 2.4 完整的分页配置示例
|
||
|
||
```json
|
||
{
|
||
"job": {
|
||
"content": [
|
||
{
|
||
"reader": {
|
||
"name": "restfulreader",
|
||
"parameter": {
|
||
"url": "https://your-woocommerce-site.com/wp-json/wc/v3/products",
|
||
"method": "GET",
|
||
"headers": {
|
||
"Accept": "application/json"
|
||
},
|
||
"requestParams": {
|
||
"consumer_key": "your_consumer_key",
|
||
"consumer_secret": "your_consumer_secret",
|
||
"per_page": 100
|
||
},
|
||
"pagination": {
|
||
"type": "page",
|
||
"pageSize": 100,
|
||
"pageNum": 1,
|
||
"totalCount": 0,
|
||
"dynamicTotalCount": true,
|
||
"totalCountPath": "$['X-WP-Total']",
|
||
"pageUrlTemplate": "${url}?page=${pageNum}&per_page=${pageSize}&consumer_key=${requestParams.consumer_key}&consumer_secret=${requestParams.consumer_secret}"
|
||
},
|
||
"dataPath": "$.*",
|
||
"column": [
|
||
{
|
||
"name": "id",
|
||
"type": "long"
|
||
},
|
||
{
|
||
"name": "name",
|
||
"type": "string"
|
||
},
|
||
{
|
||
"name": "sku",
|
||
"type": "string"
|
||
},
|
||
{
|
||
"name": "price",
|
||
"type": "string"
|
||
},
|
||
{
|
||
"name": "stock_quantity",
|
||
"type": "long"
|
||
},
|
||
{
|
||
"name": "created_at",
|
||
"type": "string"
|
||
}
|
||
]
|
||
}
|
||
},
|
||
"writer": {
|
||
// 写入配置
|
||
}
|
||
}
|
||
],
|
||
"setting": {
|
||
"speed": {
|
||
"channel": 1
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 3. 完整的作业配置示例
|
||
|
||
以下是一个完整的从 Woocommerce API 获取产品数据并写入 MySQL 的作业配置，包含了 OAuth 1.0a 认证和分页配置：
|
||
|
||
```json
|
||
{
|
||
"job": {
|
||
"content": [
|
||
{
|
||
"reader": {
|
||
"name": "restfulreader",
|
||
"parameter": {
|
||
"url": "https://your-woocommerce-site.com/wp-json/wc/v3/products",
|
||
"method": "GET",
|
||
"headers": {
|
||
"Accept": "application/json"
|
||
},
|
||
"requestParams": {
|
||
"consumer_key": "ck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
|
||
"consumer_secret": "cs_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
|
||
"per_page": 100
|
||
},
|
||
"pagination": {
|
||
"type": "page",
|
||
"pageSize": 100,
|
||
"pageNum": 1,
|
||
"totalCount": 0,
|
||
"dynamicTotalCount": true,
|
||
"totalCountPath": "$['X-WP-Total']",
|
||
"pageUrlTemplate": "${url}?page=${pageNum}&per_page=${pageSize}&consumer_key=${requestParams.consumer_key}&consumer_secret=${requestParams.consumer_secret}"
|
||
},
|
||
"dataPath": "$.*",
|
||
"column": [
|
||
{
|
||
"name": "id",
|
||
"type": "long"
|
||
},
|
||
{
|
||
"name": "name",
|
||
"type": "string"
|
||
},
|
||
{
|
||
"name": "sku",
|
||
"type": "string"
|
||
},
|
||
{
|
||
"name": "price",
|
||
"type": "string"
|
||
},
|
||
{
|
||
"name": "stock_quantity",
|
||
"type": "long"
|
||
},
|
||
{
|
||
"name": "created_at",
|
||
"type": "string"
|
||
}
|
||
]
|
||
}
|
||
},
|
||
"writer": {
|
||
"name": "mysqlwriter",
|
||
"parameter": {
|
||
"writeMode": "replace",
|
||
"username": "root",
|
||
"password": "123345678",
|
||
"column": [
|
||
"id",
|
||
"name",
|
||
"sku",
|
||
"price",
|
||
"stock_quantity",
|
||
"created_at"
|
||
],
|
||
"connection": [
|
||
{
|
||
"jdbcUrl": "jdbc:mysql://host.docker.internal:23306/inventory_v2?useUnicode=true&characterEncoding=utf-8",
|
||
"table": [
|
||
"products"
|
||
]
|
||
}
|
||
]
|
||
}
|
||
}
|
||
}
|
||
],
|
||
"setting": {
|
||
"speed": {
|
||
"channel": 1
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 4. 常见问题及解决方案
|
||
|
||
### 4.1 认证失败
|
||
|
||
**问题**：API 请求返回 401 Unauthorized
|
||
|
||
**解决方案**：
|
||
1. 检查 `consumer_key` 和 `consumer_secret` 是否正确
|
||
2. 确保 API 用户具有足够的权限
|
||
3. 检查 API 版本是否正确
|
||
|
||
### 4.2 分页失效
|
||
|
||
**问题**：只获取到部分数据，分页没有生效
|
||
|
||
**解决方案**：
|
||
1. 检查分页类型配置是否正确
|
||
2. 确保 `pageUrlTemplate` 配置正确
|
||
3. 检查 `totalCount` 是否设置合理
|
||
4. 启用 `dynamicTotalCount` 动态获取总数据量
|
||
|
||
### 4.3 请求频率限制
|
||
|
||
**问题**：API 请求返回 429 Too Many Requests
|
||
|
||
**解决方案**：
|
||
1. 减少每页请求的数据量
|
||
2. 增加请求间隔时间
|
||
3. 联系 Woocommerce 支持调整 API 速率限制
|
||
|
||
### 4.4 数据类型不匹配
|
||
|
||
**问题**：数据写入数据库时类型不匹配
|
||
|
||
**解决方案**：
|
||
1. 检查 DataX 配置中的列类型与数据库表结构是否匹配
|
||
2. 使用 DataX 的转换器功能进行数据类型转换
|
||
3. 在读取阶段指定正确的数据类型
|
||
|
||
## 5. 性能优化建议
|
||
|
||
1. **调整分页大小**：根据 API 限制和网络状况调整 `pageSize`，建议设置为 API 允许的最大值（100）
|
||
2. **增加并发通道**：在 DataX 作业配置中增加 `channel` 数量，提高数据同步速度
|
||
3. **使用增量同步**：通过添加时间过滤条件，只同步新增或修改的数据
|
||
4. **优化数据库写入**：使用 `insert` 或 `update` 模式替代 `replace` 模式，减少数据库操作开销
|
||
5. **定期清理日志**：定期清理 DataX 日志文件，避免磁盘空间不足
|
||
|
||
## 6. 扩展阅读
|
||
|
||
- [Woocommerce REST API 文档](https://woocommerce.github.io/woocommerce-rest-api-docs/)
|
||
- [DataX RESTful Reader 文档](https://github.com/alibaba/DataX/blob/master/restfulreader/doc/restfulreader.md)
|
||
- [DataX MySQL Writer 文档](https://github.com/alibaba/DataX/blob/master/mysqlwriter/doc/mysqlwriter.md)
|