Airbyte Zenloop Source 连接器实战指南:五大数据端点、连接配置与增量同步机制解析

原创2026-09-23 17:28:531,836 阅读
文章标签:数据工程数据集成ETL后端大数据

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,切片字段 id
  • survey_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(历史实现与增量语义),即可完整掌握该连接器的数据流设计。

登录后查看全文
airbyte