상태 및 상태 관리 방법 | Frame.io API Documentation

소개

이 가이드에서는 디바이스 상태를 관리하고 Frame.io와 동기화를 유지하는 방법을 설명합니다. 저희는 Frame.io와 디바이스 간의 실시간 통신을 가능하게 하는 웹소켓 프로토콜을 사용합니다. 웹소켓에 익숙하지 않으시더라도, 이 가이드가 C2C 통합을 위한 구현을 이해하는 데 도움을 줄 것입니다.

웹소켓을 사용하면 Frame.io가 디바이스로 메시지를 푸시할 수 있으며, 지속적인 연결을 유지함으로써 기존 HTTP 요청보다 효율적인 통신 채널을 제공합니다.

이 가이드에서 다룰 내용은 다음과 같습니다.

디바이스가 ‘온라인’임을 나타내기 위한 소켓 연결 열기
디바이스 연결에 대한 정보 검색
Frame.io 백엔드 가용성 확인

사전 요구 사항

아직 확인하지 않으셨다면, 계속하기 전에 C2C 구현: 설정 가이드를 검토해 주세요. 인증 및 권한 부여 과정에서 획득한 access_token이 필요합니다. 토큰은 8시간 후에 만료되므로 토큰을 새로 고치거나 인증 프로세스를 다시 거쳐야 할 수 있습니다. 이 가이드의 웹소켓 연결 예제에서는 다양한 운영 체제에 대한 포괄적인 설치 지침을 제공하는 CLI 도구인 websocat을 사용하는 것을 권장합니다.

MacOS

다음과 같이 설치하세요. brew install websocat

연결 정보 검색

새로운 인증이나 토큰 새로 고침 후, 디바이스는 즉시 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초당 1회를 넘지 않도록 제한하는 것이 좋습니다.

id

다음 섹션의 웹소켓 연결에 필요하므로 id 값을 기록해 두세요.

웹소켓 연결 설정

Frame.io의 C2C Connections 패널에는 각 디바이스의 연결 상태가 표시됩니다. 디바이스에 활성 소켓 연결이 있으면 카드 왼쪽 상단에 녹색 표시와 함께 online으로 표시됩니다. 활성 연결이 없는 디바이스는 회색으로 비활성화되어 offline으로 표시됩니다.

서버는 “하트비트” 메시지 없이 60초가 지나면 자동으로 소켓 연결을 종료합니다. 이 간격으로도 충분하지만, 안정성을 위해 15초마다 하트비트를 전송하는 것을 권장합니다. 연결이 예기치 않게 끊어지면 단순히 다시 설정하세요.

Frame.io의 웹소켓에 연결하는 과정은 두 단계로 이루어집니다.

TCP/IP 핸드셰이크 설정 및 물리적 웹소켓 연결 열기
디바이스의 특정 채널에 조인하여 백엔드에 디바이스 식별시키기

웹소켓 연결을 열려면:

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

인증 헤더

액세스 토큰이 Authorization 헤더에 들어가는 표준 API 엔드포인트와 달리, 웹소켓 연결의 경우 URL 인코딩된 쿼리 매개변수로 포함됩니다. 여전히 액세스 토큰 앞에 Bearer (공백 포함)를 포함해야 합니다. URL 인코딩된 문자열에서 공백은 %20으로 표시되므로, 이러한 형식이 정상입니다.

연결에 성공하면 wss로의 프로토콜 전환을 나타내는 101 상태 코드가 반환됩니다. 웹소켓 라이브러리가 이 작업을 자동으로 처리할 수 있습니다. 만료된 토큰은 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"}

ref 및 payload 필드

ref 필드는 응답을 이를 시작한 이벤트와 연결합니다. 이벤트 순서가 보장되지 않으므로, 이 식별자는 서버 응답을 트리거 이벤트와 연결하는 데 도움이 됩니다. Frame.io는 수신 이벤트에 이 필드를 사용하지 않으며 전적으로 클라이언트 참조용입니다. payload 필드는 항상 존재해야 하지만 종종 빈 문자열일 수 있습니다(payload에 특정 콘텐츠가 필요한 경우 명시하겠습니다).

C2C 대시보드를 확인하세요. 이제 디바이스가 온라인으로 표시될 것입니다! 이 연결을 유지하기 위해 백그라운드 프로세스를 구현하는 것을 권장합니다.

Python

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)을 그대로 표시하기보다는, 사용자에게 더 의미 있는 지표로 변환하여 표시하는 것을 권장합니다.

Paused: true/false - 상태가 paused이면 true를 표시하고, 그렇지 않으면 false를 표시합니다.
Connected: 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에 연결할 수 없는 시나리오가 있을 수 있습니다.

다음 단계

궁금한 점이 있으시면 저희 팀에 문의해 주시고 기본 업로드 가이드로 진행하시기 바랍니다. 귀하의 통합 진행 과정을 지원할 수 있기를 기대합니다. 디바이스 인증 관리에 대한 자세한 내용은 인증 관리 가이드를 참조하세요.