Ansible Semaphore API 接口详解与使用指南

概述

Ansible Semaphore 是一个现代化的 Ansible 任务编排工具，提供了直观的 Web 界面来管理和执行 Ansible playbook。本文重点分析其 REST API 接口规范，帮助开发者更好地理解和集成 Semaphore 的功能。

API 基础信息

Semaphore API 遵循 OpenAPI 3.0.1 规范，当前版本为 2.14.0-beta1。API 提供了完整的认证机制和丰富的功能端点，主要涵盖以下核心领域：

• 用户认证与管理
• 项目管理与操作
• 事件日志查询
• 集成功能配置

认证机制

Semaphore API 支持多种认证方式：

1. Bearer Token 认证：通过 API 令牌进行认证
2. Cookie 认证：适用于 Web 界面交互
3. OIDC 认证：支持第三方身份提供商集成

登录认证端点

POST /auth/login
- 功能：执行用户登录
- 请求体：包含用户名和密码的 JSON 对象
- 成功响应：204 No Content（登录成功）

GET /auth/login
- 功能：获取登录元数据（如可用的 OIDC 提供商）
- 响应：LoginMetadata 对象

API 令牌管理

GET /user/tokens
- 功能：获取当前用户的 API 令牌列表
- 响应：APIToken 对象数组

POST /user/tokens
- 功能：创建新的 API 令牌
- 响应：201 Created，返回新创建的 APIToken 对象

DELETE /user/tokens/{api_token_id}
- 功能：使指定 API 令牌失效

用户管理 API

Semaphore 提供了完整的用户管理功能：

GET /users
- 功能：获取所有用户列表
- 响应：User 对象数组

POST /users
- 功能：创建新用户
- 请求体：UserRequest 对象
- 成功响应：201 Created，返回创建的 User 对象

PUT /users/{user_id}
- 功能：更新用户信息
- 请求体：UserPutRequest 对象

DELETE /users/{user_id}
- 功能：删除指定用户

项目管理 API

项目管理是 Semaphore 的核心功能，相关 API 端点丰富：

GET /projects
- 功能：获取项目列表
- 响应：Project 对象数组

POST /projects
- 功能：创建新项目
- 请求体：ProjectRequest 对象
- 成功响应：201 Created，返回创建的 Project 对象

GET /project/{project_id}
- 功能：获取指定项目详情
- 响应：Project 对象

PUT /project/{project_id}
- 功能：更新项目信息
- 请求体：ProjectRequest 对象（含项目ID）

DELETE /project/{project_id}
- 功能：删除指定项目

项目备份与恢复

GET /project/{project_id}/backup
- 功能：备份项目数据
- 响应：ProjectBackup 对象

POST /projects/restore
- 功能：从备份恢复项目
- 请求体：ProjectBackup 对象
- 响应：恢复后的 Project 对象

项目用户管理

GET /project/{project_id}/users
- 功能：获取项目关联用户列表
- 查询参数：
  - sort：排序字段（name/username/email/role）
  - order：排序方向（asc/desc）
- 响应：ProjectUser 对象数组

POST /project/{project_id}/users
- 功能：关联用户到项目
- 请求体：包含 user_id 和 role 的对象
- 角色选项：owner/manager/task_runner/guest

PUT /project/{project_id}/users/{user_id}
- 功能：更新用户在项目中的角色
- 请求体：包含 role 字段的对象

DELETE /project/{project_id}/users/{user_id}
- 功能：从项目中移除用户

事件与日志 API

Semaphore 提供了完善的事件记录功能：

GET /events
- 功能：获取与当前用户相关的所有事件
- 响应：Event 对象数组（按时间顺序）

GET /events/last
- 功能：获取最近200条事件
- 响应：Event 对象数组

GET /project/{project_id}/events
- 功能：获取指定项目相关的事件
- 响应：Event 对象数组

集成功能 API

GET /project/{project_id}/integrations
- 功能：获取项目所有集成配置
- 响应：Integration 对象数组

POST /project/{project_id}/integrations
- 功能：创建新集成配置
- 请求体：Integration 对象

实用工具端点

GET /ping
- 功能：服务健康检查
- 响应：200 OK，"PONG"文本
- 注意：此端点无需认证

POST /debug/gc
- 功能：手动触发垃圾回收
- 响应：204 No Content

GET /ws
- 功能：WebSocket 连接端点
- 用于实时通信和事件推送

最佳实践建议

1. 认证管理：优先使用 API 令牌进行自动化集成，妥善保管令牌并定期轮换
2. 错误处理：注意处理 401（未认证）和 403（无权限）响应
3. 分页查询：对于可能返回大量数据的端点（如事件查询），考虑实现客户端分页
4. WebSocket：对于需要实时更新的场景，使用 WebSocket 连接获取事件推送
5. 备份策略：定期使用项目备份API进行数据备份

通过合理利用这些 API 端点，开发者可以构建强大的自动化工具与 Semaphore 进行交互，实现持续部署、监控告警等高级功能。