Apache Airflow 公共 REST API 参考指南基于 OpenAPI 规范的稳定接口解析与实战【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow本文围绕 Airflow 公共 REST API 参考页 展开该页面通过 Sphinxswagger-plugin指令将 Airflow 核心 API 的 OpenAPI 3.1 规范v2-rest-api-generated.yaml渲染为交互式接口文档是整个 Apache Airflow 对外编程接口的权威入口。读完本文你将掌握/api/v2前缀下所有稳定端点DAG、DAG Run、Task Instance、Connection、Variable、Pool、Backfill、Asset 等的定位方式、JWT 认证流程、分页与过滤参数语义以及这些接口与 FastAPI 实现源码之间的对应关系可直接据此编写集成脚本或客户端。一、文档是什么一份由 OpenAPI 规范驱动的接口参考stable-rest-api-ref.rst本身是一个极简的文档装配页其核心是一条 Sphinxswagger-plugin指令Airflow public REST API reference .. swagger-plugin:: ../src/airflow/api_fastapi/core_api/openapi/v2-rest-api-generated.yaml :id: core-rest-api-ref :page-title: Airflow public REST API :swagger-options: { tryItOutEnabled: false, supportedSubmitMethods: [] }它声明了三点关键信息内容来源../src/airflow/api_fastapi/core_api/openapi/v2-rest-api-generated.yaml即仓库根下的 v2-rest-api-generated.yaml全文超过 1.7 万行采用 OpenAPI 3.1.0 规范info.version: 2。渲染方式构建文档时由swagger-plugin插件把 YAML 渲染成带可折叠 Schema 的交互式 API 页面tryItOutEnabled被显式关闭supportedSubmitMethods为空说明该页定位是精确查阅而非在线调试。权威性它是 Airflow 公共接口的官方参考所有以/api/v2开头的端点都以此为唯一事实来源。也就是说阅读该参考页 阅读 OpenAPI 规范本身。下面基于这份规范文件展开系统讲解。二、稳定性承诺与接口边界/api/v2vs/ui规范文件在info.description中给出了明确的接口边界这是使用 Airflow API 的第一原则All endpoints located under/api/v2can be used safely, are stable and backward compatible. Endpoints located under/uiare dedicated to the UI and are subject to breaking change depending on the need of the frontend. Users should not rely on those but use the public ones instead.即/api/v2/**公共、稳定、向后兼容是第三方集成的唯一可靠接口面/ui/**仅供 Airflow 自身前端使用随时可能随 UI 需求变更而破坏性调整业务集成方不得依赖。在实现层面这一边界也体现在路由注册上app.py 的init_views分别挂载了ui_router与public_router其中公共路由全部位于 routes/public/ 目录下dags.py、dag_run.py、task_instances.py、connections.py、variables.py、pools.py、backfills.py、assets.py等 30 余个模块UI 专属路由则在 routes/ui/。前端合并 API 时也会显式区分二者参见 airflow-core/src/airflow/ui/openapi-merge.json。三、认证与安全基于 JWT 的 Bearer Token从规范的securitySchemes可以确认公共 API 支持两种认证方式securitySchemes: OAuth2PasswordBearer: type: oauth2 flows: password: tokenUrl: /auth/token scopes: {} HTTPBearer: type: http scheme: bearerOAuth2PasswordBearer客户端需先向POST /auth/token发起密码模式请求换取JWTJSON Web Token随后在每次请求的Authorization头携带Bearer token服务端用该 Token 校验身份与权限范围。HTTPBearer同样以Authorization: Bearer ...传递适用于已持有 Token 的调用方。/api/v2/auth/login携带可选next查询参数用于登录后跳转与/api/v2/auth/logout两个端点负责浏览器会话侧的登录/登出流程响应可能为 200 或 307 重定向。关于 Token 的签发细节、过期策略与权限模型仓库在 security/api.rst 与 security/jwt_token_authentication.rst 中有完整专题文档建议在对接前先阅读这两篇。四、通用约定分页与模式过滤参数规范文件在info.description中定义了所有列表端点通用的两大约定直接影响查询参数的使用。4.1 分页列表端点普遍支持limit与offset两个查询参数。以/api/v2/assets为例limit为整数、最小值 0、默认值50offset同样为整数、最小值 0、默认值0。即默认每页最多返回 50 条、从第 0 条开始这是编写批量拉取脚本时必须遵守的约束。4.2*_pattern与*_prefix_pattern过滤语义这是 Airflow 公共 API 最具特色的通用能力几乎所有列表端点都提供两类模式匹配参数参数形态匹配语义大小写索引友好性适用场景*_pattern子串匹配SQLILIKE %term%%匹配任意序列_匹配任意单字符不敏感无法走 B 树索引大表上慢灵活模糊查询*_prefix_pattern匹配值开头前缀%、_按字面量处理尾部非字母数字字符被剥离以保证区域排序下的范围扫描仍可用索引敏感索引友好建议大规模场景优先精确前缀/路径式过滤两者共同的语法细节|表示OR例如dag1|dag2匹配任一~匹配全部不支持正则表达式需要正则能力的端点会另行提供独立参数。举例test_能匹配所有以test开头的值尾部下划线被剥离s3://能匹配以s3开头的值。这意味着对连接 ID、DAG ID 这类含分隔符的字段前缀匹配可以做到既快又符合直觉。五、端点全景按资源分组的接口清单规范文件paths段包含 100 个路径按tags可分为以下资源组路径均位于/api/v2之下资源组代表端点说明Assets/api/v2/assets、/assets/aliases、/assets/events、/assets/{asset_id}/materialize、/assets/{asset_id}/queuedEvents、/assets/{asset_id}/state-storeAirflow 2.9 的资产Asset模型、事件与排队事件、状态存储Backfills/api/v2/backfills、/backfills/{backfill_id}、/backfills/{backfill_id}/pause、/unpause、/cancel、/backfills/dry_run回填任务的创建、查询、暂停/恢复/取消与干跑Connections/api/v2/connections、/connections/{connection_id}、/connections/test、/connections/enqueue-test、/connections/defaults连接管理、同步/异步连接测试、默认连接DAGs/api/v2/dags、/dags/{dag_id}、/dags/{dag_id}/details、/favorite、/unfavorite、/dags/{dag_id}/clearDagRuns、/clearPartitionsDAG 生命周期、详情、收藏、批量清理DAG Runs/api/v2/dags/{dag_id}/dagRuns、/dagRuns/{dag_run_id}、/dagRuns/{dag_run_id}/clear、/wait、/upstreamAssetEvents、/dags/{dag_id}/dagRuns/listDAG Run 的创建、查询、清理、等待与上游资产事件Task Instances/api/v2/dags/{dag_id}/dagRuns/{dag_run_id}/taskInstances、/{task_id}、/listMapped、/tries、/dependencies、/logs/{try_number}、/externalLogUrl/{try_number}、/dry_run任务实例全生命周期状态、重试、依赖、日志、外部日志链接、映射任务Task Groups/api/v2/dags/{dag_id}/dagRuns/{dag_run_id}/taskGroupInstances/{group_id}、/dry_runTask Group 实例查询与干跑XCom / 状态存储/taskInstances/{task_id}/xcomEntries/{xcom_key}、/taskInstances/{task_id}/state-store/{key}XCom 读写、任务级状态存储state-storeConfig/api/v2/config、/config/section/{section}/option/{option}运行时配置查询按节、按选项元数据类/api/v2/dagSources/{dag_id}、/dagStats、/dagWarnings、/dagTags、/dagVersions、/importErrors、/eventLogs、/jobs、/plugins、/providersDAG 源码、统计、告警、标签、版本、导入错误、审计日志、任务、插件、Provider 信息运维类/api/v2/monitor/health、/version健康检查Get Health、版本信息Get Version工具类/api/v2/parseDagFile/{file_token}、/dags/{dag_id}/tasks、/tasks/{task_id}解析 DAG 文件、任务定义查询、额外链接taskInstances/.../links其中monitor/health与version两个端点不依赖业务资源常用于探活与版本确认。六、重点资源详解Schema 与关键参数规范components.schemas定义了全部请求/响应模型命名规律是XxxResponse单条、XxxCollectionResponse集合、XxxBody写操作请求体。以下选取高频资源说明。6.1 DAG 与 DAG RunDAGResponse/DAGCollectionResponseDAG 列表与详情列表端点支持dag_id_pattern、dag_id_prefix_pattern、owners、tags、only_active、paused等过滤参数具体以 YAML 中各参数描述为准。DAGRunResponse/DAGRunCollectionResponse/DAGRunPatchBody/DAGRunClearBodyDAG Run 的创建POST /dags/{dag_id}/dagRuns、状态更新、清理clear与批量操作。批量能力BulkBody_BulkDAGRunBody_、BulkBody_BulkTaskInstanceBody_、BulkBody_ConnectionBody_、BulkBody_PoolBody_、BulkBody_VariableBody_等模型表明DAG Run、任务实例、连接、池、变量均支持批量创建/更新/删除配合BulkCreateAction_*、BulkUpdateAction_*、BulkDeleteAction_*动作描述返回BulkResponse。需要批量编排时优先考虑这些端点以减少往返次数。6.2 Task Instance 与日志任务实例是运维中最常用的资源GET /dags/{dag_id}/dagRuns/{dag_run_id}/taskInstances按 DAG Run 拉取任务实例列表GET .../taskInstances/{task_id}单实例详情映射任务Dynamic Task Mapping可追加{map_index}定位具体分片GET .../taskInstances/{task_id}/listMapped列出映射任务的所有分片GET .../taskInstances/{task_id}/tries/{task_try_number}指定重试次数的详情GET .../taskInstances/{task_id}/logs/{try_number}拉取指定重试的日志/externalLogUrl/{try_number}返回外部日志系统链接POST .../taskInstances/{task_id}/dry_run与.../{map_index}/dry_run任务渲染/干跑校验。6.3 Connection 与连接测试GET/POST /connections、GET/PUT/DELETE /connections/{connection_id}连接的增删改查POST /connections/test同步测试连接POST /connections/enqueue-test异步测试返回AsyncConnectionTestResponse/ConnectionTestQueuedResponse适用于耗时连接测试GET /connections/defaults读取默认连接连接认证信息密码等在响应中会被脱敏写操作使用ConnectionBody模型承载。6.4 Backfill 回填BackfillPostBody/BackfillResponse定义了回填请求与结果/backfills/dry_run可在正式创建前预览将被执行的 DAG Runpause/unpause/cancel提供运行中回填的控制能力。回填是弥补历史数据窗口的推荐手段。6.5 Asset 资产数据依赖/api/v2/assets及其子路径覆盖资产别名aliases、资产事件events、排队事件queuedEvents、物化materialize与状态存储state-store。AssetEventResponse、AssetExpressionRef等模型体现了 Airflow 3 以资产为中心的依赖表达方式/dags/{dag_id}/dagRuns/{dag_run_id}/upstreamAssetEvents则可查询一次 DAG Run 的上游资产事件用于数据链路审计。七、从规范到实现源码级对应关系公共 API 的请求链路是OpenAPI 规范YAML ⇄ FastAPI 路由实现 ⇄ 业务 Service。可以在仓库中一一对应文档 → 规范stable-rest-api-ref.rst 直接引用 v2-rest-api-generated.yaml规范 → 路由每个operationId对应 routes/public/ 下某模块中的 FastAPI 路由函数例如get_dags、get_dag_runs、get_task_instances分别位于dags.py、dag_run.py、task_instances.py路由 → 应用app.py 中的init_views完成public_router/ui_router的挂载并装配/health旧版探活Airflow 2 风格路径返回 404 以提示迁移等辅助端点前端集成airflow-core/src/airflow/ui/openapi-merge.json 将核心 API 规范与 UI 规范合并供前端代码生成使用。因此规范文件就是权威的接口字典任何端点的参数默认值、必填字段、响应模型都应优先以该 YAML 为准而非记忆中的旧版 API 行为。八、实战示例从认证到调用以下示例基于规范确认的端点与认证方式适用于对稳定接口的常规调用。第一步获取 JWT Tokencurl -X POST http://localhost:8080/auth/token \ -H Content-Type: application/x-www-form-urlencoded \ -d usernameadminpasswordyour_password成功后拿到access_token后续请求携带curl http://localhost:8080/api/v2/dags?limit50offset0dag_id_prefix_patternexample \ -H Authorization: Bearer access_token第二步常用运维组合# 查询某 DAG 最近一次运行的实例状态 curl http://localhost:8080/api/v2/dags/example_dag/dagRuns?limit10order_by-start_date \ -H Authorization: Bearer access_token # 获取某 DAG Run 下所有任务实例 curl http://localhost:8080/api/v2/dags/example_dag/dagRuns/run_2026_01_01/taskInstances \ -H Authorization: Bearer access_token # 拉取任务某次重试的日志 curl http://localhost:8080/api/v2/dags/example_dag/dagRuns/run_2026_01_01/taskInstances/print_date/logs/1 \ -H Authorization: Bearer access_token # 健康与版本检查探活 curl http://localhost:8080/api/v2/monitor/health curl http://localhost:8080/api/v2/version第三步构造写操作请求体。写端点如POST /api/v2/dags/{dag_id}/dagRuns的请求体结构以DAGRunPostBody类 Schema 为准创建回填则以BackfillPostBody为准字段是否必填、默认值均在 v2-rest-api-generated.yaml 的required与default中显式声明对接时逐字段核对即可无需猜测。九、注意事项与最佳实践只依赖/api/v2一切面向 UI 的/ui端点都可能随时变更集成方应将其排除在契约之外。大列表用*_prefix_pattern模糊子串过滤*_pattern无法利用索引在海量 DAG、连接、事件数据上应改用前缀过滤或配合分页游标式拉取offset递增。批量操作优先需要成批创建/更新 DAG Run、任务实例、连接、变量、池时使用Bulk*端点减少请求数。Token 安全JWT 通过Authorization: Bearer传递应使用 HTTPS 保护传输链路Token 过期与权限模型详见 security/jwt_token_authentication.rst 与 security/api.rst。以 OpenAPI 文件为准接口行为若与旧文档或记忆冲突一律以当前仓库的 v2-rest-api-generated.yaml 为准该文件由代码生成与 FastAPI 路由实现保持同步。十、扩展阅读security/api.rstAPI 权限体系与认证总览security/jwt_token_authentication.rstJWT 签发与验证细节16_adding_api_endpoints.rst如何为 Airflow 新增公共 API 端点理解端点实现与规范生成的内部机制api_fastapi/core_api/app.py核心 API 应用的装配入口api_fastapi/core_api/routes/public/全部公共端点的路由实现。【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/10 22:03:01 · 阅读 1.2k Apache Airflow 公共 REST API 参考指南：基于 OpenAPI 规范的稳定接口解析与实战
Apache Airflow 公共 REST API 参考指南基于 OpenAPI 规范的稳定接口解析与实战【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow本文围绕 Airflow 公共 REST API 参考页 展开该页面通过 Sphinxswagger-plugin指令将 Airflow 核心 API 的 OpenAPI 3.1 规范v2-rest-api-generated.yaml渲染为交互式接口文档是整个 Apache Airflow 对外编程接口的权威入口。读完本文你将掌握/api/v2前缀下所有稳定端点DAG、DAG Run、Task Instance、Connection、Variable、Pool、Backfill、Asset 等的定位方式、JWT 认证流程、分页与过滤参数语义以及这些接口与 FastAPI 实现源码之间的对应关系可直接据此编写集成脚本或客户端。一、文档是什么一份由 OpenAPI 规范驱动的接口参考stable-rest-api-ref.rst本身是一个极简的文档装配页其核心是一条 Sphinxswagger-plugin指令Airflow public REST API reference .. swagger-plugin:: ../src/airflow/api_fastapi/core_api/openapi/v2-rest-api-generated.yaml :id: core-rest-api-ref :page-title: Airflow public REST API :swagger-options: { tryItOutEnabled: false, supportedSubmitMethods: [] }它声明了三点关键信息内容来源../src/airflow/api_fastapi/core_api/openapi/v2-rest-api-generated.yaml即仓库根下的 v2-rest-api-generated.yaml全文超过 1.7 万行采用 OpenAPI 3.1.0 规范info.version: 2。渲染方式构建文档时由swagger-plugin插件把 YAML 渲染成带可折叠 Schema 的交互式 API 页面tryItOutEnabled被显式关闭supportedSubmitMethods为空说明该页定位是精确查阅而非在线调试。权威性它是 Airflow 公共接口的官方参考所有以/api/v2开头的端点都以此为唯一事实来源。也就是说阅读该参考页 阅读 OpenAPI 规范本身。下面基于这份规范文件展开系统讲解。二、稳定性承诺与接口边界/api/v2vs/ui规范文件在info.description中给出了明确的接口边界这是使用 Airflow API 的第一原则All endpoints located under/api/v2can be used safely, are stable and backward compatible. Endpoints located under/uiare dedicated to the UI and are subject to breaking change depending on the need of the frontend. Users should not rely on those but use the public ones instead.即/api/v2/**公共、稳定、向后兼容是第三方集成的唯一可靠接口面/ui/**仅供 Airflow 自身前端使用随时可能随 UI 需求变更而破坏性调整业务集成方不得依赖。在实现层面这一边界也体现在路由注册上app.py 的init_views分别挂载了ui_router与public_router其中公共路由全部位于 routes/public/ 目录下dags.py、dag_run.py、task_instances.py、connections.py、variables.py、pools.py、backfills.py、assets.py等 30 余个模块UI 专属路由则在 routes/ui/。前端合并 API 时也会显式区分二者参见 airflow-core/src/airflow/ui/openapi-merge.json。三、认证与安全基于 JWT 的 Bearer Token从规范的securitySchemes可以确认公共 API 支持两种认证方式securitySchemes: OAuth2PasswordBearer: type: oauth2 flows: password: tokenUrl: /auth/token scopes: {} HTTPBearer: type: http scheme: bearerOAuth2PasswordBearer客户端需先向POST /auth/token发起密码模式请求换取JWTJSON Web Token随后在每次请求的Authorization头携带Bearer token服务端用该 Token 校验身份与权限范围。HTTPBearer同样以Authorization: Bearer ...传递适用于已持有 Token 的调用方。/api/v2/auth/login携带可选next查询参数用于登录后跳转与/api/v2/auth/logout两个端点负责浏览器会话侧的登录/登出流程响应可能为 200 或 307 重定向。关于 Token 的签发细节、过期策略与权限模型仓库在 security/api.rst 与 security/jwt_token_authentication.rst 中有完整专题文档建议在对接前先阅读这两篇。四、通用约定分页与模式过滤参数规范文件在info.description中定义了所有列表端点通用的两大约定直接影响查询参数的使用。4.1 分页列表端点普遍支持limit与offset两个查询参数。以/api/v2/assets为例limit为整数、最小值 0、默认值50offset同样为整数、最小值 0、默认值0。即默认每页最多返回 50 条、从第 0 条开始这是编写批量拉取脚本时必须遵守的约束。4.2*_pattern与*_prefix_pattern过滤语义这是 Airflow 公共 API 最具特色的通用能力几乎所有列表端点都提供两类模式匹配参数参数形态匹配语义大小写索引友好性适用场景*_pattern子串匹配SQLILIKE %term%%匹配任意序列_匹配任意单字符不敏感无法走 B 树索引大表上慢灵活模糊查询*_prefix_pattern匹配值开头前缀%、_按字面量处理尾部非字母数字字符被剥离以保证区域排序下的范围扫描仍可用索引敏感索引友好建议大规模场景优先精确前缀/路径式过滤两者共同的语法细节|表示OR例如dag1|dag2匹配任一~匹配全部不支持正则表达式需要正则能力的端点会另行提供独立参数。举例test_能匹配所有以test开头的值尾部下划线被剥离s3://能匹配以s3开头的值。这意味着对连接 ID、DAG ID 这类含分隔符的字段前缀匹配可以做到既快又符合直觉。五、端点全景按资源分组的接口清单规范文件paths段包含 100 个路径按tags可分为以下资源组路径均位于/api/v2之下资源组代表端点说明Assets/api/v2/assets、/assets/aliases、/assets/events、/assets/{asset_id}/materialize、/assets/{asset_id}/queuedEvents、/assets/{asset_id}/state-storeAirflow 2.9 的资产Asset模型、事件与排队事件、状态存储Backfills/api/v2/backfills、/backfills/{backfill_id}、/backfills/{backfill_id}/pause、/unpause、/cancel、/backfills/dry_run回填任务的创建、查询、暂停/恢复/取消与干跑Connections/api/v2/connections、/connections/{connection_id}、/connections/test、/connections/enqueue-test、/connections/defaults连接管理、同步/异步连接测试、默认连接DAGs/api/v2/dags、/dags/{dag_id}、/dags/{dag_id}/details、/favorite、/unfavorite、/dags/{dag_id}/clearDagRuns、/clearPartitionsDAG 生命周期、详情、收藏、批量清理DAG Runs/api/v2/dags/{dag_id}/dagRuns、/dagRuns/{dag_run_id}、/dagRuns/{dag_run_id}/clear、/wait、/upstreamAssetEvents、/dags/{dag_id}/dagRuns/listDAG Run 的创建、查询、清理、等待与上游资产事件Task Instances/api/v2/dags/{dag_id}/dagRuns/{dag_run_id}/taskInstances、/{task_id}、/listMapped、/tries、/dependencies、/logs/{try_number}、/externalLogUrl/{try_number}、/dry_run任务实例全生命周期状态、重试、依赖、日志、外部日志链接、映射任务Task Groups/api/v2/dags/{dag_id}/dagRuns/{dag_run_id}/taskGroupInstances/{group_id}、/dry_runTask Group 实例查询与干跑XCom / 状态存储/taskInstances/{task_id}/xcomEntries/{xcom_key}、/taskInstances/{task_id}/state-store/{key}XCom 读写、任务级状态存储state-storeConfig/api/v2/config、/config/section/{section}/option/{option}运行时配置查询按节、按选项元数据类/api/v2/dagSources/{dag_id}、/dagStats、/dagWarnings、/dagTags、/dagVersions、/importErrors、/eventLogs、/jobs、/plugins、/providersDAG 源码、统计、告警、标签、版本、导入错误、审计日志、任务、插件、Provider 信息运维类/api/v2/monitor/health、/version健康检查Get Health、版本信息Get Version工具类/api/v2/parseDagFile/{file_token}、/dags/{dag_id}/tasks、/tasks/{task_id}解析 DAG 文件、任务定义查询、额外链接taskInstances/.../links其中monitor/health与version两个端点不依赖业务资源常用于探活与版本确认。六、重点资源详解Schema 与关键参数规范components.schemas定义了全部请求/响应模型命名规律是XxxResponse单条、XxxCollectionResponse集合、XxxBody写操作请求体。以下选取高频资源说明。6.1 DAG 与 DAG RunDAGResponse/DAGCollectionResponseDAG 列表与详情列表端点支持dag_id_pattern、dag_id_prefix_pattern、owners、tags、only_active、paused等过滤参数具体以 YAML 中各参数描述为准。DAGRunResponse/DAGRunCollectionResponse/DAGRunPatchBody/DAGRunClearBodyDAG Run 的创建POST /dags/{dag_id}/dagRuns、状态更新、清理clear与批量操作。批量能力BulkBody_BulkDAGRunBody_、BulkBody_BulkTaskInstanceBody_、BulkBody_ConnectionBody_、BulkBody_PoolBody_、BulkBody_VariableBody_等模型表明DAG Run、任务实例、连接、池、变量均支持批量创建/更新/删除配合BulkCreateAction_*、BulkUpdateAction_*、BulkDeleteAction_*动作描述返回BulkResponse。需要批量编排时优先考虑这些端点以减少往返次数。6.2 Task Instance 与日志任务实例是运维中最常用的资源GET /dags/{dag_id}/dagRuns/{dag_run_id}/taskInstances按 DAG Run 拉取任务实例列表GET .../taskInstances/{task_id}单实例详情映射任务Dynamic Task Mapping可追加{map_index}定位具体分片GET .../taskInstances/{task_id}/listMapped列出映射任务的所有分片GET .../taskInstances/{task_id}/tries/{task_try_number}指定重试次数的详情GET .../taskInstances/{task_id}/logs/{try_number}拉取指定重试的日志/externalLogUrl/{try_number}返回外部日志系统链接POST .../taskInstances/{task_id}/dry_run与.../{map_index}/dry_run任务渲染/干跑校验。6.3 Connection 与连接测试GET/POST /connections、GET/PUT/DELETE /connections/{connection_id}连接的增删改查POST /connections/test同步测试连接POST /connections/enqueue-test异步测试返回AsyncConnectionTestResponse/ConnectionTestQueuedResponse适用于耗时连接测试GET /connections/defaults读取默认连接连接认证信息密码等在响应中会被脱敏写操作使用ConnectionBody模型承载。6.4 Backfill 回填BackfillPostBody/BackfillResponse定义了回填请求与结果/backfills/dry_run可在正式创建前预览将被执行的 DAG Runpause/unpause/cancel提供运行中回填的控制能力。回填是弥补历史数据窗口的推荐手段。6.5 Asset 资产数据依赖/api/v2/assets及其子路径覆盖资产别名aliases、资产事件events、排队事件queuedEvents、物化materialize与状态存储state-store。AssetEventResponse、AssetExpressionRef等模型体现了 Airflow 3 以资产为中心的依赖表达方式/dags/{dag_id}/dagRuns/{dag_run_id}/upstreamAssetEvents则可查询一次 DAG Run 的上游资产事件用于数据链路审计。七、从规范到实现源码级对应关系公共 API 的请求链路是OpenAPI 规范YAML ⇄ FastAPI 路由实现 ⇄ 业务 Service。可以在仓库中一一对应文档 → 规范stable-rest-api-ref.rst 直接引用 v2-rest-api-generated.yaml规范 → 路由每个operationId对应 routes/public/ 下某模块中的 FastAPI 路由函数例如get_dags、get_dag_runs、get_task_instances分别位于dags.py、dag_run.py、task_instances.py路由 → 应用app.py 中的init_views完成public_router/ui_router的挂载并装配/health旧版探活Airflow 2 风格路径返回 404 以提示迁移等辅助端点前端集成airflow-core/src/airflow/ui/openapi-merge.json 将核心 API 规范与 UI 规范合并供前端代码生成使用。因此规范文件就是权威的接口字典任何端点的参数默认值、必填字段、响应模型都应优先以该 YAML 为准而非记忆中的旧版 API 行为。八、实战示例从认证到调用以下示例基于规范确认的端点与认证方式适用于对稳定接口的常规调用。第一步获取 JWT Tokencurl -X POST http://localhost:8080/auth/token \ -H Content-Type: application/x-www-form-urlencoded \ -d usernameadminpasswordyour_password成功后拿到access_token后续请求携带curl http://localhost:8080/api/v2/dags?limit50offset0dag_id_prefix_patternexample \ -H Authorization: Bearer access_token第二步常用运维组合# 查询某 DAG 最近一次运行的实例状态 curl http://localhost:8080/api/v2/dags/example_dag/dagRuns?limit10order_by-start_date \ -H Authorization: Bearer access_token # 获取某 DAG Run 下所有任务实例 curl http://localhost:8080/api/v2/dags/example_dag/dagRuns/run_2026_01_01/taskInstances \ -H Authorization: Bearer access_token # 拉取任务某次重试的日志 curl http://localhost:8080/api/v2/dags/example_dag/dagRuns/run_2026_01_01/taskInstances/print_date/logs/1 \ -H Authorization: Bearer access_token # 健康与版本检查探活 curl http://localhost:8080/api/v2/monitor/health curl http://localhost:8080/api/v2/version第三步构造写操作请求体。写端点如POST /api/v2/dags/{dag_id}/dagRuns的请求体结构以DAGRunPostBody类 Schema 为准创建回填则以BackfillPostBody为准字段是否必填、默认值均在 v2-rest-api-generated.yaml 的required与default中显式声明对接时逐字段核对即可无需猜测。九、注意事项与最佳实践只依赖/api/v2一切面向 UI 的/ui端点都可能随时变更集成方应将其排除在契约之外。大列表用*_prefix_pattern模糊子串过滤*_pattern无法利用索引在海量 DAG、连接、事件数据上应改用前缀过滤或配合分页游标式拉取offset递增。批量操作优先需要成批创建/更新 DAG Run、任务实例、连接、变量、池时使用Bulk*端点减少请求数。Token 安全JWT 通过Authorization: Bearer传递应使用 HTTPS 保护传输链路Token 过期与权限模型详见 security/jwt_token_authentication.rst 与 security/api.rst。以 OpenAPI 文件为准接口行为若与旧文档或记忆冲突一律以当前仓库的 v2-rest-api-generated.yaml 为准该文件由代码生成与 FastAPI 路由实现保持同步。十、扩展阅读security/api.rstAPI 权限体系与认证总览security/jwt_token_authentication.rstJWT 签发与验证细节16_adding_api_endpoints.rst如何为 Airflow 新增公共 API 端点理解端点实现与规范生成的内部机制api_fastapi/core_api/app.py核心 API 应用的装配入口api_fastapi/core_api/routes/public/全部公共端点的路由实现。【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考