Ansible Semaphore API 接口全解析

概述

Ansible Semaphore 是一个现代化的 Ansible 任务调度和可视化界面工具，它提供了丰富的 REST API 接口，允许开发者通过编程方式管理 Ansible 任务、项目和资源。本文将全面解析 Semaphore 的 API 接口规范，帮助开发者更好地理解和使用这些接口。

API 基础信息

Semaphore API 遵循 RESTful 设计原则，使用 JSON 作为主要数据交换格式，当前版本为 2.14.0-beta1。API 支持 HTTP 和 HTTPS 协议，基础路径为 /api。

主要功能模块

1. 认证模块

认证模块提供用户登录、登出和 API 令牌管理功能：

• 登录接口：支持用户名/密码和 OIDC 认证
• API 令牌：可创建、管理和撤销访问令牌
• 登录元数据：获取可用的 OIDC 提供者信息

{
  "auth": "user@semaphoreui.com",
  "password": "your_password"
}

2. 用户管理

用户管理模块允许管理员创建、修改和查询用户信息：

• 用户基本属性：名称、用户名、邮箱、密码等
• 权限控制：管理员标识、告警设置等
• 用户类型：区分内部用户和外部用户

3. 项目管理

项目管理是 Semaphore 的核心功能，API 提供了完整的项目生命周期管理：

• 项目创建与配置：设置项目名称、告警配置、并行任务限制等
• 项目备份与恢复：完整的项目配置导出与导入
• 项目成员管理：分配项目角色（owner、manager、task_runner、guest）

4. 资源管理

Semaphore 提供了多种资源的管理接口：

4.1 访问密钥

支持三种类型的密钥管理：

• SSH 密钥：用于代码仓库访问
• 登录密码：用于认证
• 无密钥：不使用密钥

4.2 环境变量

环境变量分为两种类型：

• 环境变量（env）：直接注入执行环境
• 任务变量（var）：仅在任务中使用

4.3 库存管理

支持多种库存类型：

• 静态库存（static）
• 静态 YAML 库存（static-yaml）
• 文件库存（file）
• Terraform 工作区（terraform-workspace）

4.4 代码仓库

管理项目关联的 Git 仓库：

• 仓库 URL 和分支配置
• 关联的 SSH 密钥

5. 模板管理

模板是 Semaphore 中定义 Ansible 任务的核心组件：

• 基础配置：关联库存、仓库、环境等资源
• 任务参数：Playbook 路径、参数、描述等
• 高级功能：
  • 参数覆盖控制
  • 成功告警抑制
  • 自动运行设置
  • 调查变量（Survey Variables）

6. 任务管理

任务执行相关接口：

• 任务状态查询：获取任务执行状态
• 任务输出：实时获取任务日志
• 任务参数：调试模式、干运行等选项

7. 集成功能

Semaphore 提供了强大的集成能力：

• 集成匹配器：基于请求体或头部的条件匹配
• 值提取器：从响应中提取特定值并存储为变量
• 集成类型：支持 JSON、XML 等多种数据格式处理

数据结构详解

用户数据结构

{
  "id": 1,
  "name": "Admin User",
  "username": "admin",
  "email": "admin@example.com",
  "created": "2023-01-01T00:00:00Z",
  "alert": true,
  "admin": true,
  "external": false
}

项目数据结构

{
  "id": 1,
  "name": "Production",
  "created": "2023-01-01T00:00:00Z",
  "alert": true,
  "alert_chat": "#alerts",
  "max_parallel_tasks": 5,
  "type": "ansible"
}

任务模板数据结构

{
  "id": 1,
  "project_id": 1,
  "inventory_id": 1,
  "repository_id": 1,
  "environment_id": 1,
  "view_id": 1,
  "name": "Deploy Web",
  "playbook": "deploy.yml",
  "arguments": "[]",
  "description": "Web application deployment",
  "allow_override_args_in_task": true,
  "suppress_success_alerts": false,
  "type": "deploy",
  "autorun": false
}

最佳实践

1. 认证流程：先获取 API 令牌，再在后续请求的 Authorization 头中使用
2. 错误处理：检查 HTTP 状态码和响应体中的错误信息
3. 批量操作：合理使用项目备份/恢复接口进行批量配置
4. 任务监控：结合 Webhook 和任务状态接口实现自动化监控
5. 权限控制：遵循最小权限原则分配用户角色

总结

Ansible Semaphore 的 API 设计完善，覆盖了从用户管理到任务执行的全生命周期。通过合理使用这些接口，开发者可以实现 Semaphore 与现有系统的深度集成，构建自动化程度更高的 Ansible 任务管理平台。本文详细介绍了各模块的功能和数据结构，可作为开发时的参考指南。