用途:从外部编排工具触发 Hex 项目运行,并传入输入参数、轮询运行状态、处理错误,是把 Hex 嵌入数据管道的主要集成模式。
主要能力:一是参数化触发项目运行,向 /project/{projectId}/run 发送 POST 请求,可传 inputParams、updateCacheResult、killRunningExecution;二是同步等待运行结果,轮询运行状态直到 COMPLETED、ERRORED 或 KILLED;三是按顺序执行多个 Hex 项目组成数据管道;四是取消长时间运行的项目(对运行接口发 DELETE)。
使用方式:需配置 HEZ_API_TOKEN 环境变量(代码中为 HEX_API_TOKEN),接口基址为 https://app.hex.tech/api/v1,请求头带 Authorization 与 Content-Type。文中给出 triggerRun、runAndWait、runPipeline、cancelRun 等 TypeScript 示例函数,均需保留原样使用。
前置条件:指定项目所有者、环境允许清单、已批准的参数模式,以及使用虚构或已批准测试数据的沙盒项目;执行/取消权限限定在单个项目,需约定关联标识和回滚或取消流程。输出为编排回执,含不透明项目/运行 ID、参数版本、触发身份类别、起止状态、聚合断言、取消结果和回滚引用;不应存储 SQL、单元格输出或凭据。
限制与错误:429 为速率限制(20/分钟、60/小时),需排队加延迟;运行 ERRORED 表示项目代码失败,需在 Hex UI 查看日志;KILLED 表示超时或手动取消,可增大超时或修复慢查询;404 表示项目未发布,触发前需先发布。后续定时运行可参考 hex-core-workflow-b。