> This page is for プラットフォーム, version V4 (default).
> For other versions, use one of these documentation indexes:
> - V4 (default): https://next.developer.frame.io/platform/v4/llms.txt
> - V4 Experimental: https://next.developer.frame.io/platform/v4-experimental/llms.txt
> - レガシー: https://next.developer.frame.io/platform/v2/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://next.developer.frame.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://next.developer.frame.io/_mcp/server.

# カスタムアクション

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

## アクションについて

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

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

カスタムアクションを使用して、プログラム可能なUIコンポーネントとして[Frame.io](https://next.frame.io/)に直接統合を構築します。これにより、アプリ内でユーザーがトリガーできるワークフローが可能になり、webhookと同じ基盤イベントルーティングを活用します。Frame.ioに別のフォームまたは基本的な応答として戻ってくる、ユーザートリガー型の単一または複数ステップフォームを作成できます。そして、ユーザーがアセット上のカスタムアクションをクリックすると、Frame.ioは指定したURLにペイロードを送信します。受信アプリケーションは、受信確認のためHTTPステータスコードで応答するか、Frame.ioに追加UIをレンダリングできるカスタムコールバックで応答します。

## V4でのアクション改良

レガシーバージョンのユーザーからの学びを活用し、Frame.io V4のアクション機能セットに多数の拡張を含めました：

#### 新しいフィールドタイプ

以前はテキストフィールドと単一選択フィールドに制限されていましたが、現在は複数選択、テキストエリア（より大きなテキストボックス用）、およびブーリアンフィールド（ラジオボタン用）もサポートしています。

#### クリック可能なリンク

テキストフィールドでは、ユーザーがURLを簡単にコピー・ペーストできません。代わりに新しいリンクフィールドを使用して、簡単なワンクリックでコピー体験を実現してください。

#### 動的モーダル

返されるデータの量に応じて、アクションのモーダルが動的にサイズ変更され、フォーム内の情報に最適にフィットし、必要に応じてスクロール可能なモーダルも含まれます。

#### 複数アセットアクション

アクションを設定して、一度のリクエストで最大100個のアセットを対象にできます。

\


NEW

#### 混合アセットタイプ

1つのアセットタイプに制限されません。アクションは、ファイル、フォルダー、バージョンスタックの組み合わせ全体でトリガーできます。

#### [アプリ内フィードバックフォーム](https://next.frame.io/settings/actions)

アクションの使用方法について、デベロッパーとエンドユーザーの両方からお聞きしたいので、webの設定ページにフィードバックフォームを表示しています。

## 移行されたアクション

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の違いについて詳しくは、[移行ガイド](/docs/resources/migration)をご覧ください。

> **Info**
>
> APIで[カスタムアクション](/api-reference/custom-actions/actions-show)を設定します。

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

| フィールド名  | 説明                                                     |
| ------- | ------------------------------------------------------ |
| 名前      | カスタムアクション用に選択する名前。Frame.ioで利用可能なカスタムアクションのメニューに表示されます。 |
| 説明      | アクションの動作を参照用に説明します（説明はFrame.io webアプリには表示されません）。       |
| Event   | 標準webhook イベントと独自のイベントを区別するのに役立つ内部イベントキー。              |
| URL     | イベントの配信先。                                              |
| ワークスペース | カスタムアクションを使用するWorkspace。                               |

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

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

> **Warning**
>
> Workspaceのカスタムアクションを作成するには、アカウント管理者権限が必要です。アクセス権がない場合は、管理者に権限の変更を依頼してください。

### マルチアセット設定

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

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

## Frame.ioからのペイロード

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

#### アクションコンテキスト

* クリックされたカスタムアクション

* クリックされたリソース

* アクションを実行したユーザー

* トリガーされたイベントタイプ

#### 組織コンテキスト

* カスタムアクションに関連付けられたアカウント

* カスタムアクションに関連付けられたWorkspace

* リソースを含むプロジェクト

#### ペイロード - 単一または複数アセットのサポート

カスタムアクションは、もともと1つのアセットを含む`resource`オブジェクトを使用して、リクエストごとに1つのアセットのみを受け入れていました。複数アセットのサポートが有効になると、ペイロードは1つまたは複数のアセットの`resources`リストを使用します（1回のリクエストで最大100個のアセット）。

```json
  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"
    }
  }
```

#### レガシーペイロード - 単一アセットサポートのみ

```json
  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"
      }
  }                                  
```

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

> **レガシーペイロードの廃止予定**
>
> レガシーペイロードは廃止が予定されており、ユーザーは新しいペイロードを処理するようにサービスを移行することを強く推奨しています。
>
> 設定フラグを有効にしてペイロード処理を更新することで、アクションは複数アセットペイロードをサポートするようにシームレスに移行できます。
>
> 1. 単一の`resource`オブジェクトの使用を`resources`リストに置き換える 2。`resources`リストを反復するようにコードを更新する
>
> 2. アクション設定で複数アセットフラグを有効にする

| フィールド名           | 説明                                                                                                                 |
| ---------------- | ------------------------------------------------------------------------------------------------------------------ |
| `account_id`     | アクションの一意のアカウントID。                                                                                                  |
| `action_id`      | アクションの一意のID。                                                                                                       |
| `interaction_id` | Frame.ioによって生成される一意の識別子で、連鎖したメッセージやフォームコールバックなど、複数のリクエストにわたってトランザクションを追跡するために使用されます。アクションのすべてのシーケンスを通じて同じまま維持されます。 |
| `project_id`     | アクションの一意のプロジェクトID。                                                                                                 |
| `resource.id`    | アクションをトリガーしたリソースのID。                                                                                               |
| `resource.type`  | アクションをトリガーしたリソースのタイプ。                                                                                              |
| `type`           | アクションを設定する際に`event`フィールドに指定された名前。                                                                                  |
| `user.id`        | アクションをトリガーしたユーザーのID。                                                                                               |
| `workspace.id`   | アクションを使用しているWorkspaceのID。                                                                                          |
| `data`           | ユーザーが選択したフォームフィールド名と値を含むキーと値のペア。どのような選択がされたかを知るために、アプリケーションがこれを受信します。                                              |

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

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

> **Note**
>
> Frame.ioは10秒未満での応答を期待し、成功した応答を待つ間に最大5回まで再試行を試みます。理想的には応答は即座で、非同期アクションはカスタムアクションを介したトリガー後に発生します。

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

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

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

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

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

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

```json
{
  "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でイベントを受信します：

```json
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** -- Frame.io UIに期待するデータのタイプと、どのコンポーネントをレンダリングするかを伝えます。\* **label** -- フィールドの上にヘッダーとしてUIに表示されます。

#### フィールドデータ

* **name** -- 後続のペイロードでフィールドが識別されるキー。\* **value** -- フィールドに事前入力する値。

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

### テキストフィールド

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

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

### テキストエリア

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

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

### 選択リスト

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

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

### チェックボックス

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

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

### リンク

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

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

## Frame.io権限モデル

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

#### 作成と管理

* すべての管理者がWorkspace上でカスタムアクションを作成できます。

* すべての管理者がチーム上に存在するカスタムアクションを変更または削除できます。

#### ライブ更新

* 変更されると、すべてのユーザーは変更の結果を即座に確認できます。

## セキュリティと検証

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

| 名前                            | 説明                   |
| ----------------------------- | -------------------- |
| `X-Frameio-Request-Timestamp` | カスタムアクションがトリガーされた時刻。 |
| `X-Frameio-Signature`         | 計算された署名。             |

#### タイムスタンプ検証

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

#### 署名検証

**署名**は、カスタムアクションが最初に作成されたときに提供される署名キーを使用したHMAC SHA-256ハッシュです。

### 署名の検証

#### 署名の抽出

HTTPヘッダーから署名を抽出します。

#### 署名するメッセージを作成

バージョン、配信時間、リクエスト本文を組み合わせて署名するメッセージを作成します`v0:timestamp:body`。

#### HMAC SHA256を計算

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

#### 署名を比較

計算した署名と提供された署名を比較してください！

> **Note**
>
> 提供された署名には`v0=`の接頭辞が付いています。現在Frame.ioではリクエストの署名にはこのバージョンのみを使用しています。計算した署名にこの接頭辞を追加する必要があります。

**`Python`**

```python title="Python"
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でアクションを使用したい方法について、デベロッパーやエンドユーザーからご意見をお聞かせください。優先順位を決定するために、質問、アイデア、ユースケースを[お聞かせください](https://forum.frame.io/)。