시작 | Frame.io API Documentation

Adobe Developer Console

Adobe API를 사용하는 첫 번째 단계는 Adobe Developer Console에서 프로젝트를 만드는 것입니다. Developer Console의 프로젝트는 Frame.io 개발자 API를 사용하기 위해 빌드 중인 애플리케이션에 해당합니다. 이는 Frame.io 내의 프로젝트와는 구분됩니다.

리소스 계층 구조

Account → Workspace → Project → Folder → Folder / Version Stack / File

프로젝트 가이드

Developer Console에서 프로젝트를 생성한 후, 여기에 Frame.io API를 추가하세요.

Frame.io V4 개발자 API의 새로운 기능은 무엇인가요?

Version 4에 맞게 Frame.io 애플리케이션이 완전히 탈바꿈한 것처럼, V4 API 역시 처음부터 완전히 새롭게 재설계되었습니다. 일부 핵심 개념은 이전 버전과 유사하게 유지되지만, 더 강력한 공동 작업 워크플로와 통합을 지원하기 위해 많은 개념이 대체되거나 재설계되었습니다. 완전히 새로운 API의 도입은 저희의 운영을 대폭 간소화하고 중요한 고객 워크플로를 우선순위에 둘 수 있는 기회도 제공했습니다.

Frame.io V4와 이전 버전의 비교는 여기에서 확인할 수 있습니다.

V4 API 내에서 Workspace(Frame.io 이전 버전에서는 Teams로 불림)와 같은 일부 리소스는 Frame.io Version 4와 일치하도록 이름이 변경된 반면, 이전 버전의 에셋과 같은 다른 리소스는 개발자의 혼란을 줄이기 위해 특정 스토리지 엔터티(파일, 폴더, 버전 스택)를 지칭하도록 이름이 변경되었습니다. 또한 사용자 지정 필드와 공유와 같이 완전히 새로운 기능도 있습니다. 그 외의 주요 변경 사항으로는 리소스 요청 시 기본적으로 반환되는 데이터 양을 대폭 줄이고, 응답 내 일부 속성 이름을 전체 API 인터페이스에 걸쳐 더욱 정확하고 일관되게 변경했으며, 새로운 커서 기반 페이지 매김 메커니즘으로 전환했습니다. 따라서 C2C(Camera to Cloud) API를 제외하고, 이전 API와 통합되는 클라이언트는 V4 API와 호환되지 않는다는 점을 명심해야 합니다.

또한 일부 기능은 여전히 작업 중이며, 실제 고객 사용 사례와 피드백에 따라 빠르게 뒤따라 발전할 것으로 예상됩니다. 사용자 지정 작업 및 버전 스택을 생성하는 기능이 그 예입니다. 이전 API에서 사용할 수 있었던 기능이 누락된 것처럼 보인다면 대안이 있거나 곧 제공될 가능성이 높지만, 저희는 이에 대한 여러분의 의견을 듣고 싶습니다.

V4 API를 살펴보기 전에 먼저 Frame.io Version 4 애플리케이션에 표현된 핵심 개념을 이해하는 것이 좋습니다. 시작하기에 가장 좋은 곳은 Frame.io V4 기술 자료입니다. 계정, 사용자, Workspace, 프로젝트, 컬렉션, 공유, 사용자 지정 필드(메타데이터)와 같은 개념은 V4 API에서 별개의 리소스로 모델링되며, 애플리케이션에서의 이들의 관계와 기능을 이해하면 V4 API에서 작동하는 방식을 이해하는 데 도움이 될 것입니다.

API 개요

Frame.io V4 API는 RESTful 아키텍처 원칙을 따르도록 설계되었으며, 고유한 리소스별 URL과 함께 표준 HTTP 메서드 및 응답 코드를 사용합니다. Frame.io는 V4 API에 대한 OpenAPI 3.0 사양을 게시하여, 엔드포인트, 요청 매개변수, 응답에 대한 자세한 정보를 제공합니다. 이 OpenAPI 사양은 신속한 클라이언트 애플리케이션 개발을 촉진하기 위해 다양한 서드파티 코드 생성 도구에서 활용될 수 있습니다.

URL 및 경로 규칙

OpenAPI 사양에 게시된 URL 경로는 일반적으로 리소스 소유권 및 포함 관계를 반영합니다. 따라서 일부 요청 매개변수(예: 계정 ID, 폴더 ID 등)는 리소스 경로 내에 포함되어 있습니다. 이러한 경로는 예측 가능하고 이해하기 쉽도록 의도되었지만, API 요청에서 반환되는 일부 URL(예: 사전 서명된 업로드 URL, 디스플레이 링크)의 구조는 변경될 수 있으므로 클라이언트 애플리케이션에서 직접 구성해서는 안 됩니다.

요청 쿼리 매개변수

페이지 매김 동작과 응답 오브젝트에 관련 리소스를 선택적으로 포함하는 것을 제어하는 요청 매개변수는 include, page_size, include_total_count와 같은 표준 쿼리 매개변수 세트로 정의됩니다. 일부 요청은 해당 리소스나 작업에 특정한 추가 쿼리 매개변수를 지원할 수 있습니다.

1 GET https://api.frame.io/v4/accounts/{account_id}/folders/{folder_id}/children?&include=project&page_size=5&include_total_count=true

요청 및 응답 페이로드

요청 및 응답 페이로드는 모두 JSON 오브젝트로 구성되며, 따라서 HTTP POST, PUT, 또는 PATCH 요청의 content-type 헤더는 application/json 미디어 유형을 지정해야 합니다. 리소스를 생성하거나 업데이트할 때 요청의 data 속성에는 리소스 오브젝트가 포함되어야 합니다. 생성 또는 업데이트되는 리소스의 속성은 이 오브젝트 내에 포함됩니다. 마찬가지로 리소스를 포함하는 성공적인 응답은 응답의 data 속성 내에 이러한 리소스를 제공합니다.

페이지 매김

잠재적으로 많은 수의 리소스 오브젝트(예: 폴더 또는 코멘트 목록)를 반환할 수 있는 응답은 결과 집합이 커짐에 따른 요청 지연 시간을 줄이기 위해 페이지 매김됩니다. 즉, 요청에 대한 응답에는 결과의 단일 “페이지”만 포함될 수 있습니다. 위에서 언급했듯이, 클라이언트는 요청 시 page_size 쿼리 매개변수를 통해 최대 100개의 요소까지 특정 페이지 크기를 선택할 수 있습니다. 지정하지 않으면 페이지 크기는 기본적으로 50개 요소로 설정됩니다. V4 API는 커서 기반 페이지 매김이라는 형태의 페이지 매김을 사용하며, 응답 오브젝트의 links 속성에 상대 링크를 포함합니다(아래 예시 참조). 이 링크의 after 쿼리 매개변수에는 불투명한(클라이언트가 이 문자열을 직접 구성하려고 시도해서는 안 됨) 커서 문자열이 포함되어 있어, 클라이언트가 후속 요청을 수행하여 결과의 다음 페이지를 검색할 수 있도록 합니다(아래 응답 예시 참조). 현재 V4 API는 단방향 페이지 매김만 지원합니다.

1 {
2     "data": [
3         {
4             "created_at": "2024-10-02T00:22:44.887775Z",
5             "creator_id": "8ea72912-d40d-4b88-8d31-3762e055a2aa",
6             "file_size": 102432,
7             "id": "df171f3e-c95f-4454-9071-825cd924b572",
8             "media_type": "application/pdf",
9             "name": "sample.pdf",
10             "parent_id": "e183c7ba-07d9-425a-9467-ebdf0223d9ce",
11             "project": {
12                 "created_at": "2024-08-21T17:45:41.881596Z",
13                 "description": "For demonstration purposes",
14                 "id": "976dd413-a92b-4af6-b465-98aded0174a8",
15                 "name": "Demo Project",
16                 "owner_id": "8ea72912-d40d-4b88-8d31-3762e055a2aa",
17                 "root_folder_id": "e183c7ba-07d9-425a-9467-ebdf0223d9ce",
18                 "storage": 20881946,
19                 "updated_at": "2024-10-02T00:22:47.168489Z",
20                 "workspace_id": "378fcbf7-6f88-4224-8139-6a743ed940b2"
21             },
22             "project_id": "976dd413-a92b-4af6-b465-98aded0174a8",
23             "status": "created",
24             "type": "file",
25             "updated_at": "2024-10-02T00:22:44.927993Z"
26         }
27     ],
28     "links": {
29         "next": "/v4/accounts/6f70f1bd-7e89-4a7e-b4d3-7e576585a181/folders/e183c7ba-07d9-425a-9467-ebdf0223d9ce/children?after=g3QAAAACZAAGb2Zmc2V0YQVkAAR0eXBlZAANb2Zmc2V0X2N1cnNvcg%3D%3D"
30     },
31     "total_count": 21
32 }

오류

오류가 발생하는 경우 응답 오브젝트의 errors 속성에는 발생한 오류에 대한 세부 정보를 제공하는 하나 이상의 오류 오브젝트 배열이 포함됩니다. 현재 배치 작업은 V4 API에서 지원되지 않으므로, 클라이언트가 부분적인 성공과 오류를 처리해야 하는 경우는 없습니다.

1 {
2     "errors": [
3         {
4             "detail": "Unexpected field: foo",
5             "source": {
6                 "pointer": "/data/foo"
7             },
8             "title": "Invalid value"
9         }
10     ]
11 }

다음 표에는 V4 API에서 사용되는 일반적인 상태 코드가 나열되어 있습니다.

상태 코드	상태	설명
200	확인	요청에 성공했습니다.
201	Created	리소스가 생성되었습니다.
204	No Content	리소스가 삭제되었습니다. 응답 페이로드가 없습니다.
400	잘못된 요청	잘못된 형식이나 누락된 매개변수 또는 페이로드로 인해 요청이 잘못되었습니다.
401	Unauthorized	Authorization 토큰이 누락되었거나 유효하지 않습니다.
403	금지됨	Authorization 토큰에 이 요청에 대한 충분한 권한이 없습니다.
404	Not Found	요청한 리소스가 존재하지 않습니다.
422	Unprocessable Entity	요청 페이로드 및/또는 매개변수의 형식은 올바르지만 그 외의 측면에서 유효하지 않아 요청을 실행할 수 없습니다(400 Bad Request와 대부분 상호 교환적으로 사용됨).
429	Too Many Requests	요청이 이 계정에 대한 저희의 API 요청 제한을 초과했습니다. 자세한 내용은 시작 가이드의 요청 제한 섹션을 참조하세요.
5xx	Server Errors	서버에서 예기치 않은 오류가 보고되었습니다. 클라이언트는 이벤트를 재시도하기 전에 최소 30초를 기다려야 하며, 모든 자동 재시도는 횟수를 제한해야 할 뿐만 아니라 연속적인 요청에서 지수 백오프를 사용하는 것 외에도 무작위 간격을 포함해야 합니다.

인증 및 권한 부여

V4 API는 사용자를 인증(AuthN)하고 해당 사용자를 대신하여 액세스 토큰을 생성하기 위해 OAuth 2.0 및 Adobe IMS(Identity Management Server)를 사용합니다. 액세스 토큰은 HTTP Authorization 헤더(즉, Bearer 토큰 인증)를 통해 각 API 요청과 함께 제공되어야 합니다.

IMS에서 생성된 토큰 범위는 정적이며, 사용자가 수행할 수 있는 작업(그리고 해당 사용자를 대신하여 API가 수행할 수 있는 작업)을 결정하는 권한 부여(AuthZ)는 Frame.io 내에서 사용자에게 부여된 역할과 권한에 의해 결정됩니다. 액세스 토큰 생성 및 요청에 대한 자세한 내용은 개발자 콘솔 시작하기 및 인증 설정(Postman으로 개발 시작하기 하위) 섹션을 참조하세요.

버전 및 이전 버전과의 호환성

Frame.io V4 API는 이전 버전의 Frame.io API와 하위 호환되지 않으며, V4 개념과 데이터 모델에 상당한 변경이 있었기 때문에 일반적으로 이전 계정에 포함된 리소스에 액세스하거나 업데이트하는 데 사용할 수 없습니다. 따라서 V4 API와 연결된 URI에는 모두 /v4 경로 접두사가 포함됩니다. 그러나 V4 API는 여전히 빠르게 발전하고 있으며, 새로운 기능으로 인해 때때로 호환성을 깨는 변경이 발생할 수 있습니다. 더 일반적으로, Frame.io는 일정 기간 동안 실험적으로 운영할 새로운 추가 기능을 API에 출시하여, 고객 피드백과 사용량 지표를 수집하고 이에 대응할 수 있도록 합니다. 높은 가동 시간 요구 사항이 있는 프로덕션 품질의 통합을 관리하는 고객에게 이전 버전과의 호환성이 주요 관심사라는 점을 인식하여, 클라이언트가 실험적인 엔드포인트 사용을 선택하고, 파괴적인 변경을 피하며, /V4 API 네임스페이스 내에서 이전 버전과의 호환성을 보장할 수 있도록 사용자 지정 HTTP 헤더를 통해 추가적인 버전 관리 수준을 지원하도록 V4를 설계하고 있습니다. 자세한 내용은 곧 제공될 예정이지만, 현재로서는 V4 API의 초기 릴리스가 안정적인 것으로 간주되며 호환성을 깨는 변경 사항 도입을 고려하기까지는 어느 정도 시간이 걸릴 것이라고 가정해도 무방합니다.

요청 제한

모든 V4 API 호출에는 요청 제한이 적용되며, 각 API 리소스 및 작업은 분당 10개 요청에서 최고 초당 100개 요청에 이르는 자체 제한으로 구성됩니다. 현재 각 제한은 사용자별로 적용되지만, 정책과 제한 자체는 변경될 수 있습니다.

V4 API는 점진적 요청 제한의 “리키 버킷” 알고리즘을 사용하며, 이 방식에서는 할당된 시간 범위 동안 제한이 점진적으로 갱신됩니다. 즉, 특정 리소스에 대해 제한이 갱신되는 엄격한 컷오프 개념은 없습니다(즉, “고정” 및 “슬라이딩 윈도우” 적용 전략). 대신 남은 제한 횟수는 리소스의 제한 및 시간 창에 비례하는 속도로 지속해서 갱신됩니다. 특정 엔드포인트의 요청 제한을 초과하는 요청은 429 HTTP 오류와 함께 실패합니다.

429 오류에 대한 저희의 권장 대응 전략은 일반적으로 “지수 백오프”라고 합니다.

요약하자면:

429를 수신하면 요청을 다시 시도하기 전에 일정 기간(최소 1초) 일시 중지합니다.
또 다른 429를 수신하면 정상 기능이 재개될 때까지 이전 대기 시간을 기하급수적으로 늘리거나 최소 두 배로 늘립니다.

특정 요청에 적용되는 요청 제한을 확인하기 위해 클라이언트는 응답에 반환된 다음 HTTP 헤더를 검사할 수 있습니다.

머리글	값 설명
`x-ratelimit-limit`	이 리소스 경로에 대한 요청 제한으로, 요청 수로 측정됩니다.
`x-ratelimit-remaining`	현재 시간 범위에 남은 요청 수입니다.
`x-ratelimit-window`	이 리소스 경로의 제한에 대한 시간 창으로, 밀리초(ms) 단위로 측정됩니다.

API 세부 정보

V4 API에 대한 최종 설명서는 저희의 API 참조 가이드이지만, 첫 요청을 보내기 전에 V4 API에 모델링된 리소스 계층 구조를 이해하는 것이 도움이 될 것입니다.

리소스 계층 구조

계정은 일반적으로 조직과 연관되며, 구독 플랜, 콘텐츠 소유권, 사용자 역할/권한, Workspace 구성을 결정하는 기본적인 리소스를 나타냅니다. 따라서 V4 API의 거의 모든 엔드포인트에 대한 URL 경로는 리소스가 상주하는 계정을 식별하는 접두사를 포함합니다. Workspace(Frame.io 이전 버전에서는 Teams로 불림)와 프로젝트는 콘텐츠와 사용자를 모두 구성하는 데 사용되며, 여기에는 해당 콘텐츠에 액세스할 수 있는 사용자가 포함됩니다.

Frame.io 내 콘텐츠 리소스의 기본 계층 구조는 다음과 같습니다.

리소스 계층 구조

Account → Workspace → Project → Folder → Folder / Version Stack / File

Frame.io에 업로드되는 모든 에셋은 궁극적으로 파일로 표현되는 반면, 폴더와 버전 스택은 컨테이너 역할을 하며 버전이 지정된 에셋을 지원하는 계층적 스토리지 모델의 토대를 제공하는 스토리지 리소스입니다. 대부분의 사용자는 이미 Frame.io의 폴더라는 기본 개념에 익숙합니다. 폴더는 다른 스토리지 리소스(하위 항목으로 모델링됨)를 순서 없이 담는 컨테이너 역할을 하며, 폴더 트리 내의 하나의 노드를 나타냅니다. 모든 프로젝트에는 고유한 루트 폴더(root_folder_id 키로 식별됨)가 있으며, 이는 프로젝트의 모든 에셋이 상주하는 폴더 트리의 루트 역할을 합니다.

버전 스택은 순서가 지정된 파일의 컨테이너입니다. 그 순서는 엄격하게 선형적이며 각 하위 항목의 버전 번호를 결정하지만, 클라이언트는 적절하다고 판단되는 경우 버전 스택 내에서 파일 순서를 변경할 수 있습니다. 파일은 특정 시점에 항상 정확히 하나의 폴더 또는 버전 스택의 하위 항목(내부에 포함됨)이 됩니다. 마찬가지로 폴더나 버전 스택도 항상 정확히 하나의 폴더(프로젝트의 루트 폴더 제외)의 하위 항목이 됩니다.

Frame.io에 저장된 파일과 폴더에 대한 기본 CRUD 작업을 수행하는 것에 대한 자세한 내용은 API 참조 가이드를 참조하세요. 현재 V4 API는 폴더의 콘텐츠를 나열할 때 버전 스택만 지원하지만, 버전 스택을 생성하고 업데이트하기 위한 엔드포인트가 곧 제공될 예정입니다.

SDK

TypeScript와 Python용 SDK를 사용할 수 있습니다. 아래 명령을 사용하여 설치할 수 있습니다. 설명서의 SDK 참조 섹션에는 Python 및 TypeScript SDK에 대한 전체 참조가 포함되어 있습니다.

TypeScript

$ npm i -s frameio

npm에서 보기

Python

$ pip install frameio

PyPi에서 보기