# 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)