方法：ステータスと状態の管理

はじめに

このガイドでは、デバイスのステータスを管理し、Frame.io との同期を維持する方法について説明します。Frame.io では、デバイスとのリアルタイム通信を可能にする websocket プロトコルを使用します。Websocket に慣れていない場合は、このガイドを参考にして、C2C 統合の実装について理解してください。

Websocket を使用すると、Frame.io はメッセージをデバイスにプッシュできます。また、永続的な接続を維持することで、従来の HTTP リクエストよりも効率的な通信チャネルを提供できます。

このガイドでは、以下の内容について説明します。

• デバイスが「オンライン」であることを示すソケット接続を開く
• デバイス接続に関する情報を取得する
• Frame.io バックエンドの可用性を検証する

前提条件

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

認証および承認プロセス中に、access_token の取得が必要になります。トークンは 8 時間後に期限切れになることから、トークンを更新するか、承認プロセスを再度実行する必要が生じる場合があります。

このガイドの websocket 接続例では、様々なオペレーティングシステム向けの包括的なインストール手順を含む CLI ツール、websocat の使用をお勧めします。

接続情報の取得

新しい承認またはトークン更新の後、デバイスはすぐ identity エンドポイントへのクエリを実行します。これにより、接続に関する重要な情報が得られます。

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

レスポンスは次のようになります（一部のデータは省略されています）。

{
    "_type": "project_device",
    "id": "a7e95254-8cd6-4d59-b54d-28c58570a8de",
    "asset_type": "video",
    "authorization": {
        "_type": "project_device_authorization",
        "creator": {
            "_type": "user",
            "id": "e7e96254-8bd6-4d59-b54d-28c58570a8de",
            "name": "Harry Potter"
        },
        "expires_at": null,
        "id": "7b2b68e5-788d-497c-8597-f9362cb1a75e",
        ...
        "project_device_id": "14856308-46e0-4d7d-8438-320262eec74e",
        "scopes": {
            ...
            "asset_create": true,
            ...
            "id": "0fe0accb-447f-44f6-b2af-177d913b3a29",
            "offline": true,
            ...
        }
    },
    ...
    "name": "Frameio-BPEAKE-TEST-DEVICE",
    "project": {
        "_type": "project",
        "id": "2ad59fe6-77b6-4fbc-a9d2-3dd0413ed4a3",
        "name": "Testbed"
    },
    "project_id": "2ad59fe6-77b6-4fbc-a9d2-3dd0413ed4a3",
    "status": "online",
    ...
}

このエンドポイントは、接続の詳細確認に役立ちます。デバイスはユーザーに次の情報を表示します。

• project.name - 接続されているプロジェクトの名前
• authorization.creator.name - デバイスを承認したユーザー
• authorization.expires_at （オプション） - 接続の有効期限（設定されている場合）
• status （オプション） - デバイスステータス。次のいずれかです。
  • online - デバイスはオンラインで、ペアリング済み
  • offline - デバイスは 5 分以上通信していない（エンドポイントへのクエリを実行すると、ステータスが online に変わります）
  • paused -Frame.io の C2C 接続パネルでデバイスが一時的に無効になっている

有効期限と一時停止ステータスは Frame.io 内でいつでも変更される可能性があるので、この情報をユーザーに表示する場合は定期的なポーリングを検討してください。ポーリング頻度は 60 秒に 1 回以下に制限することをお勧めします。

Websocket 接続の確立

Frame.io の C2C 接続パネルには、各デバイスの接続ステータスが表示されます。デバイスにアクティブなソケット接続がある場合は、カードの左上隅に緑色のインジケーターとともに online と表示されます。アクティブな接続のないデバイスは、グレーで offline と表示されます。

サーバーはソケット接続を、「ハートビート」メッセージなしの 60 秒後に自動終了します。この間隔で十分ですが、信頼性のためにハートビートを 15 秒ごとに送信することをお勧めします。接続が予期せず終了した場合は、接続を再確立してください。

Frame.io と websocket の接続は、次の 2 つの手順を伴います。

1. TCP/IP ハンドシェイクを確立し、物理 websocket 接続を開く
2. デバイスの特定チャネルに参加し、そのデバイスをバックエンドで識別できるようにする

Websocket 接続を開くには、次のコマンドを実行します。

$
websocat -n "wss://api.frame.io/devices/websocket?Authorization=Bearer ACCESS_TOKEN"

接続に成功すると 101 ステータスコードが返され、プロトコルが wss に切り替わったことを示します。お使いの websocket ライブラリがこれを自動的に処理する場合があります。有効期限が切れたトークンは 403 レスポンスを生成します。

次に、接続情報の id を使用して、この JSON メッセージを送信してデバイスのチャネルに参加します。

1
{"topic":"devices:YOUR_DEVICE_ID", "event":"phx_join", "payload":"", "ref":"channel_connect"}

確認メッセージが返されます。

1
{"event":"phx_reply","payload":{"response":{},"status":"ok"},"ref":"channel_connect","topic":"devices:YOUR_DEVICE_ID"}

C2C ダッシュボードを確認してください。デバイスがオンラインになっているはずです。この接続を維持するため、バックグラウンドプロセスの実装をお勧めします。

1
def heartbeat_task():
2
    """
3
    Task that emits heartbeats every 15 seconds.
4
    """
5

6
    while True:
7
        c2c.emit_socket_heartbeat()
8
        sleep(15)

ハートビートメッセージの形式：

1
{"topic":"phoenix", "event":"heartbeat", "payload":"", "ref":"heartbeat"}

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

1
{"event":"phx_reply","payload":{"response":{},"status":"ok"},"ref":"heartbeat","topic":"phoenix"}

アクティブなソケット接続とチャネルサブスクリプションがあると、Frame.io の C2C 接続パネルにデバイスがオンラインとして表示されます。接続が終了すると、オフラインと示されます。

デバイスステータスの表示

生のステータス値（online、offline、paused）を表示するのではなく、ユーザー向けのよりわかりやすいインジケーターに変換することをお勧めします。

• Paused：true/false - ステータスが paused の場合は true、それ以外の場合は false
• Connected：true/false - デバイスが Frame.io バックエンドに到達できるかどうか（後述のバックエンド接続テストを参照）

一時停止ステータスの管理

一時停止ステータスの表示は任意ですが、その機能を理解することが重要です。

一時停止機能は、機密コンテンツのアップロードを一時的にブロックするために設計されたものです。ネットワークトラフィックはブロックされませんが、特定のメディアが Frame.io に到達するのを防ぎます。これは、機密性が高く、すぐクラウドに保管するのが適切ではない可能性のある素材を含むシーンを撮影する場合などに便利です。

一時停止は、お客様の統合ではなく Frame.io インターフェイスを介して制御されます。デバイスが一時停止されると、一時停止期間中に作成されたメディアのみがブロックされ、その前にキャプチャされていたメディアは引き続きアップロード対象です。

重要な考慮事項：

• アップロード適格性の検証を identity エンドポイントだけに頼らないでください。バックエンドはこれを自動処理します。
• ソケットイベントは、event: "status_updated" と、payload: "paused" または "resumed" を使用して、ステータスの変更を通知します。
• イベントはステータスの管理に役立ちますが、見逃されたり、順番どおりに配信されなかったりする可能性もあります。
• アップロード中に 409 エラーが返されても、必ずしもデバイスが現在一時停止中だとは限らず、そのメディアが前回の一時停止期間中に作成されたものであることを示している可能性があります。
• 一時停止ステータスが示されている場合は、定期的に接続情報を確認して、その正確性を確認してください。

バックエンド接続の検証

Frame.io バックエンドの可用性を確認するには、このエンドポイントを使用します。

$
curl -X GET https://api.frame.io/health \
>
    | python -m json.tool

このエンドポイントに承認は不要です。成功レスポンスは、接続されていることを示します。

1
{
2
    "ok": true
3
}

この正常性チェックは非常に価値があります。一般的なネットワークの可用性ではなく、Frame.io との接続を確認しているからです。お客様のネットワークが機能していても、サービスの問題やルーティングの問題によって Frame.io に到達できない場合が考えられます。

次のステップ

不明点がありましたら、当社チームまでお問い合わせください。そのうえで、アップロード（基本）ガイドに進んでください。お客様の統合の進捗を支援できる機会を楽しみにしています。

デバイス承認の管理の詳細については、承認の管理ガイドを参照してください。