From 6b8fe56b9d9fb602ea9a040df4078c10a503c1d0 Mon Sep 17 00:00:00 2001
From: Song Gao <disxiaofei@163.com>
Date: Fri, 19 Apr 2024 10:19:08 +0800
Subject: [PATCH] docs: add ping doc for source/sink (#2674)

Signed-off-by: yisaer <disxiaofei@163.com>
---
 docs/directory.json                           |  8 +++
 docs/en_US/api/restapi/connection.md          | 46 +++++++++++++++-
 docs/en_US/guide/sinks/builtin/mqtt.md        |  2 +
 docs/en_US/guide/sinks/builtin/neuron.md      |  2 +
 docs/en_US/guide/sinks/builtin/websocket.md   |  2 +
 docs/en_US/guide/sinks/plugin/kafka.md        |  2 +
 docs/en_US/guide/sinks/plugin/sql.md          |  2 +
 docs/en_US/guide/sources/builtin/mqtt.md      |  2 +
 docs/en_US/guide/sources/builtin/neuron.md    |  2 +
 docs/en_US/guide/sources/builtin/websocket.md |  2 +
 docs/en_US/guide/sources/plugin/kafka.md      |  2 +
 docs/en_US/guide/sources/plugin/sql.md        |  2 +
 docs/zh_CN/api/restapi/connection.md          | 52 +++++++++++++++++--
 docs/zh_CN/guide/sinks/builtin/mqtt.md        |  2 +
 docs/zh_CN/guide/sinks/builtin/neuron.md      |  2 +
 docs/zh_CN/guide/sinks/builtin/websocket.md   |  2 +
 docs/zh_CN/guide/sinks/plugin/kafka.md        |  2 +
 docs/zh_CN/guide/sinks/plugin/sql.md          |  2 +
 docs/zh_CN/guide/sources/builtin/mqtt.md      |  2 +
 docs/zh_CN/guide/sources/builtin/neuron.md    |  2 +
 docs/zh_CN/guide/sources/plugin/kafka.md      |  2 +
 docs/zh_CN/guide/sources/plugin/sql.md        |  2 +
 22 files changed, 139 insertions(+), 5 deletions(-)

diff --git a/docs/directory.json b/docs/directory.json
index adf399d77c..d42480e365 100644
--- a/docs/directory.json
+++ b/docs/directory.json
@@ -475,6 +475,10 @@
           "title": "认证配置",
           "path": "api/restapi/authentication"
         },
+        {
+          "title": "连接管理",
+          "path": "api/restapi/connection"
+        },
         {
           "title": "流管理",
           "path": "api/restapi/streams"
@@ -1220,6 +1224,10 @@
           "title": "Authentication",
           "path": "api/restapi/authentication"
         },
+        {
+          "title": "Connection Management",
+          "path": "api/restapi/connection"
+        },
         {
           "title": "Streams",
           "path": "api/restapi/streams"
diff --git a/docs/en_US/api/restapi/connection.md b/docs/en_US/api/restapi/connection.md
index 3c2ec6319d..c5f347c853 100644
--- a/docs/en_US/api/restapi/connection.md
+++ b/docs/en_US/api/restapi/connection.md
@@ -1,4 +1,48 @@
-# Manage websocket connection
+# Manage connection
+
+## Connectivity check
+
+Check eKuiper connection connectivity via API
+
+### sink connection check
+
+```shell
+POST http://localhost:9081/metadata/sinks/connection/{sink}
+{
+  "configuration": "xxxx"
+}
+```
+
+The sink-side connection check will check the connectivity of the connection based on the incoming sinkType and configuration. Take mysql Sink as an example:
+
+```shell
+POST http://localhost:9081/metadata/sinks/connection/sql
+{
+  "url": "mysql://root@127.0.0.1:4000/test",
+  "table": "test",
+  "fields": ["a","b","c"]
+}
+```
+
+### Source side connection check
+
+```shell
+POST http://localhost:9081/metadata/sources/connection/{source}
+{
+  "configuration": "xxxx"
+}
+```
+
+The source-side connection check will check the connectivity of the connection based on the incoming sourceType and configuration. Take mysql Source as an example:
+
+```shell
+POST http://localhost:9081/metadata/sources/connection/sql
+{
+  "url": "mysql://root@127.0.0.1:4000/test",
+}
+```
+
+## Manage websocket connection
 
 Manage websocket endpoint connection in eKuiper through REST API
 
diff --git a/docs/en_US/guide/sinks/builtin/mqtt.md b/docs/en_US/guide/sinks/builtin/mqtt.md
index d759d2988b..73c75c935f 100644
--- a/docs/en_US/guide/sinks/builtin/mqtt.md
+++ b/docs/en_US/guide/sinks/builtin/mqtt.md
@@ -60,6 +60,8 @@ Below is another sample configuration for connecting to AWS IoT by using certifi
     }
 ```
 
+You can check the connectivity of the corresponding sink endpoint in advance through the API: [Connectivity Check](../../../api/restapi/connection.md#connectivity-check)
+
 ## Dynamic Topic
 
 If the result data contains the topic name, we can use it as the property of the mqtt action to achieve dynamic topic support. Assume the selected data has a field named `mytopic`, we can use data template syntax to set it as the property value for `topic` as below:
diff --git a/docs/en_US/guide/sinks/builtin/neuron.md b/docs/en_US/guide/sinks/builtin/neuron.md
index 0f6ea8067f..fb50700ab8 100644
--- a/docs/en_US/guide/sinks/builtin/neuron.md
+++ b/docs/en_US/guide/sinks/builtin/neuron.md
@@ -24,6 +24,8 @@ Assume the sink receive result map like:
 }
 ```
 
+You can check the connectivity of the corresponding sink endpoint in advance through the API: [Connectivity Check](../../../api/restapi/connection.md#connectivity-check)
+
 ### Send specify tags to neuron
 
 Below is a sample neuron action configuration. In which, raw is false so the sink will convert the result map into neuron's default format. The `tags` specify the tag names to be sent.
diff --git a/docs/en_US/guide/sinks/builtin/websocket.md b/docs/en_US/guide/sinks/builtin/websocket.md
index fd9ab89e13..b36af441a9 100644
--- a/docs/en_US/guide/sinks/builtin/websocket.md
+++ b/docs/en_US/guide/sinks/builtin/websocket.md
@@ -22,6 +22,8 @@ Other common sink properties are supported. Please refer to the [sink common pro
 
 When the websocket sink defines both addr and path, eKuiper will act as a websocket client to establish a websocket connection to the remote end and push messages through the connection.
 
+You can check the connectivity of the corresponding sink endpoint in advance through the API: [Connectivity Check](../../../api/restapi/connection.md#connectivity-check)
+
 ## eKuiper as websocket server
 
 When the websocket sink only defines path and addr is empty, eKuiper will serve as the websocket server and wait for the remote websocket connection to be established and push the message through the connection.
diff --git a/docs/en_US/guide/sinks/plugin/kafka.md b/docs/en_US/guide/sinks/plugin/kafka.md
index 122a9b9885..9fbae05dbc 100644
--- a/docs/en_US/guide/sinks/plugin/kafka.md
+++ b/docs/en_US/guide/sinks/plugin/kafka.md
@@ -73,6 +73,8 @@ Restart the eKuiper server to activate the plugin.
 | key                | true | Key information carried by the Kafka client in messages sent to the server |
 | headers            | true     | The header information carried by the Kafka client in the message sent to the server |
 
+You can check the connectivity of the corresponding sink endpoint in advance through the API: [Connectivity Check](../../../api/restapi/connection.md#connectivity-check)
+
 ### Setting Kafka Key and Headers
 
 Set the metadata when the Kafka client sends messages through keys and headers:
diff --git a/docs/en_US/guide/sinks/plugin/sql.md b/docs/en_US/guide/sinks/plugin/sql.md
index 39bbe2fd12..ac4379ffcc 100644
--- a/docs/en_US/guide/sinks/plugin/sql.md
+++ b/docs/en_US/guide/sinks/plugin/sql.md
@@ -40,6 +40,8 @@ When using `sqlserver` as the target, you need to confirm that the `sqlserver` e
 
 Other common sink properties are supported. Please refer to the [sink common properties](../overview.md#common-properties) for more information.
 
+You can check the connectivity of the corresponding sink endpoint in advance through the API: [Connectivity Check](../../../api/restapi/connection.md#connectivity-check)
+
 ## Sample usage
 
 Below is a sample for using sql to get the target data and set to mysql database
diff --git a/docs/en_US/guide/sources/builtin/mqtt.md b/docs/en_US/guide/sources/builtin/mqtt.md
index 0b2da66c19..66c4c14c46 100644
--- a/docs/en_US/guide/sources/builtin/mqtt.md
+++ b/docs/en_US/guide/sources/builtin/mqtt.md
@@ -84,6 +84,8 @@ Users can specify the global MQTT configurations here. The configuration items s
 
   :::
 
+You can check the connectivity of the corresponding sink endpoint in advance through the API: [Connectivity Check](../../../api/restapi/connection.md#connectivity-check)
+
 ### **Payload Handling**
 
 - `decompression`: Decompress the payload with the specified compression method. Support `gzip`, `zstd` method now.
diff --git a/docs/en_US/guide/sources/builtin/neuron.md b/docs/en_US/guide/sources/builtin/neuron.md
index c85bfcc684..85c84cd154 100644
--- a/docs/en_US/guide/sources/builtin/neuron.md
+++ b/docs/en_US/guide/sources/builtin/neuron.md
@@ -15,6 +15,8 @@ The Neuron source connector features an asynchronous dial mechanism, ensuring co
 
 In the eKuiper side, all Neuron source and sink instances share the same connection, thus the events consumed are also the same.
 
+You can check the connectivity of the corresponding sink endpoint in advance through the API: [Connectivity Check](../../../api/restapi/connection.md#connectivity-check)
+
 ## Configurations
 
 The connector in eKuiper can be configured with [environment variables](../../../configuration/configuration.md#environment-variable-syntax), [rest API](../../../api/restapi/configKey.md), or configuration file. This section focuses on the configuration file approach.
diff --git a/docs/en_US/guide/sources/builtin/websocket.md b/docs/en_US/guide/sources/builtin/websocket.md
index d59bf76aa4..adca021bb0 100644
--- a/docs/en_US/guide/sources/builtin/websocket.md
+++ b/docs/en_US/guide/sources/builtin/websocket.md
@@ -23,6 +23,8 @@ CREATE STREAM demo'() with(CONF_KEY="default", datasource="/api/data", type="web
 
 At this time, eKuiper will act as a websocket client, establish a websocket connection to 127.0.0.1:8080/api/data, and use this connection to receive data as the message source.
 
+You can check the connectivity of the corresponding sink endpoint in advance through the API: [Connectivity Check](../../../api/restapi/connection.md#connectivity-check)
+
 ## eKuiper serve as websocker server
 
 eKuiper can serve as a websocket server. At this time, the remote websocket client can actively initiate a websocket connection to eKuiper, and eKuiper will receive messages on the websocket connection as the message source.
diff --git a/docs/en_US/guide/sources/plugin/kafka.md b/docs/en_US/guide/sources/plugin/kafka.md
index 0372f7ff15..f327d42464 100644
--- a/docs/en_US/guide/sources/plugin/kafka.md
+++ b/docs/en_US/guide/sources/plugin/kafka.md
@@ -26,6 +26,8 @@ default:
   maxBytes: 1000000
 ```
 
+You can check the connectivity of the corresponding sink endpoint in advance through the API: [Connectivity Check](../../../api/restapi/connection.md#connectivity-check)
+
 ### Global configurations
 
 User can specify the global Kafka source settings here. The configuration items specified in `default` section will be taken as default settings for the source when running this source.
diff --git a/docs/en_US/guide/sources/plugin/sql.md b/docs/en_US/guide/sources/plugin/sql.md
index d4a41cf849..ce8c98acc5 100644
--- a/docs/en_US/guide/sources/plugin/sql.md
+++ b/docs/en_US/guide/sources/plugin/sql.md
@@ -148,6 +148,8 @@ select * from t where a > '2022-04-21 10:23:55' and b > 1 order by a asc, b asc
 
 ### *Note*: users only need set internalSqlQueryCfg or templateSqlQueryCfg, if both set, templateSqlQueryCfg will be used
 
+You can check the connectivity of the corresponding sink endpoint in advance through the API: [Connectivity Check](../../../api/restapi/connection.md#connectivity-check)
+
 ## Override the default settings
 
 If you have a specific connection that need to overwrite the default settings, you can create a customized section. In the previous sample, we create a specific setting named with `template_config`.  Then you can specify the configuration with option `CONF_KEY` when creating the stream definition (see [stream specs](../../../sqls/streams.md) for more info).
diff --git a/docs/zh_CN/api/restapi/connection.md b/docs/zh_CN/api/restapi/connection.md
index 3367904439..029802ead7 100644
--- a/docs/zh_CN/api/restapi/connection.md
+++ b/docs/zh_CN/api/restapi/connection.md
@@ -1,8 +1,52 @@
-# websocket 连接管理
+# 连接管理
+
+## 连通性检查
+
+通过 API 检查 eKuiper 连接的连通性
+
+### sink 端连接检查
+
+```shell
+POST http://localhost:9081/metadata/sinks/connection/{sink}
+{
+  "configuration": "xxxx"
+}
+```
+
+sink 端连接检查会根据传入的 sinkType 和配置来检查连接的连通性，以 mysql Sink 为例:
+
+```shell
+POST http://localhost:9081/metadata/sinks/connection/sql
+{
+  "url": "mysql://root@127.0.0.1:4000/test",
+  "table": "test",
+  "fields": ["a","b","c"]
+}
+```
+
+### source 端连接检查
+
+```shell
+POST http://localhost:9081/metadata/sources/connection/{source}
+{
+  "configuration": "xxxx"
+}
+```
+
+source 端连接检查会根据传入的 sourceType 和配置来检查连接的连通性，以 mysql Source 为例:
+
+```shell
+POST http://localhost:9081/metadata/sources/connection/sql
+{
+  "url": "mysql://root@127.0.0.1:4000/test",
+}
+```
+
+## websocket 连接管理
 
 通过 API 管理 eKuiper websocket 的连接
 
-## 创建 websocket endpoint
+### 创建 websocket endpoint
 
 ```shell
 POST http://localhost:9081/connection/websocket
@@ -16,7 +60,7 @@ POST http://localhost:9081/connection/websocket
 }
 ```
 
-## 删除 websocket endpoint
+### 删除 websocket endpoint
 
 ```shell
 DELETE http://localhost:9081/connection/websocket
@@ -30,7 +74,7 @@ DELETE http://localhost:9081/connection/websocket
 }
 ```
 
-## 查看 websocket endpoint
+### 查看 websocket endpoint
 
 ```shell
 GET http://localhost:9081/connection/websocket
diff --git a/docs/zh_CN/guide/sinks/builtin/mqtt.md b/docs/zh_CN/guide/sinks/builtin/mqtt.md
index 4f5faa7f7a..ad1b7f15dd 100644
--- a/docs/zh_CN/guide/sinks/builtin/mqtt.md
+++ b/docs/zh_CN/guide/sinks/builtin/mqtt.md
@@ -57,6 +57,8 @@
     }
 ```
 
+你可以通过 api 的方式提前检查对应 sink 端点的连通性: [连通性检查](../../../api/restapi/connection.md#连通性检查)
+
 ## 动态主题
 
 若结果数据中包含主题内容，可以将其作为主题属性，从而实现动态主题的需求。假设 SQL 选出的数据包含 `mytopic`, 则可以使用数据模板的语法将其设置为 `topic` 属性的值，如下所示：
diff --git a/docs/zh_CN/guide/sinks/builtin/neuron.md b/docs/zh_CN/guide/sinks/builtin/neuron.md
index be337d07ab..1192be5ba2 100644
--- a/docs/zh_CN/guide/sinks/builtin/neuron.md
+++ b/docs/zh_CN/guide/sinks/builtin/neuron.md
@@ -11,6 +11,8 @@
 
 其他通用的 sink 属性也支持，请参阅[公共属性](../overview.md#公共属性)。
 
+你可以通过 api 的方式提前检查对应 sink 端点的连通性: [连通性检查](../../../api/restapi/connection.md#连通性检查)
+
 ## 示例
 
 假设接收到的结果如下所示：
diff --git a/docs/zh_CN/guide/sinks/builtin/websocket.md b/docs/zh_CN/guide/sinks/builtin/websocket.md
index 92aef9f8ee..0e288f7c2d 100644
--- a/docs/zh_CN/guide/sinks/builtin/websocket.md
+++ b/docs/zh_CN/guide/sinks/builtin/websocket.md
@@ -17,6 +17,8 @@
 
 其他通用的 sink 属性也支持，请参阅[公共属性](../overview.md#公共属性)。
 
+你可以通过 api 的方式提前检查对应 sink 端点的连通性: [连通性检查](../../../api/restapi/connection.md#连通性检查)
+
 ## ekuiper 作为 websocket 客户端
 
 当 websocket sink 同时定义了 addr 和 path 后，eKuiper 将作为 websocket 客户端向远端建立 websocket 连接，并将消息通过该连接推送。
diff --git a/docs/zh_CN/guide/sinks/plugin/kafka.md b/docs/zh_CN/guide/sinks/plugin/kafka.md
index b166f3c7d1..38a5e632d2 100644
--- a/docs/zh_CN/guide/sinks/plugin/kafka.md
+++ b/docs/zh_CN/guide/sinks/plugin/kafka.md
@@ -75,6 +75,8 @@ $(PLUGINS_CUSTOM):
 
 其他通用的 sink 属性也支持，请参阅[公共属性](../overview.md#公共属性)。
 
+你可以通过 api 的方式提前检查对应 sink 端点的连通性: [连通性检查](../../../api/restapi/connection.md#连通性检查)
+
 ### 设置 key 和 headers
 
 通过 key 和 headers 设置 Kafka 客户端发送消息时的元数据:
diff --git a/docs/zh_CN/guide/sinks/plugin/sql.md b/docs/zh_CN/guide/sinks/plugin/sql.md
index 3d26f2ff3b..35b3cc6262 100644
--- a/docs/zh_CN/guide/sinks/plugin/sql.md
+++ b/docs/zh_CN/guide/sinks/plugin/sql.md
@@ -37,6 +37,8 @@
 
 其他通用的 sink 属性也支持，请参阅[公共属性](../overview.md#公共属性)。
 
+你可以通过 api 的方式提前检查对应 sink 端点的连通性: [连通性检查](../../../api/restapi/connection.md#连通性检查)
+
 ## 使用样例
 
 下面是一个获取目标数据并写入 MySQL 数据库的示例
diff --git a/docs/zh_CN/guide/sources/builtin/mqtt.md b/docs/zh_CN/guide/sources/builtin/mqtt.md
index eab9bd8573..cc152a85e5 100644
--- a/docs/zh_CN/guide/sources/builtin/mqtt.md
+++ b/docs/zh_CN/guide/sources/builtin/mqtt.md
@@ -41,6 +41,8 @@ demo_conf: #Conf_key
   server: "tcp://10.211.55.6:1883"
 ```
 
+你可以通过 api 的方式提前检查对应 sink 端点的连通性: [连通性检查](../../../api/restapi/connection.md#连通性检查)
+
 ## 全局配置
 
 用户可在 `default` 部分指定全局设置。
diff --git a/docs/zh_CN/guide/sources/builtin/neuron.md b/docs/zh_CN/guide/sources/builtin/neuron.md
index b32308b22d..7434c758d2 100644
--- a/docs/zh_CN/guide/sources/builtin/neuron.md
+++ b/docs/zh_CN/guide/sources/builtin/neuron.md
@@ -35,6 +35,8 @@ ipc:
 
 :::
 
+你可以通过 api 的方式提前检查对应 sink 端点的连通性: [连通性检查](../../../api/restapi/connection.md#连通性检查)
+
 ## Neuron 事件格式
 
 Neuron 事件通常采用以下 JSON 格式：
diff --git a/docs/zh_CN/guide/sources/plugin/kafka.md b/docs/zh_CN/guide/sources/plugin/kafka.md
index 36967886b0..fd44314717 100644
--- a/docs/zh_CN/guide/sources/plugin/kafka.md
+++ b/docs/zh_CN/guide/sources/plugin/kafka.md
@@ -26,6 +26,8 @@ default:
   maxBytes: 1000000
 ```
 
+你可以通过 api 的方式提前检查对应 sink 端点的连通性: [连通性检查](../../../api/restapi/connection.md#连通性检查)
+
 ### 全局配置
 
 用户可以在此处指定全局 kafka 源设置。`default` 部分中指定的配置项将在运行此源时作为源的默认设置。
diff --git a/docs/zh_CN/guide/sources/plugin/sql.md b/docs/zh_CN/guide/sources/plugin/sql.md
index c3a74309ed..74ac71dc09 100644
--- a/docs/zh_CN/guide/sources/plugin/sql.md
+++ b/docs/zh_CN/guide/sources/plugin/sql.md
@@ -65,6 +65,8 @@ template_config:
     dateTimeFormat: "YYYY-MM-dd HH:mm:ssSSS"
 ```
 
+你可以通过 api 的方式提前检查对应 sink 端点的连通性: [连通性检查](../../../api/restapi/connection.md#连通性检查)
+
 ### 全局配置
 
 用户可以在此处指定全局 sql 源设置。`default` 部分中指定的配置项将在运行此源时作为源的默认设置。