将 Semaphore 连接到您的工具

如果外部事件需要选择预定义任务模板，并将请求值映射到允许的输入，可采用 Webhook 集成。如果应用需要更明确的资源与执行流程，例如启动任务后读取状态，则使用 REST API。两种情况下，自动化都通过 Semaphore 配置的执行模型运行。应根据调用方需要发送和跟踪的内容选择方式。

项目别名会检查其集成中配置的匹配规则，并可启动与请求匹配的集成。特定集成的别名则直接访问单个集成，不会检查其匹配规则。如果您依赖分支或事件类型规则控制执行，这一区别尤为重要。请有意识地选择端点，同时测试匹配与不匹配的请求载荷，不要假定所有别名路径都采用相同的过滤规则。

配置提取器，读取相关请求头或请求体字段，并映射到文档规定的环境变量或任务参数。参数目标必须与模板接受的提示项一致。映射范围应明确：发布版本应成为预期输入，而不是不受限制的命令片段。如果值的含义要求验证，应在自动化中验证，并在生产使用前测试字段缺失或异常的情况。

API 令牌使用其所属 Semaphore 用户的权限。请选择项目访问权限符合集成预期操作的身份，并在调用方存储令牌的任何位置保护它。API 不会绕过项目授权。对于 Webhook 集成，还应按照文档有意识地配置请求认证和端点暴露方式。调用方的身份验证与任务访问基础设施所用的凭据应分别管理。

在 REST API 流程中，保留文档所述操作返回的任务标识符，并使用相应 API 方法查询状态和输出。请求成功仅表示已请求执行，不代表基础设施工作已成功完成。服务应区分请求错误、等待或运行中的任务，以及已完成的结果。当工程师需要排查实际执行证据时，为其提供任务链接。

不要假定执行具有严格一次语义或持久投递保证。外部服务可能在请求超时后重试，即使第一次请求已经到达 Semaphore。应根据操作的影响设计重复请求处理和重试决策，并在适当情况下确保底层自动化具有幂等性。保留原始事件与服务所跟踪执行之间的关联，以便工程师理解重复或送达状态不确定的请求。

本网站的参考页面展示随 Semaphore 版本发布的 Swagger/OpenAPI 文档，因此操作、路径和模式对应特定版本，而不是手写摘要。可在 /api-docs/ 按资源浏览，若需生成客户端也可读取原始文档。请始终检查实际运行版本的规范，因为端点和请求模式可能随版本变化。

调用系统必须能够访问 Semaphore 实例，但这不一定意味着公开互联网。如果调用方位于私有网络、VPN 或内部负载均衡器之后，该网络即可满足访问要求。我们对匹配器和提取器的验证使用了关闭认证的仅回环监听器，这不是公开端点的配置范例。只要别名可从可信网络之外访问，就应配置受支持的身份验证方式，并在网络层限制暴露范围。

先将集成指向一个无害的任务模板，再使用 curl 或任意 HTTP 客户端自行发送载荷。发送不匹配的请求体，确认没有创建任务；再发送匹配的请求体，确认只启动一个任务。打开该任务的 Details 视图：其中记录了集成来源，提取的值也对本次运行可见。这与我们本地测试使用的顺序相同，可在外部服务依赖集成之前发现错误的匹配键。

可以。REST API 覆盖项目、仓库、清单、凭据、变量组、任务模板及其他自动化资源。门户或基础设施服务可配置这些资源、启动任务并读取执行状态和输出。Pro 还通过 API 提供工作流运行与审批，使 CI/CD 流水线能启动完整的多步骤操作。端点参数与响应模式请参阅 OpenAPI 参考。