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

前言

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

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

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

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

前提条件

如果您还没有阅读，请在继续之前先查阅实施 C2C：设置指南。 您需要用到在身份验证和授权流程中获取的 access_token。 请注意，令牌在 8 小时后过期，因此您可能需要刷新令牌或重新进行授权流程。 对于本指南中的 WebSocket 连接示例，我们推荐使用 websocat，这是一个 CLI 工具，提供了针对多种操作系统的详细安装说明。

检索连接信息

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

$
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 秒不超过一次。

建立 WebSocket 连接

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

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

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

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

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

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

成功的连接会返回 101 状态代码，表示协议正在切换为 wss。 您的 WebSocket 库可能会自动处理此状态代码。 过期的令牌将产生 403 响应。 接下来，使用您连接信息中的 id，通过发送以下 JSON 消息来加入设备的通道：

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

您将收到一条确认消息：

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

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

1
def heartbeat_task():
2
    """
3
    Task that emits heartbeats every 15 seconds.
4
    """
5
6
    while True:
7
        c2c.emit_socket_heartbeat()
8
        sleep(15)

心跳消息的格式：

1
{"topic":"phoenix", "event":"heartbeat", "payload":"", "ref":"heartbeat"}

将收到以下响应：

1
{"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: "status_updated" 和 payload: "paused" 或 "resumed" 来通知您状态的变更
• 虽然事件有助于管理状态，但它们可能会被遗漏，或者以错误的顺序传递
• 在上传过程中收到 409 错误并不一定意味着设备当前已暂停——它可能表示媒体文件是在之前的某个暂停窗口期间创建的
• 如果显示暂停状态，请通过定期检查连接信息来验证其准确性

验证后端连接

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

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

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

1
{
2
    "ok": true
3
}

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

后续步骤

我们鼓励您就任何疑问联系我们的团队，并继续参阅基础上传指南。 我们期待为您的集成进度提供支持。 有关管理设备授权的更多信息，请参阅授权管理指南。