カスタムアクションの概要

• JavaScript
• Python

カスタムアクションは、統合をプログラミング可能な UI コンポーネントとして Frame.io に直接構築する方法です。これにより、Webhook と同じ、基盤となるイベントルーティングを活用して、ユーザーがアプリ内でトリガーできる多彩なワークフロークラスが実現します。現在、カスタムアクションはアセットに対して使用でき、次の画像に示すように、任意のアセットで使用可能なコンテキスト／右クリックドロップダウンメニューに表示されます。

アセットは、S3 内のファイルとその Frame.io でのコンテキストの包括的な表現です。これには、トランスコード、ユーザー／チーム／プロジェクトのコンテキスト、メタデータが含まれます。ユーザーがアセットでカスタムアクションをクリックすると、指定された URL に Frame.io がペイロードを送信します。受信アプリケーションは、受信確認として HTTP ステータスコードで応答したり、Frame.io で追加の UI をレンダリングできるカスタムコールバックで応答したりできます。

カスタムアクションのセットアップ

カスタムアクションは、developer.frame.io の「カスタムアクション」エリアで設定できます。アクションには以下が必要です。

クリック - Frame.io から返されるペイロードの内容

ユーザーがカスタムアクションをクリックすると、「URL」フィールドに指定した URL にペイロードが送信されます。

1
POST /your/url
2
{
3
  "action_id": "2444cccc-7777-4a11-8ddd-05aa45bb956b",
4
  "interaction_id": "aafa3qq2-c1f6-4111-92b2-4aa64277c33f",
5
  "project": {
6
    "id": "a7d6a74b-d45d-4019-9069-24651e0b9f64"
7
  },
8
  "resource": {
9
    "id": "9q2e5555-3a22-44dd-888a-abbb72c3333b",
10
    "type": "asset"
11
  },
12
  "team": {
13
    "id": "54353cd2-c6ee-4aa1-954a-ce9e19602aa9"
14
  },
15
  "type": "my.action",
16
  "user": {
17
    "id": "fb57eee0-79f2-4bc7-9b70-99fbc175175c"
18
  }
19
}

このペイロードを使用して、以下を識別できます。

• クリックされたカスタムアクション
• クリックされたリソース
• アクションを実行したユーザー

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

Webhook イベントへの HTTP レスポンスでは、Frame.io UI で開始ユーザーに返されるメッセージを記述する JSON オブジェクトを返すことができます。メッセージを作成し、それがどのように表示されるかを確認したい場合は、カスタムアクションビルダーをお試しください。これを使用すると、メッセージのコールバックやフォームを設定し、それが Frame.io web アプリでどのように表示されるかを確認できます。

オブジェクトの例を次に示します。

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

これにより、次のようなアラートがユーザーに表示されます。

メッセージは、アクションライフサイクルのループを閉じる簡単な方法であり、アクションを起こしたユーザーに対し、コンテキストの切り替えを求めることなく、可変コンテキストを提供します。

多くのユースケースはこれで十分ですが、初期ペイロードとそれに続く Frame.io API 呼び出しでは、受信アプリケーションに十分なコンテキストが提供されない場合があります。このようなシナリオ向けに、フォームコールバックもサポートされています。

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

プロセスを開始する前に、さらに情報が必要だとします。例えば、追加の詳細や設定が必要なコンテンツをシステムにアップロードしている場合について考えてみましょう。レスポンスでフォームについて「説明」し、それをユーザーに実際に表示できます。それに対し、ユーザーが入力します。そして、すぐに送り返されます。

アクションを開始したユーザーが入力して送信できるフォームを 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 属性をサポートしています。このほか、各フォームフィールドは次の基本属性を受け付けます。

• type — Frame.io UI に、予期するデータ型、コンポーネント、レンダリングを指示します。
• label — UI にフィールドの上のヘッダーとして表示されます。
• name — 後続のペイロードでフィールドの識別に使用されるキーです。
• value — フィールドに事前入力する値です。

サポートされているフィールドの種類

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

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
}

カスタムアクションと Frame.io 権限モデル

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

• 管理者またはチームマネージャーであれば、チームにカスタムアクションを作成できる。
• 管理者またはチームマネージャーであれば、チームに存在するカスタムアクションを変更または削除できる。 変更すると、変更の結果がすべてのユーザーにただちに示されます。

セキュリティ

デフォルトで、すべてのカスタムアクションには、作成時に生成された署名鍵があります。これは設定できません。このキーを使用して、リクエストが Frame.io から発生していることを確認できます。

検証

POST リクエストには以下が含まれます。

タイムスタンプは、リクエストが Frame.io のネットワークを出る際に署名された時刻です。これは、リプレイ攻撃を防ぐために使用できます。この時刻が現地時間から 5 分以内であることを確認することをお勧めします。

署名は、カスタムアクションの初回作成時に提供された署名鍵を使用する HMAC SHA-256 ハッシュです。

署名の検証

1. HTTP ヘッダーから署名を抽出します。
2. バージョン、配信時刻、リクエスト本文を組み合わせて、署名するメッセージを作成します。

• v0:timestamp:body

3. 署名シークレットを使用して、HMAC SHA256 署名を計算します。

• 注意：指定された署名には、接頭辞 v0= が付きます。現在、Frame.io で署名リクエスト用に用意されているのはこれだけです。計算された署名には、この接頭辞を追加する必要があります。

4. 比較します。

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