통합 아키텍처 | Frame.io API Documentation

소개

API 요청을 시작하기 전에 C2C 통합의 기본 아키텍처를 이해해야 합니다. (걱정하지 마세요. 다음 문서에서는 터미널 환경에서 작업하게 될 것입니다. 지금은 필수적인 개념들만 먼저 다루겠습니다.)

통합을 위한 단순화된 데이터 모델은 다음과 같습니다.

                                   ┌───────────────────┐    ┌─────────┐
                                   │ Project Device 01 │ -> │ Project │
┌───────────┐    ┌──────────────┐  └───────────────────┘    └─────────┘
│ Oauth App │ -> │ Device Model │ ──────────⭥
└───────────┘    └──────────────┘  ┌───────────────────┐    ┌─────────┐
                                   │ Project Device 02 │ -> │ Project │
                                   └───────────────────┘    └─────────┘

OAuth 앱

귀하의 통합 시스템은 OAuth 앱에 의해 정의됩니다. 이는 디바이스가 OAuth 2를 사용하여 Frame.io에서 권한을 부여받을 수 있도록 저희 백엔드에 등록된 엔터티입니다. OAuth 앱은 통합 시스템 전체에 대한 권한 부여 전략을 정의합니다. 사용자가 Frame.io에 연결하는 모든 디바이스는 동일한 OAuth 앱을 통해 권한을 부여받게 됩니다(단, 여러 제품 라인을 보유한 연동 개발자의 경우 각 라인마다 별도의 OAuth 앱을 원할 수 있습니다).

C2C 통합의 경우 UI 기능이 제한된 디바이스를 위해 특별히 설계된 특수한 OAuth 흐름을 사용합니다.

C2C 디바이스 인증

C2C API는 UI 기능이 제한된 디바이스를 위해 설계되었습니다. 이러한 디바이스는 6자리 코드를 표시하여 사용자가 Frame.io에 연결할 수 있도록 하며, 사용자는 자신의 브라우저를 사용하여 Frame.io 웹사이트에 이 코드를 입력합니다.

디바이스에는 6자리 권한 부여 코드를 받기 위해 백엔드에 제공해야 하는 client_secret이 발급됩니다. 이러한 간소화된 접근 방식은 모든 C2C 연동에서 일관되고 안전한 인증 경험을 보장합니다.

디바이스 모델

디바이스 모델은 C2C 백엔드와 상호 작용할 때 디바이스의 작동 방식(지원하는 기능 포함)을 구성합니다. 디바이스 모델에 의해 다음 설정이 구성됩니다.

소켓 상태

통합 시스템이 현재 상태를 통신하기 위해 짧은 지연 시간의 소켓을 사용할지, 아니면 긴 지연 시간의 REST 호출을 사용할지 여부를 결정합니다.

경로 이름

업로드된 모든 에셋의 경로에 표시되어야 하는 연동 시스템의 이름입니다.

토큰화된 파일 경로

C2C는 특정 루트 파일 경로에만 에셋 업로드를 허용하지만, 이 요구 사항 아래에서는 제공된 에셋의 메타데이터를 기반으로 동적으로 계산된 파일 경로에 에셋을 업로드하도록 디바이스를 구성할 수 있습니다.

필수 메타데이터

Frame.io에 에셋을 업로드할 때 요구되는 메타데이터, 특히 토큰화된 파일 경로를 지원하기 위해 필요한 메타데이터를 지정합니다.

소켓 상태

통합 시스템이 현재 상태를 통신하기 위해 짧은 지연 시간의 소켓을 사용할지, 아니면 긴 지연 시간의 REST 호출을 사용할지 여부를 결정합니다.

디바이스가 지원하는 기능은 펌웨어 버전에 따라 달라질 수 있습니다. 이전 버전과의 호환성과 깔끔한 사용자 경험을 보장하기 위해, 디바이스의 구성은 감지된 펌웨어 버전에 따라 동적으로 선택됩니다. 가까운 시일 내에 연동 시스템은 둘 이상의 DeviceModel을 가질 수 있게 될 것입니다. 디바이스의 펌웨어 버전을 특정 디바이스 모델의 최소 펌웨어 버전 요구 사항과 비교하여 어떤 디바이스 모델을 사용할지 결정하게 됩니다.

프로젝트 디바이스 및 식별

ProjectDevice는 Frame.io에 연결된 디바이스의 각 물리적 인스턴스를 나타냅니다. ProjectDevice는 client_id라는 고유 식별 값을 사용하여 자신을 식별합니다. 이 값은 두 디바이스 간에 공유되지 않음이 보장되는 값이어야 합니다. 디바이스의 일련번호이거나 디바이스가 한 번 생성하여 저장한 임의의 문자열일 수 있습니다. client_id는 컴퓨터의 MAC 주소와 같이 디바이스 소유가 아닌 값이 되어서는 안 됩니다.

저희 백엔드는 각 프로젝트 디바이스를 추적하고 현재 펌웨어 버전과 같은 정보를 저장합니다.

각 ProjectDevice는 연결된 특정 Frame.io Project, 디바이스에 프로젝트 액세스 권한을 부여하는 OauthAuthorization, 디바이스가 수행할 수 있는 작업을 자세히 설명하는 일련의 권한 집합을 가집니다. 사용 가능한 권한에 대한 자세한 내용은 인증 및 권한 부여 구현에 관한 상세 가이드를 참조하세요. ProjectDevice는 /me 엔드포인트에서 반환되는 항목입니다. Device는 한 번에 하나의 ProjectDevice에만 활성화된 상태로 연결될 수 있으므로 결과적으로 한 번에 단일 Project에만 연결될 수 있습니다.

펌웨어 버전

https://api.frame.io에서 엔드포인트를 호출할 때마다 디바이스는 현재 펌웨어 버전을 x-client-version HTTP 헤더와 함께 제공해야 합니다. 이후 API 가이드의 각 예시에는 이 헤더가 포함될 것입니다. 일부 경우 저희 백엔드는 여러 펌웨어 버전을 정렬해야 하며, 이를 지원하기 위해 해당 값은 반드시 유효한 시맨틱 버전이어야 합니다. 여기에는 0.1.2, 2.1.3-preview.01, 2.1.3-preview.01+build_19770504.01 등과 같은 값이 포함됩니다.

펌웨어 버전 값이 유효한 시맨틱 버전이 아닌 경우 오류가 반환됩니다. 모든 연동 시스템이 시맨틱 버전 관리를 사용하여 펌웨어를 추적하는 것은 아니라는 점을 이해합니다. 이러한 경우, 생성하는 각 내부 버전에 대해 저희 백엔드에 제공할 시맨틱 버전을 추적해 주시기를 요청합니다.

헤더를 제공하면 펌웨어의 각기 다른 릴리스가 Frame.io 내에서 서로 다른(때로는 충돌하는) 기능을 지원할 수 있습니다.

헤더 호스트

펌웨어 버전은 https://api.frame.io에 대한 호출에서만 처리되며, https://applications.frame.io에 호출할 때는 헤더가 아무런 영향을 미치지 않습니다.

현재 요구 사항

이제 x-client-version은 필수 HTTP 헤더이며 Frame의 서버에 의해 강제로 적용됩니다.

다음 단계

이제 API 호출을 시작할 시간입니다! C2C로 인증 및 권한 부여를 수행하는 방법을 알아보겠습니다. 시작하려면 설정 가이드를 따라 진행하세요.