尧图网页设计 
ZenML API 令牌端点深度解析Generic 与 Workload 两类 API Token 的生成规则、参数与源码实现【免费下载链接】zenmlZenML : One AI Platform from Pipelines to Agents. https://zenml.io.项目地址: https://gitcode.com/GitHub_Trending/ze/zenml本篇围绕 ZenML REST API 的GET /api/v1/api_token端点展开。该端点是 ZenML Server 为已认证用户签发 API 令牌的唯一入口支撑两类令牌通用generic令牌用于短生命周期的自动化脚本访问工作负载workload令牌则被作用域限定到某个调度schedule、流水线运行pipeline run或部署deployment供流水线工作负载回连服务端认证。读完后你将掌握该端点的完整查询参数、每类令牌的生成前提与权限校验规则以及 SDK 客户端侧如何调用、缓存与刷新令牌。端点概览与请求方式官方 OpenAPI 文档页面 api-token.md 对应的实际实现位于服务端路由文件 auth_endpoints.py。端点签名如下router.get( API_TOKEN, # 路由常量值为 /api_token见 src/zenml/constants.py 第 473 行 response_modelstr, ) async_fastapi_endpoint_wrapper def api_token( token_type: APITokenType APITokenType.GENERIC, expires_in: Optional[int] None, schedule_id: Optional[UUID] None, pipeline_run_id: Optional[UUID] None, deployment_id: Optional[UUID] None, auth_context: AuthContext Security(authorize), ) - str:方法与路径GET /api/v1/api_token路由前缀API VERSION_1即/api/v1见同文件第 82-86 行的APIRouter定义。认证要求依赖 FastAPI 的Security(authorize)请求必须携带当前用户有效的访问令牌若令牌无效则抛出AuthorizationException源码第 525-528 行。响应体纯字符串response_modelstr直接返回签发出的 JWT 令牌本体而非 JSON 包装。查询参数一览参数类型必填说明token_typeAPITokenType枚举否默认genericgeneric或workload定义见 enums.pyexpires_inint秒否仅对 generic 令牌有效缺省时采用服务端默认生存期schedule_idUUID否将 workload 令牌作用域限定到指定调度pipeline_run_idUUID否将 workload 令牌作用域限定到指定流水线运行deployment_idUUID否将 workload 令牌作用域限定到指定部署Generic 令牌短生命周期的通用自动化凭证APITokenType枚举只有两个取值——GENERIC generic与WORKLOAD workloadenums.py。请求generic类型时源码逻辑auth_endpoints.py执行如下约束禁止作用域限定若同时传入了schedule_id、pipeline_run_id或deployment_id中的任何一个直接抛出ValueErrorGeneric API tokens cannot be scoped to...因为 generic 令牌本质上是当前用户的全权短令牌不能与资源作用域混用。默认生存期未指定expires_in时使用服务端配置config.generic_api_token_lifetime。该配置的默认值定义在 constants.py 中DEFAULT_ZENML_SERVER_GENERIC_API_TOKEN_LIFETIME 60 * 60 # 1 小时最大生存期上限请求的expires_in不得超过config.generic_api_token_max_lifetime默认值同为 constants.pyDEFAULT_ZENML_SERVER_GENERIC_API_TOKEN_MAX_LIFETIME ( 60 * 60 * 24 * 7 ) # 7 天超限时服务端返回错误信息明确告知本服务器允许的最大过期秒数。保留原始凭证作用域签发时传入api_keyauth_context.api_key与deviceauth_context.device注释明确Keep the original API key and device token scopes——即如果当前访问令牌本身是由 API key 或已认证设备换取的新 generic 令牌会继承这些作用域防止越权升级。不写入 CookieresponseNone令牌只出现在响应体中不会以 HttpOnly Cookie 形式回写该端点专为非 Web 的自动化客户端设计。Workload 令牌绑定到流水线运行、调度或部署Workload 令牌是 ZenML 流水线编排体系中的关键机制流水线任务在容器/Kubernetes 等环境里执行时需要一个作用域受限的凭证回连服务端汇报状态、读取输入输出。端点的 docstringauth_endpoints.py概括其规则如下令牌必须限定到 schedule、pipeline run、deployment 三者之一三者皆缺会抛出ValueError不设时间上限签发时expires_in0Never expire the token其生命周期与所绑定资源的生命周期一致一个 workload 令牌可以再去申请另一个workload 令牌但仅限同一schedule / pipeline run / deployment在pipeline_run_id与deployment_id上做了显式的一致性校验见第 569-585 行。各绑定目标的前置校验源码对三个绑定目标分别执行了存在性与状态校验全部通过后才进入签发1. 绑定到调度schedule_id第 589-604 行调度必须真实存在zen_store().get_schedule(schedule_id, hydrateTrue)不存在的调度不允许签发令牌注释指出这是出于安全考虑调度必须处于active状态停用的调度拒绝签发。2. 绑定到流水线运行pipeline_run_id第 606-642 行运行必须存在且调用者需对该运行模型拥有Action.READ权限verify_permission_for_model运行必须仍在进行中pipeline_run.in_progress已结束的运行为安全原因不再允许签发若当前访问令牌自身已限定到某运行则新令牌的pipeline_run_id必须与之一致唯一例外是嵌套流水线场景新目标运行必须是当前令牌所绑定运行的root_run_id。源码注释解释了原因——当前嵌套编排在同一环境中进行编排器持有的是根运行令牌子运行的令牌总是从根运行令牌派生第 627-642 行。3. 绑定到部署deployment_id第 644-655 行部署必须存在否则拒绝。三者确定project_id后端点最后执行一次 RBAC 校验第 657-662 行verify_permission( resource_typeResourceType.PIPELINE_RUN, actionAction.CREATE, project_idproject_id, )也就是说即使资源状态合法请求者还需要在对应项目中具备创建流水线运行的权限才能获得 workload 令牌。令牌如何被使用客户端 SDK 与流水线执行侧SDK 客户端封装REST 客户端 rest_zen_store.py 提供了get_api_token()方法参数与服务端一一对应token_type默认值为APITokenType.WORKLOAD将各参数组装进 query string 后执行self.get(API_TOKEN, paramsparams)并要求响应体是字符串否则抛出ValueError。其上层get_or_generate_api_token()第 4773 行起负责本地缓存仅当self._api_token is None or self._api_token.expired时才重新请求服务端令牌过期后走重新登录/生成流程并更新Authorization: Bearer token请求头第 5075-5079 行附近避免每次 API 调用都触发一次令牌签发。流水线执行侧注入服务端在派发流水线执行时于 pipeline_execution/utils.py 中为每个运行调用generate_access_token()生成 workload 令牌并注入环境变量ZENML_STORE_API_TOKEN。步骤代码运行在容器内时ZenML 客户端读取该环境变量直接完成认证从而在不向执行环境暴露用户密码或长期凭证的前提下访问服务端。小结端点设计的安全边界从源码结构看GET /api/v1/api_token的设计体现了分层收缩的凭证策略generic 令牌面向人/脚本默认 1 小时、上限 7 天不可附加资源作用域workload 令牌面向机器无时间上限但被资源作用域严格锁定且目标资源必须存在、处于允许状态调用者需具备项目级创建运行权限嵌套派生只允许沿根运行 → 子运行方向发生两类令牌均继承签发时凭证的 API key / device 作用域且不回写 Cookie杜绝了凭证升级与 Web 侧会话混淆两类风险。如果你的使用场景是临时自动化脚本请求token_typegeneric并显式传入expires_in不超过 7 天即可如果是流水线步骤、调度或部署组件需要访问服务端则应使用 SDK 的get_api_token()走 workload 路径让令牌生命周期随绑定资源自动收敛。【免费下载链接】zenmlZenML : One AI Platform from Pipelines to Agents. https://zenml.io.项目地址: https://gitcode.com/GitHub_Trending/ze/zenml创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ZenML API 令牌端点深度解析：Generic 与 Workload 两类 API Token 的生成规则、参数与源码实现
ZenML API 令牌端点深度解析Generic 与 Workload 两类 API Token 的生成规则、参数与源码实现【免费下载链接】zenmlZenML : One AI Platform from Pipelines to Agents. https://zenml.io.项目地址: https://gitcode.com/GitHub_Trending/ze/zenml本篇围绕 ZenML REST API 的GET /api/v1/api_token端点展开。该端点是 ZenML Server 为已认证用户签发 API 令牌的唯一入口支撑两类令牌通用generic令牌用于短生命周期的自动化脚本访问工作负载workload令牌则被作用域限定到某个调度schedule、流水线运行pipeline run或部署deployment供流水线工作负载回连服务端认证。读完后你将掌握该端点的完整查询参数、每类令牌的生成前提与权限校验规则以及 SDK 客户端侧如何调用、缓存与刷新令牌。端点概览与请求方式官方 OpenAPI 文档页面 api-token.md 对应的实际实现位于服务端路由文件 auth_endpoints.py。端点签名如下router.get( API_TOKEN, # 路由常量值为 /api_token见 src/zenml/constants.py 第 473 行 response_modelstr, ) async_fastapi_endpoint_wrapper def api_token( token_type: APITokenType APITokenType.GENERIC, expires_in: Optional[int] None, schedule_id: Optional[UUID] None, pipeline_run_id: Optional[UUID] None, deployment_id: Optional[UUID] None, auth_context: AuthContext Security(authorize), ) - str:方法与路径GET /api/v1/api_token路由前缀API VERSION_1即/api/v1见同文件第 82-86 行的APIRouter定义。认证要求依赖 FastAPI 的Security(authorize)请求必须携带当前用户有效的访问令牌若令牌无效则抛出AuthorizationException源码第 525-528 行。响应体纯字符串response_modelstr直接返回签发出的 JWT 令牌本体而非 JSON 包装。查询参数一览参数类型必填说明token_typeAPITokenType枚举否默认genericgeneric或workload定义见 enums.pyexpires_inint秒否仅对 generic 令牌有效缺省时采用服务端默认生存期schedule_idUUID否将 workload 令牌作用域限定到指定调度pipeline_run_idUUID否将 workload 令牌作用域限定到指定流水线运行deployment_idUUID否将 workload 令牌作用域限定到指定部署Generic 令牌短生命周期的通用自动化凭证APITokenType枚举只有两个取值——GENERIC generic与WORKLOAD workloadenums.py。请求generic类型时源码逻辑auth_endpoints.py执行如下约束禁止作用域限定若同时传入了schedule_id、pipeline_run_id或deployment_id中的任何一个直接抛出ValueErrorGeneric API tokens cannot be scoped to...因为 generic 令牌本质上是当前用户的全权短令牌不能与资源作用域混用。默认生存期未指定expires_in时使用服务端配置config.generic_api_token_lifetime。该配置的默认值定义在 constants.py 中DEFAULT_ZENML_SERVER_GENERIC_API_TOKEN_LIFETIME 60 * 60 # 1 小时最大生存期上限请求的expires_in不得超过config.generic_api_token_max_lifetime默认值同为 constants.pyDEFAULT_ZENML_SERVER_GENERIC_API_TOKEN_MAX_LIFETIME ( 60 * 60 * 24 * 7 ) # 7 天超限时服务端返回错误信息明确告知本服务器允许的最大过期秒数。保留原始凭证作用域签发时传入api_keyauth_context.api_key与deviceauth_context.device注释明确Keep the original API key and device token scopes——即如果当前访问令牌本身是由 API key 或已认证设备换取的新 generic 令牌会继承这些作用域防止越权升级。不写入 CookieresponseNone令牌只出现在响应体中不会以 HttpOnly Cookie 形式回写该端点专为非 Web 的自动化客户端设计。Workload 令牌绑定到流水线运行、调度或部署Workload 令牌是 ZenML 流水线编排体系中的关键机制流水线任务在容器/Kubernetes 等环境里执行时需要一个作用域受限的凭证回连服务端汇报状态、读取输入输出。端点的 docstringauth_endpoints.py概括其规则如下令牌必须限定到 schedule、pipeline run、deployment 三者之一三者皆缺会抛出ValueError不设时间上限签发时expires_in0Never expire the token其生命周期与所绑定资源的生命周期一致一个 workload 令牌可以再去申请另一个workload 令牌但仅限同一schedule / pipeline run / deployment在pipeline_run_id与deployment_id上做了显式的一致性校验见第 569-585 行。各绑定目标的前置校验源码对三个绑定目标分别执行了存在性与状态校验全部通过后才进入签发1. 绑定到调度schedule_id第 589-604 行调度必须真实存在zen_store().get_schedule(schedule_id, hydrateTrue)不存在的调度不允许签发令牌注释指出这是出于安全考虑调度必须处于active状态停用的调度拒绝签发。2. 绑定到流水线运行pipeline_run_id第 606-642 行运行必须存在且调用者需对该运行模型拥有Action.READ权限verify_permission_for_model运行必须仍在进行中pipeline_run.in_progress已结束的运行为安全原因不再允许签发若当前访问令牌自身已限定到某运行则新令牌的pipeline_run_id必须与之一致唯一例外是嵌套流水线场景新目标运行必须是当前令牌所绑定运行的root_run_id。源码注释解释了原因——当前嵌套编排在同一环境中进行编排器持有的是根运行令牌子运行的令牌总是从根运行令牌派生第 627-642 行。3. 绑定到部署deployment_id第 644-655 行部署必须存在否则拒绝。三者确定project_id后端点最后执行一次 RBAC 校验第 657-662 行verify_permission( resource_typeResourceType.PIPELINE_RUN, actionAction.CREATE, project_idproject_id, )也就是说即使资源状态合法请求者还需要在对应项目中具备创建流水线运行的权限才能获得 workload 令牌。令牌如何被使用客户端 SDK 与流水线执行侧SDK 客户端封装REST 客户端 rest_zen_store.py 提供了get_api_token()方法参数与服务端一一对应token_type默认值为APITokenType.WORKLOAD将各参数组装进 query string 后执行self.get(API_TOKEN, paramsparams)并要求响应体是字符串否则抛出ValueError。其上层get_or_generate_api_token()第 4773 行起负责本地缓存仅当self._api_token is None or self._api_token.expired时才重新请求服务端令牌过期后走重新登录/生成流程并更新Authorization: Bearer token请求头第 5075-5079 行附近避免每次 API 调用都触发一次令牌签发。流水线执行侧注入服务端在派发流水线执行时于 pipeline_execution/utils.py 中为每个运行调用generate_access_token()生成 workload 令牌并注入环境变量ZENML_STORE_API_TOKEN。步骤代码运行在容器内时ZenML 客户端读取该环境变量直接完成认证从而在不向执行环境暴露用户密码或长期凭证的前提下访问服务端。小结端点设计的安全边界从源码结构看GET /api/v1/api_token的设计体现了分层收缩的凭证策略generic 令牌面向人/脚本默认 1 小时、上限 7 天不可附加资源作用域workload 令牌面向机器无时间上限但被资源作用域严格锁定且目标资源必须存在、处于允许状态调用者需具备项目级创建运行权限嵌套派生只允许沿根运行 → 子运行方向发生两类令牌均继承签发时凭证的 API key / device 作用域且不回写 Cookie杜绝了凭证升级与 Web 侧会话混淆两类风险。如果你的使用场景是临时自动化脚本请求token_typegeneric并显式传入expires_in不超过 7 天即可如果是流水线步骤、调度或部署组件需要访问服务端则应使用 SDK 的get_api_token()走 workload 路径让令牌生命周期随绑定资源自动收敛。【免费下载链接】zenmlZenML : One AI Platform from Pipelines to Agents. https://zenml.io.项目地址: https://gitcode.com/GitHub_Trending/ze/zenml创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考