方法：チャネルの管理

エコシステム内に、インターネットに接続できず、Frame.io と直接通信できないが、C2C 対応デバイスと通信できるデバイスがある場合、どうなるでしょうか？統合によっては、そのようなデバイスに代わってアクションを実行することが望ましい場合があります。例えば、マイクに代わってサウンドレコーダーがアップロードを実行したり、アタッチメントのボタンに代わってカメラがリアルタイムコメントを作成したりする場合です。

こうした要請は、デバイスのチャネルを理解することで実現できます。統合でサブデバイスを管理しない場合は、このガイドをスキップしてかまいません。

必要なもの

C2C の実装：セットアップガイドをまだ読んでいない場合は、目を通してから先へ進んでください。

デバイス認証および承認ガイドで受け取った access_token が必要です。

また、プライマリデバイスを介して Frame.io に接続できるサブデバイスのデバイスモデル ID のリストも必要です。

チャネルとは

チャネルについては、アーキテクチャ概要で簡単に説明しています。すべてのプロジェクトデバイスにはチャネルが少なくとも 1 個あります。デバイスとチャネルを概して同じものとして扱ってきましたが、ここではこの 2 つの概念を区別する必要があります。詳しく見ていきましょう。

プロジェクトデバイスは、Frame.io と直接通信できます。チャネルは、プロジェクトデバイスが通信するデータを収集します。ほとんどの場合、プロジェクトデバイスと最初のチャネルは同じものです。カメラについて考えてみましょう。概念的には、プロジェクトデバイスはカメラのネットワークカードを表しており、これがデータを直接 Frame.io に送信します。一方、チャネルはカメラの CMOS センサーを表しており、ネットワークカード（プロジェクトデバイス）を介して送信する動画データを収集します。

最も重要なのは、プロジェクトデバイスは OauthApp を介して Frame.io で認証されるのに対し、チャネルは認証されないことです。チャネルは親プロジェクトデバイスの認証を使用します。

このモデルでは、プロジェクトデバイスに複数のチャネルを持たせることができます。チャネルは、物理デバイスの一部であることもとそうでないこともあります。チャネルは、TCP/IP、Bluetooth、SDI などを介してプライマリデバイスと通信するハードウェアの一部です。プロジェクトデバイスは、このデータを Frame.io に送信するためのルーターとして機能します。チャネルからプロジェクトデバイスにデータをどのように供給するかは、インテグレーター次第です。

Frame.io にプロジェクトデバイスとして接続されたサウンドレコーダーを想像してみましょう。多数のマイクそれぞれが別個のチャネルとして接続されています。この場合、レコーダーはミックスファイルをプライマリチャネルで送信し、個々のマイクのトラックをサブデバイスのチャネルで送信します。チャネルをどのように使用し、それぞれが何を表すかは、インテグレーター次第です。チャネルは認証されておらず、デバイスによっていつでも追加および削除できます。

チャネルは個別に物理サブデバイスに属することが可能なので、他のハードウェアやソフトウェアの統合と同様、各チャネルはデバイスモデルに関連付けられます。これにより、Frame.io はホストデバイスとは別個の可能性のあるサブデバイスモデルを表示でき、統合で各サブデバイスの動作を個別に定義できます。特定の統合にチャネルとして追加できるデバイスモデルは、事前に定義しておく必要があります。

新しいチャネルを C2C デバイスに接続することを検討する理由はいくつかあります。

• チャネル + デバイスモデルに応じて、1 つの統合で複数の構成が可能です。例えば、アセットの固定フォルダー構造、トークン化されたフォルダーパス、ファイル拡張子による振り分けなどです。編集プロキシと Camera Raw でアップロードに異なるチャネルを使用する DIT ステーションを想像してみてください。
• Frame.io のユーザーにサブデバイスの可視性を提供します。
• チャネルにユーザー入力、具体的にはボタンを設定し、これにリアルタイムロギング機能を持たせることができます。

C2C API を使用してチャネルを管理する方法について、もう少し詳しく見ていきましょう。

チャネルのリスト

既存のチャネルのリストは、identity エンドポイントから channels フィールドで取得できます。レスポンスペイロードの "channels" フィールドを見てみましょう。

1
{
2
    "_type": "project_device",
3
    ...
4
    "channels": [
5
        {
6
            "_type": "project_device_channel",
7
            "actor_id": null,
8
            "asset_type": "video",
9
            "device_id": "98e9367a-b26b-4c60-8e64-da83dfd9540b",
10
            "external_index": 0,
11
            "id": "5919e9bc-7fc2-4629-97e5-852ce27cfa1a",
12
            "inserted_at": "2023-07-14T19:11:43.217565Z",
13
            "name": "Test Host Device",
14
            "project_device_id": "bf30fc66-f126-4336-bdfc-75d3e659b95a",
15
            "project_id": "1eb3587f-6bca-4e8d-a2f6-e7413d82c1ad",
16
            "real_time_logging_capable": false,
17
            "status": "online",
18
            "updated_at": "2023-07-14T19:11:43.217565Z"
19
        },
20
        {
21
            "_type": "project_device_channel",
22
            "actor_id": null,
23
            "asset_type": "video",
24
            "device_id": "057b33c4-9f92-4eeb-a3d5-2fd0f4932292",
25
            "external_index": 0,
26
            "id": "0b17e1e3-588c-4365-be51-5cf097c8f004",
27
            "inserted_at": "2023-07-14T19:11:43.217565Z",
28
            "name": "Test Client Device 01234",
29
            "project_device_id": "bf30fc66-f126-4336-bdfc-75d3e659b95a",
30
            "project_id": "1eb3587f-6bca-4e8d-a2f6-e7413d82c1ad",
31
            "real_time_logging_capable": false,
32
            "status": "offline",
33
            "updated_at": "2023-07-14T19:11:43.217565Z"
34
        }
35
    ],
36
    ...
37
    "device_id": "98e9367a-b26b-4c60-8e64-da83dfd9540b",
38
    ...
39
    "id": "bf30fc66-f126-4336-bdfc-75d3e659b95am"
40
}

最初のチャネルの device_id がプロジェクトデバイス全体の device_id と一致しています。

チャネルの接続

次のリクエストで新しいチャネルを接続できます。

$
curl -X POST https://api.frame.io/v2/devices/channels/connect \
>
    --header 'Authorization: Bearer [access_token]' \
>
    --header 'Content-Type: application/json' \
>
    --header 'x-client-version: 2.0.0' \
>
    --data-binary @- <<'__JSON__'{
>
            "client_id": [client_id],
>
            "device_model_id": [device_model_id]
>
        }
$
__JSON__
$
    | python -m json.tool

次のレスポンスが返されます。

1
{
2
   "_type": "project_device_channel",
3
   "actor_id": null,
4
   "asset_type": "video",
5
   "device_id": "057b33c4-9f92-4eeb-a3d5-2fd0f4932292",
6
   "external_index": 0,
7
   "id": "0b17e1e3-588c-4365-be51-5cf097c8f004",
8
   "inserted_at": "2023-07-14T19:11:43.217565Z",
9
   "name": "Test Client Device 01234",
10
   "project_device_id": "bf30fc66-f126-4336-bdfc-75d3e659b95a",
11
   "project_id": "1eb3587f-6bca-4e8d-a2f6-e7413d82c1ad",
12
   "real_time_logging_capable": true,
13
   "status": "offline",
14
   "updated_at": "2023-07-14T19:11:43.217565Z"
15
}

このレスポンスは、identity エンドポイントからの channels フィールドをミラーリングします。

client_id は一意性を規定することから、シリアル番号などの安定した値であることが必要です。 device_model_id は、このチャネルが表すハードウェアデバイスの実機タイプ（マイクの特定のモデルなど）を Frame.io に通知します。これらはパートナーマネージャーによってセットアップ済みのはずです。

チャネルが宣言済みだった場合は、エラータイトル Already Exists の 409 エラーが返されます。

以前接続されていたが切断されたものと同じ識別子を持つチャネルを作成すると、そのチャネルの以前のすべてのユーザー設定が復元されます。

チャネルの切断

チャネルは Frame.io で定義された ID を使用して切断されます。client_id または device_model_id ではありません。

$
curl -X POST https://api.frame.io/v2/devices/channels/:channel_id/disconnect \
>
    --header 'Authorization: Bearer [access_token]' \
>
    --header 'x-client-version: 2.0.0' \
>
    | python -m json.tool

空のペイロードを持つ 204 レスポンスが返されます。

存在しないチャネルを削除しようとすると、404 が返されます。親デバイスの最初のプライマリチャネルは切断できません。

すべてのサブデバイスチャネルの切断

次の呼び出しを使用すると、プロジェクトデバイスの現在のサブデバイスチャネルをすべて切断できます。

$
curl -X POST https://api.frame.io/v2/devices/channels/disconnect \
>
    --header 'Authorization: Bearer [access_token]' \
>
    --header 'x-client-version: 2.0.0' \
>
    | python -m json.tool

空のペイロードを持つ 204 レスポンスが返されます。この呼び出しは、プロジェクトデバイスにクライアントデバイスチャネルがなくても必ず成功します。

これで、identity エンドポイントを使用してすべてのチャネルをリストできるようになりました。この段階で残っているのは、ホストデバイスのプライマリチャネルのみです。

チャネル管理フロー

中途半端なタイミングでパワーサイクルが行われると、データ整合性の問題が生じる可能性があります。それを回避するため、プロジェクトデバイスのチャネル状態を内部的に管理することはお勧めしません。例：

• チャネル接続呼び出しの処理後だが、返された id をデータストアにコミットできるようになる前に、電源をオフにする
• デバイスの電源がオフの間に、サブデバイスがホストデバイスに接続される／ホストデバイスから接続解除される

代わりに、起動時にすべてのホストデバイスで真っ先に次の手順を実行することをお勧めします。

• バルクチャネル切断エンドポイントを呼び出し、既存のすべてのサブデバイスチャネルをクリアする
• 現在接続されている各サブデバイスのチャネル接続エンドポイントを呼び出す。 初期セットアップ後、ホストデバイスは、サブデバイスが切断されるたびチャネル切断エンドポイントを呼び出し、新しいサブデバイスが追加されるたびチャネル接続エンドポイントを呼び出す必要があります。ホストデバイスは、新しいデバイスが接続されるたびにサブデバイスをクリアすることはしないでください。

ホストデバイスはデバイスを管理する際、貧弱なネットワーク状態に適切に対処し、再確立中のネットワークへの接続時に、現在接続されているデバイスを適切に追加／削除する必要があります。

次のステップ

まだの場合は、当社チームにお問い合わせください。そのうえで、次のガイドに進んでください。ご連絡をお待ちしております。