数据工程数据集成ETL后端大数据【免费下载链接】airbyteOpen-source data movement for ELT pipelines and AI agents — from APIs, databases files to warehouses, lakes, and AI applications. Both self-hosted and Cloud.项目地址https://gitcode.com/gh_mirrors/ai/airbyte点击查看免费下载本文以 source-shopwired 这一 manifest-only 连接器为对象结合 manifest.yaml、metadata.yaml 与 acceptance-test-config.yml 三份核心文件完整拆解 ShopWired 电商数据源如何仅凭一份 YAML 声明实现 14 条流的认证、分页、增量同步与子流分区并给出该类型连接器的本地开发、测试与发布链路。读完后你可以读懂任意 Airbyte 低代码Declarative连接器的 manifest 结构并具备独立修改、验证此类连接器配置的能力。1. 连接器定位一个没有一行运行时代码的 Source从 README 可以确认source-shopwired 是一个通过 Connector Builder 构建的声明式Declarative连接器其全部同步逻辑由 manifest.yaml 以 YAML 描述由 Low-Code CDK 在运行时解释执行——目录内没有任何 Python 或 Java 源码。metadata.yaml 也印证了这一点connectorBuildOptions.baseImage指定运行时基础镜像docker.io/airbyte/source-declarative-manifest:7.33.0固定 digestmanifest-only 连接器不需要构建自己的镜像层只需把 manifest 打进该镜像tags为language:manifest-only与cdk:low-codedockerRepository: airbyte/source-shopwireddockerImageTag: 0.0.44releaseStage: alpha、supportLevel: community、license: ELv2。连接器目录只有 5 个文件各自职责如下文件作用manifest.yaml连接器本体14 条流的完整声明、认证、分页、增量、转换与 JSON Schemametadata.yaml构建与注册元数据镜像、版本、标签、OSS/Cloud 注册开关、allowed hostsacceptance-test-config.yml验收测试CAT配置README.md标准声明式连接器说明与本地开发指引icon.svg连接器图标manifest 顶部声明type: DeclarativeSource与version: 6.44.0manifest 语言版本并在description中指向 ShopWired 的官网与 API 文档manifest.yaml 第 5-7 行。2. 连接配置SpecBasic Auth 三要素spec 段manifest.yaml 第 765-799 行 定义了用户在 Airbyte 界面创建 Source 时需要填写的三个必填字段字段类型说明api_keystringBasic Authentication 的用户名在 ShopWired 账户的 API settings 中获取airbyte_secret: true标记为敏感项api_secretstringBasic Authentication 的密码同为敏感项start_datestring增量同步起始时间format: date-time并用正则^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$强制YYYY-MM-DDTHH:MM:SSZUTC 带 Z 后缀格式三者均为required。认证由base_requester定义manifest.yaml 第 741-747 行base_requester: type: HttpRequester url_base: https://api.ecommerceapi.uk authenticator: type: BasicHttpAuthenticator password: {{ config[\api_secret\] }} username: {{ config[\api_key\] }}两个要点值得注意Jinja 模板引用配置{{ config[api_key] }}是 Low-Code CDK 的标准模板语法运行时被替换为用户在界面填写的实际值API Key 即用户名ShopWired 的凭据模型把 API Key / API Secret 直接映射到 HTTP Basic Auth 的 username / password因此连接器没有自定义 header 认证逻辑BasicHttpAuthenticator即可覆盖。所有 14 条流的requester都通过$ref: #/definitions/base_requester复用这一定义仅追加各自的path与http_method: GET这是声明式 manifest 典型的 DRY 写法。另外metadata.yaml 第 3-5 行 将出站域名收敛到api.ecommerceapi.uk单个 hostallowedHosts意味着同步期间连接器的网络访问被限制在该 API 域名内方便平台侧做出站白名单治理。3. 连接检查check用一条最轻的流验证凭据check: type: CheckStream stream_names: - countriescheck 段manifest.yaml 第 9-13 行 采用CheckStream策略点击 Test connection 时CDK 实际发起一次对/v1/countries的 GET 请求以响应成功作为凭据与连通性验证通过的条件。选择countries作为检查流是合理的——它无分页、数据量小、且是所有租户都存在的只读资源。4. 数据流全景14 条流的同步能力manifest 的streams列表第 749-763 行引用了 14 条流。结合 docs 侧的连接器页面各流能力汇总如下流名主键分页支持全量支持增量端点路径countriesid无是否/v1/countriespagesidDefaultPaginator是是/v1/pagesproductsidDefaultPaginator是是/v1/productsproducts_imagesidDefaultPaginator是否/v1/products/{prd_id}/imageschoice_setsidDefaultPaginator是否/v1/choice-setsproducts_reviewsidDefaultPaginator是是/v1/products/{prd_id}/reviewsproduct_optionsidDefaultPaginator是否/v1/products/{prd_id}/optionsproducts_variationsidDefaultPaginator是否/v1/products/{prd_id}/variationscustomersidDefaultPaginator是是/v1/customersordersidDefaultPaginator是是/v1/ordersshipping_zonesuuidDefaultPaginator是否/v1/shipping-zoneseventsidDefaultPaginator是是/v1/eventscategoriesidDefaultPaginator是是/v1/categoriesthemesidDefaultPaginator是是/v1/themes其中 8 条流支持基于时间的增量同步pages、products、products_reviews、customers、orders、events、categories、themescountries、choice_sets、product_options、products_variations、products_images、shipping_zones仅全量刷新。5. 分页机制统一的 Offset 分页器除countries外所有流共用同构的DefaultPaginator以 products 流为例manifest.yaml 第 113-126 行paginator: type: DefaultPaginator page_token_option: type: RequestOption field_name: offset inject_into: request_parameter page_size_option: type: RequestOption field_name: count inject_into: request_parameter pagination_strategy: type: OffsetIncrement page_size: 20 inject_on_first_request: true从源码结构看这套配置的语义是page_size_optioncount与page_token_optionoffset以 query parameter 形式注入每次请求即 ShopWired API 采用?count20offsetN的偏移量分页风格OffsetIncrement策略让 CDK 在每轮响应后自动递增offset直到响应为空为止page_size: 20是每页记录数上限inject_on_first_request: true保证第一页请求就带上offset0与count20而不是等翻页才注入响应终止判定未声明page_stop_condition/page_input_limit可以推断 CDK 以当页无记录返回作为停止条件这是 offset 分页最常见的兜底行为。响应体由JsonDecoder解码RecordSelectorDpathExtractorfield_path: []表示直接以 JSON 数组的每个元素作为一条记录——ShopWired 各列表端点均返回顶层数组无需再深入取值路径。6. 增量同步DatetimeBasedCursor 与 start_date 的协作以 orders 流manifest.yaml 第 494-507 行 为例incremental_sync: type: DatetimeBasedCursor cursor_field: created_at_utc cursor_datetime_formats: - %Y-%m-%dT%H:%M:%S datetime_format: %Y-%m-%dT%H:%M:%S start_datetime: type: MinMaxDatetime datetime: {{ config[\start_date\] }} datetime_format: %Y-%m-%dT%H:%M:%SZ end_datetime: type: MinMaxDatetime datetime: {{ now_utc().strftime(%Y-%m-%dT%H:%M:%SZ) }} datetime_format: %Y-%m-%dT%H:%M:%SZ工作机制可以拆成四层游标字段是合成字段ShopWired 原始 API 返回的是created/createdAt格式%a, %d %b %Y %H:%M:%S %z如Wed, 06 Oct 2026 12:00:00 0000而非 ISO 格式。因此各流先通过transformations用 Jinja 表达式把它格式化后写入created_at_utc字段游标再作用于该字段transformations: - type: AddFields fields: - type: AddedFieldDefinition path: - created_at_utc value: - {{ format_datetime(record[created], %Y-%m-%dT%H:%M:%S, %a, %d %b %Y %H:%M:%S %z) }}注意orders流读取原始字段record[created]而products流同时合成created_at_utc与updated_at_utc分别来自createdAt、updatedAt第 143-159 行因为products的游标是updated_at_utc——商品更新频繁用 updated 做游标能捕获存量商品的变更。start_datetime用MinMaxDatetime取用户配置start_date与状态文件中历史游标的较大值保证起点不会倒退end_datetime用now_utc()每次同步以当前 UTC 时间为上界形成(上界, 下界]语义的增量窗口cursor_datetime_formats复数声明游标值可能被解析的格式列表这里只有一种%Y-%m-%dT%H:%M:%S。这条链路完整解释了start_date为何在 spec 中必填且必须带Z后缀——它既是首次全窗口的下界也是MinMaxDatetime的输入之一。7. 子流分区以 products 为父流的 SubstreamPartitionRouterproducts_images、products_reviews、product_options、products_variations四条流请求的是嵌套端点/v1/products/{{ stream_partition[prd_id] }}/{resource}。其分区声明products_reviews 为例第 275-283 行partition_router: type: SubstreamPartitionRouter parent_stream_configs: - type: ParentStreamConfig parent_key: id partition_field: prd_id stream: $ref: #/definitions/streams/products incremental_dependency: true其含义是先跑父流productsCDK 逐条读取 products 记录取idparent_key写入子流分区的prd_id字段再渲染进 URL 模板incremental_dependency: true子流同步范围受父流游标约束。父流是增量同步时只有本次窗口内出现过的 product id才会作为子流分区被请求避免每次全量枚举所有商品去拉其图片/评论/变体。从源码结构看这是声明式 CDK 控制嵌套端点调用量的核心开关四条子流结构完全一致只是资源路径不同images/reviews/options/variations体现了父流驱动子流的电商数据建模方式商品是中心实体图片、评价、选项、变体都挂靠在商品之下。products_reviews自身还叠加了DatetimeBasedCursor游标created_at_utc同样先经format_datetime(record[createdAt], ...)合成即增量依赖 自身时间窗双重过滤。8. 一个值得注意的取巧设计shipping_zones 的合成主键shipping_zones流有一个独特的转换manifest.yaml 第 553-559 行transformations: - type: AddFields fields: - type: AddedFieldDefinition path: - uuid value: {{ now_utc() }}ShopWired 的 shipping zones 端点不返回稳定 ID而流的主键声明为uuid。连接器的做法是用同步时刻的now_utc()直接生成uuid字段——由于该流仅全量刷新每次全量替换该表用时间戳充当主键配合目的端全量 upsert 语义可以工作但它意味着同一行的 uuid 每次全量都会变化。可以推断这在目的端应配合按流全量替换或仅追加分析场景使用若你的下游依赖跨次同步的行级身份追踪这个设计需要特别注意。9. Schema 与测试证据InlineSchemaLoader testedStreams每条流的 schema 均由InlineSchemaLoader内联在 manifest 底部的schemas段manifest.yaml 第 919 行起共 2600 余行 JSON Schema。以products为例schema 覆盖了price、salePrice、costPrice、stock、sku、gtin、mpn、metaTitle、description2..5等约 40 个字段且全部字段除主键与合成时间字段外声明为type: [类型, null]双类型以容忍缺失值additionalProperties: true保证 API 新增字段不会被丢弃。几个关键 required 声明products要求id与updated_at_utcorders、customers、events、categories、themes均要求id与created_at_utcshipping_zones要求合成的uuid。manifest 的metadata段第 801-915 行还内嵌了两块测试结论autoImportSchema14 条流全部为true即允许在界面按流自动导入字段testedStreams逐流记录了streamHash、hasResponse、responsesAreSuccessful、hasRecords、primaryKeysArePresent、primaryKeysAreUnique等五项校验结果全部为true——这是对每条流做过真实 API 验证、且主键存在且唯一的留档证据也是判断该流当前配置被实测通过的直接依据。10. 本地开发与验收测试README 把开发指引指向了仓库内通用的 manifest-only 任务集。对这类连接器任务定义集中在 poe-tasks/manifest-only-connector-tasks.toml常用命令如下在连接器目录下执行# 安装 CDK CLIairbyte-cdk 提供 manifest 校验与测试能力 uv tool install --upgrade airbyte-cdk[dev] # 运行集成测试等价于 airbyte-cdk connector test connector-dir poe test-integration-tests # 查看该连接器语言 / 基础镜像 / 版本 poe -qq get-language # manifest-only poe -qq get-base-image # docker.io/airbyte/source-declarative-manifest:7.33.0sha256:... poe -qq get-version # 0.0.44该任务文件还说明了本地开发流程的通用约定install会依次安装airbyte-cdk[dev]、airbyte-internal-ops并在存在unit_tests/pyproject.toml时安装单元测试依赖本连接器没有该目录故跳过test-all聚合单元与集成两类测试。验收测试方面acceptance-test-config.yml 配置了connector_image: airbyte/source-shopwired:dev acceptance_tests: spec: tests: - spec_path: manifest.yaml connection: bypass_reason: This is a builder contribution, and we do not have secrets at this time discovery: bypass_reason: This is a builder contribution, and we do not have secrets at this time basic_read: bypass_reason: This is a builder contribution, and we do not have secrets at this time incremental: bypass_reason: This is a builder contribution, and we do not have secrets at this time full_refresh: bypass_reason: This is a builder contribution, and we do not have secrets at this time即只保留离线可跑的 spec 测试校验manifest.yaml本身的 schema 合法性connection/discovery/basic_read/incremental/full_refresh五类需要真实凭据的验收测试被显式 bypass理由是 builder contribution, and we do not have secrets at this time。这也解释了为何真实 API 行为的验证责任转移到了 manifest 内嵌的testedStreams结果上。11. 版本与发布链路当前镜像版本0.0.44metadata.yaml 第 20 行definitionId为41b34d94-1704-48b0-b921-cb3009ae69c1同时发布到 OSS 与 Cloud 连接器注册表registryOverrides.oss.enabled: true、cloud.enabled: true不发布 PyPIremoteRegistries.pypi.enabled: false包名airbyte-source-shopwired仅为占位docs/integrations/sources/shopwired.md 的 Changelog 显示该连接器自 0.0.12025-04-06由社区贡献者通过 Connector Builder 提交以来历史版本变更绝大多数是Update dependencies——对 manifest-only 连接器而言这通常意味着底层source-declarative-manifest基础镜像与依赖的安全/功能更新而非业务逻辑变化。判断一个 manifest-only 连接器行为是否变化应优先 diff manifest.yaml而非镜像 tag。12. 小结source-shopwired 是一个典型的零运行时代码Airbyte 连接器样本配置即实现specbase_requester 14 个DeclarativeStream定义构成了完整的同步行为认证复用BasicHttpAuthenticator分页复用DefaultPaginatorOffsetIncrement(page_size20)增量靠合成字段API 原始时间字段createdAt/created经format_datetime转换后写入created_at_utc/updated_at_utc再由DatetimeBasedCursorMinMaxDatetime以start_date为下界、now_utc()为上界做窗口过滤嵌套资源靠子流分区SubstreamPartitionRouter以products.id渲染prd_idincremental_dependency: true使子流请求量跟随父流增量窗口验证留档在 manifest 内testedStreams提供逐流主键校验证据acceptance-test-config.yml 则说明凭据类 CAT 处于 bypass 状态开发体验统一manifest-only 连接器由 poe-tasks/manifest-only-connector-tasks.toml 统一提供 install/test 任务airbyte-cdk connector test即可完成 manifest 校验与集成测试。若你需要为类似的 REST 电商/订阅类 API 编写 Airbyte 低代码连接器ShopWired 这份 manifest 在Basic Auth 认证、offset 分页、时间窗增量、父流驱动子流四个模式上都是可直接参照的实现范本。赞分享数据工程数据集成ETL后端大数据【免费下载链接】airbyteOpen-source data movement for ELT pipelines and AI agents — from APIs, databases files to warehouses, lakes, and AI applications. Both self-hosted and Cloud.项目地址https://gitcode.com/gh_mirrors/ai/airbyte点击查看免费下载相关推荐Airbyte Productboard 声明式 Source 连接器深度解析基于 Low-Code CDK 的 Manifest-only 实现Airbyte Productboard 声明式 Source 连接器深度解析基于 Low Code CDK 的 Manifest only 实现 本篇技术指数据工程数据集成ETL后端大数据Airbyte FireHydrant Source 连接器深度解析声明式 Low-Code 实现与事件响应数据同步实战Airbyte FireHydrant Source 连接器深度解析声明式 Low Code 实现与事件响应数据同步实战 本文以 Airbyte 开源仓库中的数据工程数据集成ETL后端大数据Airbyte source-twitter 连接器深度解析基于 Low-Code CDK 的声明式 Twitter 搜索实现Airbyte source twitter 连接器深度解析基于 Low Code CDK 的声明式 Twitter 搜索实现 Airbyte 仓库中的 so数据工程数据集成ETL后端大数据创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考