尧图网页设计 
Provider Hook 元数据迁移到 YAMLApache Airflow 声明式连接表单的实践指南【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflowApache Airflow 正在推动连接表单 UI 元数据从 Python Hook 代码迁移到声明式的provider.yaml配置文件中。本文以contributing-docs/23_provider_hook_migration_to_yaml.rst为主线系统讲解这一迁移的背景动机、YAML Schema 结构、迁移工具的使用方法并结合当前仓库的源码实现airflow-core/src/airflow/providers_manager.py、scripts/tools/generate_yaml_format_for_hooks.py与真实 provider 示例providers/docker/provider.yaml帮助 provider 贡献者快速、准确地把自定义连接表单迁移到新方案。读完本文你将能够熟练编写ui-field-behaviour、conn-fields与external-services声明并使用迁移脚本自动化完成从 Hook 代码到provider.yaml的转换。迁移背景为什么要把连接表单元数据从 Hook 代码中移出来在旧方案中provider 的连接表单 UI 元数据全部定义在 Python Hook 代码中主要依赖两类方法get_connection_form_widgets()定义自定义表单字段get_ui_field_behaviour()定义字段定制行为隐藏字段、重命名 label、占位符。这两种方法在使用时需要导入重量级依赖flask_appbuilder与wtforms。由此带来三个问题为 API 服务器增加了不必要的依赖负担API 服务器为了展示一个静态表单不得不加载全部 provider 的 Hook 代码Hook 代码与 UI 表现耦合职责混杂、难以维护。新的 YAML 方案允许在不导入 Hook 类的情况下加载元数据。从源码看核心消费逻辑位于 providers_manager.py 的_load_ui_metadata()方法中它直接遍历每个 provider 的provider.yaml数据填充_hook_name_dict、_connection_form_widgets与_field_behaviours全程不触发 Hook 类导入def _load_ui_metadata(self) - None: Load connection form UI metadata from provider info without importing hooks. for package_name, provider in self._provider_dict.items(): for conn_config in provider.data.get(connection-types, []): connection_type conn_config.get(connection-type) hook_class_name conn_config.get(hook-class-name) ... if hook_name : conn_config.get(hook-name): self._hook_name_dict[connection_type] hook_name if conn_fields : conn_config.get(conn-fields): self._add_widgets(package_name, hook_class_name, connection_type, conn_fields) if behaviour : conn_config.get(ui-field-behaviour): self._add_customized_fields(package_name, connection_type, behaviour)同时_import_hook()方法会检测 provider 是否已在 YAML 中声明了 UI 元数据若conn-fields或ui-field-behaviour已存在则跳过 Hook 代码路径避免重复初始化和不必要的wtforms导入反之若 Hook 仍定义旧方法会抛出AirflowProviderDeprecationWarningdeprecated_provider_since 3.2.0提示迁移到 YAML 声明式配置。YAML Schema 结构connection-types 下的三个关键键连接元数据统一定义在 provider 的provider.yaml的connection-types列表下。一个connection-types条目最少需要三个字段由 provider.yaml.schema.json 校验字段类型说明connection-typestringprovider 定义的连接类型标识hook-class-namestring实现该连接类型的 Hook 类全限定名hook-namestring连接类型在 UI 中的显示名称如 File (path)、Slack以 providers/docker/provider.yaml 为例connection-types: - hook-class-name: airflow.providers.docker.hooks.docker.DockerHook hook-name: Docker connection-type: docker conn-fields: reauth: label: Reauthenticate schema: type: - boolean - null description: Whether or not to refresh existing authentication on the Docker server. email: label: Email schema: type: - string - null ui-field-behaviour: hidden-fields: - schema relabeling: host: Registry URL login: Username placeholders: extra: {reauth: false, email: Jane.Doeexample.org}下面逐一展开三个可选键。ui-field-behaviour标准连接字段的定制ui-field-behaviour用于定制 Airflow 连接表单中的标准字段host、port、login、password、schema、extra、description支持三种子配置ui-field-behaviour: hidden-fields: - schema - extra relabeling: host: Registry URL login: Username placeholders: port: 5432hidden-fields要在 UI 中隐藏的标准字段名列表。Schema 限定枚举值为[description, host, port, login, password, schema, extra]默认[]relabeling字段名到自定义 label 的映射如把host显示为 Registry URLplaceholders字段名到占位文本的映射如port的占位符5432。从源码看providers_manager.py的_add_customized_fields()会把 kebab-case 键转换为 Python 风格hidden_fields/relabeling/placeholders经_customized_form_fields_schema_validator校验后存入_field_behaviours并通过_ensure_prefix_for_placeholders()为占位符自动补充extra__connection_type__前缀。conn-fields自定义字段存储于 Connection.extraconn-fields定义自定义表单字段这些字段的值最终会序列化进Connection.extraJSON。字段的schema属性使用 JSON Schema 定义字段类型与校验规则Airflow 对此的用法可参考官方 Param 文档中 Use Params to Provide a Trigger UI Form 一节当前仓库的相关实现位于airflow-core/src/airflow下的模板渲染模块conn-fields: keyfile_dict: label: Keyfile JSON description: Service account JSON key schema: type: string format: password project: label: Project Id schema: type: string default: my-project字段对象支持的属性见 provider.yaml.schema.jsonlabel字段显示名description帮助文本schemaJSON Schema 定义type支持string、integer、boolean、number、object、array等format: password表示敏感字段源码_add_widgets()会据此设置is_sensitiveTrue实现密码遮罩与脱敏default设置默认值。迁移工具在生成conn-fields时默认把所有字段的schema.type生成为[type, null]以保持旧行为中 extra 字段全部可选的语义。后端_to_api_format()会把字段的label按 JSON Schema 惯例提升为schema.title并读取schema.default作为表单初始值value。external-services连接类型访问的外部服务清单external-services是connection-types条目内可选的一个字符串数组用于列出该连接类型通过网络访问的上游 provider 或模型托管服务例如OpenAI、AWS Bedrock、Ollama。Registry 会把这个列表以表格形式渲染在 provider 的版本页面上方便浏览者一眼看出某个连接类型对接了哪些外部服务。需要特别说明的两点语义该列表是代表性示例而非穷举清单有些 Hook 会根据调用方传入的模型标识解析目标服务例如PydanticAIHook此时它理论上可以访问模型 id 指向的任何服务列表永远不可能完整。所以它应被当作示例服务而不是兼容性矩阵。这一点在 schema 的描述中也有明确注释见 provider.yaml.schema.json 中external-services的description。与顶层integrations键无关顶层integrations描述的是框架级集成如 Kubernetes、Docker用于驱动 provider 文档页面、Logo 与标签的生成external-services仅作用于connection-types条目内部、只列举通过网络访问的服务对文档生成、Logo、标签均无影响。真实用例可参考 providers/common/ai/provider.yaml其中pydanticai系列连接类型声明了对应的external-services如Azure OpenAI、AWS Bedrock、Google Vertex AI、OpenAI等其生成逻辑位于providers/common/ai/src/airflow/providers/common/ai/get_provider_info.pyconnection-types: - hook-class-name: airflow.providers.common.ai.hooks.pydantic_ai.PydanticAIAzureHook hook-name: Pydantic AI (Azure OpenAI) connection-type: pydanticai-azure external-services: - Azure OpenAI迁移工具generate_yaml_format_for_hooks.pyscripts/tools/generate_yaml_format_for_hooks.py 提供从现有 Python Hook 代码中自动抽取元数据的能力。该脚本要求 Airflow 开发环境就绪所有 workspace 模块可用并在运行时把仓库根目录与dev/breeze/src加入sys.path因此请务必在 airflow 虚拟环境中运行。脚本支持两个互斥参数必选其一--provider name抽取某个 provider 下全部连接类型读取其provider.yaml的connection-types列表--hook-class full.name仅抽取指定 Hook 类适合连接类型多、只想处理单个 Hook 的场景。另有一个可选参数--update-yaml把抽取结果直接写回provider.yaml仅与--provider搭配使用。基本用法示例从 provider 抽取打印到 stdout不修改文件python scripts/generate_yaml_format_for_hooks.py --provider docker从特定 Hook 类抽取python scripts/generate_yaml_format_for_hooks.py \ --hook-class airflow.providers.docker.hooks.docker.DockerHook直接更新 provider.yamlpython scripts/generate_yaml_format_for_hooks.py --provider docker --update-yaml脚本工作原理脚本的核心抽取逻辑分为两步extract_from_hook()通过import_string导入 Hook 类读取其conn_type属性若类注意仅检查类自身__dict__不检查继承链定义了get_connection_form_widgets()则调用并交给extract_conn_fields()处理。字段转换规则extract_conn_fields()字段键去掉extra__connection_type__前缀后作为conn-fields的键名依据 wtforms 字段类名映射 JSON Schema 类型BooleanField→[boolean, null]、IntegerField→[integer, null]、PasswordField→[string, null]且format: password、其余 →[string, null]从kwargs[default]提取默认值从any_of()/AnyOf校验器提取enum枚举约束第一个位置参数args[0]作为label否则用字段名做 title 化处理。extract_ui_behaviour()同样只在 Hook 类自身定义get_ui_field_behaviour()时调用把返回字典中的hidden_fields/relabeling/placeholders转换为 kebab-case 的 YAML 键。--update-yaml模式下update_provider_yaml()会把抽取结果合并进原provider.yaml保留sort_keysFalse以维持书写顺序allow_unicodeTrue兼容中文等非 ASCII 文本仅当存在可更新的元数据时才写回文件。后端如何消费迁移结果迁移完成后连接表单的完整数据流如下providers_manager.py的_load_ui_metadata()在不导入 Hook 类的前提下从provider.yaml的connection-types中直接加载hook-name、conn-fields、ui-field-behaviour_add_widgets()把conn-fields转成ConnectionFormWidgetInfo字段名统一为extra__connection_type__field_name前缀格式format: password字段被标记为敏感_add_customized_fields()校验并注册字段行为当真正需要实例化 Hook 时_import_hook()若发现 YAML 已提供 UI 元数据则完全跳过旧方法调用否则回退到旧代码路径并发出弃用警告。这解释了迁移的核心收益API 服务器启动时不再需要为展示静态表单而导入 provider 的 Hook 类与flask_appbuilder、wtforms依赖启动性能得以改善provider 与 UI 表现彻底解耦。迁移实操建议与注意事项先跑通单个 Hook 再整包迁移先用--hook-class验证单个类的抽取结果确认conn-fields的 schema 类型、默认值、枚举都符合预期再对整包执行--provider审查生成的 label当 wtforms 字段没有显式 label 时脚本会用字段名做title()化处理下划线转空格务必人工校对生成的label与description保持可空语义生成的schema.type是数组形式如[boolean, null]这是为了兼容旧的extra 字段均可选行为迁移时不要随意改成单值type以免改变表单校验语义敏感字段必须标注format: password只有这样才能触发后端is_sensitiveTrue的脱敏与遮罩处理善用 schema 校验connection-types及其子键都有严格 JSON Schema 约束如hidden-fields的枚举、external-services的minItems: 1编写或更新后应通过 schema 校验避免字段名拼写错误导致元数据静默失效--update-yaml前先备份脚本会直接覆写provider.yaml建议先在版本控制分支上操作或先以纯打印模式核对输出external-services 保持克制只列举代表性上游服务不要试图穷举尤其是模型名驱动目标地址的 Hook如 PydanticAI 系列并在 PR 描述中说明列表的示例性质。总结把连接表单元数据从 Hook 代码迁移到provider.yaml是 Airflow 走向声明式 provider 元数据的关键一步ui-field-behaviour承载标准字段定制conn-fields以 JSON Schema 定义 extra 自定义字段external-services为 Registry 提供外部服务概览。迁移工具 generate_yaml_format_for_hooks.py 能自动化抽取绝大部分元数据配合 providers_manager.py 的免导入加载机制既消除了flask_appbuilder/wtforms的运行时依赖又提升了 API 服务器启动性能。对 provider 贡献者而言遵循本文的 Schema 结构与迁移步骤即可平滑完成迁移同时借助 provider.yaml.schema.json 保证配置的健壮性。【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Provider Hook 元数据迁移到 YAML：Apache Airflow 声明式连接表单的实践指南
Provider Hook 元数据迁移到 YAMLApache Airflow 声明式连接表单的实践指南【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflowApache Airflow 正在推动连接表单 UI 元数据从 Python Hook 代码迁移到声明式的provider.yaml配置文件中。本文以contributing-docs/23_provider_hook_migration_to_yaml.rst为主线系统讲解这一迁移的背景动机、YAML Schema 结构、迁移工具的使用方法并结合当前仓库的源码实现airflow-core/src/airflow/providers_manager.py、scripts/tools/generate_yaml_format_for_hooks.py与真实 provider 示例providers/docker/provider.yaml帮助 provider 贡献者快速、准确地把自定义连接表单迁移到新方案。读完本文你将能够熟练编写ui-field-behaviour、conn-fields与external-services声明并使用迁移脚本自动化完成从 Hook 代码到provider.yaml的转换。迁移背景为什么要把连接表单元数据从 Hook 代码中移出来在旧方案中provider 的连接表单 UI 元数据全部定义在 Python Hook 代码中主要依赖两类方法get_connection_form_widgets()定义自定义表单字段get_ui_field_behaviour()定义字段定制行为隐藏字段、重命名 label、占位符。这两种方法在使用时需要导入重量级依赖flask_appbuilder与wtforms。由此带来三个问题为 API 服务器增加了不必要的依赖负担API 服务器为了展示一个静态表单不得不加载全部 provider 的 Hook 代码Hook 代码与 UI 表现耦合职责混杂、难以维护。新的 YAML 方案允许在不导入 Hook 类的情况下加载元数据。从源码看核心消费逻辑位于 providers_manager.py 的_load_ui_metadata()方法中它直接遍历每个 provider 的provider.yaml数据填充_hook_name_dict、_connection_form_widgets与_field_behaviours全程不触发 Hook 类导入def _load_ui_metadata(self) - None: Load connection form UI metadata from provider info without importing hooks. for package_name, provider in self._provider_dict.items(): for conn_config in provider.data.get(connection-types, []): connection_type conn_config.get(connection-type) hook_class_name conn_config.get(hook-class-name) ... if hook_name : conn_config.get(hook-name): self._hook_name_dict[connection_type] hook_name if conn_fields : conn_config.get(conn-fields): self._add_widgets(package_name, hook_class_name, connection_type, conn_fields) if behaviour : conn_config.get(ui-field-behaviour): self._add_customized_fields(package_name, connection_type, behaviour)同时_import_hook()方法会检测 provider 是否已在 YAML 中声明了 UI 元数据若conn-fields或ui-field-behaviour已存在则跳过 Hook 代码路径避免重复初始化和不必要的wtforms导入反之若 Hook 仍定义旧方法会抛出AirflowProviderDeprecationWarningdeprecated_provider_since 3.2.0提示迁移到 YAML 声明式配置。YAML Schema 结构connection-types 下的三个关键键连接元数据统一定义在 provider 的provider.yaml的connection-types列表下。一个connection-types条目最少需要三个字段由 provider.yaml.schema.json 校验字段类型说明connection-typestringprovider 定义的连接类型标识hook-class-namestring实现该连接类型的 Hook 类全限定名hook-namestring连接类型在 UI 中的显示名称如 File (path)、Slack以 providers/docker/provider.yaml 为例connection-types: - hook-class-name: airflow.providers.docker.hooks.docker.DockerHook hook-name: Docker connection-type: docker conn-fields: reauth: label: Reauthenticate schema: type: - boolean - null description: Whether or not to refresh existing authentication on the Docker server. email: label: Email schema: type: - string - null ui-field-behaviour: hidden-fields: - schema relabeling: host: Registry URL login: Username placeholders: extra: {reauth: false, email: Jane.Doeexample.org}下面逐一展开三个可选键。ui-field-behaviour标准连接字段的定制ui-field-behaviour用于定制 Airflow 连接表单中的标准字段host、port、login、password、schema、extra、description支持三种子配置ui-field-behaviour: hidden-fields: - schema - extra relabeling: host: Registry URL login: Username placeholders: port: 5432hidden-fields要在 UI 中隐藏的标准字段名列表。Schema 限定枚举值为[description, host, port, login, password, schema, extra]默认[]relabeling字段名到自定义 label 的映射如把host显示为 Registry URLplaceholders字段名到占位文本的映射如port的占位符5432。从源码看providers_manager.py的_add_customized_fields()会把 kebab-case 键转换为 Python 风格hidden_fields/relabeling/placeholders经_customized_form_fields_schema_validator校验后存入_field_behaviours并通过_ensure_prefix_for_placeholders()为占位符自动补充extra__connection_type__前缀。conn-fields自定义字段存储于 Connection.extraconn-fields定义自定义表单字段这些字段的值最终会序列化进Connection.extraJSON。字段的schema属性使用 JSON Schema 定义字段类型与校验规则Airflow 对此的用法可参考官方 Param 文档中 Use Params to Provide a Trigger UI Form 一节当前仓库的相关实现位于airflow-core/src/airflow下的模板渲染模块conn-fields: keyfile_dict: label: Keyfile JSON description: Service account JSON key schema: type: string format: password project: label: Project Id schema: type: string default: my-project字段对象支持的属性见 provider.yaml.schema.jsonlabel字段显示名description帮助文本schemaJSON Schema 定义type支持string、integer、boolean、number、object、array等format: password表示敏感字段源码_add_widgets()会据此设置is_sensitiveTrue实现密码遮罩与脱敏default设置默认值。迁移工具在生成conn-fields时默认把所有字段的schema.type生成为[type, null]以保持旧行为中 extra 字段全部可选的语义。后端_to_api_format()会把字段的label按 JSON Schema 惯例提升为schema.title并读取schema.default作为表单初始值value。external-services连接类型访问的外部服务清单external-services是connection-types条目内可选的一个字符串数组用于列出该连接类型通过网络访问的上游 provider 或模型托管服务例如OpenAI、AWS Bedrock、Ollama。Registry 会把这个列表以表格形式渲染在 provider 的版本页面上方便浏览者一眼看出某个连接类型对接了哪些外部服务。需要特别说明的两点语义该列表是代表性示例而非穷举清单有些 Hook 会根据调用方传入的模型标识解析目标服务例如PydanticAIHook此时它理论上可以访问模型 id 指向的任何服务列表永远不可能完整。所以它应被当作示例服务而不是兼容性矩阵。这一点在 schema 的描述中也有明确注释见 provider.yaml.schema.json 中external-services的description。与顶层integrations键无关顶层integrations描述的是框架级集成如 Kubernetes、Docker用于驱动 provider 文档页面、Logo 与标签的生成external-services仅作用于connection-types条目内部、只列举通过网络访问的服务对文档生成、Logo、标签均无影响。真实用例可参考 providers/common/ai/provider.yaml其中pydanticai系列连接类型声明了对应的external-services如Azure OpenAI、AWS Bedrock、Google Vertex AI、OpenAI等其生成逻辑位于providers/common/ai/src/airflow/providers/common/ai/get_provider_info.pyconnection-types: - hook-class-name: airflow.providers.common.ai.hooks.pydantic_ai.PydanticAIAzureHook hook-name: Pydantic AI (Azure OpenAI) connection-type: pydanticai-azure external-services: - Azure OpenAI迁移工具generate_yaml_format_for_hooks.pyscripts/tools/generate_yaml_format_for_hooks.py 提供从现有 Python Hook 代码中自动抽取元数据的能力。该脚本要求 Airflow 开发环境就绪所有 workspace 模块可用并在运行时把仓库根目录与dev/breeze/src加入sys.path因此请务必在 airflow 虚拟环境中运行。脚本支持两个互斥参数必选其一--provider name抽取某个 provider 下全部连接类型读取其provider.yaml的connection-types列表--hook-class full.name仅抽取指定 Hook 类适合连接类型多、只想处理单个 Hook 的场景。另有一个可选参数--update-yaml把抽取结果直接写回provider.yaml仅与--provider搭配使用。基本用法示例从 provider 抽取打印到 stdout不修改文件python scripts/generate_yaml_format_for_hooks.py --provider docker从特定 Hook 类抽取python scripts/generate_yaml_format_for_hooks.py \ --hook-class airflow.providers.docker.hooks.docker.DockerHook直接更新 provider.yamlpython scripts/generate_yaml_format_for_hooks.py --provider docker --update-yaml脚本工作原理脚本的核心抽取逻辑分为两步extract_from_hook()通过import_string导入 Hook 类读取其conn_type属性若类注意仅检查类自身__dict__不检查继承链定义了get_connection_form_widgets()则调用并交给extract_conn_fields()处理。字段转换规则extract_conn_fields()字段键去掉extra__connection_type__前缀后作为conn-fields的键名依据 wtforms 字段类名映射 JSON Schema 类型BooleanField→[boolean, null]、IntegerField→[integer, null]、PasswordField→[string, null]且format: password、其余 →[string, null]从kwargs[default]提取默认值从any_of()/AnyOf校验器提取enum枚举约束第一个位置参数args[0]作为label否则用字段名做 title 化处理。extract_ui_behaviour()同样只在 Hook 类自身定义get_ui_field_behaviour()时调用把返回字典中的hidden_fields/relabeling/placeholders转换为 kebab-case 的 YAML 键。--update-yaml模式下update_provider_yaml()会把抽取结果合并进原provider.yaml保留sort_keysFalse以维持书写顺序allow_unicodeTrue兼容中文等非 ASCII 文本仅当存在可更新的元数据时才写回文件。后端如何消费迁移结果迁移完成后连接表单的完整数据流如下providers_manager.py的_load_ui_metadata()在不导入 Hook 类的前提下从provider.yaml的connection-types中直接加载hook-name、conn-fields、ui-field-behaviour_add_widgets()把conn-fields转成ConnectionFormWidgetInfo字段名统一为extra__connection_type__field_name前缀格式format: password字段被标记为敏感_add_customized_fields()校验并注册字段行为当真正需要实例化 Hook 时_import_hook()若发现 YAML 已提供 UI 元数据则完全跳过旧方法调用否则回退到旧代码路径并发出弃用警告。这解释了迁移的核心收益API 服务器启动时不再需要为展示静态表单而导入 provider 的 Hook 类与flask_appbuilder、wtforms依赖启动性能得以改善provider 与 UI 表现彻底解耦。迁移实操建议与注意事项先跑通单个 Hook 再整包迁移先用--hook-class验证单个类的抽取结果确认conn-fields的 schema 类型、默认值、枚举都符合预期再对整包执行--provider审查生成的 label当 wtforms 字段没有显式 label 时脚本会用字段名做title()化处理下划线转空格务必人工校对生成的label与description保持可空语义生成的schema.type是数组形式如[boolean, null]这是为了兼容旧的extra 字段均可选行为迁移时不要随意改成单值type以免改变表单校验语义敏感字段必须标注format: password只有这样才能触发后端is_sensitiveTrue的脱敏与遮罩处理善用 schema 校验connection-types及其子键都有严格 JSON Schema 约束如hidden-fields的枚举、external-services的minItems: 1编写或更新后应通过 schema 校验避免字段名拼写错误导致元数据静默失效--update-yaml前先备份脚本会直接覆写provider.yaml建议先在版本控制分支上操作或先以纯打印模式核对输出external-services 保持克制只列举代表性上游服务不要试图穷举尤其是模型名驱动目标地址的 Hook如 PydanticAI 系列并在 PR 描述中说明列表的示例性质。总结把连接表单元数据从 Hook 代码迁移到provider.yaml是 Airflow 走向声明式 provider 元数据的关键一步ui-field-behaviour承载标准字段定制conn-fields以 JSON Schema 定义 extra 自定义字段external-services为 Registry 提供外部服务概览。迁移工具 generate_yaml_format_for_hooks.py 能自动化抽取绝大部分元数据配合 providers_manager.py 的免导入加载机制既消除了flask_appbuilder/wtforms的运行时依赖又提升了 API 服务器启动性能。对 provider 贡献者而言遵循本文的 Schema 结构与迁移步骤即可平滑完成迁移同时借助 provider.yaml.schema.json 保证配置的健壮性。【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考