カスタムアクション

Frame.ioアクションは、ダウンロード、名前変更、項目の複製などの一般的なメディア操作への素早いアクセスを提供し、Frame.ioのユーザーインターフェイス内で直接、サードパーティツールやサービスとの統合も可能にします。

アクションについて

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

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

カスタムアクションを使用して、プログラム可能なUIコンポーネントとしてFrame.ioに直接統合を構築します。これにより、アプリ内でユーザーがトリガーできるワークフローが可能になり、webhookと同じ基盤イベントルーティングを活用します。Frame.ioに別のフォームまたは基本的な応答として戻ってくる、ユーザートリガー型の単一または複数ステップフォームを作成できます。そして、ユーザーがアセット上のカスタムアクションをクリックすると、Frame.ioは指定したURLにペイロードを送信します。受信アプリケーションは、受信確認のため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を受信しますが、ユースケースに応じて、アクションの動作を定義する際に複数のオプションがあります。フォルダーリソース自体とやり取りしたい場合は、フォルダーIDを使用してFrame.io APIへの後続の呼び出しを行ってください。または、そのフォルダーの子を取得して、内部のアセットでさらなる処理を実行することもできます。バージョンスタックでアクションが実行されると、ペイロードにはスタックの最上位ファイルである「ヘッドアセット」のIDが含まれ、これがFrame.io UIに表示される内容です。

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

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

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

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

マルチアセット設定

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

マルチアセットサポートが有効になると、ペイロード形式は即座に切り替わります。レガシーとマルチアセットサポートのペイロードは相互排他的です。

Frame.ioからのペイロード

ユーザーがカスタムアクションをクリックすると、URLフィールドで設定したURLにペイロードが送信されます。このペイロードを使用して以下を識別します：

  POST /your/url
  {
    "account_id": "1a94720e-f7f5-4c41-ab62-d11eebe3d504",
    "action_id": "0aeb9feb-f8eb-4100-a8c2-b39b66d354ab",
    "data": {
        "description": "Pretty cool video.",
        "title": "Hey there!"
    },
    "interaction_id": "985559de-865a-40e5-a687-2bbed4497eaa",
    "project": {
        "id": "3e34e7cb-5c21-49f5-8ca9-a1419584c2ea"
    },
    "resources": [
        {
            "id": "fe41c5a8-1b8d-417d-a7df-0b88bc19b476",
            "type": "file"
        },
        {
            "id": "fe81fb2b-1316-4a76-9cf6-0630f474fc39",
            "type": "file"
        }
    ],
    "type": "some.event",
    "user": {
        "id": "68093c1c-4b05-41ce-a3c9-e64d195b1935"
    },
    "workspace": {
        "id": "629086c0-f6aa-4d63-a284-f39bcd415b9f"
    }
  }

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

レガシーペイロードからの移行

インタラクション、再試行、タイムアウト

interaction_idは、時間の経過とともに進化するインタラクションをトラッキングするための一意の識別子です。ユーザーに応答する必要がない場合は、200ステータスコードを返せば完了です。オプションですが、成功メッセージやエラーアラートなど、アクションの結果に関する情報を含めることをお勧めします。カスタムアクションはメッセージコールバックをサポートしています。

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

WebhookイベントへのHTTP応答で、Frame.io UIで開始ユーザーに返されるメッセージを説明するJSONオブジェクトを返すことができます。

{
  "title": "Success!",
  "description": "The thing worked! Nice."
}

メッセージを使用すると、Frame.io UIでユーザーに直接フィードバックを提供できます。ユーザーから追加情報を収集する必要がある場合は、代わりにフォームコールバックを使用してください。

フォームコールバックを作成

プロセスを開始する前に、さらに情報が必要だとしましょう。例えば、追加の詳細が必要なシステムにコンテンツをアップロードする場合があります。応答でフォームを記述でき、ユーザーがそれを記入して送信すると、あなたに返されます。以下に例を示します：

{
  "title": "Need some more info!",
  "description": "Getting ready to submit this file!",
  "fields": [
    {
      "type": "text",
      "label": "Title",
      "name": "title",
      "value": "MyVideo.mp4"
    },
    {
      "type": "select",
      "label": "Captions",
      "name": "captions",
      "options": [
        {
          "name": "Off",
          "value": "off"
        },
        {
          "name": "On",
          "value": "on"
        }
      ]
    }
  ]
}

ユーザーがフォームを送信すると、最初のPOSTと同じURLでイベントを受信します：

POST /your/url
{
  "type": "your-specified-event-name",
  "interaction_id": "the-same-id-as-before",
  "action_id": "unique-id-for-this-custom-action",
  "data":{
    "title": "MyVideo.mp4",
    "captions": "off"
  }
}

フォームに追加されたすべてのカスタムフィールドは、Frame.ioから送信されるJSONペイロードのdataセクションに表示されます。interaction_idを使用して、初期リクエストとこの新しいフォームデータをマッピングします。メッセージで応答するか、別のフォームをチェーンできます。アクション、フォーム、メッセージをチェーンすることで、外部システムからのビジネスロジックを使用して、Frame.ioで多段階のワークフローを効果的にプログラムできます。

フォームの詳細

メッセージと同様に、フォームもフォームの上部にレンダリングされるtitleとdescription属性をサポートしています。それ以外に、各フォームフィールドは以下の基本属性を受け入れます：

サポートされているフィールドタイプ

テキストフィールド

追加パラメーターのないシンプルなテキストフィールド。

{  
  "type": "text",
  "label": "Title",
  "name": "title",
  "value": "MyVideo.mp4"
}

テキストエリア

追加パラメーターのないシンプルなテキストエリア。

{  
  "type": "textarea",
  "label": "Description",
  "name": "description",
  "value": "This video is really, really popular."
}

選択リスト

ユーザーが選択できるピックリストを定義します。optionsリストを含める必要があり、各メンバーには人間が読めるnameと機械解析可能なvalueを含める必要があります。

{
  "type": "select",
  "label": "Captions",
  "name": "captions",
  "value": "off",
  "options": [
       {
         "name": "Off",
         "value": "off"
       },
       {
         "name": "On",
         "value": "on"
      }
   ]
}

チェックボックス

追加パラメーターのないシンプルなチェックボックス。

{ 
   "type": "boolean", 
   "name": "enabled", 
   "label": "Enabled", 
   "value": "false"
}

リンク

追加パラメーターのないシンプルなリンク。

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

Frame.io権限モデル

カスタムアクションには特別な権限モデルがあります。これらはアカウント上の特定のユーザーではなく、Workspaceに属します。つまり：

セキュリティと検証

デフォルトで、すべてのカスタムアクションは作成時に生成される署名キーを持ちます。これは設定できません。このキーは、リクエストがFrame.ioから発信されたことを検証するために使用できます。POSTリクエストには以下が含まれます：

署名の検証

import hmac
import hashlib
def verify_signature(curr_time, req_time, signature, body, secret):
    """
    Verify webhook/custom action signature
    :Args:
        curr_time (float): Current epoch time
        req_time (float): Request epoch time
        signature (str): Signature provided by the frame.io API for the given request
        body (str): Custom Action body from the received POST
        secret (str): The secret for this Custom Action that you saved when you first created it
    """
    if int(curr_time) - int(req_time) < 500:
        message = 'v0:{}:{}'.format(req_time, body)
        calculated_signature = 'v0={}'.format(hmac.new(
            bytes(secret, 'latin-1'),
            msg=bytes(message, 'latin-1'),
            digestmod=hashlib.sha256).hexdigest())
        if calculated_signature == signature:
            return True
    return False

フィードバック

Frame.io V4でアクションを使用したい方法について、デベロッパーやエンドユーザーからご意見をお聞かせください。優先順位を決定するために、質問、アイデア、ユースケースをお聞かせください。