跳转到主要内容

VillageSQL is a drop-in replacement for MySQL with extensions.

All examples on this page work on VillageSQL. Install Now →
MySQL 没有内置的发起网络请求的方式。如果您想调用一个 HTTP API,您需要把数据从数据库中取出来,在应用程序代码中发起请求,再把结果推回去。VillageSQL 的 vsql_http 扩展把 http_get()、http_post() 以及全部的 HTTP 方法直接添加到 SQL 中——这样您就可以在数据所在的地方调用外部 API。

问题:每次 API 调用都要离开数据库

没有 VillageSQL 时的典型模式:
这可以工作,但每一行都是三次往返:SELECT、API 调用、UPDATE。数据补充逻辑存在于应用程序代码中,而不是在数据所在的 schema 中。

使用 VillageSQL:从 SQL 发起 HTTP

http_get(url) 发起一个 GET 请求,并返回一个包含完整响应的 JSON 字符串。
vsql_http 中的每个函数都返回相同的 JSON 结构:

字符集转换

在 VillageSQL 0.0.6 及更早版本上,VEF STRING 函数返回 binary 字符集。在把结果传给 JSON_VALUE 或 JSON_EXTRACT 之前,请用 CONVERT(... USING utf8mb4) 包装它:
VillageSQL 0.0.7 及更高版本直接返回正确的字符集,因此那里不再需要 CONVERT——但保留它没有坏处,下面的每个示例仍然使用它,以兼容 0.0.6 及更早版本。用 CONVERT 赋值给变量一次,然后重用该变量,以避免重复转换。

POST 请求

http_post(url, content_type, body) 发送一个带正文的 POST:

自定义请求头和其他方法

http_request(method, url, headers_json, body, content_type, options_json) 处理带自定义请求头的任意方法:
headers_json 参数是一个 JSON 对象,其键是请求头名称,值是请求头的值。

所有可用的函数

所有函数对 NULL 输入都返回 NULL。在连接失败时(连接被拒绝、DNS 失败、超时),HTTP 函数同样返回 NULL,并发出一条携带 curl 错误消息的警告——当请求似乎消失时,用 SHOW WARNINGS 检查它。

URL 编码

url_encode() 和 url_decode() 处理查询参数的百分号编码:

已知限制

256KB 响应上限——大于 256KB 的响应会被截断。这覆盖了 SQL 查询中使用的典型 API 负载;它不适合大文件下载。被此上限截断的响应不再是有效的 JSON:JSON_EXTRACT/JSON_UNQUOTE 对它会引发 ERROR 3141,而 JSON_VALUE 在其默认的 NULL ON ERROR 行为下返回 NULL 并给出 Warning 3141,而不是报错。 JSON_VALUE 大小限制——当提取的值超过 MySQL 的内部大小限制时,JSON_VALUE 返回 NULL。对于大的响应正文,请改用 JSON_UNQUOTE(JSON_EXTRACT(...)):
同步——每次 HTTP 调用都会阻塞,直到完成或超时。max_execution_time 不会限制或中断阻塞中的 vsql_http 调用——一个缓慢或无法访问的端点会让语句一直等到它自己的连接/读取超时为止。http_get/http_post/http_put/http_delete/http_patch 不接受选项;只有 http_request(method, url, headers_json, body, content_type, options_json) 接受超时,形式是其 options_json 参数中以秒为单位的 {"timeout": N}(默认 30)。当您需要缩短超时时,请使用 http_request 而不是简写函数(请参阅 HTTP Webhook)。

故障排除

后续步骤

另请参阅