在EasySQLMAIL中使用HTTP命令
HTTP命令让您可以在任务中通过HTTP(或HTTPS)协议调用远程服务器上的API接口。例如，您可以通过HTTP命令调用企业微信或钉钉提供的各种API，并把调用的结果存到本地的数据库中。
HTTP命令配置界面
Step1: 在任务配置对话框的"SQL命令"Tab页中点击"新建命令"，然后选择"创建一个HTTP命令"选项，点击"确定".
Step2: 在命令配置对话框中输入命令名称、选择命令的执行场景和执行时机. 如果需要通过HTTP代理服务器连接远程HTTP主机，还可以在这里选择要使用的HTTP代理服务器.
您可以在"用于生成HTTP调用请求的SQL" TAB页中配置命令开始执行时要发起的HTTP请求的内容。包括HTTP请求的URL，HTTP头，HTTP Method(GET或POST)，以及要提交的请求内容等。
配置"用于生成HTTP调用请求的SQL"
EasySQLMAIL使用SQL语句来构造HTTP请求的各项参数。您可以通过SQL语句灵活组合HTTP请求。用于构造HTTP请求的SQL语句必须返回一个名为"_http_request_"的字段，EasySQLMAIL会将这个字段的值作为HTTP请求的参数。
EasySQLMAIL会将SQL语句返回的结果集中的第一行的"_http_request_"字段值作为HTTP请求内容。
"_http_request_"的值应该是一个多行文本，每一行的行首是行的类型，然后是一个字段分隔符":"，后面是行的数据。例如下面这个SQL语句可以构造一个HTTP请求，用于调用位于test.com服务器上的Web API。
SELECT '
url : https://test.com/api/getClientIP
method : get
header : Authorization=Bearer xxx
field : client_id=AACCD
field : ip_count=20
' AS _http_request_ ;
_http_request_语法表
| 行类型名称 | 说明 | 是否必须 | 语法 | 示例 |
|
url |
设置HTTP请求的URL地址 |
必须 |
url : https://xxx或http://xxx |
url : https://test.com/api/getClientIP |
|
method |
设置HTTP请求的方法。只支持POST和GET方法。如果不出现这个类型，默认使用GET方法发起HTTP请求。 |
可选 |
method : get或post |
method : post |
|
header |
设置HTTP请求的头部选项。一个请求中可以出现多次header类型，每行一个。行类型分隔符后的语法如下： 选项名称 = 选项值 例如：
Content-Type = application/x-www-form-urlencoded |
可选 |
header : 选项名称=选项值 |
header : Content-Type=application/x-www-form-urlencoded header : Sec-Ch-Ua-Platform=Windows header : XToken= |
|
field |
设置要通过HTTP请求提交的数据字段的内容。一个请求中可以出现多次field类型，每行一个。行类型分隔符后的语法如下： 字段名称 = 字段值 例如：
UserName = Andy 字段值一般是单行文本。如果字段值包含回车换行符，请在字段值两端用双引号(")定界。例如： UserName = "Andy 如果字段值中要同时出现换行符和双引号，除了用双引号在字段值两端定界外，还需要在SQL语句生成HTTP请求内容前用数据库的replace方法把双引号替换为两个连续的双引号。替换后的字符串应该像下面这样： UserName = " |
可选 |
field : 字段名称=字段值 |
field : UserName=Andy field : age=35 field : city=New York |
|
file |
设置要通过HTTP请求提交的文件信息。一个请求中可以出现多次file类型，每行一个。此类型只能在用"POST"方法提交的HTTP请求中出现。行类型分隔符后的语法如下： 字段名称 = 字段值(可以是一个文件名，也可以是一个FILE_UUID)。 例如：
report_file_name = d:\temp\report.xlsx Note: 命令执行时，对应的文件将通过您设置的URL上传给HTTP服务器。文件的Content-Type是"multipart/form-data"。 |
可选 |
file : 字段名称=文件名或FILE_UUID |
file : report_file_name=d:\temp\report.xlsx |
通过_body_字段提交请求数据
有一些Web API要求调用者提交一个JSON或XML文档作为调用参数。在调用这些Web API时，可以在SQL中使用一个名为"_body_"的单独字段来存放到提交的数据。例如，下面的这个SQL用于构造一个HTTP请求，调用test.com服务器上的API方法"dataUpdate"，并把一个JSON文档发送给服务器:
SELECT '
url:https://test.com/api/dataUpdate
header:Content-type=application/json; charset=utf-8
header:Authorization=Bearer XXXXXXX
method:post
' AS _http_request_,
'
{
"count":1,
"data":[{"area":"四川","date":"2024-12-26 00:00:00","amount":"1234.88"}]
}
' AS _body_
在这个例子中，"_body_"字段的值将被作为调用参数发送给Web API。
注意: "_body_"字段只能与POST方法一起使用，对于GET方法此字段无效，HTTP命令会失败。
注意: 使用"_body_"存放要提交的数据时，"_http_request_"字段中不能包含"field"和"file"行。
您可以在"用于处理HTTP调用结果的SQL" Tab页中配置SQL语句来处理HTTP命令的调用结果，例如对Web API返回的数据进行解析和处理。
配置"用于处理HTTP调用结果的SQL"
在处理HTTP调用结果时，您应该先判断HTTP的返回代码是否正常。例如，您需要先使用以下SQL语句判断如果HTTP返回代码是否是200，如果不是就中止任务：
SELECT 'Error. HTTP code:' || #[@@HTTPResponseCode]# AS _$user_error$_
WHERE #[@@HTTPResponseCode]#::int4 <> 200
具体出现哪些HTTP代码需要中止任务，请参考您要调用的Web API的官方文档获取相关信息。
在"用于处理HTTP调用结果的SQL"中，您可以使用以下系统变量获取HTTP调用后返回的内容：
|
@@HTTPResponseBody |
取得HTTP调用后返回的正文内容。例如JSON数据或XML数据，文字, HTML代码等。 如果HTTP命令下载了一个文件，则这个变量会返回文件的FILE_UUID。 |
|
@@GetHTTPResponseHeader(HeaderName) |
取得HTTP命令最后一次执行服务器返回的HTTP响应头的值。参数是要获取的头部的名称，例如"Content-Type"。 如果不指定HeaderName，则EasySQLMAIL会返回一个包含所有HTTP响应头的JSON数据，格式如下： { |
|
@@HTTPCommandInstId |
取得HTTP命令最后一次执行时生成的命令实例的ID。命令实例ID是一个长整数。 |
|
@@HTTPResponseCode |
取得HTTP命令最后一次执行服务器返回的HTTP响应代码。HTTP响应代码是一个整数，例如200或302。 |
在"用于处理HTTP调用结果的SQL"中，您可以:
触发异常并中止任务：如果您在处理数据时发现错误，可以在SQL语句中使用"_$user_error$_"字段来触发一个异常并中止任务。例如，下面的语句表示如果在HTTP调用时获得的JSON数据中的"ok"字段等于"false"时，中止任务并把"error"字段的错误消息记录到任务日志中：
SELECT data->>'error' AS _$user_error$_
FROM (
SELECT #[@@HTTPResponseBody]#::jsonb AS data
) a WHERE data->>'ok' = 'false';
构造并发起新的HTTP请求：如果您要在"用于处理HTTP调用结果的SQL"中发起一个新的HTTP调用请求，您可以在最后一条SQL语句中按2.2 发起HTTP请求中所述的规则构造一个HTTP请求，EasySQLMAIL会按您的要求发起一个新的HTTP调用，并在调用完成后再次执行"用于处理HTTP调用结果的SQL"中的语句对调用结果进行处理。如果最后一条SQL语句中不包含"_http_request_"字段，或是包含"_http_request_"字段但没有查询到任何记录，EasySQLMAIL会结束这条HTTP命令，继续执行任务的其它命令。
案例：使用HTTP命令调用test.com的Web API读取会话列表。在这个案例中:
如果JSON数据的"ok"字段等于"false"，就中止任务。
如果JSON数据的next_cursor字段不为空，就继续调用读取下一页，直到next_cursor为空为止。
--如果JSON数据的"ok"字段等于"false"，就中止任务并把错误信息记录到任务日志中
SELECT data->>'error' AS _$user_error$_
FROM (select #[@@HTTPResponseBody]#::jsonb AS data) a
WHERE data->>'ok' = 'false';
--数据处理语句，把获取到的回话数据保存到数据库的t_channels表中
INSERT INTO t_channels(task_inst_id,channel_data)
SELECT #[@@TaskInstId]#::int8,channel
FROM (
SELECT jsonb_array_elements(result->'channels') AS channel FROM (
SELECT #[@@HTTPResponseBody]#::jsonb AS result
) a) a;
--如果next_cursor不为空，就构造一个新的HTTP请求继续读取下一页，直到next_cursor字段为空为止
SELECT
'
url:https://test.com/api/conversations.list?limit=100&cursor=' || (result->'response_metadata'->>'next_cursor')::text || '&types=public_channel,private_channel,mpim,im
header:Authorization=Bearer XXX
header:Content-type=application/x-www-form-urlencoded
' AS _http_request_
FROM (select #[@@HTTPResponseBody]#::jsonb as result) a WHERE result->'response_metadata'->>'next_cursor' <> '';
为保障您的机密信息(例如您的企业微信的Access Token)的安全，EasySQLMAIL为HTTP命令提供了一些方法用于获取加密的变量值。这些变量的值在任务日志中显示为"****"。
|
@@GetGlobalVarForHTTPCmd(VarName) |
从Global Variable List中取出一个加密变量的值。此方法只能在HTTP命令的SQL语句中使用。变量值在任务日志中显示为"****"。 |
|
@@GetEncryptedTempVarForHTTPCmd(VarName) |
从使用@@PutEncryptedTempVar方法生成的加密变量表中取出一个加密变量的值。此方法只能在HTTP命令的SQL语句中使用。变量值在任务日志中显示为"****"。 |
此外，在HTTP命令中您还可以使用EasySQLMAIL提供的其它系统变量，也可以使用任务变量或查询参数来构造HTTP请求。这些变量的值在任务日志中显示为明文。
EasySQLMAIL自身使用PostgreSQL数据库来存储数据。PostgreSQL提供了强大的JSON数据处理功能。您可以通过EasySQLMAIL的"默认数据源"(PostgreSQL数据库)来调用这些功能。
例如，使用以下语句，您可以对Web API的调用结果进行判断，并把返回的JSON Array数据展开后插入另一个表中：
--如果JSON数据的"ok"字段等于"false"，就中止任务并把错误信息记录到任务日志中
SELECT data->>'error' AS _$user_error$_
FROM (select #[@@HTTPResponseBody]#::jsonb AS data) a
WHERE data->>'ok' = 'false';
--数据处理语句，把获取到的会话数据保存到数据库的t_channels表中
INSERT INTO t_channels(channel_data)
SELECT channel
FROM (
SELECT jsonb_array_elements(result->'channels') AS channel FROM (
SELECT #[@@HTTPResponseBody]#::jsonb AS result
) a) a;
使用"默认数据源"处理JSON数据
关于PostgreSQL的JSON数据处理功能的详细信息请访问https://www.postgresql.org/docs/14/functions-json.html。
(1) 预览任务时谨慎使用"按正常执行流程进行预览(正常运行任务的SQL命令并执行先决条件判断)"选项。如果您的HTTP命令中会调用某些Web API向员工发送消息(例如企业微信的消息推送API)，或是上传文件到HTTP服务器，在预览任务时如果选择了"按正常执行流程进行预览(正常运行任务的SQL命令并执行先决条件判断)"选项，这些消息可能通过您调用的Web API发送给HTTP服务器。
(2) HTTP命令不受"不发送任务执行后生成的邮件和消息(只允许在企业信息查询平台上查询邮件内容)"选项的限制。如果您的HTTP命令中会调用某些Web API向员工发送消息(例如企业微信的消息推送API)，或是上传文件到HTTP服务器，在手动启动这些任务时，即使选择了"不发送任务执行后生成的邮件和消息(只允许在企业信息查询平台上查询邮件内容)"选项，这些消息任然有可能通过您调用的Web API发送给HTTP服务器。
