REF-API でビデオコンテンツを再生する方法

下記の手順で、ITK 初心者が HTML / JavaScript アプリを使用して最初のビデオコンテンツを再生できるようになります。

前提条件

開始する前に、下記の事項が必須です。

【必須】：最初に ”ITK Sandbox と discover REF-API の利用を開始する” を完了してください。
上記を完了後、 sandbox ユーザは REF-API 中のどの API でも使うことができるようになるはずです。

【必須】：ご自身のアプリ（ APACHE, XAMPP ）をローカルでテストするためにローカルサーバをインストールすること
ローカルサーバは、URI リダイレクションに基づき、認証を実行するために必須です。
インターネット上でフリーのサーバを簡単に見つけることができます。まずはこちらのリンクを開いてみてください。
https://www.maketecheasier.com/setup-local-web-server-all-platforms/

【必須】： REF-API の特徴
この API の特徴はこちらでご確認いただけます。
https://anypoint.mulesoft.com/apiplatform/apx/#/portals

【オプション】： Infinite Toolkit プレゼンテーション
こちらのリンクを開いてください。： https://developer.cisco.com/site/infinite-toolkit

【オプション】もし、ご自身が CORS がどのように動いているか知りたい場合は、
こちらのリンクを開いてください。： https://en.wikipedia.org/wiki/Cross-origin_resource_sharing

ステップ２－ Sandbox API でイベントを検索する
重要：ビデオを再生するまでに常に２ステップ必要です。

1. イベントを見つけても、チャンネルグリッドか VOD カタログを表示する。
2. 前のステップで選択した１つのイベントからプレイセッションを作成する。
このセクションでは、チャンネルエンドポイントからのチャンネルリストについてどのように情報を取得するのかご説明します。
そのために、REF-API を使用した sandbox を選択する必要があります。
sandbox リストは、こちらで利用可能です。https://anypoint.mulesoft.com/apiplatform/apx/#/portals
”sandbox” というキーワードを使うことで、最新のバージョンを見つけることができます。

メインページの左側では、sandbox から提示されたメイン機能についての情報が利用可能です。
このラボでは、まず最初にチャンネルブラウジングユースケースについてご一読ください。
それから、全ての API とクエリパラメータが説明されている API リファレンスセクションに遷移してください。

チャンネルブラウジングユースケースセクションでは、
基本的なケース／チャンネルコマンドを確認することができます。

API リファレンスセクションでは、
チャンネルエンドポイントを見つけ、”GET” ボタンを押下してください。

チャンネルセクションでは、ユーザは下記の項目について、見つけることができます。
API name
API の目的についての簡単な説明
この API にサポートされたクエリパラメータのリスト
このリクエストを試すための ”TRY IT” ボタン
サポートされたエラーコード
スタンダードアンサーの例

ステップ３－”/channels” エンドポイント
Live TV チャンネルリストを取得する最も一般的な API は
/channels
ご自身が有効なトークンをもってるか確認したら、POSTMAN で下記の GET コマンドを入力してください。
（もし、トークンの問題に直面している場合、ラーニングラボ101のトークンの取得についてを確認してください。）
https://apx.cisco.com/spvss/infinitehome/ivptoolkit/clientrefapi/sandbox_0.4.1/channels?limit=3
これは、sandbox チャンネルリストの最初の３つのチャンネルについて JSON のアンサーを返します。
”count” は、アンサー内でチャンネル数を返します。
”total” は、利用可能なチャンネル数の総数です。
"channels[]" はチャンネルのアレイです。
{
"count": 3,
"total": 5,
"channels": [
{
"id": "150747",
"name": "FOODHD",
"logicalChannelNumber": 91,
"isFavorite": false,
"media": [
{
"type": "regular",
"mimeType": "image/jpg",
"url": "http://origin.ztv.systems/logo/foodhd.jpg"
}
]
},
{
"id": "187925",
"name": "NEWSMAX",
"logicalChannelNumber": 92,
"isFavorite": false,
"media": [
{
"type": "regular",
"mimeType": "image/jpg",
"url": "http://origin.ztv.systems/logo/newsmax.jpg"
}
]
},
{
"id": "193393",
"name": "KIDSCEN",
"logicalChannelNumber": 93,
"isFavorite": false,
"media": [
{
"type": "regular",
"mimeType": "image/jpg",
"url": "http://origin.ztv.systems/logo/kidscentral.jpg"
}
]
}
]
}

チャンネルの下記のメタデータは、チャンネルメタデータの一部として提供されます。

Channel ID
Name （チャンネルの）
Logical channel number
Favourite status
Channel logo

ステップ４－プレイセッションを作成する
特定のコンテンツのプレイセッションを作成するために、クライアントは下記の手順を行う必要があります。

1. 再生するコンテンツのプレイセッションハイパーリンクを取得する
2. プレイセッションハイパーリンクを POST し、オプションとしてセッションを作成するクエリ内でプレイポジションを提供する。
レスポンスは、playUrl ハイパーリンク、tearDown ハイパーリンクと keeoAlive ハイパーリンクを含みます。
トランスコードされるストリーミング中のコンテンツ向けに、transcodeProfile が提供されている必要があります。
オプションとしてストリーム中のトランスコードされたコンテンツ向けに、アウトプットストリーム内で提供されるべきaudioLanguage と subutitleLanguage を選択することができます。
一旦クライアントがプレイセッションを作成すると、playUrl を使ってストリーミングデータの取得を開始できます。
トリックモードはクライアントベースになっていますが、クライアントがトリックモードを実行するために基礎にあるトランスポートメカニズムを使う必要があります。
例：
チャンネル ID**** に応答する HLS フォーマットで再生可能な URL を取得するために
POST モードの POSTMAN で下記のコマンドを使います。
https://apx.cisco.com/spvss/infinitehome/ivptoolkit/clientrefapi/sandbox_0.4.1/devices/me/playSessions?channelId=150747

下記の JSON アンサー内で再生可能なURLを取得します。

次のセクションで HLS のようなストリームされたコンテンツがどのようにプレイバックされるかを確認します。

（ HLS=Http Live Stream ）

REF-API は様々なタイプのビデオコンテンツを提供します。
-ライブTVチャンネル１
- VOD アセット（VOD = ビデオオンデマンド）
- CDVR レコード(CDVR= Cloud Digital Video Recorder)

生き残りのセッション
クライアントはコンテンツのプレイバック中に残り続けるセッションを保持する役割があります。
プレイセッションは、呼び出される POST メソッドである keepAlive と hyperlink URL の実行の頻度を決定することによりサーバを ping するための情報を提供します。
このハイパーリンクはテンプレート化されていません。
デリートセッション
クライアントがセッションからの仕様が完了した際に "playSession" を削除されるはずです。
デリートセッションはさらにオプショナルパラメータである playPosition をクライアントに投げさせることを許可することで contentInstance 内で lastPlayPosition を store/update するメカニズムを提供します。

最後に再生されるポジションマネジメント
クライアントは与えられたコンテンツの最後に再生されるポジションにアクセスします。システム中に保存されているコンテンツの開始から時間を表示します。

セッションの失敗

サーバは、playSession が再生するために許可されているかチェックします。例えば、サーバは全てのポリシーがデバイス上でプレイバックするための条件に合っているかチェックします。
このチェックは、playSession の生成時間で実行されています。
playSession の生成が失敗するか異なる条件があります。
プレイセッションがポリシーのために作成されない時は、HTTP403 エラーがエラー理由が記載された追加のペイロードとともに返ってきます。
エラーコードと詳細は REF-API の仕様において利用可能です。
どの情報が RFP API によって与えられたかについて初めて経験したかと思います。
asset
live channel
metadata
play session

これらの情報を表示する最初のアプリケーションを使ってみましょう。

ステップ５-「チャンネル」アンサーを表示するサンプルアプリケーション

REF-API は管理可能で様々な実装で様々なデバイス上に表示される JSON を返します。
全てのブラウザ上で実行中の HTML5 / Javascriptアプリケーション
Angular アプリケーション
Amazon Fire や Nexus プレイヤーで実行中の Android アプリケーション
全ての Mac デバイス上で実行中の IOS アプリケーション
最初の実装でデバイス最大数をカバーしたいときは、
同じデバイス、ラップトップ、OC や STB 上で簡単に実行できる HTML5 で開始しましょう。
こちらはどのように HTML5 / Javascript アプリケーションでチャンネルリストのメタデータを表示する方法です。

下記の機能はサンプルアプリケーションで使われており、少し説明が必要です。
Bootstrap は、スクリーンデバイスに適応するためのプログレッシブなデザインです。
Accordion はアプリケーションのアクティブで部分にフォーカスしています。
CORS contraint は HTML5 ブラウザでクロスドメインの互換性があります。

5.2　ブートストラップ

ブートストラップはデスクトップ、タブレットとモバイルスクリーンディスプレイに適応するパワフルに反応するデザインを実現する CSS 、HTML と Javascript フレームワークです。

ブートストラップレスポンシブデザインの多くのプレゼンテーションはウェブ上で確認することができ、こちらにいくつかリンクがあります。

https://www.sitepoint.com/responsive-web-design-tips-bootstrap-css/

http://getbootstrap.com/2.3.2/scaffolding.html

5.3　アコーディオン

アコーディオンはパネルを開閉するのに便利な方法です。
アプリケーションのアクティブな部分にフォーカスできるため、マルチデバイス実装にとても適しています。
この機能はもともとブートストラップパッケージに含まれてます。
サンプルアプリケーションは４つのパネルを管理しています。
最初のパネルはトークンステータス専用です。
認証で問題が発生した際に自動的に開きます。
しかし、トークンの有効期限についての情報を取得するために、手動で開くこともできます。

2つ目のパネルは、チャンネル情報専用です。

３つ目の情報は高度なクエリパラメータで JSON アンサーを読み取るためにエリアを知らせます。

4つ目のパネルは、ナビゲーションリンク専用です。

5.4 CORS

Cross-Origin Resource Sharing ( CORS ) は、ブラウザからのクロスドメインコミュニケーションを可能にする機能です。
XMLHttpRequest オブジェクトのトップに構築することで、CORS はクライアントアプリケーションが base URL とは異なるドメインリクエストにアクセスすることを可能にします。
プリフライトアンサーリクエストは、そのヘッダーにある Access-Control-Allow-Origin についての情報を保持しています。
Access-Control-Allow-Originーこのヘッダーは、全ての有効な CORS レスポンスに含まれていなければならず、ヘッダーを省略することは、CORS リクエストの失敗を引き起こします。ヘッダーの値は、次の値として扱うことが可能です。
リクエストを送るための認証済みのドメインリスト
もしくは、どこからのリクエストも許可するもの

下記のリンクで CORS についての詳細情報をご確認できます。

https://en.wikipedia.org/wiki/Cross-origin_resource_sharing

警告：
CORS 問題はサーバ側にあります。
もし、予測された CORS 情報 **Access-Control-Allow-Origin** がヘッダーに見つからない場合
クライアントアプリケーションは、その問題を回避できません。

ステップ6－「チャンネルリスト」サンプルアプリケーション（ HTML5 ）を使う

6.1　サンプルアプリケーションをインストールする
Windows 上で：管理者権限でコンソールを開く（ Windows キー＋Xを押下）
下記のコマンドで GIT からソースコードファイルをインストールする。
git clone -c core.symlinks=true git@github3.cisco.com:InfiniteToolkit/SampleApps_HTML5.git
”localhost” からソースコードにアクセスすることでローカルサーバを開始する。
ご自身のブラウザからチャンネルリストを開始する。
http://localhost/SampleApps_HTML5/sampleAppsHtml5/channelList/index.html

備考：管理者モードで git clone を実行することは Windows 上でシンボリックリンクを作成することができるようにするために必要です。この問題は Unix や Mac では見受けられません。

チップ：もしソースコードを修正せずにサンプルアプリケーションを実行することだけに興味がある場合、
こちらからアクセスできます。
http://sample-apps.spvss-infinitetoolkit.ciscolabs.com/
クライアント ID を取得するのにリダイレクト URL で Mulesoft アプリケーションを作成することが必要です。
redirect_uri=http://sample-apps.spvss-infinitetoolkit.ciscolabs.com
6.2　サンプルアプリケーションを設定する。

'Token Information'パネルを開き、ご自身のクライアント ID の値を入力してください。
RESET TOKEN' ボタンを押下してください。
チャンネルリストがご確認できるはずです。
もし、できない場合はアクセストークンの問題があります。'RESET TOKEN' ボタンを再度押下してください。

6.3　サンプルアプリケーションデザイン

css: Change Style Sheet を含みます。
フォント：アコーディオオングリフを使ったスペシャルフォントを含みます。
js: JavaScript ファンクショナルライブラリを含みます。
チャンネルリスト：HTML サンプルと関連コントローラを含みます。
tokenManager：パブリックツールとトークンマネジャーを含みます。

6.4　プレイバックスクリーン

Watch Channel 92' ボタンを押下する際に、プレイセッションが生成され、アプリケーションはプレイバックモードに切り替わります。

HLS スタンダードはサンプリアプリケーションを使った VideoJS プラグインによってサポートされています。
https://github.com/videojs/videojs-contrib-hls
HSL のメイン機能は、クライアント側で利用可能な接続帯域に応じて適応型ビットレートを提供することです。
ビデオコンテンツは専用のほぼフルスクリーンのインターフェースで再生されます。
現在の sandbox 向けに、ビデオコンテンツは HSL フォーマットで利用可能です。
Youtube で使われているものと同様のビデオコントロールは実行可能です。

ステップ７－高度なクエリパラメータを使用する
高度なクエリを選択する。
応答タブでクリックし、"Advanced Query Parameters" パネルを開きます。

/channels API がシンプルなように、２つのパラメータだけが適用されます。

offset: アンサーの最初のエレメンツを置き換えます。
limit: アンサーのエレメント数をセットします。

一度これらの２つのフィールドに数値を入力し、
'SUBMIT REQUEST' ボタンを押下し、クエリを実行してください。
JSON アンサーは、JSON Preview トグルボタンを押下することで表示と非表示を切り替えることができます。
REF-API 機能からクエリパラメータリストを取得する。

警告：
実装でクエリの長時間実行を避けるためにoffsetパラメータは255に制限されています。

ステップ８－ 'VOD catalogue' サンプルアプリケーション（ HTML5 ）を使用する。
'VOD catalogue' はチャンネルリストと同じ git リポジトリ内でも利用可能なもう一つのサンプルアプリケーションです。

8.1　サンプルアプリケーションのインストール

このステップはすでに 6.1で実行されてます。
ご自身のブラウザ内で URL を使ってください。
localhost://SampleApps_HTML5/sampleAppsHtml5/vodCatalogue/index.html

8.2　サンプルアプリケーションの設定
6.2で生成されたアクセストークンは、さらに VOD カタログアプリケーションで有効です。
クライアント ID を再度設定する必要がなく、この情報は次のブラウザセッションで取得するために保持され続けます。
しかし、1時間後にそのトークンは無効となり、ユーザは新しいトークンを取得するために ”Renew Token” ボタンを押下する必要があります。

備考：アプリケーションで、無効な日が検出された際にトークンのリフレッシュが自動的に開始されます。
アクセストークを取得するために OAuth2 認証を使った各アプリケーションのリダイレクトURLを追加する際は
注意してください。
localhost://SampleApps_HTML5/sampleAppsHtml5/channelList/index.html

8.3　サンプルアプリケーションデザイン

注意：全てのアプリケーションはCCフォント、js と toleMmanager コードをシェアしています。

これは各アプリケーション、ローカルシンボリックリンクが上の階層のモジュールを参照している理由です。
css: Change Style Sheet を含む
フォント：アコーディオングリフを表示するために使われているスペシャルフォントを含みます。
js： JavaScript ファンクショナルライブラリを含みます。
チャンネルリスト： HTML ページとチャンネルリストアプリケーションの JavaScript コントローラを含みます。
vodCatalogue: HTML ページと VOD カタログアプリケーション用の JavaScript コントローラを含みます。

tokenManager:パブリックツールとトークンマネジャーを含みます。

備考：
”チャンネルリスト” は '/channels' エンドポイントの結果を表示する例です。

VOD Catalogue は '/agg/content' エンドポイントの結果を表示する例です。
8.4　プレイバックスクリーン

'Rent it now' ボタンを押下する際に、プレイセッションが生成され、アプリケーションはプレイバックモードに切り替わります。

2つのナビゲーションボタンはユーザが ”Channel list” や ”VOD Catalogue” アプリケーションに遷移することを可能にします。
ビデオコントロールは、VideoJS プラグインによって決定されます。
Youtube 上で使われているものと同様のものがあります。
”Stop Player” ボタンはサーバ側で ”Delete play session” を呼び出します。
注意： delete play session はさらにプレイバックページを退出する際やブラウザを閉じる際に実行されます。

このセクションの記事

コメント