Hatchet API 接口详解与使用指南

概述

Hatchet 是一个功能强大的工作流编排系统，提供了丰富的 API 接口用于管理和监控工作流。本文将深入解析 Hatchet 的 API 设计、功能模块以及使用方法，帮助开发者更好地理解和使用这套接口系统。

API 基础信息

Hatchet API 遵循 OpenAPI 3.1.0 规范，提供了完善的接口文档。API 采用 RESTful 设计风格，主要支持 JSON 格式的数据交互。

认证方式

Hatchet API 支持两种认证方式：

1. Bearer Token 认证：通过 HTTP 头部 Authorization 字段传递
2. Cookie 认证：通过名为 "hatchet" 的 cookie 传递

核心功能模块

1. 任务管理

任务管理模块提供了对工作流中单个任务的操作和监控能力：

• 获取任务详情：GET /api/v1/stable/tasks/{task}
• 列出任务事件：GET /api/v1/stable/tasks/{task}/task-events
• 查看任务日志：GET /api/v1/stable/tasks/{task}/logs
• 批量取消任务：POST /api/v1/stable/tenants/{tenant}/tasks/cancel
• 重放任务：POST /api/v1/stable/tenants/{tenant}/tasks/replay
• 按 DAG ID 查询任务：GET /api/v1/stable/dags/tasks

2. 工作流运行管理

工作流运行是 Hatchet 的核心概念，API 提供了全面的管理功能：

• 列出工作流运行：GET /api/v1/stable/tenants/{tenant}/workflow-runs
• 获取工作流运行详情：GET /api/v1/stable/workflow-runs/{v1-workflow-run}
• 获取运行状态：GET /api/v1/stable/workflow-runs/{v1-workflow-run}/status
• 列出工作流运行的任务事件：GET /api/v1/stable/workflow-runs/{v1-workflow-run}/task-events
• 获取时序数据：GET /api/v1/stable/workflow-runs/{v1-workflow-run}/task-timings
• 重放工作流运行：POST /api/v1/tenants/{tenant}/workflow-runs/replay

3. 事件管理

事件是触发工作流运行的关键因素：

• 列出事件：GET /api/v1/stable/tenants/{tenant}/events
• 获取事件键：GET /api/v1/stable/tenants/{tenant}/events/keys
• 批量创建事件：POST /api/v1/tenants/{tenant}/events/bulk
• 重放事件：POST /api/v1/tenants/{tenant}/events/replay
• 取消事件：POST /api/v1/tenants/{tenant}/events/cancel

4. 工作流定义

工作流定义相关接口：

• 创建工作流：POST /api/v1/tenants/{tenant}/workflows
• 获取工作流详情：GET /api/v1/workflows/{workflow}
• 触发工作流：POST /api/v1/workflows/{workflow}/trigger
• 获取工作流指标：GET /api/v1/workflows/{workflow}/metrics
• 创建工作流定时任务：POST /api/v1/tenants/{tenant}/workflows/{workflow}/scheduled
• 创建工作流 Cron 任务：POST /api/v1/tenants/{tenant}/workflows/{workflow}/crons

5. 步骤运行管理

步骤是工作流的基本执行单元：

• 获取步骤运行日志：GET /api/v1/step-runs/{step-run}/logs
• 列出步骤事件：GET /api/v1/step-runs/{step-run}/events
• 重新运行步骤：POST /api/v1/tenants/{tenant}/step-runs/{step-run}/rerun
• 取消步骤运行：POST /api/v1/tenants/{tenant}/step-runs/{step-run}/cancel
• 获取步骤模式：GET /api/v1/tenants/{tenant}/step-runs/{step-run}/schema

6. 监控与指标

Hatchet 提供了丰富的监控指标接口：

• 获取任务状态指标：GET /api/v1/stable/tenants/{tenant}/task-metrics
• 获取任务点指标：GET /api/v1/stable/tenants/{tenant}/task-point-metrics
• 获取队列指标：GET /api/v1/tenants/{tenant}/queue-metrics
• 获取步骤运行队列指标：GET /api/v1/tenants/{tenant}/step-run-queue-metrics
• 获取 Prometheus 指标：GET /api/v1/tenants/{tenant}/prometheus-metrics

7. 用户与租户管理

• 用户登录：POST /api/v1/users/login
• 获取当前用户：GET /api/v1/users/current
• 用户注册：POST /api/v1/users/register
• 列出租户：GET /api/v1/tenants
• 更新租户：PUT /api/v1/tenants/{tenant}
• 租户成员管理：GET /api/v1/tenants/{tenant}/members

集成功能

Hatchet 支持多种第三方集成：

• Google OAuth 集成
• GitHub OAuth 集成
• Slack 集成
• SNS (Simple Notification Service) 集成
• Webhook 集成

系统健康检查

• 就绪检查：GET /api/ready
• 存活检查：GET /api/live
• 获取版本信息：GET /api/v1/version

最佳实践

1. 认证管理：建议使用 API Token 进行认证，可以在租户下创建和管理 API Token。

2. 错误处理：所有 API 调用都应检查返回状态码，4xx 表示客户端错误，5xx 表示服务器错误。

3. 分页处理：对于返回列表的接口，应考虑实现分页逻辑以避免一次性获取过多数据。

4. 事件驱动：充分利用事件系统来触发工作流，而不是直接调用工作流触发接口。

5. 监控集成：将 Hatchet 的监控指标集成到现有的监控系统中，如 Prometheus。

总结

Hatchet API 提供了从工作流定义、执行到监控的全生命周期管理能力。通过合理使用这些接口，开发者可以构建强大的自动化工作流系统，实现复杂的业务流程编排。本文介绍了主要的功能模块和接口，实际使用时建议结合具体业务场景选择合适的接口组合。