docs: add ping doc for source/sink (#2674)

Signed-off-by: yisaer <[email protected]>
lf-edge · Apr 19, 2024 · 6b8fe56 · 6b8fe56
1 parent 06caa8a
commit 6b8fe56
Show file tree

Hide file tree

Showing 22 changed files with 139 additions and 5 deletions.
diff --git 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
@@ -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://[email protected]: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://[email protected]: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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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://[email protected]: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://[email protected]: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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -65,6 +65,8 @@ template_config:
     dateTimeFormat: "YYYY-MM-dd HH:mm:ssSSS"
 ```
 
+你可以通过 api 的方式提前检查对应 sink 端点的连通性: [连通性检查](../../../api/restapi/connection.md#连通性检查)
+
 ### 全局配置
 
 用户可以在此处指定全局 sql 源设置。`default` 部分中指定的配置项将在运行此源时作为源的默认设置。