Airbyte Zenloop Source 连接器实战指南:五大数据端点、连接配置与增量同步机制解析
Airbyte Zenloop Source 连接器实战指南:五大数据端点、连接配置与增量同步机制解析
本篇技术指南围绕 airbyte-integrations/connectors/source-zenloop 连接器展开,系统讲解 Zenloop 体验管理平台(IXM)REST API 暴露的五大数据端点(Surveys、Answers、Survey Groups、Survey Group Answers、Properties),并结合该仓库内的低代码声明式配置(manifest.yaml)、连接器参数定义(spec.json)与流实现源码(streams.py),说明如何在 Airbyte 中配置、运行并验证这个 Python CDK 源连接器。读完本文,你将掌握 Zenloop 连接器的全部数据流形态、鉴权与分页机制、增量同步语义,以及本地验收测试的运行方式。
一、Zenloop 连接器概述:从体验管理平台到数据仓库
Zenloop 是一个集成式体验管理平台(Integrated eXperience Management,IXM)。该 SaaS 解决方案会自动沿客户旅程的各个触点收集客户反馈,对其进行聚类分析与洞察,并据此制定针对性措施——既包括对满意客户的留存策略,也包括对流失客户的赢回策略。Zenloop 的 REST API 允许开发者从 Zenloop 平台检索调查问卷(Survey)与回答(Answer)信息。
在 Airbyte 中,source-zenloop 连接器的作用就是把 Zenloop API 暴露的上述数据同步到任意目标端(数据仓库、数据湖或 AI 应用)。从仓库元数据 metadata.yaml 可以看到该连接器的关键信息:
- 定义 ID:
f1e4c7f6-db5c-4035-981f-d35ab4998794 - Docker 镜像:
airbyte/source-zenloop,当前版本0.1.43 - 连接器类型:
source,子类型api,采用 Python 语言实现 - 实现方式:low-code 声明式 CDK(
cdk:low-code),以 YAML 清单驱动 - 发布阶段:
beta;支持级别:community;OSS 与 Cloud 均已启用 - 允许访问的主机:
api.zenloop.com(见allowedHosts) - 当前实现基于
airbyte-cdk 0.80.0,Python 版本要求^3.9,<3.12(见 pyproject.toml)
二、五大数据端点:可提取的数据范围
Zenloop API 由五个可从中提取数据的端点构成,这也是本连接器暴露的五个数据流(Stream)——这一点在 manifest.yaml 末尾的 streams 列表(surveys、survey_groups、properties、answers、answers_survey_group)与 integration_tests/configured_catalog.json 中可以相互印证:
1. Surveys(调查问卷)
用于获取用户组织内所有调查问卷的基础数据。对应请求路径 surveys(GET),返回记录包含以下字段:
| 字段 | 说明 | 类型 |
|---|---|---|
title |
调查问卷的标题或名称 | string |
status |
调查问卷状态(如 active、inactive、completed) | string |
public_hash_id |
与该调查问卷关联的唯一公开哈希标识 | string |
inserted_at |
调查问卷数据插入系统的时间 | string(date-time 格式) |
该流仅支持 full_refresh 全量同步模式。注意 primary_key 在旧版源码中为 None,记录以 public_hash_id 作为后续子流切片的关联键。
2. Answers(调查回答)
用于获取调查回答,附带基础调查数据与聚合后的 NPS 分数。请求路径为 surveys/{survey_id}/answers,返回记录字段非常丰富:
| 字段 | 说明 | 类型 |
|---|---|---|
id |
回答数据的唯一标识 | string |
score_type |
回答所对应的分数类型 | string |
score |
回答的分数 | number |
sentiment |
回答的情感分析结果 | string |
sentiment_per_label_name |
按标签名称划分的情感分析结果 | object |
name |
受访者姓名 | string |
recipient_id |
接收者的唯一标识 | string |
property_ids |
与该回答关联的属性 ID 列表 | array |
metatags |
回答的元标签 | object |
labels / labels_with_keywords |
回答的标签及标签关键词 | array / object |
inserted_at |
回答插入时间(增量游标字段) | string(date-time) |
email |
受访者邮箱 | string |
identity / identity_type |
受访者身份及其类型 | string |
comment / translated_comment |
受访者评论及翻译后评论 | string |
additional_answers |
附加问题的回答数组(含 additional_question_id、answer、inserted_at) |
array |
additional_questions |
附加问题对象 | object |
该流支持 full_refresh 与 incremental 两种同步模式。
3. Survey Groups(调查问卷组)
用于获取用户组织内所有调查问卷组的基础数据。请求路径为 survey_groups(GET),除组自身的 name、public_hash_id、inserted_at 外,还内嵌 surveys 数组(每个元素含 title、status、public_hash_id、inserted_at),即该组所包含的全部调查问卷。支持 full_refresh 模式。
4. Survey Group Answers(调查问卷组回答)
用于获取调查问卷组回答,同样附带基础调查数据与聚合 NPS 分数。请求路径为 survey_groups/{survey_group_id}/answers。其字段与 answers 流几乎一致,并额外包含 survey_public_hash_id(回答所属调查问卷的公开哈希 ID)。支持 full_refresh 与 incremental 模式。
5. Properties(属性)
用于获取属于某个给定调查问卷的回答所携带的属性(如性别、国家等自定义属性)。请求路径为 surveys/{survey_id}/properties,记录字段为 id、name、value。从 expected_records.jsonl 中的示例记录可以看到典型形态:{"id": "WldS...", "name": "gender", "value": "agender"}、{"name": "country", "value": "US"}。支持 full_refresh 模式。
API 参考文档(Zenloop 官方):
https://docs.zenloop.com/reference,其中各端点对应锚点分别是#get-list-of-surveys、#get-answers、#get-list-of-survey-groups、#get-answers-for-survey-group、#get-list-of-properties(见 streams.py 中的注释)。
三、连接器配置参数详解
连接器认证与过滤参数定义在 source_zenloop/spec.json,共 4 个配置项,其中仅 api_token 为必填:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
api_token |
string | 是 | Zenloop API Token,可在 Zenloop 设置页(https://app.zenloop.com/settings/api)获取;标记为 airbyte_secret,加密存储 |
date_from |
string | 否 | 增量同步起始时间,格式支持 2021-10-24T03:30:30Z(ISO 时间戳)或 2021-10-24(纯日期);留空则只同步当前时刻之后的数据 |
survey_id |
string | 否 | Zenloop 调查问卷 ID,可在同一设置页找到;留空则拉取所有调查问卷的回答(此时连接器会遍历全部调查问卷) |
survey_group_id |
string | 否 | Zenloop 调查问卷组 ID,可通过先同步 survey_groups 流获取;留空则拉取所有调查问卷组的回答 |
一个完整的配置示例(见 sample_files/config.json 与 integration_tests/sample_config.json):
{
"api_token": "<secret>",
"date_from": "2021-01-01",
"survey_id": "<secret>",
"survey_group_id": "<secret>"
}
在旧版(非低代码)源码 streams.py 中,这些参数的消费逻辑清晰可见:ZenloopStream.__init__ 接收 api_token、date_from、survey_id、survey_group_id,其中 date_from 缺省时取当前日期 datetime.today().strftime("%Y-%m-%d");survey_id/survey_group_id 缺省时为 None,触发子流对父流进行全量遍历切片(详见第五节)。
四、低代码声明式实现:manifest.yaml 核心机制
当前连接器采用 Low-Code CDK,source_zenloop/source.py 中 SourceZenloop 仅继承 YamlDeclarativeSource 并指向 manifest.yaml,全部数据流逻辑由 manifest.yaml 声明。以下是几个关键机制:
4.1 鉴权与基础请求
所有请求使用 Bearer Token 认证,基地址为 https://api.zenloop.com/v1/:
requester:
type: HttpRequester
http_method: "GET"
authenticator:
type: BearerAuthenticator
api_token: "{{ config['api_token'] }}"
4.2 分页机制
采用 DefaultPaginator + PageIncrement 策略,每页 50 条,从第 1 页开始,页码通过 per_page 请求参数注入:
paginator:
type: DefaultPaginator
pagination_strategy:
type: PageIncrement
page_size: 50
start_from_page: 1
page_size_option:
field_name: "per_page"
inject_into: "request_parameter"
这与旧版实现 streams.py 中的 next_page_token 逻辑一致:从响应的 meta 字段读取 page、per_page、total,只要 page < ceil(total / per_page) 就继续请求下一页。
4.3 增量同步游标
incremental_base_stream 使用 DatetimeBasedCursor,游标字段为 inserted_at,并固定追加 order_type=desc、order_by=inserted_at、date_shortcut=custom 三个请求参数:
incremental_sync:
type: DatetimeBasedCursor
cursor_field: "inserted_at"
datetime_format: "%Y-%m-%dT%H:%M:%S.%fZ"
cursor_granularity: "PT0.000001S"
start_datetime:
datetime: "{{ config['date_from'] }}"
datetime_format: "%Y-%m-%d"
end_datetime:
datetime: "{{ today_utc() }}"
datetime_format: "%Y-%m-%d"
step: "P1M"
时间边界通过 date_from(起始)与 date_to(结束)两个请求参数传给 API,且以 1 个月(P1M)为步长分段拉取,避免单次请求数据量过大。游标字段 inserted_at 的时间格式为带微秒的 ISO 时间戳 %Y-%m-%dT%H:%M:%S.%fZ,粒度精确到微秒(PT0.000001S)。
4.4 子流切片(Partition Router)
answers、properties、answers_survey_group 三个流都依赖父流(surveys 或 survey_groups)进行子流切片:
surveys_slicer:以surveys为父流,父键public_hash_id,切片字段idsurvey_groups_slicer:以survey_groups为父流,父键public_hash_id,切片字段id
自定义切片逻辑实现在 source_zenloop/components.py 的 ZenloopPartitionRouter 中:它继承 CDK 的 SubstreamPartitionRouter,读取 config_parent_field(即 survey_id 或 survey_group_id)——若用户在配置中指定了该值,则直接以该值生成单个切片(只同步指定的调查问卷/组);若未指定,则退化为标准的 Substream 逻辑,遍历父流所有记录逐个切片,实现"拉取全部调查问卷的回答"。对应子流的动态路径模板如下:
# properties 流路径(配置了 survey_id 时直取,否则按切片遍历)
"{{ 'surveys/' + config['survey_id'] + '/properties' if config['survey_id'] else 'surveys/' + stream_slice.id + '/properties' }}"
# answers 流路径
"{{ 'surveys/' + stream_slice.id + '/answers' }}"
# answers_survey_group 流路径
"{{ 'survey_groups/' + stream_slice.id + '/answers' }}"
4.5 连接检查
连接检查(check)仅需验证 surveys 流可用即可:
check:
type: CheckStream
stream_names: ["surveys"]
五、旧版流实现中的关键细节(增量语义与去重保护)
尽管当前实现已迁移到低代码清单,仓库中仍保留的 streams.py 完整呈现了连接器的历史实现思路,对理解增量语义极有价值:
- 游标推进与防重:
IncrementalZenloopStream.get_updated_state在记录inserted_at基础上 +1 秒(timedelta(seconds=1))作为新状态,确保下次同步不会重复拉取同一条记录; - 检查点间隔:
state_checkpoint_interval = 1000,即每读取 1000 条记录写一次状态检查点,兼顾断点续传与状态写入开销; - 子流切片:
ChildStreamMixin.stream_slices在未指定survey_id/survey_group_id时遍历父流所有记录,并把当前游标值作为每个切片的date_from传入,实现逐调查问卷的有状态增量拉取; - 父流缓存:
Surveys与SurveyGroups均设置use_cache = True,在子流多次遍历父流时复用已读取的父记录,减少 API 调用; - 主键:
answers、properties、answers_survey_group以id为主键,surveys、survey_groups无主键(全量覆盖语义)。
六、同步模式与本地验收测试
6.1 各流的同步模式一览
依据 integration_tests/configured_catalog.json:
| 流 | 支持的同步模式 | 推荐目标同步模式 |
|---|---|---|
answers |
full_refresh / incremental | append(追加) |
surveys |
full_refresh | overwrite(覆盖) |
survey_groups |
full_refresh | overwrite(覆盖) |
answers_survey_group |
full_refresh / incremental | append(追加) |
properties |
full_refresh | overwrite(覆盖) |
6.2 验收测试配置
仓库通过 acceptance-test-config.yml 定义了标准的 Connector Acceptance Tests(CAT)套件,覆盖 spec、connection(成功/失败)、discovery、basic_read、incremental(使用 abnormal_state.json 模拟未来状态)、full_refresh 全部用例,其中 basic_read 以 expected_records.jsonl 为期望记录且不要求严格顺序(exact_order: no),超时上限 2400 秒。
本地运行验收测试(需先构建镜像并按 integration_tests/sample_config.json 准备 secrets/config.json):
# 1. 构建连接器镜像
docker build -t airbyte/source-zenloop:dev .
# 2. 运行验收测试(在连接器目录内)
cd airbyte-integrations/connectors/source-zenloop
poetry install
poetry run pytest -p connector_acceptance_test
七、使用场景小结
- NPS 与反馈分析:通过
answers(或answers_survey_group)流将回答、评分(score)、情感(sentiment)与标签同步到数据仓库,支撑客户成功团队的回访与流失预警; - 问卷资产管理:
surveys与survey_groups流提供问卷/问卷组的元数据(标题、状态、创建时间),可用于维护问卷资产清单; - 用户画像补充:
properties流提供回答携带的自定义属性(性别、国家等),可与回答记录按property_ids关联,完善用户画像。
配置上只需记住三个要点:必填 api_token;需要历史数据时设置 date_from,否则默认从当前时刻开始;需要定向拉取时填写 survey_id/survey_group_id,留空则遍历全部——这正对应了 manifest.yaml 中 ZenloopPartitionRouter 的双路径切片逻辑。对于希望深入源码的读者,建议依次阅读 manifest.yaml(声明式数据流骨架)、components.py(自定义切片器)与 streams.py(历史实现与增量语义),即可完整掌握该连接器的数据流设计。