コンテンツにスキップ

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

APIキーの用途

組織管理者が管理画面の「API設定編集」で、用途に合わせてAPI種類を選びます。

API種類 用途 キーの扱い
embedded（デフォルト） ページへ動画を埋め込む 埋め込みHTMLへ記載可能
readonly サーバーから参照系APIを利用 秘密情報としてサーバーに保管
fullaccess サーバーから参照・更新・削除系APIを利用 秘密情報としてサーバーに保管

embedded のキーでは、公開中の動画を指定した短期再生JWTの発行だけができます。ファイル一覧や会員情報などの一般APIは利用できません。

ページ埋め込み用キーで再生する

  1. /filmaadmin/user/new でAPIユーザーを作成するか、埋め込み専用の既存APIユーザーを選びます。
  2. /filmaadmin/apisettings/edit/:user_id でAPI種類が「ページ埋め込み用 (embedded)」であることを確認します。新規キーはこの設定で作成されます。
  3. 「アクセス許可ドメイン」に埋め込み先のドメインを1行ずつ登録します。
  4. 管理画面の「埋め込みHTML」をページへ貼り付けます。

埋め込みHTMLには、有効な embedded キーが優先して使われます。該当キーがない場合は既存の readonly キーを使用しますが、URL認証の制限により再生できない場合があります。埋め込み用APIユーザーを用意してHTMLをコピーし直してください。fullaccess キーは使いません。

現行プレイヤーは初期化時に POST /filmaapi/token?api_key=... を呼び、動画IDを渡してJWTを取得します。その後のDASH・HLS・DRMライセンス取得ではJWTだけを使用します。キーの値を変更しない場合、現行プレイヤーを使った既存の埋め込みHTMLもそのまま利用できます。

JWTの対象組織・対象動画・再生権限・有効期限はFilma側で制限します。動画の長さに余裕を加えた有効期間となり、埋め込み側で期限を延長することはできません。JWTはJSONで返され、Cookieを上書きしません。

独自実装でJWTを取得する場合は、mediafile_id に対象動画のMediafile IDを指定します。Storage APIのファイルID（FilmaFile ID）とは異なります。expires_in、jwt_expires_at、show_all は指定できず、一般API・ダウンロード・JWT更新にも利用できません。

既存キーをembeddedへ変更する前に

  • サーバーの一般APIに同じキーを使用していないことを確認してください。
  • APIキーを直接使ってDASH・HLS・DRMへアクセスする古いプレイヤーは、変更後に再生できなくなります。JWT交換に対応した現行プレイヤーへ更新してください。
  • 変更前に発行したJWTも利用できなくなります。ページを再読み込みして新しい再生JWTを取得します。
  • リリース時の移行で既存キーの種類が変更される場合があります。ユーザー名だけで判断せず、「API設定編集」の現在のAPI種類を確認してください。

同じキーを一般APIでも使っている場合は、サーバー用キーを維持し、別の埋め込み用APIユーザーを作成してください。ページ上のHTMLは新しい埋め込み用キーのものへ貼り替えます。

許可ドメインの役割

example.com を登録すると、その配下のサブドメインも照合対象になります。特定のサブドメインだけを対象とする場合は app.example.com のように指定します。

Referer / Origin の照合は、ブラウザからの意図しない利用を抑える補助機能です。これらのヘッダーがない要求は許可され、APIクライアントから任意に指定することもできます。公開キーだけで会員認証や購入者限定の視聴権を保証することはできません。

サーバーでJWTを取得する

動画一覧やメタデータを取得する場合や、利用者の認証・視聴権を自社側で確認する場合は、readonly／fullaccess の秘密キーをサーバーで保管し、FilmaからJWTを取得してブラウザへ渡します。

  1. ブラウザが自社バックエンドへ再生を要求します。
  2. バックエンドが認証・視聴権を確認します。
  3. バックエンドから X-Api-Key ヘッダーでFilmaのJWT発行APIを呼び出します。
  4. 取得したJWTまたはJWT付き埋め込みHTMLをブラウザへ渡します。

読み取り用JWTをサーバーから取得する例:

curl -X POST "https://filma.biz/filmaapi/token" \
  -H "X-Api-Key: YOUR_READONLY_KEY"

一覧取得に使う場合は mediafile_id を省略します。特定の動画に限定する場合はMediafile IDを指定してください。通常のJWTは有効期限を設定できますが、embeddedの再生JWTではFilmaが期限を決定します。

ブラウザでは取得したJWTをAPI要求の Authorization: Bearer ヘッダーに渡します。iframeやプレイヤーにはJWT付きURLを使用します。DRMの独自プレイヤーではライセンス要求にもJWTを渡してください。管理画面の埋め込みHTMLは、現行プレイヤーがJWTの取得と後続の要求への設定を行います。

サーバー用キーのURL認証・IP制限

サーバー用キーは原則としてURLパラメーター認証を禁止します。移行対象として指定された例外組織にだけ「API設定編集」の「URLパラメーター認証」選択欄を表示し、次の設定を選べます。対象外の組織では常に禁止です。

  • 禁止する（推奨）: 新規キーの初期値です。X-Api-Key ヘッダーを使用します。
  • 許可する（既存連携の互換用）: 例外対象の組織が移行中の連携を維持するための一時設定です。URLはログに残るため、既存連携がヘッダー認証に移行したことを確認したら、必ず禁止してください。

ページ埋め込み用ではこの設定を操作できず、JWT発行のURL認証は引き続き利用できます。既存の readonly キーを埋め込みに使っている場合は、JWT交換もURL認証にあたるため、用途の確認と embedded への切り替えを先に行ってください。

「アクセス許可IP／CIDR」には、バックエンドの送信元IPv4／IPv6またはCIDRを1行1件で指定できます。空欄は制限なしです。設定すると、JWT発行を含むAPIキー認証を指定した範囲に限定します。発行したJWTにはこの制限を適用しないため、ブラウザのIPが異なっても利用できます。embedded も対象外です。

動作確認用サンプル

  • 動画埋め込みサンプル: 埋め込みHTMLの使用例です。公開URLは従来のままですが、以前のAPI一覧取得コードは廃止しています。
  • JWTサンプル: 動作確認のためブラウザでreadonlyキーを使ってJWTを取得します。通常の運用ではキーをサーバーに保管し、JWT取得処理をサーバーへ移してください。取得したJWTを使う一覧表示・再生処理はその構成でも利用できます。

ローカルHTTPサーバーでAPIキーを使って確認する場合は、localhost や 127.0.0.1 など利用するホストの許可も必要です。サーバー用キーにIP制限を設定している場合は、送信元IPも確認してください。

関連