カスタムアクション (Beta)

Frame.io アクションを使用すると、アイテムのダウンロード、名前の変更、複製などの一般的なメディア操作に素早くアクセスできます。また、サードパーティのツールやサービスとの統合を Frame.io のユーザーインターフェイス内に直接表示することもできます。

アクションについて

カスタムアクション (Beta) の導入により、開発者は Frame.io V4 で独自のアクションを設定および管理できます。カスタムアクションは Webhook と同じ基盤イベントシステムを活用しており、Frame.io アカウントのユーザーにとって最も重要なツールに開発者が自分のアセットを接続するための代替メカニズムです。

アクションは、アクションが有効になっている Frame.io ワークスペースのメンバーであるすべてのユーザーが実行できます。アクションを実行すると、Frame.io は指定した URL にペイロードを送信します。受信アプリケーションは、受信を確認するための HTTP ステータスコードで応答したり、Frame.io UI に追加のフォームフィールドを表示するためのカスタムコールバックで応答したりします。受信アプリケーションは、独自のホスト型プログラムやサービス、さらには Workfront Fusion や Zapier などのローコード / ノーコード IPaaS ツールでも構いません。

カスタムアクション (Beta) を使用して、統合を Frame.io にプログラミング可能な UI コンポーネントとして直接構築します。これにより、Webhook と同じ、基盤となるイベントルーティングを活用して、ユーザーがアプリ内でトリガーできるワークフローが実現します。ユーザーがトリガーするシングルまたはマルチステップフォームを作成し、別のフォームまたは基本レスポンスとして Frame.io に戻るようにできます。ユーザーがアセットでカスタムアクションをクリックすると、指定された URL に Frame.io がペイロードを送信します。受信アプリケーションは、受信確認として HTTP ステータスコードで応答したり、Frame.io で追加の UI をレンダリングできるカスタムコールバックで応答したりします。

V4 でのアクションの改善

レガシーバージョンのユーザーから学んだことを活かして、Frame.io V4 のアクション機能セットにいくつかの機能強化を追加しました。

移行されたアクション

Frame.io のレガシーバージョンで以前に作成されたカスタムアクションを含む Frame.io V4 アカウントに移行する際には、注意が必要な点がいくつかあります。

アクションステータス

アカウントを Frame.io V4 に移行すると、以前のバージョンで作成されたすべてのカスタムアクションのステータスが「null」になり、自動的に無効になります。未更新のアクションは失敗することから、ユーザーは有効化する前にまずはアクションを更新してから V4 API を使用する機会が得られます。このステータスのアクションを識別するには、アクション設定ページにアクセスし、「ステータス」列を参照するか、API を使用している場合は is_active フィールドを確認します。

アクション可能なリソース：ファイル、フォルダー、バージョンスタック

Frame.io V4 API ではアセットタイプが個別のリソースとして分離されているので、アクションのペイロードで受信したリソース ID を解釈する際に考慮すべき動作がある場合があります。ID はアクションが実行された特定のファイルを反映するため、個々のファイルの動作に複雑なところはありません。フォルダーについても同様に、アクションが実行されたフォルダーの ID が表示されます。ただし、ユースケースによっては、アクションの動作を定義する際に複数のオプションがあります。フォルダーリソース自体とやり取りしたい場合は、以降の Frame.io API を呼び出しにフォルダー ID を使用できます。または、そのフォルダーの子を取得し、子の中のアセットにさらなる処理を実行することもできます。バージョンスタックに対してアクションが実行されると、ペイロードには「ヘッドアセット」の ID が含まれます。ヘッドアセットはスタック内で最上位のファイルで、Frame.io UI に表示されます。

Frame.io レガシー API と V4 の違いについて詳しくは、移行ガイドを参照してください。

カスタムアクションには以下が必要です。

カスタムアクションの設定

ユーザーがカスタムアクションをトリガーすると、指定された URL に Frame.io がペイロードを送信します。受信アプリケーションは、受信確認として HTTP ステータスコードで応答したり、Frame.io で追加の UI をレンダリングできるカスタムコールバックで応答したりできます。

マルチアセット設定

マルチアセットのサポートは設定主導型であり、web でアクションの設定モーダルから明示的に有効にする必要があります。これは、新しいアクションの作成時または既存のアクションの更新時に実行できます。

マルチアセットサポートが有効な場合、ペイロード形式はすぐに切り替わります。従来のペイロードとマルチアセットでサポートされているペイロードは相互に排他的です。

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 を返して完了です。オプションですが、成功メッセージやエラーアラートなど、アクションの結果に関する情報を含めることをお勧めします。カスタムアクションは、メッセージコールバックをサポートしています。

メッセージコールバックの作成

Webhook イベントへの 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 を使用して、最初のリクエストとこの新しいフォームデータをマッピングします。メッセージで応答したり、別のフォームを連結したりできます。アクション、フォーム、メッセージをつなぐことで、外部システムのビジネスロジックを使用して、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 権限モデル

カスタムアクションには特別な権限モデルがあり、これらはアカウントに存在する特定のユーザーではなく、ワークスペースに属します。これは以下を意味します。

セキュリティと検証

デフォルトで、すべてのカスタムアクションには、作成時に生成された署名鍵があります。これは設定できません。このキーを使用して、リクエストが 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 のアクションの使用方法について、開発者やエンドユーザーの皆様のご意見を伺いたいと考えております。ご質問、アイデア、ユースケースをお知らせください。当社の優先順位付けに活用させていただきます。