사용자 지정 작업

Frame.io Actions는 항목 다운로드, 이름 바꾸기, 복제와 같은 일반적인 미디어 작업에 대한 빠른 액세스를 제공하며, 서드파티 도구 및 서비스와의 통합을 Frame.io의 사용자 인터페이스 내에 직접 표시할 수 있도록 해줍니다.

액션 정보

사용자 지정 작업이 도입됨에 따라 개발자는 Frame.io V4에서 자체 Actions를 구성하고 관리할 수 있습니다. 웹훅과 동일한 기본 이벤트 시스템을 활용하는 사용자 지정 작업은 개발자가 Frame.io 계정 사용자에게 가장 중요한 도구에 에셋을 연결할 수 있는 대안적인 메커니즘입니다.

Actions는 해당 기능이 활성화된 Frame.io Workspace의 멤버인 사용자라면 누구나 실행할 수 있습니다. Action을 실행하면 Frame.io는 제공된 URL로 페이로드를 보냅니다. 수신 애플리케이션은 HTTP 상태 코드로 응답하여 수신을 확인하거나, 사용자 지정 콜백으로 응답하여 Frame.io UI에 추가 양식 필드를 렌더링합니다. 수신 애플리케이션은 직접 호스팅하는 프로그램, 서비스, Workfront Fusion이나 Zapier 같은 로우코드/노코드 IPaaS 도구가 될 수 있습니다.

사용자 지정 작업을 사용하여 Frame.io에 직접 프로그래밍 가능한 UI 구성 요소로 통합을 구축하세요. 이를 통해 웹훅과 동일한 기본 이벤트 라우팅을 활용하여 앱 내에서 사용자가 트리거할 수 있는 워크플로를 구현할 수 있습니다. 사용자가 트리거하며, 다른 양식이나 기본 응답의 형태로 Frame.io에 다시 반환되는 단일 또는 다중 단계 양식을 만들 수 있습니다. 사용자가 에셋에서 사용자 지정 작업을 클릭하면 Frame.io는 제공된 URL로 페이로드를 보냅니다. 수신 애플리케이션은 HTTP 상태 코드로 응답하여 수신을 확인하거나, Frame.io에 추가 UI를 렌더링할 수 있는 사용자 지정 콜백으로 응답합니다.

V4의 Actions 개선 사항

이전 버전 사용자들의 피드백을 바탕으로, Frame.io V4의 Actions 기능 세트에 다음과 같은 여러 개선 사항을 포함했습니다.

마이그레이션된 Actions

이전 버전의 Frame.io에서 이전에 생성한 사용자 지정 작업을 포함하여 Frame.io V4 계정으로 마이그레이션할 때 명심해야 할 몇 가지 사항이 있습니다.

Action 상태

Frame.io V4로 계정을 마이그레이션하면 이전 버전에서 생성된 모든 사용자 지정 작업의 상태가 ‘null’이 되며 자동으로 비활성화됩니다. 이를 통해 사용자는 업데이트되지 않은 Actions가 실패하는 것을 방지하기 위해, 활성화하기 전에 먼저 V4 API를 사용하도록 Actions를 업데이트할 기회를 갖게 됩니다. 이 상태의 Actions를 확인하려면 Actions 설정 페이지를 방문하여 “Status” 열을 참조하거나, API를 사용하는 경우 is_active 필드를 확인하세요.

실행 가능한 리소스: 파일, 폴더, 버전 스택

Frame.io V4 API에서는 에셋 유형이 별도의 리소스로 분리되어 있으므로, Action의 페이로드에서 수신된 리소스 ID를 해석할 때 고려해야 할 동작이 있을 수 있습니다. 개별 파일에 대한 동작은 매우 간단합니다. ID가 Action이 실행된 특정 파일을 반영하기 때문입니다. 폴더의 경우에도 Action이 실행된 폴더의 ID를 받게 되지만, 사용 사례에 따라 Action의 동작을 정의할 때 여러 옵션을 선택할 수 있습니다. 폴더 리소스 자체와 상호 작용하려면 폴더 ID를 사용하여 Frame.io API를 후속 호출하세요. 또는 해당 폴더에 포함된 에셋에 대해 추가 처리를 수행하기 위해 해당 폴더의 하위 항목을 가져올 수도 있습니다. 버전 스택에서 Action이 실행되면 페이로드에 ‘Head Asset’의 ID가 포함됩니다. 이는 스택의 맨 위에 있는 파일이자 Frame.io UI에 표시되는 파일입니다.

마이그레이션 가이드에서 Frame.io 이전 API와 V4의 차이점에 대해 자세히 알아볼 수 있습니다.

사용자 지정 작업에는 다음이 필요합니다.

사용자 지정 작업 구성

사용자가 사용자 지정 작업을 트리거하면 Frame.io는 제공된 URL로 페이로드를 보냅니다. 수신 애플리케이션은 HTTP 상태 코드로 응답하여 수신을 확인하거나, Frame.io에 추가 UI를 렌더링하는 사용자 지정 콜백으로 응답할 수 있습니다.

다중 에셋 구성

다중 에셋 지원은 구성을 기반으로 하며, 웹의 Action 구성 모달에서 명시적으로 활성화해야 합니다. 이는 새 Action을 생성하거나 기존 Action을 업데이트할 때 수행할 수 있습니다. 

다중 에셋 지원이 활성화되면 페이로드 형식이 즉시 전환됩니다. 이전 페이로드와 다중 에셋 지원 페이로드는 상호 배타적입니다.

Frame.io에서 전송되는 페이로드

사용자가 사용자 지정 작업을 클릭하면 URL 필드에 설정한 URL로 페이로드가 전송됩니다. 이 페이로드를 사용하여 다음을 식별하세요.

1
  POST /your/url
2
  {
3
    "account_id": "1a94720e-f7f5-4c41-ab62-d11eebe3d504",
4
    "action_id": "0aeb9feb-f8eb-4100-a8c2-b39b66d354ab",
5
    "data": {
6
        "description": "Pretty cool video.",
7
        "title": "Hey there!"
8
    },
9
    "interaction_id": "985559de-865a-40e5-a687-2bbed4497eaa",
10
    "project": {
11
        "id": "3e34e7cb-5c21-49f5-8ca9-a1419584c2ea"
12
    },
13
    "resources": [
14
        {
15
            "id": "fe41c5a8-1b8d-417d-a7df-0b88bc19b476",
16
            "type": "file"
17
        },
18
        {
19
            "id": "fe81fb2b-1316-4a76-9cf6-0630f474fc39",
20
            "type": "file"
21
        }
22
    ],
23
    "type": "some.event",
24
    "user": {
25
        "id": "68093c1c-4b05-41ce-a3c9-e64d195b1935"
26
    },
27
    "workspace": {
28
        "id": "629086c0-f6aa-4d63-a284-f39bcd415b9f"
29
    }
30
  }

1
  POST /your/url
2
  {
3
      "account_id": "1a94720e-f7f5-4c41-ab62-d11eebe3d504",
4
      "action_id": "0e38b93a-9f10-4bc7-90bc-bd07a16e510a",
5
      "data": {
6
          "description": "Wow look at this.",
7
          "title": "Hey there!!"
8
      },
9
      "interaction_id": "dff6d369-7150-41f9-8e6f-4f0895f6b416",
10
      "project": {
11
          "id": "3e34e7cb-5c21-49f5-8ca9-a1419584c2ea"
12
      },
13
      "resource": {
14
          "id": "fe81fb2b-1316-4a76-9cf6-0630f474fc39",
15
          "type": "file"
16
      },
17
      "type": "some.event",
18
      "user": {
19
          "id": "68093c1c-4b05-41ce-a3c9-e64d195b1935"
20
      },
21
      "workspace": {
22
          "id": "629086c0-f6aa-4d63-a284-f39bcd415b9f"
23
      }
24
  }                                  

이전 페이로드에서 마이그레이션

상호 작용, 재시도, 시간 초과

interaction_id는 시간이 지남에 따라 진행되는 상호 작용을 추적하는 고유 식별자입니다. 사용자에게 응답할 필요가 없는 경우 200 상태 코드를 반환하면 완료됩니다. 선택 사항이지만, 성공 메시지나 오류 알림과 같은 작업 결과에 대한 정보를 포함하는 것이 좋습니다. 사용자 지정 작업은 메시지 콜백을 지원합니다.

메시지 콜백 만들기

웹훅 이벤트에 대한 HTTP 응답에서 Frame.io UI의 시작 사용자에게 반환될 메시지를 설명하는 JSON 오브젝트를 반환할 수 있습니다.

1
{
2
  "title": "Success!",
3
  "description": "The thing worked! Nice."
4
}

메시지를 사용하면 Frame.io UI에서 사용자에게 직접 피드백을 제공할 수 있습니다. 사용자로부터 추가 정보를 수집해야 하는 경우 대신 양식 콜백을 사용하세요.

양식 콜백 만들기

프로세스를 시작하기 전에 추가 정보가 필요하다고 가정해 보겠습니다. 예를 들어 추가 세부 정보가 필요한 시스템에 콘텐츠를 업로드할 수 있습니다. 응답에서 양식을 설명할 수 있으며, 사용자는 이 양식을 작성하여 다시 제출하게 됩니다. 예를 들면 다음과 같습니다.

1
{
2
  "title": "Need some more info!",
3
  "description": "Getting ready to submit this file!",
4
  "fields": [
5
    {
6
      "type": "text",
7
      "label": "Title",
8
      "name": "title",
9
      "value": "MyVideo.mp4"
10
    },
11
    {
12
      "type": "select",
13
      "label": "Captions",
14
      "name": "captions",
15
      "options": [
16
        {
17
          "name": "Off",
18
          "value": "off"
19
        },
20
        {
21
          "name": "On",
22
          "value": "on"
23
        }
24
      ]
25
    }
26
  ]
27
}

사용자가 양식을 제출하면 초기 POST와 동일한 URL에서 이벤트를 받게 됩니다.

1
POST /your/url
2
{
3
  "type": "your-specified-event-name",
4
  "interaction_id": "the-same-id-as-before",
5
  "action_id": "unique-id-for-this-custom-action",
6
  "data":{
7
    "title": "MyVideo.mp4",
8
    "captions": "off"
9
  }
10
}

양식에 추가된 모든 사용자 지정 필드는 Frame.io에서 보낸 JSON 페이로드의 data 섹션에 나타납니다. interaction_id를 사용하여 초기 요청과 이 새로운 양식 데이터를 매핑하세요. 메시지로 응답하거나 다른 양식을 연결할 수 있습니다. Action, 양식, 메시지를 연결하여 외부 시스템의 비즈니스 로직을 사용해 Frame.io에서 다단계 워크플로를 효과적으로 프로그래밍할 수 있습니다.

양식 세부 정보

메시지와 마찬가지로 양식은 양식 맨 윗부분에 렌더링되는 title 및 description 특성을 지원합니다. 그 외에도 각 양식 필드에는 다음의 기본 특성이 허용됩니다.

지원되는 필드 유형

텍스트 필드

추가 매개변수가 없는 간단한 텍스트 필드입니다.

1
{  
2
  "type": "text",
3
  "label": "Title",
4
  "name": "title",
5
  "value": "MyVideo.mp4"
6
}

텍스트 영역

추가 매개변수가 없는 간단한 텍스트 영역입니다.

1
{  
2
  "type": "textarea",
3
  "label": "Description",
4
  "name": "description",
5
  "value": "This video is really, really popular."
6
}

선택 목록

사용자가 선택할 수 있는 선택 목록을 정의합니다. options 목록이 포함되어야 하며, 각 멤버에는 사람이 읽을 수 있는 name과 기계가 파싱할 수 있는 value가 포함되어야 합니다.

1
{
2
  "type": "select",
3
  "label": "Captions",
4
  "name": "captions",
5
  "value": "off",
6
  "options": [
7
       {
8
         "name": "Off",
9
         "value": "off"
10
       },
11
       {
12
         "name": "On",
13
         "value": "on"
14
      }
15
   ]
16
}

확인란

추가 매개변수가 없는 간단한 체크박스입니다.

1
{ 
2
   "type": "boolean", 
3
   "name": "enabled", 
4
   "label": "Enabled", 
5
   "value": "false"
6
}

링크

추가 매개변수가 없는 간단한 링크입니다.

1
{
2
  "type": "link",
3
  "name": "videoLink",
4
  "label": "Video Link",
5
  "value": "https://www.youtube.com/watch?v=XtX1zv9CEVc"
6
}

Frame.io 권한 모델

사용자 지정 작업에는 특별한 권한 모델이 있습니다. 계정에 존재하는 특정 사용자가 아니라 Workspace에 속합니다. 이는 다음을 의미합니다.

보안 및 검증

기본적으로 모든 사용자 지정 작업에는 생성 시 만들어지는 서명 키가 있습니다. 이는 구성할 수 없습니다. 이 키를 사용하여 요청이 Frame.io에서 보낸 것인지 확인할 수 있습니다. POST 요청에는 다음이 포함됩니다.

서명 검증

1
import hmac
2
import hashlib
3
4
def verify_signature(curr_time, req_time, signature, body, secret):
5
    """
6
    Verify webhook/custom action signature
7
    :Args:
8
        curr_time (float): Current epoch time
9
        req_time (float): Request epoch time
10
        signature (str): Signature provided by the frame.io API for the given request
11
        body (str): Custom Action body from the received POST
12
        secret (str): The secret for this Custom Action that you saved when you first created it
13
    """
14
    if int(curr_time) - int(req_time) < 500:
15
        message = 'v0:{}:{}'.format(req_time, body)
16
        calculated_signature = 'v0={}'.format(hmac.new(
17
            bytes(secret, 'latin-1'),
18
            msg=bytes(message, 'latin-1'),
19
            digestmod=hashlib.sha256).hexdigest())
20
        if calculated_signature == signature:
21
            return True
22
    return False

피드백

개발자와 최종 사용자가 Frame.io V4에서 Actions를 어떻게 활용하고자 하는지 의견을 듣고 싶습니다. 우선순위를 정하는 데 도움이 되도록 질문, 아이디어, 사용 사례를 저희에 문의해 주세요.