方法：承認（ハードウェア） | Frame.io API Documentation

はじめに

このガイドでは、Frame.io プロジェクトで Camera to Cloud （C2C）ハードウェアデバイスを認証および承認する方法について説明します。コードの手入力を使用した従来のペアリングと、ユーザーエクスペリエンスを向上させる新しい QR コードペアリングの方法について説明します。

必要なもの

実装を開始する前にガイドをまだ読んでいない場合は、目を通してから先へ進んでください。

また、統合の識別用に、当社チームから client_secret を受け取っているはずです。client_secret を受け取っていない場合は、C2C エコシステムに関するこちらの概要を参照し、当社チームにお問い合わせください。

QR コードペアリングの前提条件

QR コードのペアリングを開始する前に、次の前提条件が満たされていることを確認してください。

機能フラグのアクティブ化：Frame.io アカウントで特定の機能フラグ（v4.c2c_qr_code_activate）が有効になっている必要があります。この機能フラグを使用すると、QR コードベースのペアリング方法を利用できます。選択したアカウントでこの機能をオンにする作業は、お客様の Frame.io 担当者がお手伝いできます。
カメラの互換性：カメラのハードウェアがアップデートされており、デバイスのペアリング処理での QR コード生成に対応していることを確認してください。

ハードウェア承認フローの手順

実装する承認フローで予期されるユーザーエクスペリエンスについて、概要を理解していることを確認しましょう。以下のリソースをチェックして、このフローをユーザー目線で確認してください。

新しいハードウェアデバイスを追加する方法に関するサポート記事
Teradek Cube の承認方法に関するトレーニング動画

ハードウェア承認フローは、実装者から、ひいてはデバイス UI からできるだけ多くの詳細情報を引き出せるように設計されています。このフローでは、以下の心配は不要です。

Web ブラウザーへのリダイレクト
Frame.io ユーザーのログイン／認証の処理
接続先のアカウントやプロジェクトのリスト／選択
基本情報を表示する以外の UI 要素

QR コードペアリングによるユーザーエクスペリエンスの向上

効率性と使いやすさに対するニーズが高まるにつれ、ユーザーはデバイスとのシームレスなやり取りをいっそう期待しています。カメラを Frame.io の C2C サービスにペアリングする現在のプロセスでは、ペアリングコードの手入力など、いくつかの手順が必要です。このプロセスは機能していますが、合理化の余地があります。

Netflix や Disney+ などのストリーミングサービスで見られるデバイスペアリング体験と同様に、QR コードを活用することで、プロセスを簡素化し、手入力によるエラーを排除し、カメラのペアリングにかかる時間を短縮できます。

デバイス ID（client_id）

Camera to Cloud に接続する場合、物理ハードウェアデバイスは、ユーザーのプロジェクトでデバイス接続をリストできるようにするため、一意に識別される必要があります。

ハードウェアデバイスの場合、使用する承認パターンに応じて、これをデバイスの client_id と呼びます。実装をセットアップする際には、識別子をどのように付与するかを考える必要があります。ハードウェアデバイスのシリアル番号、UUID または一意に識別する文字列を使用できます。

個人を特定できる情報を漏洩しないように注意してください。例えば、ユーザーのメールアドレスは、client_id としての使用に適した値ではありません。

同様に、一意の識別子をソフトウェアが所有していることを確認してください。C2C API をソフトウェアデバイスとして実装する場合は、デバイスの MAC アドレスなどを使用しないでください。MAC アドレスはソフトウェアの所有ではないうえ、個人を特定できる情報と見なされる場合もあります。

使用する値に確信が持てない場合は、この選択について当社と協議し、統合ができるだけ簡単になる適切な値を選択することができます。

手順 1：デバイスコードの要求

実装を開始しましょう。最初に行う必要があるのは、デバイスのユーザーに提供するデバイスコードをリクエストすることです。これを行うには、/v2/auth/device/code エンドポイントを呼び出します。

従来のペアリング方法

curl -X POST https://api.frame.io/v2/auth/device/code \
    --form 'client_id=[client_id]' \
    --form 'client_secret=[client_secret]' \
    --form 'scope=asset_create offline' \
    | python -m json.tool

QR コードペアリングの有効化

QR コードベースのペアリングを有効にするには、API 呼び出しを若干変更する必要があります。具体的には、デバイスコードリクエストに 2 つの新しいヘッダーを追加する必要があります。これにより、デバイスをペアリングページに直接リンクし、ペアリングプロセスを合理化できます。

curl -X POST https://api.frame.io/v2/auth/device/code \
    --header "x-client-version: 2.0.0" \
    --header "x-client-platypus-enabled: true" \  # New header to enable QR code
    --form 'client_id=[client_id]' \
    --form 'client_secret=[client_secret]' \
    --form 'scope=asset_create offline' \
    | python -m json.tool

**注意：**ここでは JSON データではなくフォームデータを使用しています。C2C 認証エンドポイントは、フォームデータのみを受け入れます。認証後、他のエンドポイントは JSON ペイロードを受け入れますが、認証エンドポイントは JSON ペイロードが送信されるとエラーを返します。

ペイロードパラメーター

client_id：物理ハードウェアデバイスの一意の識別子。この値はデバイス固有であることが保証されている必要があります。シリアル番号やランダム生成された UUID などが可能です。
client_secret：Frame.io サポートから発行されるもので、お使いのデバイスモデルを識別します。この値はユーザーには秘密にし、保管時には暗号化する必要があります。
scope: リクエストしている権限。区切り文字としてスペースが使用されます。ハードウェアデバイスは、次の 2 つのスコープのみリクエストできます。
asset_create：デバイスがアセットを作成およびアップロードできるようにします。
offline：デバイスが更新トークンを使用して自身の承認を更新できるようにします。承認トークンは 8 時間後に期限切れになるので、このスコープがない場合、ユーザーは 8 時間ごとにデバイスを再承認する必要があります。

実際には、ほとんどの場合、デバイスはどちらのスコープもリクエストします。

API 応答の理解

リクエストを行うと、次のようなレスポンスが返されます。

従来のペアリング応答

{
  "device_code": "[device_code]",
  "expires_in": 120,
  "interval": 5,
  "name": "MyDevice-[client_id]",
  "user_code": "573131"
}

QR コードペアリングのレスポンス

{
  "device_code": "[device_code]",
  "expires_in": 120,
  "interval": 5,
  "name": "MyDevice-[client_id]",
  "user_code": "573131",
  "verification_uri": "https://next.frame.io/pair",
  "verification_uri_complete": "https://next.frame.io/pair/573131"
}

応答ブレークダウン

device_code：デバイスコードがユーザーに表示されないようにしてください。このコードは、ポーリング時にこの承認リクエストを識別し、ユーザーがコードを正常に入力したかどうかを確認するために使用されます。
expires_in：このコードが期限切れになるまでの秒数。
interval：ユーザーがコードを入力したかどうかを確認するために、ポーリングリクエスト間に待機する必要がある時間。
name：接続しようとしているデバイスの名前。
user_code：ユーザーが Frame.io に入力してデバイスをプロジェクトにペアリングするための 6 桁のコード。
verification_uri：QR コードがスキャンされない場合にユーザーが手入力する URL です。簡潔で覚えやすいものにする必要があります。
verification_uri_complete：この URL にはペアリングコードが含まれています。テキスト以外の送信（QR コードなど）を目的としています。スキャンすると、ユーザーは自動的にペアリングエクスペリエンスにルーティングされ、そこでデバイスを接続するアカウントとプロジェクトを選択します。

ユーザーへの QR コードの表示

これで verification_uri_complete を取得できたので、この URL から QR コードを生成し、デバイスの画面でユーザーに表示できます。これにより、ユーザーはモバイルデバイスまたはカメラで QR コードをスキャンするだけでよくなり、ペアリングプロセスが合理化されます。

例：QR コードが表示されたカメラ画面

QR コードが表示されているカメラ画面の画像またはイラストを挿入してください。

ユーザーが何らかの理由で QR コードをスキャンできない場合は、user_code と verification_uri も表示して、万一の場合にユーザーがペアリングコードを手入力できるようにしておく必要があります。または、verification_uri を静的 QR コードとして表示して、ユーザーがモバイルデバイスでスキャンできるようにすることも可能です。

統合がモバイルデバイス上のアプリの場合、アプリが搭載されているデバイスでは QR コードをスキャンできないので、ユーザーがタップするハイパーリンクとして verification_uri_complete を表示して接続しやすくする機能は欠かせません。

手順 2：ユーザー承認をポーリングする

ペアリングコードを提示したり、QR コードをユーザーに表示したりしたら、ユーザーがそれを入力したかどうかを確認する必要があります。そのためには、次のようなリクエストを実行できます。

curl -X POST https://api.frame.io/v2/auth/token \
    --form 'client_id=[client_id]' \
    --form 'device_code=[device_code]' \
    --form 'grant_type=urn:ietf:params:oauth:grant-type:device_code' \
    | python -m json.tool

ペイロードパラメーター

client_id：手順 1 で送信されたものと同じ client_id。
device_code：/v2/auth/device/code から返された device_code。
grant_type：OAuth システムが発行している承認付与のタイプ。この値は常に urn:ietf:params:oauth:grant-type:device_code です。

このリクエストの最初の数回に対しては、おそらく次のようなレスポンスが返されます。

{
  "error": "authorization_pending"
}

ですが、心配は不要です。これは致命的なエラーではありません。単に、ユーザーが Frame.io の UI にユーザーコードをまだ入力していないという意味です。必要なのはポーリングを続けることだけです。

代わりに、次のようなエラーが返された場合：

{
  "error": "expired_token"
}

ユーザーによる入力前にコードの有効期限が切れました。このような場合は、手順 1 を使用して新しいペアリングコードまたは QR コードを生成し、ユーザーに表示してから、ポーリングを再開する必要があります。

最終的には、次のようなレスポンスが得られます。

{
  "access_token": "[access_token]",
  "expires_in": 28800,
  "refresh_token": "[refresh_token]",
  "token_type": "bearer"
}

このようなレスポンスペイロードが返ってきたら：完了しました。最初の Camera to Cloud デバイスを承認しました。ご苦労さまでした。

最後に、そのレスポンスペイロードを見て、内容の理解を確認しましょう。

access_token：Frame.io バックエンドの残り部分に対する鍵です。これらのチュートリアルで行う以降のリクエストのヘッダーにこれを追加する必要があります。
expires_in：access_token の有効期限が切れるまでの秒数。このトークンの時間が経過したら更新が必要です。これについては、今後のチュートリアルで説明します。
refresh_token：access_token の管理に使用できるトークン。主に承認の更新に使用されますが、取り消しにも使用できます。
token_type：C2C API では常に bearer で、特に処理は不要です。

ステップのまとめ

必要な呼び出しがわかったので、それらを Python 風擬似コードにまとめてみましょう。デバイスコードが期限切れになる可能性があるので、ロジックをセットアップする際にはその可能性に対処する必要があります。

Python

1 def authorize_with_frame():
2     """
3     Handles authorizing our device with Frame.io.
4     """
5 
6     # Our client ID can be a serial number, UUID, or some other unique string.
7     client_id = THIS_DEVICE.get_serial_number()
8 
9     while True:
10         # Make the call to Frame.io to get our device codes.
11         pairing_codes = c2c.get_device_codes(client_id)
12 
13         # We need to keep track of how long we have been polling for
14         polling_started = datetime.now()
15 
16         # Now we are going to poll for authorization until the user enters the code.
17         while True:
18 
19             # Re-write this output each time we poll. Note: This message will only update once
20             # per `interval` (e.g., 5 seconds), so if a smooth countdown is desired, that will
21             # need a different implementation.
22             print(
23                 f"\rPAIRING CODE: {pairing_codes.user_code}, "
24                 f"EXPIRES IN: {pairing_codes.expires_in - (datetime.now() - polling_started).seconds} seconds"
25             )
26 
27             # Wait for `interval` before polling each time.
28             sleep(pairing_codes.interval)
29 
30             # Make a call to Frame.io to see if the user has entered the code and authorized
31             # the device.
32             authorization, error = c2c.poll_for_authorization(
33                 client_id, pairing_codes.device_code
34             )
35 
36             if error and error.message == "authorization_pending":
37                 # If the authorization is pending, try again.
38                 continue
39             elif error and error.message == "expired_token":
40                 # If the pairing codes have expired, break to generate new codes.
41                 break
42             elif error:
43                 # If we get another error, we should raise it. (advanced error handling will
44                 # be covered in another tutorial)
45                 raise Exception(error.message)
46 
47             return authorization

**注意：**この疑似コードでは、ペアリングコードの有効期限切れに対処するループを外側に追加して、新しいコードをリクエストする必要があります。

最後に、接続したプロジェクトに関する情報を Frame.io から取得し、それをユーザーに表示して、デバイスが目的のプロジェクトにペアリングされたことを再確認できるようにします。これについては次のチュートリアルで説明します。

トラブルシューティング

ここをご確認いただいている方は、問題の解決方法をお探しだと思われます。サードパーティとの統合は、エラーなしとはいかないものです。このセクションでは、一般的な問題の一覧と、それらを解決できる可能性が最も高い手順について説明します。次の一覧を参照して、目下の問題と一致するものがないか確認してください。

ここで解決策が見つからない場合は、発生した問題をお聞かせください。ここに追加します。

「デバイスを接続」ボタンが表示されない：C2C 管理パネルに移動しても、「デバイスを接続」ボタンが表示されない場合は、次の 2 つのいずれかが発生しています。
アカウントで C2C が有効になっていない：画面が空白で、アカウントで C2C が利用できないというメッセージが表示された場合、アカウント管理者がアカウント設定で該当プロジェクトの C2C を有効にする必要があります。
デバイス管理者ではない：画面が空白で、権限がないというメッセージが表示された場合、アカウント管理者が、C2C デバイスへの接続を許可されているユーザーの権限を変更するか、それらの権限を持つロールにユーザーを追加する必要があります。
デバイスは接続済み：最初のデバイスが接続されると、大きくて青い「新規デバイスを追加」ボタンが消えるので、C2C 接続パネルの右上隅にある 3 点メニューに移動する必要があります。
無効なクライアントエラー：デバイスに関してお客様から提供された情報が、当社が記録しているものと一致しない場合、invalid_client が返されます。これは多くの場合、client_secret が正しくないことを意味します。
不正な要求エラー：リクエストデータの形式が何らかの形で不正な場合、bad_request が返されます。フィールド名のスペルが間違っていたり、必須フィールドの追加を忘れたりしていないことを再確認してください。

次のステップ

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

保留事項

To do：動的 QR コードを生成できないパートナー向けに非常手段を追加する。具体的には、代替策として「このコードを入力するには **verification_uri** へ移動してください」と表示してもらう