統合アーキテクチャ | Frame.io API Documentation

はじめに

API 要求の作成を開始する前に、C2C 統合の基本的なアーキテクチャを理解する必要があります。（次の記事では、端末で作業を行います。ここでは、これらの基本的な概念について説明します。）

統合を簡単に示したデータモデルは次のようになります。

                                   ┌───────────────────┐    ┌─────────┐
                                   │ Project Device 01 │ -> │ Project │
┌───────────┐    ┌──────────────┐  └───────────────────┘    └─────────┘
│ Oauth App │ -> │ Device Model │ ──────────⭥
└───────────┘    └──────────────┘  ┌───────────────────┐    ┌─────────┐
                                   │ Project Device 02 │ -> │ Project │
                                   └───────────────────┘    └─────────┘

OAuth アプリ

統合は、バックエンドに登録されたエンティティである OAuth アプリによって定義されます。これにより、デバイスは OAuth 2 を使用して Frame.io で認証できるようになります。OAuth アプリは、統合全体の承認戦略を定義します。ユーザーが Frame.io に接続するすべてのデバイスは、同じ OAuth アプリを介して認証されます（ただし、複数のデバイスラインを持つインテグレーターの場合、それぞれに 1 つの OAuth アプリが必要となる場合があります）。

C2C 統合では、UI 機能が制限されているデバイス専用に設計された専用の OAuth フローを使用します。

C2C デバイス認証

C2C API は、UI 機能が制限されているデバイス向けに設計されています。これらのデバイスでは、ユーザーは 6 桁のコードを表示して Frame.io に接続することができ、ユーザーは自分のブラウザーを使用して Frame.io の web サイトに入力します。

デバイスに client_secret が発行され、バックエンドに提供して 6 桁の認証コードを受信する必要があります。この合理化された手法により、すべての C2C 統合で一貫性のある安全な認証エクスペリエンスが実現します。

デバイスモデル

デバイスモデルでは、C2C バックエンドとやり取りする際のサポートされる機能を含むデバイスの動作を設定します。次の設定内容は、お使いのデバイスモデルにより構成されます。

Asset Type

The category of asset your device produces. May be “video,” “audio,” or “data.” Note that “video” includes video files that are muxed with audio.

Path Name

The name of your integration as it should appear in any uploaded asset’s path.

Tokenized Filepath

C2C only allows uploading assets to specific root filepaths, but below that requirement your device can be configured to upload assets to a dynamically calculated filepath based on the asset’s supplied metadata.

Required Metadata

What metadata will be required when you upload an asset to Frame.io, most notably to support the tokenized file path.

Socket Status

Whether the integration will use low-latency sockets for communicating its current status, or higher-latency REST calls.

お使いのデバイスがサポートする機能は、ファームウェアのバージョンによって異なる場合があります。下位互換性と最適なユーザーエクスペリエンスを有効にするために、検出されたファームウェアバージョンに基づいてデバイスの設定が動的に選択されます。今後、統合で複数のデバイスモデルが使用できるようになる予定です。どのデバイスモデルを使用するかは、デバイスのファームウェアバージョンと特定のデバイスモデルの最小ファームウェアバージョン要件を比較することで決定されます。

プロジェクトデバイスおよび ID

ProjectDevice は、Frame.io に接続されているデバイスの各物理インスタンスを表します。

ProjectDevice は、client_id と呼ばれる一意の識別値を使用して、自身を識別します。この値では、2 つのデバイス間で共有されていないことを確認する必要があります。例として、デバイスのシリアル番号、またはデバイスが一度生成して保存したランダムな文字列があります。client_id として、コンピューターの MAC アドレスなどの、デバイスが所有している値を指定することはできません。

バックエンドは各プロジェクトデバイスを追跡し、現在のファームウェアバージョンなどの情報を保存します。

それぞれの ProjectDevice には、関連付けられた特定の Frame.io Project、プロジェクトへのデバイスアクセスを許可する OauthAuthorization と、デバイスが実行できることを詳述したスコープのセットがあります。使用可能なスコープの詳細については、認証および認可の実装に関する詳細なガイドを参照してください。

ProjectDevice は、/me エンドポイントによって返されます。Device は、一度に 1 つの ProjectDevice にのみアクティブにリンクできます。したがって、一度に 1 つの Project にのみリンクできます。

ファームウェアバージョン

https://api.frame.io でエンドポイントを呼び出すたびに、デバイスの最新のファームウェアバージョンと x-client-version HTTP ヘッダーを提示する必要があります。後述の API ガイドの各例に、このヘッダーが含まれています。

場合によっては、バックエンドで複数のファームウェアバージョンを並べ替える必要があり、これをサポートするには、値が有効なセマンティックバージョンである必要があります。これらには、0.1.2、2.1.3-preview.01、2.1.3-preview.01+build_19770504.01 などの値が含まれます。

ファームウェアバージョンの値が有効なセマンティックバージョンでない場合は、エラーが返されます。当社では、すべての統合でセマンティックのバージョン管理を使用してファームウェアを追跡するわけではないことを理解しています。そのような場合、作成する内部バージョンごとにバックエンドを提供するために、セマンティックバージョンを追跡するようにしてください。

ヘッダーを提示することで、ファームウェアの異なるリリースで、Frame.io 内の異なる機能（場合によっては競合する機能を含む）をサポートできます。

Header Host

The firmware version is only handled by calls to https://api.frame.io, when making calls to https://applications.frame.io, the header has no effect.

Current Requirement

The x-client-version is now a required HTTP header, and will be enforced by Frame’s servers.

次のステップ

API 呼び出しを実行しましょう。C2C を使用して認証および認可を行う方法を説明します。設定ガイドに従って開始してください。