HTTP API 参考手册 (Pusher Protocol)

本服务实现了标准的 Pusher HTTP API。你可以使用任何支持 Pusher 协议的客户端库或直接调用 WebSocket 服务器的 REST API。

接口地址

在生产环境中，API 请求通常直接发往 WebSocket 服务（通过内网或本地回环）。

• Internal URL: `http://127.0.0.1:8080`
• Connection Timeout: 建议设置为 5 秒

认证 (Authentication)

请求签名机制遵循 Pusher 协议标准。详情请查阅 Pusher HTTP API 认证文档。

所有 API 请求都需要包含 auth_key, auth_timestamp, auth_version, body_md5 (POST请求) 和 auth_signature。

接口列表

1. 触发事件 (Trigger Event)

发布消息到一个或多个频道。

• Endpoint: `POST /apps/{app_id}/events`

Payload 示例 (私有频道)

```json { "name": "App\Events\OrderShipped", "channels": ["private-user.1"], "data": "{"order_id": "ORD-2023-001", "status": "shipped"}" } ```

IMPORTANT

`data` 字段必须是一个 JSON 编码的字符串。如果你传递的是对象，服务将无法正确解析。

Payload 示例 (排除发送者)

在实现“打字指示器”或“即时聊天”时，你可能希望排除发送消息的用户自己。

```json { "name": "client-typing", "channel": "chat-room.1", "data": "{"user_id": 42}", "socket_id": "1234.5678" } ``` 注意：`socket_id` 是客户端连接时获得的唯一标识符。

2. 查询频道状态 (Fetch Channels)

获取当前活跃的频道列表。

• Endpoint: `GET /apps/{app_id}/channels`
• Query Params:
  • `filter_by_prefix` (string): 例如 `presence-`
  • `info` (string): 逗号分隔的附加信息，如 `user_count` (仅限 presence 频道)

Channels Response

```json { "channels": { "presence-chat": { "user_count": 5 }, "public-news": {} } } ```

3. 查询频道用户 (Fetch Users)

获取 Presence 频道中的在线用户列表。

• Endpoint: `GET /apps/{app_id}/channels/{channel_name}/users`

Users Response

```json { "users": [ { "id": "1" }, { "id": "2" } ] } ```

---

错误代码对照表

状态码	含义	常见原因
200	OK	请求成功
400	Bad Request	JSON 格式错误，或缺少必填字段 (name, channels, data)
401	Unauthorized	App Key 不存在，或者 auth_signature 校验失败
403	Forbidden	该应用被禁用，或尝试向未授权的频道发送消息
413	Payload Too Large	消息体超过大小限制 (默认 10KB，可在配置中调整)