This is an automated email from the ASF dual-hosted git repository.
davidzollo pushed a commit to branch dev
in repository https://gitbox.apache.org/repos/asf/seatunnel.git
The following commit(s) were added to refs/heads/dev by this push:
new 49def59104 [Docs][Connector-V2] Improve Feishu sink docs (#11373)
49def59104 is described below
commit 49def5910491616b4f29265f9cf90dea9ad941f3
Author: Daniel Carter <[email protected]>
AuthorDate: Wed Jul 8 20:20:08 2026 +0800
[Docs][Connector-V2] Improve Feishu sink docs (#11373)
Co-authored-by: DanielCarter-stack
<[email protected]>
---
docs/en/connectors/sink/Feishu.md | 104 +++++++++++++++++++++++++++++++++-----
docs/zh/connectors/sink/Feishu.md | 104 ++++++++++++++++++++++++++++++++++----
2 files changed, 185 insertions(+), 23 deletions(-)
diff --git a/docs/en/connectors/sink/Feishu.md
b/docs/en/connectors/sink/Feishu.md
index 5a28a5ee1c..28df8f9f28 100644
--- a/docs/en/connectors/sink/Feishu.md
+++ b/docs/en/connectors/sink/Feishu.md
@@ -14,19 +14,26 @@ import ChangeLog from
'../changelog/connector-http-feishu.md';
- [ ] [exactly-once](../../introduction/concepts/connector-v2-features.md)
- [ ] [cdc](../../introduction/concepts/connector-v2-features.md)
+- [x] [support multiple table
write](../../introduction/concepts/connector-v2-features.md)
- [ ] [timer flush](../../introduction/concepts/connector-v2-features.md)
## Description
-Used to launch Feishu web hooks using data.
+Used to launch Feishu webhooks using upstream data.
> For example, if the data from upstream is [`age: 12, name: tyrantlucifer`],
> the body content is the following: `{"age": 12, "name": "tyrantlucifer"}`
-**Tips: Feishu sink only support `post json` webhook and the data from source
will be treated as body content in web hook.**
+The Feishu sink sends `POST` requests. Each upstream row is converted to JSON
and used as the request body. When `array_mode = true`, multiple rows are
accumulated into one JSON array before sending.
+
+:::tip
+
+Feishu webhook URLs and custom authentication headers are sensitive. Do not
print real tokens in logs or examples.
+
+:::
## Data Type Mapping
-| Seatunnel Data Type | Feishu Data Type |
+| SeaTunnel Data Type | Feishu Data Type |
|-----------------------------|------------------|
| ROW<br/>MAP | Json |
| NULL | null |
@@ -45,24 +52,97 @@ Used to launch Feishu web hooks using data.
## Sink Options
-| Name | Type | Required | Default |
Description |
-|----------------|--------|----------|---------|-------------------------------------------------------------------------------------------------------------|
-| url | String | Yes | - | Feishu webhook url
|
-| headers | Map | No | - | Http request headers
|
-| common-options | | no | - | Sink plugin common
parameters, please refer to [Sink Common
Options](../common-options/sink-common-options.md) for details |
+| Name | Type | Required | Default | Description
|
+|-----------------------------|---------|----------|---------|-------------------------------------------------------------------------------------------------------------------------|
+| url | String | Yes | - | Feishu webhook
URL. The current sink writer sends requests to this fixed URL and does not
replace table-name placeholders. |
+| headers | Map | No | - | HTTP request
headers. Use it when the webhook gateway requires extra headers.
|
+| params | Map | No | - | Accepted by the
option rule, but the current sink writer does not pass it to requests. Put
non-sensitive query parameters directly in `url` when needed. |
+| retry | Int | No | - | The maximum
retry times when the HTTP request fails with an `IOException`.
|
+| retry_backoff_multiplier_ms | Int | No | 100 | Retry backoff
multiplier in milliseconds.
|
+| retry_backoff_max_ms | Int | No | 10000 | Maximum retry
backoff in milliseconds.
|
+| array_mode | Boolean | No | false | Send rows as a
JSON array when true, or as one JSON object per request when false.
|
+| batch_size | Int | No | 1 | The maximum
number of rows sent in one request. Only works when `array_mode` is true.
|
+| request_interval_ms | Int | No | 0 | Interval in
milliseconds between two HTTP requests, used to avoid sending requests too
frequently. |
+| multi_table_sink_replica | Int | No | 1 | Number of sink
replicas used for multi-table write. See [Sink Common
Options](../common-options/sink-common-options.md). |
+| common-options | | No | - | Sink plugin
common parameters, please refer to [Sink Common
Options](../common-options/sink-common-options.md) for details. |
+
+## Usage Notes
+
+- The sink always sends `POST` JSON requests; it does not expose a `method`
option.
+- If the webhook URL needs query parameters, include non-sensitive parameters
directly in `url`. Prefer `headers` for authentication material when the
gateway supports it, because the full URL, including its query string, may
appear in logs or job metadata.
+- Multi-table jobs can use `multi_table_sink_replica`, but the Feishu sink
sends every row to the configured fixed `url`. It does not replace
`${database_name}`, `${schema_name}`, or `${table_name}` in the URL.
+- `array_mode` is useful when the receiver accepts a JSON array and you want
fewer HTTP requests.
+- Feishu webhook delivery is not exactly-once. If a retry happens after the
remote service has already handled a request, the receiver may see duplicate
messages.
## Task Example
### Simple
```hocon
-Feishu {
- url =
"https://www.feishu.cn/flow/api/trigger-webhook/108bb8f208d9b2378c8c7aedad715c19";
+env {
+ parallelism = 1
+ job.mode = "BATCH"
+}
+
+source {
+ FakeSource {
+ row_num = 1
+ schema = {
+ fields {
+ name = string
+ age = int
+ }
}
+ rows = [
+ {
+ fields = [tyrantlucifer, 12]
+ kind = INSERT
+ }
+ ]
+ }
+}
+
+sink {
+ Feishu {
+ url = "https://open.feishu.cn/open-apis/bot/v2/hook/<your-hook-token>"
+ }
+}
```
-## Changelog
+### With headers and retry
-<ChangeLog />
+```hocon
+Feishu {
+ url = "https://open.feishu.cn/open-apis/bot/v2/hook/<your-hook-token>"
+ headers {
+ Content-Type = "application/json"
+ }
+ retry = 3
+ retry_backoff_multiplier_ms = 200
+ retry_backoff_max_ms = 5000
+}
+```
+### Batch rows as JSON array
+```hocon
+Feishu {
+ url = "https://open.feishu.cn/open-apis/bot/v2/hook/<your-hook-token>"
+ array_mode = true
+ batch_size = 20
+ request_interval_ms = 500
+}
+```
+
+### Multi-table sink replica
+
+```hocon
+Feishu {
+ url = "https://open.feishu.cn/open-apis/bot/v2/hook/<your-hook-token>"
+ multi_table_sink_replica = 2
+}
+```
+
+## Changelog
+
+<ChangeLog />
diff --git a/docs/zh/connectors/sink/Feishu.md
b/docs/zh/connectors/sink/Feishu.md
index 923e16ec40..6aa3b35a05 100644
--- a/docs/zh/connectors/sink/Feishu.md
+++ b/docs/zh/connectors/sink/Feishu.md
@@ -14,15 +14,22 @@ import ChangeLog from
'../changelog/connector-http-feishu.md';
- [ ] [精确一次](../../introduction/concepts/connector-v2-features.md)
- [ ] [变更数据捕获](../../introduction/concepts/connector-v2-features.md)
-- [ ] [timer flush](../../introduction/concepts/connector-v2-features.md)
+- [x] [支持多表写入](../../introduction/concepts/connector-v2-features.md)
+- [ ] [定时刷新](../../introduction/concepts/connector-v2-features.md)
## 描述
-用于通过数据调用飞书的web hooks。
+用于通过上游数据调用飞书 Webhook。
> 例如，如果来自上游的数据是 [`年龄: 12, 姓名: tyrantlucifer`]，则 body 内容如下：`{"年龄": 12, "姓名":
> "tyrantlucifer"}`
-**提示：飞书接收器仅支持 `post json`类型的web hook，并且源数据将被视为web hook的正文内容。**
+飞书 Sink 会发送 `POST` 请求。每一条上游数据都会被转换成 JSON 并作为请求体发送。当 `array_mode = true`
时，多条数据会先合并成一个 JSON 数组再发送。
+
+:::tip 提示
+
+飞书 Webhook URL 和自定义鉴权请求头通常包含敏感信息，请不要在日志或示例中暴露真实 Token。
+
+:::
## 数据类型映射
@@ -45,22 +52,97 @@ import ChangeLog from
'../changelog/connector-http-feishu.md';
## 接收器选项
-| 名称 | 类型 | 是否必需 | 默认值 | 描述
|
-|----------------|--------|------|-----|------------------------------------------------------------|
-| url | String | 是 | - | 飞书web hook URL
|
-| headers | Map | 否 | - | HTTP 请求头
|
-| common-options | | 否 | - | 接收器插件常见参数，请参阅
[接收器通用选项](../common-options/sink-common-options.md) 以获取详细信息 |
+| 名称 | 类型 | 是否必需 | 默认值 | 描述
|
+|-----------------------------|---------|------|-------|------------------------------------------------------------------------------------------|
+| url | String | 是 | - | 飞书 Webhook URL。当前
Sink 写入器会向这个固定 URL 发送请求，不会替换表名相关占位符。 |
+| headers | Map | 否 | - | HTTP 请求头。Webhook
网关需要额外请求头时使用。 |
+| params | Map | 否 | - | 该参数会通过参数校验，但当前 Sink
写入器不会把它传入请求。如需查询参数，请把非敏感参数直接写在 `url` 中。 |
+| retry | Int | 否 | - | HTTP 请求发生
`IOException` 时的最大重试次数。 |
+| retry_backoff_multiplier_ms | Int | 否 | 100 | 重试退避时间倍数，单位毫秒。
|
+| retry_backoff_max_ms | Int | 否 | 10000 | 最大重试退避时间，单位毫秒。
|
+| array_mode | Boolean | 否 | false | 为 true 时按 JSON
数组发送多条数据；为 false 时每次请求发送一个 JSON 对象。 |
+| batch_size | Int | 否 | 1 | 单次请求最多发送的数据条数，仅在
`array_mode` 为 true 时生效。 |
+| request_interval_ms | Int | 否 | 0 | 两次 HTTP
请求之间的间隔毫秒数，用于避免请求过于频繁。 |
+| multi_table_sink_replica | Int | 否 | 1 | 多表写入时的 Sink 副本数。详情请参考
[Sink 通用选项](../common-options/sink-common-options.md)。 |
+| common-options | | 否 | - | Sink 插件通用参数，详情请参考
[Sink 通用选项](../common-options/sink-common-options.md)。 |
+
+## 使用说明
+
+- Sink 固定发送 `POST` JSON 请求，不提供 `method` 配置。
+- 如果 Webhook URL 需要查询参数，请把非敏感参数直接写在 `url` 中。鉴权类信息建议优先放在 `headers`
里，前提是网关支持这种方式，因为完整 URL（包括查询参数）可能出现在日志或作业元数据中。
+- 多表作业可以使用 `multi_table_sink_replica`，但飞书 Sink 会把所有数据发送到配置的固定 `url`，不会替换 URL
中的 `${database_name}`、`${schema_name}` 或 `${table_name}`。
+- 当接收端支持 JSON 数组，且希望减少 HTTP 请求次数时，可以启用 `array_mode`。
+- 飞书 Webhook 投递不是精确一次。如果远端已经处理成功但本地收到异常并触发重试，接收端可能看到重复消息。
## 任务示例
### 简单示例
```hocon
-Feishu {
- url =
"https://www.feishu.cn/flow/api/trigger-webhook/108bb8f208d9b2378c8c7aedad715c19";
+env {
+ parallelism = 1
+ job.mode = "BATCH"
+}
+
+source {
+ FakeSource {
+ row_num = 1
+ schema = {
+ fields {
+ name = string
+ age = int
+ }
}
+ rows = [
+ {
+ fields = [tyrantlucifer, 12]
+ kind = INSERT
+ }
+ ]
+ }
+}
+
+sink {
+ Feishu {
+ url = "https://open.feishu.cn/open-apis/bot/v2/hook/<your-hook-token>"
+ }
+}
+```
+
+### 配置请求头和重试
+
+```hocon
+Feishu {
+ url = "https://open.feishu.cn/open-apis/bot/v2/hook/<your-hook-token>"
+ headers {
+ Content-Type = "application/json"
+ }
+ retry = 3
+ retry_backoff_multiplier_ms = 200
+ retry_backoff_max_ms = 5000
+}
+```
+
+### 将多条数据按 JSON 数组发送
+
+```hocon
+Feishu {
+ url = "https://open.feishu.cn/open-apis/bot/v2/hook/<your-hook-token>"
+ array_mode = true
+ batch_size = 20
+ request_interval_ms = 500
+}
+```
+
+### 多表 Sink 副本
+
+```hocon
+Feishu {
+ url = "https://open.feishu.cn/open-apis/bot/v2/hook/<your-hook-token>"
+ multi_table_sink_replica = 2
+}
```
## 变更日志
-<ChangeLog />
\ No newline at end of file
+<ChangeLog />
