버전 스택 관리

개요

버전 스택은 Frame.io의 조직적 원칙으로, 에셋을 폴더에 넣지 않고도 수직으로 “스택(겹치기)“할 수 있게 해줍니다. 스택된 버전은 Frame.io UI 내에서 에셋 간 탐색을 더 쉽게 만들고 나란히 보며 리뷰하는 것을 지원합니다.

현재 스택에 직접 업로드하는 기능은 지원하지 않으므로 기본 버전 스택 워크플로 관리를 위한 API 시퀀스는 Frame.io UI와 동일한 순서를 따릅니다.

1. 에셋을 업로드합니다(선택 사항: 비공개로 표시).
2. 에셋을 스택에 할당합니다.

기존 버전 스택은 순서를 바꿀 수 있으며, 개별 버전을 스택에서 제외시킬 수도 있습니다. 마지막으로, 버전 스택은 이를 구성하는 에셋을 삭제하지 않고도 스택 자체만 삭제할 수 있습니다.

핵심 개념

버전 스택은 폴더와 마찬가지로 특별한 유형의 에셋입니다. 동일한 엔드포인트로 가져올 수 있으며, API 응답의 type 키 값에 따라 구문 분석하고 적절히 라우팅할 수 있습니다. 이는 실제로는 대체로 간단하지만, 대규모로 스택을 관리할 때는 몇 가지 까다로운 부분이 있을 수 있습니다. 버전 스택 작업의 핵심은 가장 일반적인 4가지 시나리오를 분리하는 것입니다.

1. 에셋을 다른 에셋에 추가하면 새 id를 가진 스택이 생성됩니다.
2. 기존 스택에 에셋을 추가할 수 있습니다.
3. 스택 순서를 바꿀 수 있습니다.
4. 개별 버전을 제거할 수 있습니다.

처음 두 시나리오는 동일한 엔드포인트 호출을 사용하므로, (두 개의 에셋에서) 새 스택을 생성하는 것인지 아니면 기존 스택에 에셋을 추가하는 것인지 파악하는 것이 유일한 차이점입니다. 그 외에 제약 조건은 예측 가능합니다.

1. 스택은 asset_type이 일치해야 합니다(예: stream 에셋 위에 image 에셋을 스택할 수 없음).
2. 작업을 수행하는 사용자는 소스 에셋과 대상 에셋 또는 스택 모두에 대한 권한이 있어야 합니다.
3. 에셋을 순차적으로 스택합니다.
4. 스택 위에 스택을 쌓을 수는 없습니다.
5. 폴더는 제외됩니다.

마지막 두 시나리오도 꽤 간단하지만 스택 자체에 대해 조금 더 알아야 합니다. 예를 들어, 스택에서 에셋의 순서를 변경하려면 타깃 에셋을 배치하려는 위치의 양옆에 있는 에셋의 id를 알아야 하며, 이는 일반적으로 전체 스택을 이미 가져왔음을 의미합니다.

필수 범위

이 가이드를 시작하기 전에 다음 권한을 포함하는 토큰이 있는지 확인해야 합니다.

버전 스택에 에셋 추가

1단계: 대상 찾기

첫 번째 단계는 에셋을 다른 에셋에 추가하여 스택을 생성하는 것인지, 아니면 에셋을 기존 스택에 추가하여 스택을 확장하는 것인지 두 가지 주요 시나리오 중 어느 상황에 해당하는지 식별하는 것입니다.

버전이 지정되지 않은 에셋을 사용 중이거나 이미 버전 스택 id가 있는 경우 2단계로 이동할 수 있습니다.

그렇지 않은 경우 대상 에셋이 이미 스택의 일부인지 여부를 확인하는 가장 쉬운 방법은 다음과 같습니다.

1. /v2/assets/:id에 대한 호출을 통해 타깃 에셋을 가져옵니다(GET).

2. 반환되는 type을 확인합니다.

• version_stack인 경우, 방금 확인한 uuid가 대상 uuid가 됩니다. 2단계로 이동합니다.

3. type이 file인 경우 parent_id를 가져와
4. 동일한 엔드포인트를 통해 상위 항목을 가져와서(GET) 해당 type을 확인합니다.

상위 항목의 type이 version_stack인 경우 해당 id를 대상으로 사용합니다. type이 다른 것이라면 일반 에셋을 처리하고 있는 것이며 원래 ID를 대상으로 사용할 수 있습니다.

2단계: 페이로드 준비

이제 대상 uuid를 얻었으므로 스택에 추가하려는 에셋의 uuid를 알아야 합니다.

1. 새 에셋을 업로드하는 경우, 에셋을 생성할 때 성공 응답과 함께 반환된 ID를 사용하기만 하면 됩니다.
2. 기존 에셋을 스택에 추가하는 경우, 위에 설명된 프로세스를 통해 id를 이미 확보한 상태여야 합니다.

버전 스택 추가에 필요한 유일한 body 매개변수는 next_asset_id입니다.

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

3단계: 대상에 소스 에셋 추가

이제 두 에셋 id 매개변수를 모두 얻었으므로 /assets/:id/version에 POST 요청을 보낼 준비가 되었습니다. 여기서 :id는 대상 에셋 또는 버전 스택이며, 소스(새) 에셋은 본문 페이로드에 포함됩니다.

버전 스택 순서 바꾸기

버전 스택은 각 에셋에 next_asset_id와 prev_asset_id 이웃이 있다는 단순한 서열 개념에 의존합니다. 여기서 순서는 버전 번호가 아니라 각 에셋의 index 속성을 나타냅니다. index는 버전 번호와 반대로 적용되므로 다음과 같습니다.

• 스택의 첫 번째(가장 낮은 번호의) 버전에는 prev 에셋이 있지만 next 에셋은 없습니다.
• 스택의 더 최근(가장 높은 번호의) 버전에는 next 에셋이 있지만 prev 에셋은 없습니다.
• 모든 “내부” 버전에는 prev 에셋과 next 에셋이 모두 있으며, 이는 각각 더 높고 더 낮은 버전 ID를 가진 에셋입니다.

이는 세 가지 고유한 시나리오를 제공하며, 모두 동일한 엔드포인트 호출에 의존합니다.

호출:

PUT https://api.frame.io/v2/asset/:id/tween

본문:

1
{
2
  "prev_asset_id": "<asset_id>",
3
  "next_asset_id": "<asset_id>"
4
}

모든 경우에 URL 경로의 id는 이동하려는 에셋이 됩니다.

에셋 제거 및 버전 스택 삭제

에셋 제거

에셋이 버전 스택으로 이동되면 스택 자체의 하위 항목이 됩니다. 버전 스택에서 에셋을 꺼내려면 해당 에셋을 스택이 포함된 폴더로 다시 효과적으로 재배치해야 합니다.

1. /v2/assets/:id 호출을 통해 버전 스택 자체를 가져옵니다(GET).
2. 스택 자체의 parent_id를 가져옵니다(이것이 새로운 타깃 폴더 id가 됩니다).
3. 다음과 같이 타깃 에셋을 해당 폴더로 이동합니다.

호출:

POST https://api.frame.io/v2/assets/:parent_id/move

본문:

1
{
2
    "id":"<asset_id>"
3
}

버전 스택 삭제

버전 스택을 삭제하는 것은 매우 간단합니다.

DELETE https://api.frame.io/v2/assets/:version_stack_id/unversion

이것이 전부입니다. 스택을 삭제하면 이를 구성하는 모든 에셋이 스택이 포함된 폴더로 돌아갑니다.

이 모든 상황은 기술적으로 문제없습니다. 싱글톤 버전도 로드 및 재생되고 새 버전을 추가할 수도 있으며 모든 것이 정상적으로 작동합니다. 하지만 Frame.io의 웹 및 기타 애플리케이션에서 사용자에게 혼란을 주는 상황을 피하려면 싱글톤 스택을 삭제하는 것을 권장합니다.

버전 스태킹 엔드포인트에 대한 자세한 내용은 에셋 설명서를 참조하세요.