数据工程数据集成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点击查看免费下载PokeAPI 是 Airbyte 开源仓库中一个典型的manifest-only 声明式连接器declarative connector它没有手写 Python 源码整个连接器的行为完全由一个manifest.yaml文件声明。本文以该连接器为样例逐层拆解其声明式结构check / stream / spec / schema、metadata.yaml与acceptance-test-config.yml的配套约定并给出基于仓库内实际文件的本地开发、运行与测试路径帮助你理解 Airbyte 低代码/无代码连接器的构建与交付全流程。一、连接器概览一个读取单只宝可梦数据的 REST 源source-pokeapi 的作用是从公开的 PokéAPI REST API 读取一只宝可梦的资源数据每次同步请求https://pokeapi.co/api/v2/pokemon/{pokemon_name}其中{pokemon_name}是你在配置源时选择的宝可梦名称。该连接器的主要用途是教程、测试与演示场景例如官方 quickstart 与 Connector Builder 教学而非生产级数据管道。其发布信息可在仓库内的 metadata.yaml 中确认字段值名称PokeAPI定义 IDdefinitionId6371b14b-bc68-4236-bfbd-468e8df8e968Docker 镜像airbyte/source-pokeapi当前版本dockerImageTag0.3.74发布阶段alpha支持级别community连接器子类型api标签cdk:low-code、language:manifest-only许可ELv2从版本演进看见 docs/integrations/sources/pokeapi.md 的 Changelog该连接器经历了多次形态变化0.1.02020-05作为手写 source 首次加入 →0.2.02023-10迁移到 Low-code CDK →0.3.02024-08重构为 manifest-only 格式→ 后续版本陆续补齐cries、past_abilities、past_stats等字段0.3.69。可以说它就是观察「Python 手写 → 低代码 → 纯 manifest 声明」演进路线的最佳标本。二、声明式连接器是什么README 背后的技术底座仓库内 source-pokeapi/README.md 开篇即明确这是一个用 Connector Builder 构建的声明式连接器declarative connector其底层 YAML 格式遵循 Low-Code CDKconfig-based CDK的规范用户侧的使用文档与配置指南则对应docs/integrations目录下的连接器页面。所谓 manifest-only指的是连接器目录中不再有source.py等 Python 实现文件而是以manifest.yaml作为唯一的行为定义来源。仓库为此类连接器提供了专门的打包方式见 docker-images/Dockerfile.manifest-only-connector# Manifest-Only connector images are built on top of source-declarative-manifest image ARG BASE_IMAGEdocker.io/airbyte/source-declarative-manifest:latest FROM ${BASE_IMAGE} ... # Copy manifest.yaml to expected location (required for manifest-only connectors) RUN cp manifest.yaml ./source_declarative_manifest/manifest.yaml # Copy components.py if it exists (optional) RUN if [ -f components.py ]; then cp components.py ./source_declarative_manifest/components.py; fi也就是说镜像基于source-declarative-manifest基础镜像构建运行期由 CDK 运行时读取manifest.yaml生成连接器行为若需要自定义组件可选地附带components.py。这正是「零手写代码」的关键——连接器是一个配置声明 通用运行时的组合。仓库根目录的 poe-tasks/manifest-only-connector-tasks.toml 也印证了这类连接器的开发约定它们没有独立的lint-check/format-check步骤直接输出 No lint/format check step for this connector.集成测试统一通过airbyte-cdk connector test驱动。三、manifest.yaml 逐节拆解一个完整的最小声明式源source-pokeapi 的 manifest.yaml当前version: 4.5.4是理解声明式连接器的绝佳范本。它由check、definitions、streams、spec、metadata、schemas六大部分组成。3.1 check连接检查策略check: type: CheckStream stream_names: - pokemonCheckStream表示连接检查check通过尝试读取指定 stream 来完成——只要pokemon流能成功取到数据连接即视为有效。这是 API 型连接器最常见的检查方式之一相比显式调用健康检查端点它对任何 REST API 都通用。3.2 streams / retriever核心数据获取链路definitions.streams.pokemon是整个连接器的灵魂完整声明如下节选自 manifest.yaml 第 11–37 行definitions: streams: pokemon: type: DeclarativeStream name: pokemon primary_key: - id retriever: type: SimpleRetriever requester: $ref: #/definitions/base_requester path: /{{config[pokemon_name]}} http_method: GET record_selector: type: RecordSelector extractor: type: DpathExtractor field_path: [] schema_loader: type: InlineSchemaLoader schema: $ref: #/schemas/pokemon base_requester: type: HttpRequester url_base: https://pokeapi.co/api/v2/pokemon逐个理解其中的关键部件DeclarativeStream声明式流的容器声明了流名称、主键与数据获取策略。primary_key: [id]将 API 返回的id字段作为流主键供去重与写入目标表时使用。SimpleRetriever单请求取数器。它由requester如何发请求与record_selector如何从响应中取记录组成。requester通过$ref复用definitions.base_requester中定义的url_base: https://pokeapi.co/api/v2/pokemon并拼接运行时配置插值path: /{{config[pokemon_name]}}。也就是说最终请求 URL 形如https://pokeapi.co/api/v2/pokemon/dittopokemon_name来自用户配置。record_selectorDpathExtractorfield_path: []表示整个响应体即为一条记录PokéAPI 的/pokemon/{name}接口返回的就是单只宝可梦的完整 JSON 对象不需要从嵌套路径提取。InlineSchemaLoaderschema 直接内联在 manifest 中通过$ref指向文件底部的schemas.pokemon定义。这种「一个请求 整体作为单条记录 内联 schema」的组合就是声明式连接器处理单资源详情型 API的标准写法。3.3 spec连接配置规范JSON Schemaspec部分定义用户在 UI 中填写的配置表单本质是一份 JSON Schemaspec: type: Spec connection_specification: type: object $schema: http://json-schema.org/draft-07/schema# required: - pokemon_name properties: pokemon_name: type: string description: Pokemon requested from the API. title: Pokemon Name pattern: ^[a-z0-9_\-]$ enum: - bulbasaur - ivysaur - ... examples: - ditto - luxray - snorlax order: 0 additionalProperties: true关键点唯一必填字段pokemon_name即「Pokemon Name」用户在此选择要同步哪只宝可梦。enum白名单从bulbasaur一直枚举到calyrex共 898 个值对应前八世代图鉴。这意味着你只能选择列表内定义的宝可梦——这是该连接器最重要的使用限制详见后续「限制」一节。pattern: ^[a-z0-9_\-]$限定名称只能由小写字母、数字、下划线与连字符构成与 PokéAPI 的 URL 路径语义保持一致例如nidoran-f、ho-oh、typenull、jangmo-o。examples提供ditto、luxray、snorlax等常见示例方便用户在表单里快速选择。order: 0控制该字段在表单中的展示顺序。additionalProperties: true允许未来向配置中追加额外字段而不破坏 schema。3.4 schemaspokemon 流的完整数据模型schemas.pokemonmanifest.yaml 第 962–1484 行是一份手写维护的 JSON Schema完整描述了 PokéAPI/pokemon/{name}响应的结构。顶层字段包括字段类型说明idinteger图鉴编号同时是流主键namestring宝可梦名称base_experienceinteger基础经验值height/weightinteger身高 / 体重orderinteger排序号is_defaultboolean是否为默认形态location_area_encountersstring遭遇区域接口地址abilitiesarray能力列表含ability、is_hidden、slotheld_itemsarray携带道具含item、version_detailsmovesarray招式含move、version_group_detailsforms/speciesobject形态 / 物种引用name urlgame_indicesarray历代游戏索引spritesobject各方向/闪光的图片 URLfront_default、front_shiny、back_default等 8 个字符串字段statsarray种族值base_stat、effort、stattypesarray属性slot、typecriesobject叫声资源latest/legacypast_abilities/past_stats/past_typesarray历史世代中的能力 / 种族值 / 属性从 manifest 第 958–960 行的metadata.autoImportSchema.pokemon: false可以看出该 schema 是人工维护、禁用自动导入的——这是为了保证「重字段」模型稳定可控。同时 schema 大量使用type: [null, ...]的联合类型并开启additionalProperties: true体现了对第三方 API 响应结构变化的宽容设计。值得一提0.3.69 版本才补齐cries、past_abilities、past_stats三个字段见 docs/integrations/sources/pokeapi.md 的 Changelog说明这份 schema 是随 API 演进持续维护的。四、metadata.yaml连接器的发布与测试元数据metadata.yaml 是 Airbyte 连接器发布/编排的「身份证」几个值得关注的点allowedHosts.hosts: [*]允许连接任意主机PokéAPI 无域名限制。releases.rolloutConfiguration启用了渐进式发布progressive rollout默认模式autopilotautoStart: true、autoPromoteStages: true、strategy: fast。这与 Changelog 中多次出现的 autopilot 发布测试记录相呼应。remoteRegistries.pypi.enabled: false未启用 PyPI 注册不通过 PyAirbyte/Python 包方式发布。connectorBuildOptions.baseImage固定为docker.io/airbyte/source-declarative-manifest:7.33.0sha256:...带 sha256 摘要以保证构建可复现。connectorTestSuitesOptions声明了 liveTestspokeapi_config_dev_null与 acceptanceTests 两套测试验收测试所需的密钥从 GSM 读取SECRET_SOURCE-POKEAPI__CREDS。externalDocumentationUrls关联官方 PokéAPI v2 API 文档作为 api_reference 类型的外部链接。五、配置与使用连接一个 PokeAPI 源5.1 前置条件无。PokéAPI 是公开 API不需要认证见 docs/integrations/sources/pokeapi.md 的 Prerequisites。5.2 配置步骤Airbyte UI添加一个新的PokeAPIsource在Pokemon Name下拉框中选择要同步的宝可梦如ditto测试连接并保存。5.3 运行时配置样例仓库内的 integration_tests/sample_config.json 给出了最小配置{ pokemon_name: ditto }而 integration_tests/invalid_config.json 展示了非法配置datto不在 enum 白名单内用于验证 spec 校验能力。5.4 支持的同步模式与流同步模式仅支持Full Refresh全量刷新不支持增量同步。仓库的 integration_tests/configured_catalog.json 中pokemon流的supported_sync_modes只有[full_refresh]acceptance-test-config.yml 也直接以bypass_reason: This connector does not implement incremental sync跳过增量测试。唯一数据流pokemon主键id每次同步产出一条包含能力、种族值、叫声、形态、携带道具、招式、图片与属性等完整信息的记录含历史世代的past_abilities、past_stats。5.5 限制一个 source 配置只能同步一只宝可梦需要多只时请为每只宝可梦分别创建 source。pokemon_name被限制为 898 个枚举值截至calyrex列表之外的宝可梦无法选择。5.6 频率与限流PokéAPI 本身不强制限流但其 fair use 政策要求客户端降低请求频率并缓存响应。请合理编排同步计划避免违反公平使用政策导致 IP 被永久封禁详见 docs/integrations/sources/pokeapi.md 的 Rate limits 一节。若在 Airbyte Cloud 中使用且组织配置了 IP 白名单还需将 Airbyte Cloud 的 IP 地址加入允许列表对应连接器文档中的 IP allow list 一节。六、本地开发与测试manifest-only 连接器的标准流程README 将本地开发指引指向 Airbyte 的 connector 开发文档。结合仓库内 docs/platform/connector-development/local-connector-development.md 与 manifest-only 专属任务定义标准工具链如下6.1 工具链准备工具用途uv安装 Python CLI 应用如 Poe、airbyte-cdk CLIPoe the Poetpoe统一的任务入口poe直接列出可用任务docker构建与运行连接器容器镜像Airbyte CDK CLI通过uv tool install --upgrade airbyte-cdk[dev]安装6.2 常用命令在连接器目录内执行# 查看该连接器可用的 Poe 任务列表 poe # 安装连接器依赖manifest-only 连接器会安装 CDK CLI、ops CLI 与可选的单元测试依赖 poe install # 运行集成测试manifest-only 连接器统一走 airbyte-cdk connector test poe test-integration-tests # 获取连接器元数据信息由 poe-tasks/manifest-only-connector-tasks.toml 定义 poe get-version # 读取 metadata.yaml 的 dockerImageTag poe get-base-image # 读取 connectorBuildOptions.baseImage poe get-language # 读取 tags 中的 language:* 值从 poe-tasks/manifest-only-connector-tasks.toml 可以看到manifest-only 连接器没有 lint/format 步骤format-check、lint-check直接输出跳过提示单元测试仅当目录下存在unit_tests/pyproject.toml时才运行——source-pokeapi 目录中没有该文件因此实际主要执行集成测试。6.3 验收测试Acceptance Tests配置acceptance-test-config.yml 声明了标准 CAT 测试套件connector_image: airbyte/source-pokeapi:dev acceptance_tests: spec: tests: - spec_path: manifest.yaml backward_compatibility_tests_config: disable_for_version: 0.1.5 connection: tests: - config_path: secrets/config.json status: succeed discovery: tests: - config_path: secrets/config.json backward_compatibility_tests_config: disable_for_version: 0.1.5 basic_read: tests: - config_path: secrets/config.json configured_catalog_path: integration_tests/configured_catalog.json empty_streams: [] incremental: bypass_reason: This connector does not implement incremental sync full_refresh: tests: - config_path: secrets/config.json configured_catalog_path: integration_tests/configured_catalog.json逐一解读spec 测试以manifest.yaml作为 spec 来源并针对0.1.5之前的版本禁用向后兼容检查因为该版本之后 spec 结构发生过变化。connection 测试读取secrets/config.json由 GSM 拉取见metadata.yaml的connectorTestSuitesOptions期望连接成功。discovery 测试同样读取密钥配置期望发现 schema 与 manifest 一致。basic_read 测试按 integration_tests/configured_catalog.json 执行一次读取empty_streams: []表示不允许任何流为空。incremental 测试明确绕过——该连接器不支持增量同步。full_refresh 测试验证全量刷新流程。配套的测试脚手架在 integration_tests/acceptance.py它仅声明connector_acceptance_test.plugin插件并提供空的connector_setupfixture实际断言全部由 CAT 框架驱动。integration_tests/abnormal_state.json与sample_state.json则是状态state相关测试的占位文件。本地运行验收测试时需要先将密钥从 GSM 拉取到secrets/config.jsonpoe fetch-secrets等价于uvx airbyte-internal-ops secrets fetch。密钥文件在.gitignore中排除请务必注意凭证安全。6.4 运行验证在 Airbyte 中使用该连接器的最小运行流程为配置{pokemon_name: ditto}→ 触发 sync → 得到一条pokemon记录。也可以直接向 API 验证取数逻辑GET https://pokeapi.co/api/v2/pokemon/ditto返回的 JSON 即 manifest 中DpathExtractorfield_path: []将要整体透传的记录。若配置了不存在的名称如dattospec 的enum/pattern校验会在 UI 层直接拦截。七、从示例中学到的声明式设计模式以 source-pokeapi 为参照可以提炼出三类可复用的声明式连接器设计模式单资源详情型 API当端点形如/resource/{id}且返回整个资源对象时使用SimpleRetrieverpath插值/{{config[field]}}DpathExtractor(field_path: [])InlineSchemaLoader即可零代码完成连接器。配置白名单化用enum把用户输入收敛到 API 实际支持的取值集合配合pattern约束 URL 路径安全性将非法请求消灭在配置校验阶段。schema 人工维护 宽容建模对第三方 API 采用additionalProperties: true与[null, ...]联合类型既能容纳响应结构漂移又能保证「重字段」如moves、sprites的稳定性——这在metadata.autoImportSchema关闭时尤为重要。八、延伸阅读连接器用户文档与完整 Changelogdocs/integrations/sources/pokeapi.md声明式连接器的运行时与打包docker-images/Dockerfile.manifest-only-connector本地开发与测试指引docs/platform/connector-development/local-connector-development.mdmanifest-only 连接器的 Poe 任务定义poe-tasks/manifest-only-connector-tasks.tomlConnector Builder 与低代码 CDK 概览docs/platform/connector-development/connector-builder-ui/overview.md验收测试参考acceptance-test-config.yml 及 integration_tests/acceptance.py赞分享数据工程数据集成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 source-k6-cloud 声明式连接器全解析从 manifest 配置到验收测试Airbyte source k6 cloud 声明式连接器全解析从 manifest 配置到验收测试 本篇文章以 Airbyte 仓库中的 source k数据工程数据集成ETL后端大数据Airbyte source-pennylane 声明式连接器manifest.yaml 全量配置解析与本地调试实践Airbyte source pennylane 声明式连接器manifest.yaml 全量配置解析与本地调试实践 本文以 Airbyte 仓库中 sour数据工程数据集成ETL后端大数据Airbyte 声明式连接器实践source-castor-edc 的 Low-Code Manifest 架构、配置与本地开发指南Airbyte 声明式连接器实践source castor edc 的 Low Code Manifest 架构、配置与本地开发指南 本指南以 source数据工程数据集成ETL后端大数据创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考