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 b6ea086b51 [Docs][Connector-V2] Improve Notion source docs (#11378)
b6ea086b51 is described below
commit b6ea086b51c66bc49673a277fa8aeddc9e0d44c0
Author: Daniel Carter <[email protected]>
AuthorDate: Wed Jul 8 22:35:04 2026 +0800
[Docs][Connector-V2] Improve Notion source docs (#11378)
Co-authored-by: DanielCarter-stack
<[email protected]>
---
docs/en/connectors/source/Notion.md | 322 ++++++++----------------------------
docs/zh/connectors/source/Notion.md | 196 ++++++++++++----------
2 files changed, 177 insertions(+), 341 deletions(-)
diff --git a/docs/en/connectors/source/Notion.md
b/docs/en/connectors/source/Notion.md
index 8c2015eb08..fbed4eedcc 100644
--- a/docs/en/connectors/source/Notion.md
+++ b/docs/en/connectors/source/Notion.md
@@ -6,9 +6,9 @@ import ChangeLog from '../changelog/connector-http-notion.md';
## Description
-Used to read data from Notion.
+The Notion source connector reads data from the Notion API. It is based on the
HTTP source connector and automatically adds the `Authorization: Bearer
<password>` and `Notion-Version: <version>` headers from the connector options.
-## Key features
+## Key Features
- [x] [batch](../../introduction/concepts/connector-v2-features.md)
- [ ] [stream](../../introduction/concepts/connector-v2-features.md)
@@ -17,292 +17,108 @@ Used to read data from Notion.
- [ ] [parallelism](../../introduction/concepts/connector-v2-features.md)
- [ ] [support user-defined
split](../../introduction/concepts/connector-v2-features.md)
-## Options
+## Source Options
-| name | type | required | default value |
-|-----------------------------|---------|----------|---------------|
-| url | String | Yes | - |
-| password | String | Yes | - |
-| version | String | Yes | - |
-| method | String | No | get |
-| schema.fields | Config | No | - |
-| format | String | No | json |
-| params | Map | No | - |
-| body | String | No | - |
-| json_field | Config | No | - |
-| content_json | String | No | - |
-| poll_interval_millis | int | No | - |
-| retry | int | No | - |
-| retry_backoff_multiplier_ms | int | No | 100 |
-| retry_backoff_max_ms | int | No | 10000 |
-| enable_multi_lines | boolean | No | false |
-| common-options | config | No | - |
+| Name | Type | Required | Default | Description |
+|-----------------------------|---------|----------|---------|-------------|
+| url | String | Yes | - | Notion API
request URL, for example `https://api.notion.com/v1/users`. |
+| password | String | Yes | - | Notion
integration token. The connector sends it as the `Authorization` bearer token. |
+| version | String | Yes | - | Notion API
version, for example `2022-06-28`. The connector sends it as the
`Notion-Version` header. |
+| method | String | No | get | HTTP request
method. Supported values are `GET` and `POST`. |
+| headers | Map | No | - | Extra HTTP
headers. `Authorization` and `Notion-Version` are set by `password` and
`version`. |
+| params | Map | No | - | Query
parameters sent with the request. |
+| body | String | No | - | HTTP request
body. Usually used with `method = "POST"`. |
+| format | String | No | text | Response
format. Use `json` when reading Notion JSON into a SeaTunnel schema; use `text`
to return the raw response as `content`. |
+| schema | Config | No | - | Output schema.
Required when `format = "json"`. |
+| schema.fields | Config | No | - | Field names and
SeaTunnel data types used to parse the JSON response. |
+| content_field | String | No | - | JSONPath used
to select a nested part of the response before parsing it with `schema`. |
+| json_field | Config | No | - | Field-level
JSONPath mapping. Use it with `schema` when output fields come from different
JSON paths. |
+| pageing | Config | No | - | HTTP pagination
settings inherited from the HTTP source connector. |
+| poll_interval_millis | Int | No | - | Request
interval in milliseconds when the source is used in streaming mode. |
+| retry | Int | No | - | 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. |
+| json_filed_missed_return_null | Boolean | No | false | Return null
when a configured JSON field is missing. |
+| common-options | Config | No | - | Source plugin
common parameters. See [Source Common
Options](../common-options/source-common-options.md). |
-### url [String]
+:::tip
-http request url
+`password` is a sensitive Notion integration token. Avoid hardcoding real
tokens in shared job files. Use SeaTunnel variable substitution or your
deployment secret mechanism when possible.
-### password [String]
+:::
-API key for login, you can get more detail at this link:
+## Usage Notes
-https://developers.notion.com/docs/authorization
+- Set `format = "json"` and configure `schema` when you want typed SeaTunnel
rows.
+- Use `content_field` when the Notion response wraps records in a nested
array, such as `$.results.*`.
+- Use `json_field` only when each output field needs its own JSONPath
expression.
+- `password` and `version` override the `Authorization` and `Notion-Version`
headers. Put only other custom headers in `headers`.
-### version [String]
+## Task Example
-The Notion API is versioned. API versions are named for the date the version
is released
-
-### method [String]
-
-http request method, only supports GET, POST method
-
-### params [Map]
-
-http params
-
-### body [String]
-
-http body
-
-### poll_interval_millis [int]
-
-request http api interval(millis) in stream mode
-
-### retry [int]
-
-The max retry times if request http return to `IOException`
-
-### retry_backoff_multiplier_ms [int]
-
-The retry-backoff times(millis) multiplier if request http failed
-
-### retry_backoff_max_ms [int]
-
-The maximum retry-backoff times(millis) if request http failed
-
-### format [String]
-
-the format of upstream data, now only support `json` `text`, default `json`.
-
-when you assign format is `json`, you should also assign schema option, for
example:
-
-upstream data is the following:
-
-```json
-{
- "code": 200,
- "data": "get success",
- "success": true
-}
-```
-
-you should assign schema as the following:
+### Read Users
```hocon
-
-schema {
- fields {
- code = int
- data = string
- success = boolean
- }
+env {
+ parallelism = 1
+ job.mode = "BATCH"
}
-```
-
-connector will generate data as the following:
-
-| code | data | success |
-|------|-------------|---------|
-| 200 | get success | true |
-
-when you assign format is `text`, connector will do nothing for upstream data,
for example:
-
-upstream data is the following:
-
-```json
-{
- "code": 200,
- "data": "get success",
- "success": true
-}
-```
-
-connector will generate data as the following:
-
-| content |
-|----------------------------------------------------------|
-| {"code": 200, "data": "get success", "success": true} |
-
-### schema [Config]
-
-#### fields [Config]
-
-The schema fields of upstream data. For more details, please refer to [Schema
Feature](../../introduction/concepts/schema-feature.md).
-
-### content_json [String]
-
-This parameter can get some json data.If you only need the data in the 'book'
section, configure `content_field = "$.store.book.*"`.
-
-If your return data looks something like this.
-
-```json
-{
- "store": {
- "book": [
- {
- "category": "reference",
- "author": "Nigel Rees",
- "title": "Sayings of the Century",
- "price": 8.95
- },
- {
- "category": "fiction",
- "author": "Evelyn Waugh",
- "title": "Sword of Honour",
- "price": 12.99
+source {
+ Notion {
+ url = "https://api.notion.com/v1/users";
+ password = "<notion-integration-token>"
+ version = "2022-06-28"
+ method = "GET"
+ format = "json"
+ content_field = "$.results.*"
+ schema = {
+ fields {
+ object = string
+ id = string
+ type = string
+ person = {
+ email = string
+ }
+ name = string
+ avatar_url = string
}
- ],
- "bicycle": {
- "color": "red",
- "price": 19.95
- }
- },
- "expensive": 10
-}
-```
-
-You can configure `content_field = "$.store.book.*"` and the result returned
looks like this:
-
-```json
-[
- {
- "category": "reference",
- "author": "Nigel Rees",
- "title": "Sayings of the Century",
- "price": 8.95
- },
- {
- "category": "fiction",
- "author": "Evelyn Waugh",
- "title": "Sword of Honour",
- "price": 12.99
- }
-]
-```
-
-Then you can get the desired result with a simpler schema,like
-
-```hocon
-Http {
- url = "http://mockserver:1080/contentjson/mock";
- method = "GET"
- format = "json"
- content_field = "$.store.book.*"
- schema = {
- fields {
- category = string
- author = string
- title = string
- price = string
}
}
}
-```
-
-Here is an example:
-
-- Test data can be found at this link
[mockserver-config.json](../../../../seatunnel-e2e/seatunnel-connector-v2-e2e/connector-http-e2e/src/test/resources/mockserver-config.json)
-- See this link for task configuration
[http_contentjson_to_assert.conf](../../../../seatunnel-e2e/seatunnel-connector-v2-e2e/connector-http-e2e/src/test/resources/http_contentjson_to_assert.conf).
-
-### json_field [Config]
-This parameter helps you configure the schema,so this parameter must be used
with schema.
-
-If your data looks something like this:
-
-```json
-{
- "store": {
- "book": [
- {
- "category": "reference",
- "author": "Nigel Rees",
- "title": "Sayings of the Century",
- "price": 8.95
- },
- {
- "category": "fiction",
- "author": "Evelyn Waugh",
- "title": "Sword of Honour",
- "price": 12.99
- }
- ],
- "bicycle": {
- "color": "red",
- "price": 19.95
- }
- },
- "expensive": 10
+sink {
+ Console {
+ }
}
```
-You can get the contents of 'book' by configuring the task as follows:
+### Extract Fields With JSONPath
```hocon
source {
- Http {
- url = "http://mockserver:1080/jsonpath/mock";
+ Notion {
+ url = "https://api.notion.com/v1/users";
+ password = "<notion-integration-token>"
+ version = "2022-06-28"
method = "GET"
format = "json"
json_field = {
- category = "$.store.book[*].category"
- author = "$.store.book[*].author"
- title = "$.store.book[*].title"
- price = "$.store.book[*].price"
+ id = "$.results[*].id"
+ type = "$.results[*].type"
+ name = "$.results[*].name"
}
schema = {
fields {
- category = string
- author = string
- title = string
- price = string
+ id = string
+ type = string
+ name = string
}
}
}
}
```
-- Test data can be found at this link
[mockserver-config.json](https://github.com/apache/seatunnel/blob/dev/seatunnel-e2e/seatunnel-connector-v2-e2e/connector-http-e2e/src/test/resources/mockserver-config.json)
-- See this link for task configuration
[http_jsonpath_to_assert.conf](https://github.com/apache/seatunnel/blob/dev/seatunnel-e2e/seatunnel-connector-v2-e2e/connector-http-e2e/src/test/resources/http_jsonpath_to_assert.conf).
-
-### common options
-
-Source plugin common parameters, please refer to [Source Common
Options](../common-options/source-common-options.md) for details
-
-## Example
-
-```hocon
-Notion {
- url = "https://api.notion.com/v1/users";
- password = "SeaTunnel-test"
- version = "2022-06-28"
- content_field = "$.results.*"
- schema = {
- fields {
- object = string
- id = string
- type = string
- person = {
- email = string
- }
- avatar_url = string
- }
- }
-}
-```
-
## Changelog
<ChangeLog />
-
diff --git a/docs/zh/connectors/source/Notion.md
b/docs/zh/connectors/source/Notion.md
index 9be4d9a406..4e224a6e40 100644
--- a/docs/zh/connectors/source/Notion.md
+++ b/docs/zh/connectors/source/Notion.md
@@ -6,99 +6,119 @@ import ChangeLog from
'../changelog/connector-http-notion.md';
## 描述
-用于从 Notion 读取数据。
+Notion 源连接器用于从 Notion API 读取数据。它基于 HTTP 源连接器实现，并会根据 `password` 和 `version`
配置自动添加 `Authorization: Bearer <password>` 与 `Notion-Version: <version>` 请求头。
-## 关键特性
+## 主要特性
-- [x] [批](../../introduction/concepts/connector-v2-features.md)
-- [ ] [流](../../introduction/concepts/connector-v2-features.md)
+- [x] [批处理](../../introduction/concepts/connector-v2-features.md)
+- [ ] [流处理](../../introduction/concepts/connector-v2-features.md)
- [ ] [精确一次](../../introduction/concepts/connector-v2-features.md)
- [ ] [列投影](../../introduction/concepts/connector-v2-features.md)
-- [ ] [并行性](../../introduction/concepts/connector-v2-features.md)
-- [ ] [支持用户自定义split](../../introduction/concepts/connector-v2-features.md)
-
-## 选项
-
-| 参数名 | 类型 | 必须 | 默认值 | 描述 |
-|--------|------|------|--------|------|
-| url | String | 是 | - | HTTP 请求 URL |
-| password | String | 是 | - | API 密钥用于登录 |
-| version | String | 是 | - | Notion API 版本 |
-| method | String | 否 | get | HTTP 请求方法，仅支持 GET、POST 方法 |
-| schema.fields | Config | 否 | - | 上游数据的模式字段 |
-| format | String | 否 | json | 上游数据的格式，现在仅支持 `json` `text`，默认 `json`。 |
-| params | Map | 否 | - | HTTP 参数 |
-| body | String | 否 | - | HTTP 请求体 |
-| json_field | Config | 否 | - | JSON 字段配置 |
-| content_json | String | 否 | - | 内容 JSON 配置 |
-| poll_interval_millis | int | 否 | - | 流模式下请求 HTTP API 的间隔（毫秒） |
-| retry | int | 否 | - | 如果 HTTP 请求返回 `IOException` 的最大重试次数 |
-| retry_backoff_multiplier_ms | int | 否 | 100 | HTTP 请求失败时的重试退避倍数（毫秒） |
-| retry_backoff_max_ms | int | 否 | 10000 | HTTP 请求失败时的最大重试退避时间（毫秒） |
-| enable_multi_lines | boolean | 否 | false | 是否启用多行模式 |
-| common-options | config | 否 | - | 源插件通用参数 |
-
-### url [String]
-
-HTTP 请求 URL
-
-### password [String]
-
-API 密钥用于登录，您可以在以下链接获取更多详情：
-
-https://developers.notion.com/docs/authorization
-
-### version [String]
-
-Notion API 是版本化的。API 版本以发布版本的日期命名
-
-### method [String]
-
-HTTP 请求方法，仅支持 GET、POST 方法
-
-### params [Map]
-
-HTTP 参数
-
-### body [String]
-
-HTTP 请求体
-
-### poll_interval_millis [int]
-
-流模式下请求 HTTP API 的间隔（毫秒）
-
-### retry [int]
-
-如果 HTTP 请求返回 `IOException` 的最大重试次数
-
-### retry_backoff_multiplier_ms [int]
-
-HTTP 请求失败时的重试退避倍数（毫秒）
-
-### retry_backoff_max_ms [int]
-
-HTTP 请求失败时的最大重试退避时间（毫秒）
-
-### format [String]
-
-上游数据的格式，现在仅支持 `json` `text`，默认 `json`。
-
-### schema [Config]
-
-#### fields [Config]
-
-上游数据的模式字段。更多详情请参考 [Schema 特性](../../introduction/concepts/schema-feature.md)。
-
-### content_json [String]
-
-此参数可以获取一些 JSON 数据。
-
-### json_field [Config]
-
-此参数帮助您配置模式，因此此参数必须与 schema 一起使用。
+- [ ] [并行度](../../introduction/concepts/connector-v2-features.md)
+- [ ] [支持用户自定义切分](../../introduction/concepts/connector-v2-features.md)
+
+## 源选项
+
+| 名称 | 类型 | 是否必需 | 默认值 | 描述 |
+|-----------------------------|---------|------|-------|------|
+| url | String | 是 | - | Notion API 请求 URL，例如
`https://api.notion.com/v1/users`。 |
+| password | String | 是 | - | Notion 集成
Token。连接器会把它作为 `Authorization` Bearer Token 发送。 |
+| version | String | 是 | - | Notion API 版本，例如
`2022-06-28`。连接器会把它作为 `Notion-Version` 请求头发送。 |
+| method | String | 否 | get | HTTP 请求方法。支持 `GET` 和
`POST`。 |
+| headers | Map | 否 | - | 额外 HTTP
请求头。`Authorization` 和 `Notion-Version` 会由 `password` 与 `version` 设置。 |
+| params | Map | 否 | - | 随请求发送的查询参数。 |
+| body | String | 否 | - | HTTP 请求体，通常与 `method
= "POST"` 一起使用。 |
+| format | String | 否 | text | 响应格式。读取 Notion JSON
并转换为 SeaTunnel 字段时使用 `json`；返回原始响应内容时使用 `text`。 |
+| schema | Config | 否 | - | 输出结构。`format =
"json"` 时需要配置。 |
+| schema.fields | Config | 否 | - | 用于解析 JSON 响应的字段名和
SeaTunnel 数据类型。 |
+| content_field | String | 否 | - | JSONPath
表达式，用于先选取响应中的嵌套内容，再按 `schema` 解析。 |
+| json_field | Config | 否 | - | 字段级 JSONPath
映射。当不同输出字段来自不同 JSON 路径时，与 `schema` 一起使用。 |
+| pageing | Config | 否 | - | 继承自 HTTP 源连接器的分页配置。 |
+| poll_interval_millis | Int | 否 | - | 以流模式使用时，两次请求之间的间隔毫秒数。
|
+| retry | Int | 否 | - | HTTP 请求发生
`IOException` 时的最大重试次数。 |
+| retry_backoff_multiplier_ms | Int | 否 | 100 | 重试退避时间倍数，单位毫秒。 |
+| retry_backoff_max_ms | Int | 否 | 10000 | 最大重试退避时间，单位毫秒。 |
+| json_filed_missed_return_null | Boolean | 否 | false | 配置的 JSON 字段不存在时返回
null。 |
+| common-options | Config | 否 | - | 源插件通用参数，详情请参考 [Source
通用选项](../common-options/source-common-options.md)。 |
+
+:::tip 提示
+
+`password` 是敏感的 Notion 集成 Token。请避免在共享作业文件中硬编码真实 Token，优先使用 SeaTunnel
变量替换或部署环境的密钥管理方式注入。
+
+:::
+
+## 使用说明
+
+- 如果希望把 Notion JSON 响应解析成带类型的 SeaTunnel 行，请设置 `format = "json"` 并配置 `schema`。
+- 当 Notion 响应把记录包在嵌套数组中时，可以使用 `content_field`，例如 `$.results.*`。
+- 只有当每个输出字段都需要单独的 JSONPath 表达式时，才需要使用 `json_field`。
+- `password` 和 `version` 会覆盖 `Authorization` 与 `Notion-Version` 请求头，`headers`
中只需要放其他自定义请求头。
+
+## 任务示例
+
+### 读取用户列表
+
+```hocon
+env {
+ parallelism = 1
+ job.mode = "BATCH"
+}
+
+source {
+ Notion {
+ url = "https://api.notion.com/v1/users";
+ password = "<notion-integration-token>"
+ version = "2022-06-28"
+ method = "GET"
+ format = "json"
+ content_field = "$.results.*"
+ schema = {
+ fields {
+ object = string
+ id = string
+ type = string
+ person = {
+ email = string
+ }
+ name = string
+ avatar_url = string
+ }
+ }
+ }
+}
+
+sink {
+ Console {
+ }
+}
+```
+
+### 使用 JSONPath 提取字段
+
+```hocon
+source {
+ Notion {
+ url = "https://api.notion.com/v1/users";
+ password = "<notion-integration-token>"
+ version = "2022-06-28"
+ method = "GET"
+ format = "json"
+ json_field = {
+ id = "$.results[*].id"
+ type = "$.results[*].type"
+ name = "$.results[*].name"
+ }
+ schema = {
+ fields {
+ id = string
+ type = string
+ name = string
+ }
+ }
+ }
+}
+```
## 变更日志
<ChangeLog />
-
