Semaphore API 接口详解与使用指南
2025-07-06 04:24:11作者：宗隆裙
项目概述
Semaphore 是一个现代化的持续集成与持续部署(CI/CD)平台，提供了丰富的 API 接口用于自动化管理和集成。本文档将详细介绍 Semaphore 的 API 结构、功能模块以及使用方法。
API 基础信息
Semaphore API 遵循 RESTful 设计原则，使用 JSON 作为主要数据交换格式，当前版本为 2.2.0。API 支持 HTTP 和 HTTPS 协议，基础路径为 /api。
主要功能模块
1. 认证模块 (Authentication)
认证模块负责用户登录、登出以及 API 令牌管理。
核心端点：
- 登录接口：接收用户名/邮箱和密码
- 登出接口：终止当前会话
- API 令牌管理：创建、查看和撤销 API 访问令牌
数据结构：
Login：包含auth(用户名/邮箱) 和password字段APIToken：包含令牌 ID、创建时间、过期状态和关联用户 ID
2. 用户管理 (User)
用户管理模块提供用户信息的 CRUD 操作。
核心功能：
- 创建新用户
- 获取用户列表
- 更新用户信息
- 删除用户
数据结构：
UserRequest：创建用户时的请求体UserPutRequest：更新用户时的请求体User：用户实体，包含 ID、姓名、用户名、邮箱等基本信息
3. 项目管理 (Project)
项目管理是 Semaphore 的核心模块，负责 CI/CD 项目的配置和管理。
核心功能：
- 创建和管理项目
- 设置项目告警
- 配置并行任务限制
- 项目备份与恢复
数据结构：
ProjectRequest：创建/更新项目时的请求体Project：项目实体，包含 ID、名称、创建时间等ProjectBackup：完整的项目备份数据结构，包含模板、仓库、密钥等所有配置
4. 资源管理
4.1 访问凭证 (Credential)
管理 SSH 密钥和登录凭证。
类型支持：
- none：无凭证
- ssh：SSH 密钥
- login_password：用户名密码凭证
4.2 环境变量 (Environment)
管理项目环境变量和配置。
数据结构：
EnvironmentRequest：创建/更新环境时的请求体Environment：环境实体，支持 JSON 和键值对格式
4.3 清单管理 (Inventory)
管理 Ansible 清单文件。
类型支持：
- static：静态清单
- static-yaml：YAML 格式静态清单
- file：文件形式清单
4.4 代码仓库 (Repository)
管理 Git 代码仓库配置。
配置项：
- Git URL
- 分支名称
- 关联的 SSH 密钥
5. 模板管理 (Template)
模板是 Semaphore 中定义自动化任务的核心单元。
核心功能：
- 创建和管理任务模板
- 配置 Playbook 路径和参数
- 设置任务限制条件
- 管理模板变量
数据结构：
TemplateRequest：创建/更新模板时的请求体Template：模板实体TemplateSurveyVar：模板调查变量，支持多种数据类型
6. 任务调度 (Schedule)
定时执行模板任务的调度系统。
配置项：
- cron 表达式
- 关联模板
- 调度名称
- 激活状态
7. 集成功能 (Integration)
Semaphore 的外部系统集成能力。
核心组件：
- 集成匹配器 (Matcher)：定义触发条件
- 值提取器 (ExtractValue)：从响应中提取数据
匹配方式：
- 支持 body 和 header 匹配
- 支持 equals/unequals/contains 等方法
- 支持 JSON/XML/string 数据类型
使用示例
用户登录
POST /api/auth/login
{
"auth": "user@example.com",
"password": "securepassword"
}
创建项目
POST /api/project
{
"name": "My Project",
"alert": true,
"alert_chat": "#devops-alerts",
"max_parallel_tasks": 5
}
创建模板
POST /api/project/1/templates
{
"project_id": 1,
"inventory_id": 1,
"repository_id": 1,
"environment_id": 1,
"view_id": 1,
"name": "Deploy Production",
"playbook": "deploy.yml",
"arguments": "[]",
"description": "Production deployment workflow",
"allow_override_args_in_task": false
}
最佳实践
- 认证安全：始终使用 HTTPS 协议，妥善保管 API 令牌
- 错误处理：检查 HTTP 状态码和响应体中的错误信息
- 批量操作：合理使用项目备份/恢复功能进行批量配置
- 集成测试：利用匹配器和值提取器构建健壮的集成流程
- 监控告警：配置项目告警及时获取任务状态通知
总结
Semaphore 提供了全面的 API 接口，覆盖了从用户管理到任务执行的所有核心功能。通过合理使用这些 API，可以实现 CI/CD 流程的完全自动化管理，并与现有工具链无缝集成。开发者可以根据实际需求组合不同的 API 端点，构建定制化的持续交付解决方案。
