SmartChart 新连接器使用指南 #

本文档介绍 SmartChart 新增的 8 个通用连接器（含 MQTT、Anthropic Claude），补充了消息推送、数据获取、IoT 通信和 AI 对话能力。

重要说明 #

sql_list 不是 SQL 语句：所有连接器的 dataset() / insert_dataset() 接收的 sql_list 是 数据/配置字符串列表（如 ['{"a":1}', '...']），框架会自动 ';'.join(sql_list) 后传入连接器处理。连接器内部将 join 后的内容作为数据/配置来解析（JSON 对象、纯文本、key=value 等）。

补充配置统一写在数据源的 remark 字段中（JSON 格式）。

目录 #

1. httpApi - 通用 HTTP API 调用
2. webhookGeneric - 通用 Webhook 推送
3. graphql - GraphQL 查询
4. sms - 短信发送
5. telegramBot - Telegram Bot 消息
6. slackWebhook - Slack 消息
7. mqtt - MQTT 消息(IoT)
8. anthropic - Anthropic Claude API

1. httpApi - 通用 HTTP API 调用 #

功能说明 #

调用任意 RESTful API，将结果自动解析为 SmartChart 数据集格式（df0）。

数据源配置 #

remark 补充配置：

{
  "method": "GET",
  "headers": {"Accept": "application/json"},
  "params": {"page": 1, "size": 20},
  "body": {"key": "value"},
  "content_type": "application/json",
  "timeout": 30,
  "response_path": "data.list"
}

数据内容写法 #

① 空或变量（URL 写在 host 中）：

'13800138000'

或直接留空，host 中配完整 URL

② 变量字典（替换 host 中的 {var} 占位符）：

'{"user_id":"1001","status":"active"}'

→ host 为 https://api.api.com/{user_id}/orders?status={status} → 实际请求 https://api.api.com/1001/orders?status=active

③ 完整请求配置（JSON，含 url/method 等）：

'{"url":"https://api.ex.com/data","method":"GET","headers":{"Accept":"application/json"}}'

返回值格式 #

成功 → [列名列表, row1, row2, ...] （df0 格式）
失败 → 抛出异常

2. webhookGeneric - 通用 Webhook 推送 #

功能说明 #

向任意支持 Webhook 的平台推送消息（Teams、Discord、自定义回调等），支持 HMAC 签名。

数据源配置 #

remark 补充配置：

{
  "sign_algorithm": "sha256",
  "headers": {},
  "template": {"text": "告警: {message}", "channel": "#alerts"}
}

数据内容写法 #

① 纯文本消息：

'服务器CPU使用率达到95%!'

② JSON 消息体：

'{"text":"告警: CPU 95%","channel":"#alerts"}'

③ 与 template 配合的变量：

'{"message":"服务器异常","level":"critical"}'

返回值 #

{msg: '发送成功', status: 200, response: {...}}

3. graphql - GraphQL 查询 #

功能说明 #

向任意 GraphQL 端点发送 Query 和 Mutation 请求。

数据源配置 #

remark 补充配置：

{
  "headers": {"User-Agent": "SmartChart"},
  "timeout": 30,
  "response_path": "data",
  "default_variables": {"first": 10}
}

数据内容写法 #

① 纯 Query 文本：

'{ user(login:"octocat") { name email bio repositories(first:5){ totalCount } } }'

② 含 query + variables 的 JSON：

'{"query":"query($login:String!){ user(login:$login){ name } }","variables":{"login":"octocat"}}'

③ Mutation：

'{"mutation":"mutation($t:String!,$b:String){ createIssue(input:{title:$t,body:$b}){ issue{ number } } }","variables":{"title":"Bug","body":"详情"}}'

返回值格式 #

成功 → [列名列表, row1, row2, ...] （df0 格式）
失败 → 抛出异常（含 GraphQL errors）

4. sms - 短信发送 #

功能说明 #

支持阿里云和腾讯云短信发送。

数据源配置 #

remark 阿里云配置：

{
  "sign_name": "您的签名",
  "template_code": "SMS_123456789",
  "phone_col": "phone",
  "content_cols": ["name", "code"],
  "content_keys": ["Name", "Code"]
}

remark 腾讯云配置：

{
  "sms_sdk_app_id": "1400000000",
  "template_code": "123456",
  "sign_name": "您的签名",
  "phone_col": "phone",
  "content_cols": ["name", "code"]
}

数据内容写法 #

① 单条 JSON（推荐）：

'{"phone":"13800138000","name":"张三","code":"123456"}'

② 多条批量（sql_list 中每条一条记录）：

['{"phone":"13800138000","name":"张三","code":"123456"}',
 '{"phone":"13800138001","name":"李四","code":"789012"}']

③ 纯手机号（通知类短信）：

'13800138000'

返回值 #

{msg: '发送成功 N 条', status: 200, sent: N, total: M}

5. telegramBot - Telegram Bot 消息 #

功能说明 #

通过 Telegram Bot API 发送消息到指定聊天/频道。

数据源配置 #

remark 补充配置：

{
  "chat_id": "-1001234567890",
  "disable_preview": false,
  "silent": false,
  "reply_to_message_id": 123456789
}

数据内容写法 #

① 发送到默认聊天（chat_id 配置在 user 或 remark 中）：

'Hello from SmartChart!'

② JSON（可覆盖 chat_id 和其他参数）：

'{"text":"告警: 服务异常","chat_id":"@channel_name"}'

③ HTML 格式（password 配置为 HTML）：

'<b>告警</b>\n<code>CPU: 95%</code>'

返回值 #

{msg: '发送成功', status: 200, results: [{chat_id, message_id}]}

6. slackWebhook - Slack 消息 #

功能说明 #

通过 Slack Incoming Webhook 或 chat.postMessage API 发送消息。

数据源配置 #

remark 补充配置：

{
  "channel": "#alerts",
  "username": "SmartChart Bot",
  "icon_emoji": ":chart_with_upwards_trend:",
  "thread_ts": "1672531200.123456",
  "unfurl_links": true
}

数据内容写法 #

① 纯文本：

'Hello from SmartChart!'

② Markdown（Slack mrkdwn）：

'*警报* :rotating_light:\n> 服务器 CPU 使用率 *95%*'

③ JSON（可覆盖 text/channel/thread_ts 等）：

'{"text":"告警通知","channel":"#alerts","thread_ts":"1672531200.123456"}'

返回值 #

{msg: '发送成功', status: 200, channel, ts}

7. mqtt - MQTT 消息（IoT） #

功能说明 #

支持 MQTT 协议的发布(Publish)/订阅(Subscribe)，适用于物联网场景。

数据源配置 #

remark 补充配置：

{
  "topic": "sensor/temperature",
  "timeout": 5,
  "qos": 0,
  "retain": false,
  "client_id": "smartchart_client",
  "use_ssl": false
}

数据内容写法 #

① 订阅模式（dataset）：topic 在 remark 中配置时，SQL 内容可为空或主题名：

'sensor/#'

或覆盖参数：

'{"topic":"sensor/temperature","timeout":10,"qos":1}'

② 发布模式（insert_dataset）：SQL 内容为要发送的消息体：

'{"temp":25.6,"humidity":60}'

或含 topic 覆盖：

'{"topic":"device/control","payload":{"command":"start"}}'

③ 纯文本：

'Hello MQTT!'

返回值格式 #

订阅 → df0：

[['topic', 'payload', 'qos', 'retain', 'timestamp'],
 ['sensor/temperature', '{"temp":25.6}', 0, false, 1714828800.123]]

发布 → df0：

[['success', 'topic', 'message_id', 'qos', 'retain', 'error'],
 [true, 'device/control', 1, 0, false, '']]

免费测试 Broker #

• EMQX: broker.emqx.io:1883
• HiveMQ: broker.hivemq.com:1883
• Mosquitto: test.mosquitto.org:1883

8. anthropic - Anthropic Claude API #

功能说明 #

调用 Anthropic Claude API 进行文本对话，支持流式输出和扩展思考（Extended Thinking）。

数据源配置 #

remark 补充配置：

{
  "max_tokens": 2048,
  "temperature": 0.7,
  "top_p": 1.0,
  "system": "你是一个有帮助的助手",
  "thinking": false,
  "thinking_budget": null
}

可选模型列表：

数据内容写法 #

① 纯文本对话：

'请解释量子计算的基本原理'

② 含配置覆盖的 JSON + prompt：

'{"model":"claude-opus-4-20250514","max_tokens":4096,"temperature":0.3},请写一首关于春天的诗'

→ 首项解析为配置覆盖，其余部分作为 prompt

返回值格式 #

非流式：

{
  "msg": "模型回复的完整文本",
  "token": 350,
  "input_tokens": 100,
  "output_tokens": 250,
  "status": 200
}

开启 thinking 时额外返回：

{
  "msg": "最终回复",
  "tmsg": "思考过程内容",
  "token": 800,
  "status": 200
}