Frame.io용 Storage Connect: 에셋 등록

Storage Connect는 Frame.io의 엔터프라이즈 고객이 자체 클라우드 스토리지 엔드포인트를 Frame.io의 백업 스토리지로 사용할 수 있도록 하는 기능입니다. 현재 사용자가 Frame.io에 자산을 업로드하면 해당 자산은 애플리케이션 스택을 거쳐 Frame.io의 Amazon S3 버킷에 저장됩니다. 마찬가지로, 에셋의 재생 및 전송은 Frame.io에서 관리하는 Amazon S3 버킷에서 처리됩니다.

Frame.io를 탐색, 검색, 공유, 검토를 위한 단일 표면으로 계속 사용하면서 자체 AWS S3를 정보 소스로 사용할 수 있습니다. 이제 다음 항목을 연결할 수 있습니다.

하나의 기본 S3 버킷(읽기/쓰기) - Frame.io에서 새로 업로드된 항목이 도착하는 곳입니다.
원하는 수의 추가 S3 버킷(읽기 전용)‑ - 원본을 복사하거나 복제하지 않고 S3에 있는 기존 미디어를 Frame.io에서 표시하고 재생할 수 있도록 합니다.

Frame.io는 원본이 S3에 남아 있는 상태에서 가벼운 프록시(축소판, 미리보기, 재생)를 생성합니다. 연결된 버킷에 이미 있는 파일을 등록하려면 V4 공개 API: 읽기 전용 엔드포인트를 사용합니다.

참고: 이 서비스는 Storage Connect를 사용하는 신규 및 기존 Frame.io 고객 모두에게 제공됩니다. 기존 고객 지원을 활성화하기 위해 Frame.io는 과거에 Frame.io에서 관리하는 Amazon S3 버킷에 저장된 기존 고객 데이터를 고객이 관리하는 Amazon S3 버킷으로 한 번에 마이그레이션하는 기능을 일반 가용성으로 제공합니다.

아래 정보는 Frame.io의 신규 및 기존 고객을 대상으로 Storage Connect와 호환되도록 S3 버킷을 구성하는 단계별 안내서를 제공하기 위해 설계되었습니다.

필수 조건

조직에 대해 Storage Connect가 활성화된 Frame.io 엔터프라이즈 계정.
AWS IAM 역할/정책 및 S3 버킷 권한 만들기/업데이트 액세스.
Frame.io V4 공개 API 액세스(읽기 전용 버킷에서 가져온 기존 오브젝트를 등록하는 데 사용되는파일 가져오기 엔드포인트용).‑

참고: 정확한 IAM 신뢰 구성 및 계정 매핑을 위해 Frame.io 담당자(CSM/구현 전문가)가 현재 OIDC/역할 설정을 제공하고 온보딩 중 권한을 검증합니다.

핵심 개념

기본(읽기/쓰기) 버킷: 사용자가 Frame에 업로드할 때 원본을 수신하는 S3 버킷입니다. Frame에 읽기 + 쓰기 권한이 필요합니다.
읽기 전용 버킷‑: Frame이 읽을 수 있지만 쓸 수 없는 S3 버킷이 하나 이상 필요합니다. 에셋은 파일 가져오기 API를 호출하여 Frame에 표시됩니다(원본 복사 없음).
프록시: Frame은 원본이 S3에 남아 있는 상태여도 Frame에서 에셋을 재생할 수 있도록 하기 위해 파생물(썸네일, 미리보기, 스트리밍 프록시)을 생성합니다.

파트 A - 기본 읽기/쓰기 S3 버킷 구성

기본 스토리지로 사용할 S3 버킷을 선택하거나 만듭니다.

Frame.io에 대한 IAM 역할을 만들고(Frame.io ID 공급자가 신뢰함) 버킷/접두사에 대한 읽기/쓰기 권한을 부여하는 IAM 정책을 연결합니다.

정책 뼈대 예시(가능한 경우 ARN을 바꾸고 필수 접두사로 제한):

{ 
  "Version": "2012-10-17", 
  "Statement": [ 
    { 
      "Sid": "ListPrimaryBucket", 
      "Effect": "Allow", 
      "Action": ["s3:ListBucket"], 
      "Resource": "arn:aws:s3:::YOUR_PRIMARY_BUCKET" 
    }, 
    { 
      "Sid": "RWPrimaryObjects", 
      "Effect": "Allow", 
      "Action": [ 
        "s3:GetObject", 
        "s3:PutObject", 
        "s3:DeleteObject", 
        "s3:AbortMultipartUpload", 
        "s3:ListMultipartUploadParts" 
      ], 
      "Resource": "arn:aws:s3:::YOUR_PRIMARY_BUCKET/*" 
    } 
  ] 
}

Frame.io에 세부 정보 입력: IAM 역할 ARN, 버킷 이름, 선호하는 오브젝트 접두사. Frame.io는 Frame에서 사용자의 업로드가 이 버킷을 대상으로 하도록 매핑을 완료합니다.
Frame에서 테스트 업로드를 수행하여 검증함으로써 원본이 S3에 도착하고 프록시가 프레임에 나타나는지 확인합니다.

파트 B - 하나 이상의 읽기 전용 S3 버킷 추가‑

추가 S3 버킷을 읽기 전용 소스‑로 연결할 수 있습니다. Frame은 프록시 생성 및 재생을 위해 오브젝트를 읽지만, 이 버킷에 새 오브젝트를 쓰지는 않습니다.

Frame에 노출할 추가 S3 버킷을 선택합니다. 필요한 경우 폴더 접두사도 선택할 수 있습니다.
Frame에서 각 버킷/접두사에 대한읽기 전용 액세스 권한을 부여하는 데 사용되는 IAM 역할을 만들거나 업데이트‑합니다.

버킷별 정책 뼈대 예시(ARN/접두사를 조정하고 각 버킷에 추가):

{  
  "Version": "2012-10-17",  
  "Statement": [  
    {  
      "Sid": "ListReadOnlyBucket",  
      "Effect": "Allow",  
      "Action": ["s3:ListBucket"],  
      "Resource": "arn:aws:s3:::YOUR_RO_BUCKET"  
    },  
    {  
      "Sid": "ReadObjects",  
      "Effect": "Allow",  
      "Action": ["s3:GetObject", "s3:GetObjectVersion"],  
      "Resource": "arn:aws:s3:::YOUR_RO_BUCKET/*"  
    }  
  ]  
}

Frame.io에 세부 정보 입력: 동일한 역할 ARN(또는 버킷별로 별도의 ARN), 각 버킷 이름, 읽기 전용으로 노출되어야 하는 선택적 접두사.‑
파일 가져오기 API(아래)를 사용하여 읽기 전용 버킷에서 ‑기존 파일 등록을 진행합니다.

파트 C - Frame에 기존 S3 오브젝트 등록(Import API)

읽기 전용 버킷을 추가할 때 미디어는 이미 S3에 있습니다. ‑파일 가져오기 엔드포인트를 사용하여 원본을 복사하지 않고 해당 S3 오브젝트를 Frame 프로젝트/폴더에 등록합니다.

Import의 기능

Frame에 S3 오브젝트를 가리키는 파일 에셋을 만듭니다.
Frame에서 탐색/재생을 위한 프록시를 생성하도록 트리거합니다.
원본 파일을 S3에 그대로 둡니다.

API 호출 전 점검 사항

Storage Connect 매핑이 완료되었는지(Frame.io에 역할 ARN, 버킷, 접두사가 있는지) 확인합니다.
필수 파일 범위가 설정된 OAuth 토큰을 준비합니다.
Frame에서 가져온 파일을 표시해야 하는 대상 컨테이너를 식별합니다(프로젝트 루트 또는 폴더 에셋 ID).
가져올 S3 버킷과 오브젝트 키를 식별합니다.

예(의사코드 cURL)

정확한 경로와 필드는 공식 API 참조를 사용하세요. 아래 구조는 의도를 보여줍니다.

# PSEUDOCODE — 정확한 URL 및 스키마는 "파일 가져오기" 엔드포인트 문서 참조

curl -X POST "https://api.frame.io/v4/files.import_file" \ 
  -H "Authorization: Bearer $TOKEN" \ 
  -H "Content-Type: application/json" \ 
  -d '{ 
    "container_id": "<FRAME_FOLDER_OR_PROJECT_ASSET_ID>", 
    "external": { 
      "provider": "s3", 
      "bucket": "my-readonly-bucket", 
      "key": "Marketing/2025/hero.mov" 
    }, 
    "display_name": "hero.mov" 
  }'

Frame에서 검증

대상 프로젝트/폴더를 엽니다. 가져온 파일은 다른 에셋처럼 표시됩니다.
프록시 생성이 완료되면 즉시 재생이 가능해야 합니다.
Asset Details에서 저장 위치가 S3인지 확인합니다.

동작 및 메모

모든 Frame 클라이언트(웹 iOS, 전송 앱 등)에서 모든 업로드 파일은 기본 읽기/쓰기 버킷으로 이동합니다.
읽기 전용 버킷에서 가져온 에셋은 그대로 유지됩니다. Frame에서 에셋을 ‑삭제해도 읽기전용 버킷에 있는 원본은 삭제되지 않습니다. ‑(읽기/쓰기 버킷에 대한 조직의 삭제 정책을 준수하세요.)
수명 주기/보관: 오브젝트가 Glacier로 이동하거나 일시적으로 사용할 수 없는 경우 이전에 생성된 프록시는 계속 탐색이 가능할 수도 있습니다. 원본 검색은 S3 계층과 가용성에 따라 달라집니다.

문제 해결

가져오기/재생 시 403/AccessDenied 발생 → IAM 정책에 오브젝트 ARN에 대한 s3:GetObject가 포함되어 있는지 확인합니다.
오브젝트가 검색되지 않음 → 버킷/접두사 매핑이 가져오는 오브젝트 키와 일치하는지 확인합니다.
프록시가 생성되지 않음 → 파일 형식이 지원되는지 확인하고 IAM에서 읽기를 허용하는지 확인합니다. 일시적인 S3 오류가 있는지 확인합니다.
대량 가져오기 시 속도 제한 → 지수 백오프로 재시도를 추가하고 동시 작업에 스로틀링을 적용합니다.

자주 하는 질문

질문: 읽기 전용 버킷을 몇 개나 추가할 수 있나요?‑

답변: 원하는 수만큼 추가할 수 있습니다. 각 버킷(과 필요한 경우 접두사)을 읽기 전용 권한으로 매핑합니다.

질문: 기존 라이브러리를 Frame으로 옮기거나 복사해야 하나요?

답: 아니요. 파일 가져오기 API를 사용하여 제자리에 있는 상태로 등록할 수 있습니다.

질문: 나중에 버킷을 제거할 수 있나요?

답변: 네. 읽기 전용 버킷을 제거하면 해당 에셋은 Frame에서 게시 취소됩니다(원본은 S3에 남아 있음).

질문: Frame이 내 읽기 전용 버킷에 쓰기 작업을 하는 경우가 있나요?‑

답변: 아니요. Frame은 필요할 때 프록시를 생성하고 원본을 스트리밍하기 위해 오브젝트를 읽습니다. 쓰기는 기본 읽기/쓰기 버킷에만 발생합니다.