> This page is for Camera to Cloud.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://next.developer.frame.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://next.developer.frame.io/_mcp/server.

# 操作指南：管理状态与状况

## 前言





本指南介绍了如何管理设备状态并与 Frame.io 保持同步。 我们使用 WebSocket 协议，可实现 Frame.io 与您的设备之间的实时通信。 如果您不熟悉 WebSocket，本指南将帮助您理解其在 C2C 集成中的实施方式。





借助 WebSocket，Frame.io 可以向您的设备推送消息，并通过保持持久连接，提供比传统 HTTP 请求更高效的通信通道。





在本指南中，我们将介绍：




* 打开套接字连接以表明您的设备处于“在线”状态
* 检索有关设备连接的信息
* 验证 Frame.io 后端的可用性




## 前提条件

如果您还没有阅读，请在继续之前先查阅[实施 C2C：设置](./implementing-c2c-setting-up)指南。 您需要用到在[身份验证和授权流程](./implementing-c2c-authentication-and-authorization)中获取的 `access_token`。 请注意，令牌在 8 小时后过期，因此您可能需要刷新令牌或重新进行授权流程。 对于本指南中的 WebSocket 连接示例，我们推荐使用 [websocat](https://github.com/vi/websocat)，这是一个 CLI 工具，提供了针对多种操作系统的详细安装说明。
<Info title="MacOS">
  安装命令：`brew install websocat`
</Info>


## 检索连接信息

在任何新的授权或令牌刷新之后，您的设备应立即查询 `identity` 端点。 这将提供关于您连接的重要信息：

```shell
curl -X GET https://api.frame.io/v2/devices/me \
    --header 'Authorization: Bearer [access_token]' \
    --header 'x-client-version: 2.0.0' \
    | python -m json.tool
```





响应内容将类似如下（部分数据已缩写）：





```
{
    "_type": "project_device",
    "id": "a7e95254-8cd6-4d59-b54d-28c58570a8de",
    "asset_type": "video",
    "authorization": {
        "_type": "project_device_authorization",
        "creator": {
            "_type": "user",
            "id": "e7e96254-8bd6-4d59-b54d-28c58570a8de",
            "name": "Harry Potter"
        },
        "expires_at": null,
        "id": "7b2b68e5-788d-497c-8597-f9362cb1a75e",
        ...
        "project_device_id": "14856308-46e0-4d7d-8438-320262eec74e",
        "scopes": {
            ...
            "asset_create": true,
            ...
            "id": "0fe0accb-447f-44f6-b2af-177d913b3a29",
            "offline": true,
            ...
        }
    },
    ...
    "name": "Frameio-BPEAKE-TEST-DEVICE",
    "project": {
        "_type": "project",
        "id": "2ad59fe6-77b6-4fbc-a9d2-3dd0413ed4a3",
        "name": "Testbed"
    },
    "project_id": "2ad59fe6-77b6-4fbc-a9d2-3dd0413ed4a3",
    "status": "online",
    ...
}
```





此端点有助于验证连接详情。 您的设备应向用户显示以下信息：




* `project.name` - 所连接的项目名称
* `authorization.creator.name` - 授权设备的用户
* `authorization.expires_at`（可选）- 连接过期时间（如果已设置）
* `status`（可选）- 设备状态，可能为以下值：

* `online` - 设备在线且已配对 * `offline` - 设备超过 5 分钟未通信（查询此端点将把状态更改为 `online`）* `paused` - 设备已在 Frame.io C2C Connections 面板中临时禁用

由于过期状态和暂停状态可能在 Frame.io 内随时变化，如果您需要向用户显示此信息，建议定期轮询。 我们建议将轮询频率限制为每 60 秒不超过一次。




<Info title="id">
  请记住 `id` 值，因为您在下一节中需要用它来建立 WebSocket 连接
</Info>


## 建立 WebSocket 连接

Frame.io 中的 C2C Connections 面板会显示每台设备的连接状态。 当设备拥有活跃的套接字连接时，它会显示为 `online` 状态，并且在卡片左上角有一个绿色的指示器。 没有活跃连接的设备会显示为 `offline` 状态，并显示为灰色。

如果超过 60 秒没有收到“心跳”消息，服务器会自动终止套接字连接。 虽然此间隔时间足够了，但为了可靠性，我们建议每 15 秒发送一次心跳。 如果连接意外关闭，只需重新建立连接即可。





连接到 Frame.io 的 WebSocket 需要两个步骤：




1. 建立 TCP/IP 握手并打开物理 WebSocket 连接
2. 加入设备的特定通道，以便向我们的后端标识您的设备





要打开 WebSocket 连接，请执行以下操作：





```shell
websocat -n "wss://api.frame.io/devices/websocket?Authorization=Bearer ACCESS_TOKEN"
```




<Info title="Authorization 标头">
  与将访问令牌放在 `Authorization` 标头中的标准 API 端点不同，对于 WebSocket 连接，它以 URL 编码的查询参数形式包含在内。 请注意，您仍须在访问令牌之前包含 `Bearer `（后面带一个空格）。 在 URL 编码的字符串中，空格显示为 `%20`，因此这种格式是符合预期的。
</Info>
 成功的连接会返回 `101` 状态代码，表示协议正在切换为 `wss`。 您的 WebSocket 库可能会自动处理此状态代码。 过期的令牌将产生 `403` 响应。 接下来，使用您连接信息中的 `id`，通过发送以下 JSON 消息来加入设备的通道：

```json
{"topic":"devices:YOUR_DEVICE_ID", "event":"phx_join", "payload":"", "ref":"channel_connect"}
```





您将收到一条确认消息：





```json
{"event":"phx_reply","payload":{"response":{},"status":"ok"},"ref":"channel_connect","topic":"devices:YOUR_DEVICE_ID"}
```




<Info title="ref 和 payload 字段">
  `ref` 字段用于将响应与其发起事件进行关联。 由于无法保证事件顺序，此标识符有助于将服务器响应与触发事件进行配对。 Frame.io 不会在传入事件中使用该字段——它仅供客户端参考。 `payload` 字段必须始终存在，但通常可以是一个空字符串（当 payload 需要特定内容时，我们会加以说明）。
</Info>


检查 C2C 仪表板——您的设备现在应该显示为在线状态！ 我们建议实施一个后台进程来维持此连接：





**`Python`**

```python title="Python"
def heartbeat_task():
    """
    Task that emits heartbeats every 15 seconds.
    """

    while True:
        c2c.emit_socket_heartbeat()
        sleep(15)
```





心跳消息的格式：





```json
{"topic":"phoenix", "event":"heartbeat", "payload":"", "ref":"heartbeat"}
```





将收到以下响应：





```json
{"event":"phx_reply","payload":{"response":{},"status":"ok"},"ref":"heartbeat","topic":"phoenix"}
```





当拥有活跃的套接字连接和通道订阅后，您的设备将在 Frame.io 的 C2C Connections 面板中显示为在线状态。 当连接终止时，它将显示为离线状态。





## 显示设备状态

我们建议不要显示原始的状态值（`online`、`offline`、`paused`），而是将其转换为对用户更有意义的指示信息：
* **已暂停**：true/false - 如果状态为 `paused`，则显示 `true`，否则显示 `false`
* **已连接**：true/false - 表示设备能否连接到 Frame.io 后端（请参阅下文“后端连接测试”部分）




## 管理“已暂停”状态





虽然显示暂停状态是可选的，但了解其功能也很重要。





暂停功能旨在临时阻止敏感内容被上传。 它不会阻断网络流量，但会阻止特定媒体文件到达 Frame.io。 这在拍摄包含敏感素材的场景时非常有用，因为此时立即将内容存入云端可能并不合适。





暂停功能通过 Frame.io 界面控制，而非通过您的集成。 设备暂停时，仅阻止暂停期间创建的媒体文件——之前已拍摄的媒体文件仍可上传。





重要注意事项：




* 不要仅依赖 identity 端点来验证上传资格——我们的后端会自动处理这一点
* 套接字事件会通过 `event: &quot;status_updated&quot;` 和 `payload: &quot;paused&quot;` 或 `&quot;resumed&quot;` 来通知您状态的变更
* 虽然事件有助于管理状态，但它们可能会被遗漏，或者以错误的顺序传递
* 在上传过程中收到 `409` 错误并不一定意味着设备当前已暂停——它可能表示媒体文件是在之前的某个暂停窗口期间创建的
* 如果显示暂停状态，请通过定期检查连接信息来验证其准确性




## 验证后端连接





要检查 Frame.io 后端的可用性，请使用以下端点：





```shell
curl -X GET https://api.frame.io/health \
    | python -m json.tool
```





此端点无需授权。 成功的响应表示连接正常：





```json
{
    "ok": true
}
```





此运行状况检查特别有价值，因为它确认的是与 Frame.io 的连接，而不是一般的网络可用性。 可能存在这样的场景：您的网络正常运行，但由于服务问题或路由问题而导致 Frame.io 无法访问。





## 后续步骤

我们鼓励您就任何疑问联系我们的团队，并继续参阅[基础上传指南](/camera-to-cloud/how-to-basic-upload)。 我们期待为您的集成进度提供支持。 有关管理设备授权的更多信息，请参阅[授权管理指南](./how-to-authorization-management)。