> ## Documentation Index
> Fetch the complete documentation index at: https://villagesql.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 用外部 API 数据丰富行

> 如何使用 VillageSQL 的 vsql_http 扩展，把外部 REST API 的实时数据拉取到 MySQL 查询结果中。

> [card] [VillageSQL is a drop-in replacement for MySQL with extensions.](https://villagesql.com/docs/en/8.4/stable/install-server.md)
>
> All examples on this page work on VillageSQL. Install Now →

有些数据不在您的数据库里——汇率、物流状态、地理定位查询、第三方产品详情。标准做法是在应用代码中获取它，然后要么缓存到一张表里，要么在应用层把它与查询结果拼接起来。VillageSQL 的 `vsql_http` 扩展让您可以直接在查询中拉取这些数据，或者用一条 UPDATE 把它存入某一列。

## 设置

```sql theme={null}
INSTALL EXTENSION vsql_http;
```

## 模式 1：把丰富后的数据存入列

最常见的用法：用从外部 API 获取的数据回填一列。运行一条逐行调用 API 的 UPDATE，存储结果，然后查询存储的列。

这个示例为每个订单获取物流状态：

```sql theme={null}
ALTER TABLE orders ADD COLUMN shipping_status VARCHAR(100);

UPDATE orders
SET shipping_status = JSON_VALUE(
  JSON_UNQUOTE(JSON_EXTRACT(
    CONVERT(
      vsql_http.http_get(
        CONCAT('https://api.shipping.com/track/', tracking_number)
      ) USING utf8mb4
    ),
    '$.content'
  )),
  '$.status'
)
WHERE tracking_number IS NOT NULL
  AND shipping_status IS NULL
LIMIT 50;
```

在您的应用中循环运行这条语句，直到不再有 `shipping_status IS NULL` 的行。分批处理，以免超出 API 的速率限制。

回填之后，查询读取的是存储的列——每次查询不再调用 API：

```sql theme={null}
SELECT id, customer_id, shipping_status
FROM orders
WHERE shipping_status = 'delivered'
ORDER BY updated_at DESC;
```

## 模式 2：在查询中实时查找

对于变化太快而无法缓存的数据——汇率、实时定价——您可以在 SELECT 中内联调用 API。结果中的每一行都会触发一次请求，所以请保持结果集较小。

```sql theme={null}
-- Fetch the current USD/EUR exchange rate and apply it to each row
SET @rate_resp = CONVERT(
  vsql_http.http_get('https://api.exchangerate.example.com/latest?base=USD')
  USING utf8mb4
);
SET @rate_body = JSON_UNQUOTE(JSON_EXTRACT(@rate_resp, '$.content'));
SET @eur_rate = CAST(JSON_VALUE(@rate_body, '$.rates.EUR') AS DECIMAL(10,6));

SELECT
  id,
  amount_usd,
  ROUND(amount_usd * @eur_rate, 2) AS amount_eur
FROM invoices
WHERE currency = 'USD'
LIMIT 100;
```

把共享的值一次性获取到变量中，然后在查询里使用该变量——除非每一行确实需要不同的 API 调用，否则不要在 SELECT 表达式中调用 `http_get()`。

## 模式 3：有条件的丰富

用 WHERE 在调用 API 之前先过滤，只为真正需要的行获取数据：

```sql theme={null}
-- Only enrich rows missing geocoordinates
UPDATE locations
SET
  lat = CAST(JSON_VALUE(
    JSON_UNQUOTE(JSON_EXTRACT(
      CONVERT(
        vsql_http.http_get(
          CONCAT('https://api.geocode.example.com/json?address=',
                 vsql_http.url_encode(address))
        ) USING utf8mb4
      ),
      '$.content'
    )),
    '$.lat'
  ) AS DECIMAL(10,7)),
  lng = CAST(JSON_VALUE(
    JSON_UNQUOTE(JSON_EXTRACT(
      CONVERT(
        vsql_http.http_get(
          CONCAT('https://api.geocode.example.com/json?address=',
                 vsql_http.url_encode(address))
        ) USING utf8mb4
      ),
      '$.content'
    )),
    '$.lng'
  ) AS DECIMAL(10,7))
WHERE lat IS NULL
  AND address IS NOT NULL
LIMIT 25;
```

注意包裹着地址的 `url_encode()`——在把用户数据嵌入 URL 之前，务必先编码。

## 处理 API 错误

所有 `vsql_http` 函数在连接失败时返回 NULL，并附带一条携带 curl 错误消息的警告。在使用内容之前先检查状态码：

```sql theme={null}
SET @resp = CONVERT(
  vsql_http.http_get('https://api.example.com/data/123') USING utf8mb4
);

SELECT
  CASE
    WHEN @resp IS NULL          THEN 'connection_failed'
    WHEN JSON_VALUE(@resp, '$.status') = '200' THEN
      JSON_UNQUOTE(JSON_EXTRACT(@resp, '$.content'))
    WHEN JSON_VALUE(@resp, '$.status') = '404' THEN 'not_found'
    ELSE CONCAT('error_', JSON_VALUE(@resp, '$.status'))
  END AS result;
```

对于批量 UPDATE 循环，得到 NULL 或非 200 响应的行，其列值保持为 NULL，因此您可以重新运行 UPDATE 来重试失败的行。

## 性能考量

**每次 HTTP 调用都是同步的，并会阻塞查询。** 一批 50 行、每行访问一个 200ms 的 API，至少需要 10 秒。`max_execution_time` 只限制 `SELECT` 语句——在这里不起作用。要限制这条 `UPDATE` 的运行时长，请事先用 `SELECT CONNECTION_ID()` 获取它的连接 ID，如果运行时间过长，就从另一个会话运行 `KILL QUERY <id>`：

```sql theme={null}
UPDATE orders
SET shipping_status = JSON_VALUE(
  JSON_UNQUOTE(JSON_EXTRACT(
    CONVERT(vsql_http.http_get(
      CONCAT('https://api.shipping.com/track/', tracking_number)
    ) USING utf8mb4),
    '$.content'
  )),
  '$.status'
)
WHERE shipping_status IS NULL
LIMIT 50;
```

优先存储结果而不是实时查询——一旦值进入了列，后续查询就不会再触及网络。

## 故障排除

| 问题 | 解决方案 |
| :- | :- |
| UPDATE 运行时间过长 | 减小 `LIMIT`；`max_execution_time` 不适用于 `UPDATE`，请改为从另一个会话运行 `KILL QUERY <connection_id>` |
| 所有行都返回 NULL | 服务器主机无法访问该 API；用 `SHOW WARNINGS` 查看 curl 的错误消息，并核实网络访问 |
| JSON 提取返回 NULL | `content` 是一个 JSON 编码的字符串，而不是嵌套对象，所以单步的 `'$.content.field'` 路径永远无法解析。先去除引号——`JSON_UNQUOTE(JSON_EXTRACT(resp, '$.content'))`——然后再从中提取字段。这与响应大小无关 |
| URL 参数编码不正确 | 用 `vsql_http.url_encode()` 包裹值 |
| API 返回速率限制错误 | 减小每批的 LIMIT；在批次之间添加 `SELECT SLEEP(1)` |

## 后续步骤

* [从 SQL 发起 HTTP 请求](https://villagesql.com/docs/zh/guides/http-requests-in-mysql.md)——完整的函数参考和响应解析
* [从触发器发送 webhook](https://villagesql.com/docs/zh/guides/http-webhooks.md)——向外推送变更，而不是向内拉取数据

## 另请参阅

* [从 SQL 发起 HTTP 请求](https://villagesql.com/docs/zh/guides/http-requests-in-mysql.md)——用于 API 调用的 HTTP 函数
* [MySQL 中的 JSON](https://villagesql.com/docs/zh/guides/json-in-mysql.md)——解析 API 返回的 JSON 响应
* [把表作为 REST API 提供服务](https://villagesql.com/docs/zh/guides/rest-api-from-tables.md)——通过 HTTP 发布您自己的表


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.