Companion项目HTTP按钮触发接口的使用指南

Companion作为一款流行的流媒体控制软件，其HTTP API接口功能强大但使用上存在一些需要注意的技术细节。本文将详细介绍如何通过HTTP请求正确触发Companion中的按钮操作。

HTTP请求方法的变化

在Companion 3.4版本之后，API接口发生了重要变化。旧版本使用GET请求方式，而新版本则要求使用POST方法。这一变更主要是出于安全性考虑，因为GET请求的参数会暴露在URL中，而POST请求更加安全。

新旧API接口对比

旧版API路径格式为：

/press/bank/page/button

新版API路径格式为：

/api/location/page/row/button/press

值得注意的是，旧版API仍然可用，但需要在设置中单独启用。对于新安装的系统，默认只启用新版API。

正确使用POST请求

要成功触发按钮，必须确保以下几点：

1. 使用POST方法而非GET方法
2. 请求地址格式正确
3. 确保Companion服务监听在正确的IP和端口

一个典型的cURL命令示例应该是：

curl -X POST http://192.168.1.100:8888/api/location/1/3/4/press

这个命令会触发第1页第3行第4列的按钮。

常见问题排查

如果请求不生效，建议检查以下方面：

1. 请求方法：确认使用的是POST而非GET
2. IP地址：确保请求发送到Companion服务实际运行的IP
3. 端口号：检查Companion配置的HTTP端口是否与请求一致
4. 路径格式：确认page/row/button的编号从0还是1开始（不同版本可能有差异）

自动化工具集成建议

当与Apple Automator等自动化工具集成时，需要特别注意工具默认可能使用GET请求。大多数自动化工具都支持指定请求方法，务必将其设置为POST。

通过理解这些技术细节，用户可以更可靠地实现Companion按钮的远程触发功能，为流媒体控制工作流提供更多可能性。