コンテンツにスキップ

APIを使用したサイト埋め込み

概要

  • APIユーザーは APIキー を持ち、アクセス許可ドメイン で利用元ドメインを制限できます
  • 用途に応じて API種類（readonly/fullaccess）を選択。閲覧のみなら readonly 推奨
  • 認証方式は「APIキー」または「JWT」の2種類（どちらか一方でOK）

準備

  1. 既存のデフォルトAPIユーザーを利用（初期アカウント発行時に自動作成）
    • 必要なら /filmaadmin/user/new で新規APIユーザーを作成（「APIユーザー」をON）
  2. /filmaadmin/apisettings/edit/:user_id を開き、「アクセス許可ドメイン」に自サイトのドメイン名を登録（サブドメイン可）
    • URLで入力しても保存時にドメイン名（ホスト部）へ自動変換されます
    • example.com と入力すると、その配下のサブドメイン（www.example.com / app.example.com など）も許可されます
    • 特定のサブドメインのみ許可したい場合は app.example.com のようにサブドメインまで入力してください
    • 未設定ドメインからのアクセスは拒否されます

実装フロー（例）

  1. APIキーとエンドポイントで再生用URL/トークンを取得
  2. 自サイトのプレイヤーへURL/トークンを設定
  3. ドメイン照合エラーの場合は、許可ドメイン設定を確認

認証方式の選び方（非エンジニア向け）

どちらの方式でも再生は可能です。用途に合わせて選んでください。

A. APIキーを直接使う

  • 使い方: リクエストで X-Api-Key ヘッダー（推奨）または ?api_key= を付けて呼び出します
  • ドメイン制限: アクセス許可ドメインのチェックが働きます（未設定だと自社サイトから再生できません）
  • 長所
    • 導入が簡単（追加の発行手順が不要）
    • ドメインでのアクセス制限が効く（Referer/Origin）
  • 短所
    • APIキーが長期固定になりがちで、漏えい時のリスクが高い
    • フロント側の実装でキーを扱う場合は取り扱いに注意（直接埋め込みは避け、サーバー経由に）

B. JWTを使う

  • 使い方: まずAPIキーで「短期のJWTトークン」を発行し、そのJWTを使って再生用URLを呼び出します
  • ドメイン制限: 適用されません（JWTの有効性で保護）。どのドメインからでもアクセス可
  • 長所
    • 短期の使い捨てトークンで安全（期限切れで自動無効化、Cookie運用も可能）
    • ファイル単位（mediafile_id）で限定したJWTも発行できる
  • 短所
    • 初回に「JWT発行」のひと手間が必要
    • ドメイン制限が効かないため、トークンの保管と配布に注意（短寿命運用が前提）

迷ったら…

  • 「まずは簡単に」→ APIキーで開始（必ずアクセス許可ドメインを設定）
  • 「より安全に」→ 短期JWTを採用（必要に応じてファイル限定JWT）

推奨アーキテクチャ（JWTのバックエンド発行）

JWT はできるだけ自社バックエンドで発行・配布する運用を推奨します。APIキーをフロントに露出させず、短期トークンで安全に配信できます。

基本フロー

  1. フロント → 自社バックエンド: 対象メディアIDを渡して JWT を要求
  2. バックエンド → Filma API: APIキーで POST /filmaapi/token（必要に応じて mediafile_id 指定、expires_in で短期化）
  3. バックエンド → フロント: 短期JWT（または埋め込みHTML/URL）を返却
  4. フロント: JWT 付きURLでプレイヤーを初期化

ポイント（運用）

  1. 有効期限は短め（例: 数分〜15分）を基本に、必要時に自動リフレッシュ
  2. 外部共有や限定公開は「ファイル限定JWT（mediafile_id）」で最小権限
  3. バックエンドで発行ログ/失効ポリシーを持ち、問題時は短期運用＋差し替えで対応
  4. JWTはドメイン制限が効かないため、短寿命＋限定スコープで担保（APIキーは常にバックエンド保管）

画面から得られる情報（管理画面とAPIの対応）

  • 管理画面の「埋め込みHTML」でコピーできるコードは、プレイヤー用JS/CSS込みの完全版です
  • APIでも同等の「埋め込みHTML（完全版/シンプル版）」が取得できます（embed_code / simple_embed_code）
  • タグ/カテゴリなど管理画面のメタ情報は user_metadata として取得できます

技術メモ: 認証の優先順位や詳細は Filma API 仕様書 を参照してください（非エンジニアの方は本ページの方針だけ把握で十分です）。 参照先: Filma API 仕様書

注意

  • fullaccess は強力な権限です。キー管理（保護・ローテーション）を徹底してください

次にやること / 関連