방법: 권한 부여(하드웨어) | Frame.io API Documentation

소개

이 가이드는 Frame.io 프로젝트에서 C2C(Camera to Cloud) 하드웨어 디바이스에 대한 인증 및 권한 부여 프로세스를 보여줍니다. 최적의 사용자 경험을 위해 수동 코드 입력을 사용하는 기존 페어링 방법과 향상된 QR 코드 페어링 방식을 모두 다룹니다.

무엇이 필요할까요?

시작하기 전에 구현 전 숙지 사항 가이드를 아직 확인하지 않으셨다면 미리 검토해 주시기 바랍니다. 연동 시스템을 식별하기 위해 저희 팀으로부터 client_secret을 발급받으셨을 것입니다. client_secret을 받지 못하셨다면 이 C2C 에코시스템 소개를 확인하시고 저희 팀에 문의해 주세요.

QR 코드 페어링을 위한 전제 조건

QR 코드 페어링을 시작하기 전에 다음 전제 조건이 충족되었는지 확인하세요.

기능 플래그 활성화: Frame.io 계정에서 특정 기능 플래그(v4.c2c_qr_code_activate)가 활성화되어 있어야 합니다. 이 기능 플래그를 통해 QR 코드 기반 페어링 방식에 액세스할 수 있습니다. 지정된 Frame.io 담당자가 원하는 계정에 이 기능을 활성화하도록 도와드릴 수 있습니다.
카메라 호환성: 디바이스 페어링 프로세스 중에 QR 코드 생성을 지원하도록 카메라 하드웨어가 업데이트되었는지 확인합니다.

하드웨어 인증 흐름 살펴보기

구현하고자 하는 권한 부여 흐름에 대해 예상되는 사용자 경험을 전반적으로 이해하고 있어야 합니다. 사용자 관점에서 이 흐름을 파악하려면 다음 리소스를 확인하세요.

새 하드웨어 디바이스 추가에 대한 지원 문서입니다.
Teradek Cube 권한 부여에 대한 교육 비디오입니다.

하드웨어 권한 부여 흐름은 구현자와 디바이스 UI의 부담을 최대한 줄이도록 설계되었습니다. 이 흐름을 사용하면 다음 사항에 대해 걱정할 필요가 없습니다.

웹 브라우저로 리디렉션.
Frame.io 사용자 로그인/인증 처리
연결할 계정 및 프로젝트 나열/선택
기본 정보 표시 외의 모든 UI 요소.

QR 코드 페어링으로 사용자 경험 향상

효율성과 사용 편의성에 대한 요구가 커지면서 사용자는 디바이스와의 원활한 상호 작용을 점점 더 기대하고 있습니다. Frame.io의 C2C 서비스에 카메라를 페어링하는 현재 프로세스는 페어링 코드를 수동으로 입력하는 것을 포함하여 여러 단계가 필요합니다. 기능적으로는 문제가 없지만 이 프로세스를 더욱 간소화할 수 있습니다.

Netflix나 Disney+와 같은 스트리밍 서비스에서 볼 수 있는 디바이스 페어링 경험과 유사하게 QR 코드를 활용하면 프로세스를 단순화하고 수동 입력으로 인한 오류를 제거하며 카메라 페어링에 소요되는 시간을 단축할 수 있습니다.

디바이스 식별(client_id)

Camera to Cloud에 연결할 때 사용자의 프로젝트에 디바이스 연결을 나열할 수 있도록 각 물리적 하드웨어 디바이스를 고유하게 식별해야 합니다.

하드웨어 디바이스의 경우, 사용하기로 선택한 권한 부여 패턴에 따라 이를 디바이스의 client_id라고 합니다. 구현을 설정할 때 이 작업을 어떻게 수행할지 고려해야 합니다. 하드웨어 디바이스의 일련번호, UUID 또는 특정 고유 식별 문자열을 사용할 수 있습니다. 개인 식별 정보가 유출되지 않도록 주의하세요. 예를 들어 사용자의 이메일은 client_id로 사용하기에 적합한 값이 아닙니다.

마찬가지로 반드시 고유 식별자를 직접 제어할 수 있어야 합니다. C2C API를 소프트웨어 디바이스로 구현하는 경우, 예를 들어 디바이스의 MAC 주소를 사용해서는 안 됩니다. MAC 주소는 귀하의 소프트웨어 소유가 아니며 개인 식별 정보로 간주될 수도 있습니다.

어떤 값을 사용해야 할지 잘 모르겠다면 함께 상의하여 연동을 최대한 간소화할 수 있는 적절한 값을 선택하도록 도와드릴 수 있습니다.

1단계: 디바이스 코드 요청

본격적으로 구현을 시작해 보겠습니다. 가장 먼저 해야 할 일은 사용자에게 디바이스용으로 제공할 디바이스 코드를 요청하는 것입니다. 이를 위해 /v2/auth/device/code 엔드포인트를 호출합니다.

기존 페어링 방식

curl -X POST https://api.frame.io/v2/auth/device/code \
    --form 'client_id=[client_id]' \
    --form 'client_secret=[client_secret]' \
    --form 'scope=asset_create offline' \
    | python -m json.tool

QR 코드 페어링 활성화

QR 코드 기반 페어링을 활성화하려면 API 호출을 약간 수정해야 합니다. 특히 디바이스 코드 요청에 두 개의 새로운 헤더를 추가해야 합니다. 이를 통해 디바이스가 페어링 페이지에 직접 연결되어 페어링 프로세스를 간소화할 수 있습니다.

curl -X POST https://api.frame.io/v2/auth/device/code \
    --header "x-client-version: 2.0.0" \
    --header "x-client-platypus-enabled: true" \  # New header to enable QR code
    --form 'client_id=[client_id]' \
    --form 'client_secret=[client_secret]' \
    --form 'scope=asset_create offline' \
    | python -m json.tool

참고: 여기서는 JSON 데이터가 아닌 양식 데이터를 사용하고 있습니다. C2C 인증 엔드포인트는 양식 데이터만 허용합니다. 인증이 완료되면 다른 엔드포인트는 JSON 페이로드를 허용하지만, 인증 엔드포인트에 JSON 페이로드를 전송하면 오류가 반환됩니다.

페이로드 매개변수

client_id: 물리적 하드웨어 디바이스의 고유 식별자입니다. 이 값은 디바이스에 대해 고유성이 보장되어야 합니다. 일련번호나 임의로 생성된 UUID일 수 있습니다.
client_secret: 디바이스 모델을 식별하기 위해 Frame.io 지원팀에서 발급합니다. 이 값은 사용자로부터 비밀로 유지되어야 하며 저장 시 암호화되어야 합니다.
scope: 요청하는 권한이며 공백을 구분 기호로 사용합니다. 하드웨어 디바이스는 다음 두 가지 권한만 요청할 수 있습니다.
asset_create: 디바이스가 에셋을 생성하고 업로드할 수 있도록 허용합니다.
offline: 디바이스가 새로 고침 토큰을 사용하여 자체 권한 부여를 새로 고칠 수 있도록 허용합니다. 권한 부여 토큰은 8시간 후에 만료되므로 이 권한이 없으면 사용자는 8시간마다 디바이스를 다시 인증해야 합니다.

실제 적용 시 디바이스는 거의 항상 두 가지 권한을 모두 요청해야 합니다.

API 응답 이해

요청을 하면 다음과 유사한 응답을 받게 됩니다.

기존 페어링 응답

{
  "device_code": "[device_code]",
  "expires_in": 120,
  "interval": 5,
  "name": "MyDevice-[client_id]",
  "user_code": "573131"
}

QR 코드 페어링 응답

{
  "device_code": "[device_code]",
  "expires_in": 120,
  "interval": 5,
  "name": "MyDevice-[client_id]",
  "user_code": "573131",
  "verification_uri": "https://next.frame.io/pair",
  "verification_uri_complete": "https://next.frame.io/pair/573131"
}

응답 분석

device_code: 디바이스 코드는 사용자에게 표시되지 않아야 하며, 사용자가 코드를 올바르게 입력했는지 확인하기 위해 폴링할 때 이 권한 부여 요청을 식별하는 데 사용됩니다.
expires_in: 이 코드가 만료될 때까지 남은 시간(초 단위)입니다.
interval: 사용자가 코드를 입력했는지 확인하기 위한 폴링 요청 사이에 기다려야 하는 시간입니다.
name: 연결하려는 디바이스의 이름입니다.
user_code: 사용자가 디바이스를 프로젝트에 페어링하기 위해 Frame.io에 입력할 6자리 코드입니다.
verification_uri: QR 코드가 스캔되지 않은 경우 사용자가 수동으로 입력할 URL입니다. 간결하고 기억하기 쉬워야 합니다.
verification_uri_complete: 이 URL에는 페어링 코드가 포함되어 있으며 비텍스트 방식 전송(예: QR 코드)을 위한 것입니다. 스캔 시 디바이스를 연결할 계정과 프로젝트를 선택하는 페어링 환경으로 사용자를 자동 라우팅합니다.

사용자에게 QR 코드 표시

이제 verification_uri_complete를 얻었으므로 이 URL에서 QR 코드를 생성하여 디바이스 화면을 통해 사용자에게 표시할 수 있습니다. 이를 통해 사용자는 모바일 디바이스나 카메라로 QR 코드를 스캔하기만 하면 되므로 페어링 프로세스가 간소화됩니다.

예시: QR 코드가 표시된 카메라 화면

QR 코드가 표시된 카메라 화면의 이미지 또는 일러스트레이션을 삽입합니다.

사용자가 어떤 이유로든 QR 코드를 스캔할 수 없는 경우를 대비하여 대체 수단으로 수동으로 페어링 코드를 입력할 수 있도록 user_code와 verification_uri를 함께 표시해야 합니다. 또는 사용자가 모바일 디바이스로 스캔할 수 있도록 verification_uri를 정적 QR 코드로 표시할 수도 있습니다. 연동 시스템이 모바일 디바이스의 앱인 경우, 앱이 실행 중인 동일한 디바이스에서는 QR 코드를 스캔할 수 없으므로 사용자가 탭할 수 있는 하이퍼링크로 verification_uri_complete를 표시해야만 원활한 연결이 가능합니다.

2단계: 사용자 권한 부여 폴링

페어링 코드를 제공하거나 QR 코드를 사용자에게 표시한 후에는 코드를 입력했는지 확인해야 합니다. 이를 위해 다음과 같은 요청을 할 수 있습니다.

curl -X POST https://api.frame.io/v2/auth/token \
    --form 'client_id=[client_id]' \
    --form 'device_code=[device_code]' \
    --form 'grant_type=urn:ietf:params:oauth:grant-type:device_code' \
    | python -m json.tool

페이로드 매개변수

client_id: 1단계에서 전송한 것과 동일한 client_id입니다.
device_code: /v2/auth/device/code에서 반환된 device_code입니다.
grant_type: OAuth 시스템이 발급하는 권한 부여 유형입니다. 이 값은 항상 urn:ietf:params:oauth:grant-type:device_code입니다.

처음 몇 번 이 요청을 수행할 때는 다음과 같은 응답을 받을 가능성이 높습니다.

{
  "error": "authorization_pending"
}

하지만 걱정하지 마세요! 이 오류는 시스템 오류가 아닙니다. 이는 단순히 사용자가 Frame.io UI에 사용자 코드를 아직 입력하지 않았음을 의미합니다. 우리는 사용자가 코드를 입력할 때까지 계속 폴링만 하면 됩니다.

만약 그 대신 다음과 같은 오류가 발생한다면:

{
  "error": "expired_token"
}

이는 사용자가 코드를 입력하기 전에 코드가 만료되었음을 의미합니다. 이러한 경우 1단계를 사용하여 새 페어링 코드나 QR 코드를 생성하여 사용자에게 표시한 다음 폴링을 재개해야 합니다.

최종적으로는 다음과 같은 응답을 받아야 합니다.

{
  "access_token": "[access_token]",
  "expires_in": 28800,
  "refresh_token": "[refresh_token]",
  "token_type": "bearer"
}

응답 페이로드가 이와 같다면: 축하합니다! 첫 번째 Camera to Cloud 디바이스에 성공적으로 권한을 부여했습니다. 잠시 이 기쁨을 만끽하세요!

기쁨을 만끽한 후에는 응답 페이로드를 살펴보고 그 내용을 확실히 이해해 보겠습니다.

access_token: Frame.io 백엔드의 나머지 부분에 액세스하기 위한 키입니다. 이 튜토리얼에서 수행할 나머지 요청의 헤더에 이를 추가해야 합니다.
expires_in: access_token이 만료될 때까지 남은 시간(초 단위)입니다. 토큰 시간이 만료되면 새로 고쳐야 하며, 이는 향후 튜토리얼에서 다룰 예정입니다.
refresh_token: access_token을 관리하는 데 사용할 수 있는 토큰입니다. 대부분 권한 부여를 새로 고치는 데 사용되지만 권한 부여를 취소하는 데 사용할 수도 있습니다.
token_type: C2C API의 경우 항상 bearer가 되며 추가적인 조치가 필요하지 않습니다.

단계 조합하기

이제 호출해야 할 API를 알았으므로 이를 Python 형태의 의사 코드로 조합해 보겠습니다. 디바이스 코드는 만료될 수 있으므로 로직을 설정할 때 이러한 가능성을 반드시 처리해야 합니다.

Python

1 def authorize_with_frame():
2     """
3     Handles authorizing our device with Frame.io.
4     """
5 
6     # Our client ID can be a serial number, UUID, or some other unique string.
7     client_id = THIS_DEVICE.get_serial_number()
8 
9     while True:
10         # Make the call to Frame.io to get our device codes.
11         pairing_codes = c2c.get_device_codes(client_id)
12 
13         # We need to keep track of how long we have been polling for
14         polling_started = datetime.now()
15 
16         # Now we are going to poll for authorization until the user enters the code.
17         while True:
18 
19             # Re-write this output each time we poll. Note: This message will only update once
20             # per `interval` (e.g., 5 seconds), so if a smooth countdown is desired, that will
21             # need a different implementation.
22             print(
23                 f"\rPAIRING CODE: {pairing_codes.user_code}, "
24                 f"EXPIRES IN: {pairing_codes.expires_in - (datetime.now() - polling_started).seconds} seconds"
25             )
26 
27             # Wait for `interval` before polling each time.
28             sleep(pairing_codes.interval)
29 
30             # Make a call to Frame.io to see if the user has entered the code and authorized
31             # the device.
32             authorization, error = c2c.poll_for_authorization(
33                 client_id, pairing_codes.device_code
34             )
35 
36             if error and error.message == "authorization_pending":
37                 # If the authorization is pending, try again.
38                 continue
39             elif error and error.message == "expired_token":
40                 # If the pairing codes have expired, break to generate new codes.
41                 break
42             elif error:
43                 # If we get another error, we should raise it. (advanced error handling will
44                 # be covered in another tutorial)
45                 raise Exception(error.message)
46 
47             return authorization

참고: 이 의사 코드에서는 페어링 코드가 만료되어 새 코드를 요청해야 하는 경우를 처리하기 위해 외부 루프를 추가했습니다. 마지막으로 수행해야 할 작업은 연동한 프로젝트에 대한 정보를 Frame.io에서 가져와 사용자에게 표시함으로써 디바이스가 의도한 프로젝트에 올바르게 페어링되었음을 다시 한번 확인시켜 주는 것입니다. 이는 다음 튜토리얼에서 보여드리겠습니다.

문제 해결

여기까지 오셨다면 무언가 잘못된 것입니다! 어떤 종류의 오류도 발생하지 않는다면 서드 파티 연동이 아니겠죠? 이 섹션에서는 일반적인 문제들을 나열하고 이를 해결할 가능성이 가장 높은 단계를 안내합니다. 다음 목록을 살펴보고 귀하가 겪고 있는 문제와 일치하는 사항이 있는지 확인해 보세요.

여기서 해결책을 찾지 못하셨다면 나중에 추가할 수 있도록 겪으신 문제를 공유해 주시면 감사하겠습니다.

“디바이스 연결” 버튼이 보이지 않음: C2C 관리 패널로 이동했는데 “디바이스 연결” 버튼이 보이지 않는다면 다음 두 가지 중 하나가 원인입니다.
C2C가 계정에 대해 활성화되지 않음: 화면이 비어 있고 계정에서 C2C를 사용할 수 없다는 메시지가 표시되는 경우, 계정 관리자가 계정 설정에서 프로젝트에 대해 C2C를 활성화해야 합니다.
디바이스 관리자가 아님: 화면이 비어 있고 권한이 없다는 메시지가 표시되는 경우, 계정 관리자가 C2C 디바이스를 연결할 수 있는 사용자의 권한을 변경하거나 귀하를 해당 권한이 있는 역할에 추가해야 합니다.
이미 연결된 디바이스가 있음: 첫 번째 디바이스가 연결되면 커다란 파란색 “새 디바이스 추가” 버튼이 사라지며, 대신 C2C Connections 패널의 우측 상단에 있는 점 3개 메뉴를 클릭해야 합니다.
잘못된 클라이언트 오류: 제공한 디바이스 정보가 저희 시스템에 등록된 정보와 일치하지 않을 때 invalid_client가 반환됩니다. 이는 client_secret이 잘못되었을 가능성이 높음을 의미합니다.
잘못된 요청 오류: 요청 데이터의 형식이 잘못되었을 때 bad_request가 반환됩니다. 필드 이름의 철자가 틀렸거나 필수 필드를 누락하지 않았는지 다시 한번 확인하세요.

다음 단계

아직 문의하지 않으셨다면 저희 팀에 문의하신 후 다음 가이드로 계속 진행하시기 바랍니다: LINK. 여러분의 연락을 기다리겠습니다!

추후 고려 사항

할 일

동적 QR 코드를 생성할 수 없는 파트너를 위한 대비책 추가

백업 계획으로 “**verification_uri**로 이동하여 이 코드를 입력하세요”라고 표시하도록 안내