파일 트리 읽기

개요

최종 목표가 퍼블리싱이든, 편집이든, 또는 워크플로 단계를 통해 에셋을 전송하는 것이든, Frame.io와의 많은 심층적인 연동 시스템에는 사용자 컨텍스트를 나열하고 궁극적으로 디렉터리 뷰를 표시하는 작업이 포함됩니다.

다음은 Frame.io 내 리소스(또는 파일)의 기본 계층 구조입니다.

계정 > 팀 > 프로젝트 > 에셋

이 문서는 순차적인 API 호출을 통해 파일 트리와 상호 작용하는 방법을 설명합니다. 파일 작업을 위한 일반적인 전략은 먼저 프로젝트에 액세스하여 폴더를 나열한 다음, 그 안에 포함된 에셋 및 버전 스택을 작업하는 것입니다.

중요 개념

모든 프로젝트에는 고유한 루트 에셋이 있습니다.

RESTful API는 일반적으로 고유 식별자를 사용하여 리소스를 설명하며, root_asset_id는 프로젝트 에셋 트리의 고유 식별자입니다. 이것을 프로젝트의 루트 노드 역할을 하는 특수한 구조로 생각하세요. 나머지 에셋들은 이 루트 아래에 하향식 트리 구조로 쌓이게 됩니다.

일반적인 워크플로에서 API 사용자는 파일 계층 구조 깊은 곳에 있는 에셋과 상호 작용하기 위해 트리를 따라 한 단계씩 내려가야 합니다.

협업자 및 공유 프로젝트

협업자는 Frame.io의 주요 사용자 역할 중 하나입니다. 이러한 사용자는 프로젝트 작업 영역에 액세스할 수 있지만, 해당 프로젝트를 총괄하는 계정에는 속하지 않을 수 있습니다. 협업자와 팀 멤버 간의 권한 차이는 제쳐두더라도, 가장 큰 차이점은 협업자의 멤버십은 철저히 프로젝트 단위이며 팀과는 아무런 관련이 없을 수 있다는 점입니다.

이로 인해 디렉터리 목록이 가장 중요한 워크플로에서 약간 까다로운 부분이 생깁니다. 위의 기본 계층 구조(계정 > 팀 > 프로젝트 > 에셋)는 대부분의 활용 사례에서 작동하지만, 인증된 사용자가 팀 멤버가 아닌 협업자로 참여 중인 프로젝트는 설명하지 못합니다. 디렉터리를 나열할 때 이 문제를 피하려면 다음 중 하나를 선택할 수 있습니다.

• 사용자의 공유 프로젝트를 가져오고, 팀 및 계정 계층 구조의 압축을 푼 다음, 이들을 모두 하나로 묶습니다. 또는
• 사용자의 공유 프로젝트를 가져온 후, 이들을 별도의 컨텍스트로 함께 나열합니다.

두 방법 모두 괜찮습니다. 후자가 조금 더 쉽지만, 전자는 Frame.io의 웹 앱이 유사한 정보를 표시하는 방식에 더 가깝습니다. 어느 경우든 이 가이드에서 다루는 방법은 두 가지 모두에 적용됩니다.

디렉터리 나열

1.사용자 계정 가져오기

GET https://api.frame.io/v2/accounts

유효한 베어러 토큰을 사용하여 위 호출을 실행하면 사용자의 계정을 가져올 수 있습니다. 사용자가 팀 멤버, 팀 관리자, 또는 관리자 상태인 모든 계정을 받게 됩니다. 사용자가 청구/관리자 권한은 있지만 팀 액세스 권한은 없는 팀을 받을 수도 있습니다. 그러나 이는 드문 경우이며 다음 단계에서 걸러지게 됩니다.

Accounts 요청에 대한 페이로드는 꽤 장황합니다. 다음은 응답에서 수집할 만한 중요한 데이터에 대한 요약입니다.

• id
• display_name
• owner (email, name)
• (선택 사항) image

사용자 계정의 필수 필드는 id와 owner.email뿐이라는 점에 유의하세요. 다른 앱에서 사용자를 표시하는 경우, 사용자 계정을 나타내기 위한 조건부 로직 작성을 고려해 보세요. 저희가 권장하는 방식은 값이 null이 아닌지 확인하고, 다음 선호도 순서에 따라 계정을 표시하는 것입니다.

1. “display_name”
2. “owner.name의 계정”
3. “owner.email의 계정”

사용자가 계정을 선택하고 나면 팀을 표시하고 싶을 텐데, 이를 위해서는 추가적인 API 요청이 필요합니다.

2.계정 내에서 팀 가져오기

GET https://api.frame.io/v2/accounts/{{account_id}}/teams Frame.io의 팀은 “공개”(즉, 계정의 모든 팀 멤버가 검색 가능)이거나 “비공개”(특정 팀 멤버만 검색 가능)일 수 있습니다. API가 이러한 컨텍스트를 처리해 주므로, 위 요청에 account_id를 지정하여 유효한 호출만 수행하면 됩니다.

페이지 매김에 대한 자세한 내용은 페이지 매김 및 오류 문서에서 확인할 수 있습니다. 각 팀에서 다음 속성들을 가져오세요.

• id
• name
• (선택 사항) team_image

팀이 선택되면 해당 팀을 구성하는 프로젝트들을 표시하고 싶을 것입니다.

참고: 원한다면 특정 사용자에 대해 GET https://api.frame.io/v2/teams를 요청할 수도 있습니다. 저희 API는 계정 컨텍스트에 관계없이 사용자가 속한 모든 팀을 반환할 것입니다. 이 방법은 기술적으로 유효하지만, 다음과 같은 추가 조치를 취하지 않으면 컨텍스트를 잃을 위험이 있습니다.

1. 각 팀 옆에 계정 이름을 함께 표시하여 컨텍스트를 재설정합니다.
2. 사용자가 목록 텍스트를 검색할 수 있도록 허용합니다.

계정 수준 이하의 공유 프로젝트를 나열하는 경우, 추가로 GET https://api.frame.io/v2/projects/shared 호출을 수행해야 합니다. 응답으로 반환된 각 프로젝트에는 다음 속성들이 포함되며, 디렉터리를 구축할 때 이를 활용할 수 있습니다.

• id(프로젝트 자체의 ID)
• team_id
• team.account_id

또는, 선택한 계정 컨텍스트에 “공유 프로젝트”를 “팀”처럼 추가하여 사용 편의성을 제공할 수도 있습니다. 그렇게 할 경우 공유 프로젝트를 실제 팀 범위 프로젝트와 시각적으로 분리해 주는 것이 최종 사용자에게 유용합니다. 단일 공유 프로젝트 목록 내부에는 실제로는 다양한 계정 및 팀 컨텍스트가 섞여 있을 수 있기 때문입니다.

3.팀의 프로젝트 가져오기

GET https://api.frame.io/v2/teams/{{team_id}}/projects

다음으로, 위 호출을 수행하여 팀 내의 모든 프로젝트를 가져옵니다.

각 프로젝트에 대해 다음 항목들을 가져오세요.

• id
• name
• root_asset_id
• (선택 사항) UI에서 사용자를 위해 구분 표시를 하려는 경우 private 속성

문서 서두에서 설명했듯이, root_asset_id는 프로젝트 내의 파일 및 폴더 디렉터리를 탐색할 수 있게 해 준다는 점에서 Frame.io의 리소스 아키텍처의 중요한 구성 요소입니다.

| * 계정

| * 팀

| * 팀 프로젝트(및 root_asset_ids)

| * 공유 프로젝트(및 root_asset_ids)

| 이것이 에셋을 생성하거나 가져오는 데 필요한 전부입니다.

폴더 및 에셋 나열하기

4.초기 폴더 구조 구축하기

GET https://api.frame.io/v2/assets/{{root_asset_id}}/children?type=folder 이렇게 하면 root_asset_id부터 시작하여 프로젝트의 모든 폴더가 나열됩니다. 폴더가 없으면 빈 목록이 반환됩니다. 파일과 폴더를 모두 포함하려는 경우(예: 다음 단계가 Frame.io에서 에셋을 GET하는 것이라면) 쿼리 문자열 매개변수를 생략하기만 하면 됩니다.

type 매개변수에 사용할 수 있는 다른 두 가지 필터 옵션은 file과 version_stack입니다. 세 가지 필터는 모두 상호 배타적이며, 필터링되지 않은 호출은 세 가지 유형을 모두 혼합하여 반환합니다.

5.디렉터리 트리 탐색하기

반환된 각 폴더에 대해 다음을 캡처해야 합니다.

• id
• name

각 폴더도 하나의 에셋이므로, 폴더 구조를 파고드는 워크플로는 다음과 같습니다.

1. GET https://api.frame.io/v2/assets/{{root_asset_id}}/children?type=folder

1.폴더 이름을 목록 형태로 렌더링합니다.

2.사용자가 특정 폴더를 클릭하면 해당 폴더의 id를 다음 쿼리에 전달합니다.

2. GET https://api.frame.io/v2/assets/{{folder_id}}/children?type=folder

6.생성 및 업로드

**폴더로: **POST https://api.frame.io/v2/{{folder_id}}/children 업로드할 대상 폴더의 id를 확인했다면, 리소스 설명서 및 가이드에 따라 하위 항목에 POST 요청을 보내면 됩니다. 이를 통해 자리 표시자 에셋이 생성되며, (선택한 방법에 따라) 다음을 반환합니다.

• 사용 사례 추적을 위한 uuid
• 파일을 Frame.io의 백엔드 데이터 스토리지로 직접 PUT 요청할 때 사용할 수 있는 upload_urls 목록.

버전 스택으로: 버전 스택도 이와 유사한 워크플로를 제공하며, 이 가이드에서 다루는 한 가지 추가 단계가 존재합니다. 요약하자면 아래와 같습니다. 핵심은 버전 스택이 에셋처럼 보이지만 폴더처럼 동작하는 컨테이너라는 점, 그리고 에셋을 먼저 업로드한 다음 이를 별도의 작업을 통해 버전 스택에 쌓아야 한다는 점을 기억하는 것입니다. 따라서 에셋을 버전 스택으로 업로드하려면 다음이 필요합니다.

• 버전 스택의 id
• 버전 스택의 parent_id(예: 해당 버전 스택이 포함된 폴더 또는 프로젝트 루트)

먼저, POST https://api.frame.io/v2/assets/{{parent_id}}/children 요청을 보내 새 에셋을 생성합니다. 응답에서 얻은 새로운 id를 캡처해 둡니다. 이제 새 에셋의 id를 사용하여 다음과 같은 본문 페이로드와 함께 POST https://api.frame.io/v2/assets/{{version_stack_id}}/version 요청을 실행할 수 있습니다.

1
{
2
  "next_asset_id": "<new-asset-id>"
3
}