このトピックでは、Video Cloud Media API の概要を説明します。
Media API は、Video Cloud アカウント内のコンテンツおよびメタデータにアクセスするための REST ベースの API です。Media API は、REST ベースの API であるため、クライアントだけでなく、動的に生成した Web ページや、サーバーサイドの同期プロセスなど、Web アプリケーションのさまざまな場所からのアクセスが可能です。
アカウント内のメタデータに対する不正なアクセスを避けるために、API 呼び出しの際にパラメータとして渡すトークンによって、API へのアクセスは保護されています。他の Web ベースの API と同様に、Video Cloud によってトークンが生成され、ユーザーによって保護されます。
最初に必要なのは、ご使用のアカウント用のトークンを入手することです。Video Cloud Express エディションを $99 プランまたは $199 プランでご利用の場合は、Media API はご使用いただけません。Media API 読み取りメソッド用の読み取りトークンは Video Cloud Express エディションの $499 プランをご利用のお客様、また完全な Media API は Video Cloud Pro エディションと Enterprise エディションをご利用のお客様のみがご使用いただけます。
この概要では、次について学習し、Media API に詳しくなります。
REST、つまり Representational State Transfer は、リモート システムに格納されたデータに HTTP 経由でアクセスする標準的な方法です。SOAP とよく似ており、Web サービスに利用されているテクノロジの 1 つです。リモート システムの状態（または情報）の送信に関する処理を排除するのが、その主な機能です。コードで把握しておくべきことは、送り返されるデータのフォーマットのみです。
Media API には、読み取りメソッドと書き込みメソッドがあります。
find_all_videos であり、個別の動画のメタデータを含む VideoDTO のリストを返します。返されるデータは JSON 文字列か MRSS 形式の XML にフォーマットされています。JSON（JavaScript Object Notation）は複雑なオブジェクトを文字列として送信する軽量な方法です。現在では、JSON 文字列をパースしてネイティブ オブジェクトにするためのライブラリが、ほぼすべての言語において数多く公開されています。MRSS（Media Really Simple Syndication）は RSS モジュールの一種で、マルチメディア ファイル（音声、動画、画像）を RSS フィードでシンジケートするのに使用します。create_video であり、動画ファイルを関連のあるメタデータと共に渡して、Video Cloud アカウントに動画を作成することができます。REST を使用したメソッドの呼び出しは、基本的には Video Cloud サーバー上の特定の URL に対する HTTP GET 要求（読み取りメソッド）または POST 要求（書き込みメソッド）となります。要求は、呼び出しメソッド名と入力引数で構成され、URL のパラメータとして渡します。HTTP 応答の本体には、上記の HTTP 呼び出しの結果が、JSON 文字列または MRSS 形式の XML として含まれています。Media API 呼び出しはすべて、ベース URL http://api.brightcove.co.jp/services を使用します。IP アドレスによる Video Cloud サービスへのアクセスはサポートされていないので、必ず回避してください。Video Cloud の IP アドレスは、予告なしに変更される場合があります。変更されると、IP アドレスによりアクセスしようとするシステムは必ず失敗します。
弊社の日本の合弁事業であるブライトコーブ株式会社のお客様は、Media API にアクセスするために異なる URL を使用する必要があります。Media API 呼び出しはすべて、http://api.brightcove.co.jp ではなく http://api.brightcove.co.jp から始める必要があります。
メソッドの呼び出しにはトークンも必要です。トークンは、Video Cloud から各アカウントに対して発行され、API を使用したアカウントへのアクセスを可能にします。API の読み取りメソッド用と書き込みメソッド用に、別々のトークンがあります。トークンは、such as token=[tokenString] という URL パラメータとして、呼び出しに付加します。tokenString は URL エンコードしたトークンです。通常、Media API トークンの末尾は 1 つ以上のドット (.) であることに注意してください。API トークンを使用するときは、必ずこのドットも入れてください。カット アンド ペーストをすると、忘れることが多いようです。Video Cloud Studio の [アカウント情報] の [アカウント設定] にある [API 管理] ページで、API トークンの表示および管理ができます。また、トークンを電子メールで送信したり、トークンをクリップボードにコピーするボタンも備わっています。トークンに関する詳細は、「Media API トークンの管理」を参照してください。
例えば、アカウント内のすべての動画を取得するには、以下のような HTTP 要求を行います。
http://api.brightcove.co.jp/services/library?command=find_all_videos &token=0Z2dtxTdJAxtbZ-d0U7Bhio2V1Rhr5Iafl5FFtDPY8E.
この要求は実際に機能します。ここをクリックして試してください。すぐに呼び出し結果の画面出力を確認できます。これは生の（raw）メソッド呼び出しです。処理およびフォーマットされていないデータが返されます。サンプルでは、返されたデータを受け取り、アプリケーションで使いやすいように整形する方法を紹介しています（注: この呼び出しでは、デモ用のアカウントを使用しています。自分のアカウントを使うには、&token 引数を自分の読み取りトークンに置き換えてください）。
Media API の要求はシンプルな HTTP 呼び出しなので、アプリケーションのどこにでも組み込むことができます。一般的な Web、サーバーサイド、クライアント サイドの言語には、HTTP 要求を行う構文があります。それを使用して、API 呼び出しをアプリケーションに組み込みます。さらに、Video Cloud に精通した開発者が、一般的な Web 志向言語のほとんどについて SDK（ソフトウェア開発キット）を開発しています。これは、アプリケーションにネイティブ クラスとして組み込むことができ、API へのアクセスが容易になります。利用可能な Media API SDK の最新リストは、Video Cloud SDK を確認してください。さらに、1 ヶ所で Video Cloud プラットフォーム用の様々なアプリケーション、SDK およびツールをホストする、コミュニティがサポートするイニシアティブ、Open Source @ Brightcove を確認してください。
例えば、ページのロード時、ユーザーによるボタン クリック時など、イベントが発生した場合に、要求はオンデマンドで行われることになるでしょう。そのためには、HTTP 要求を関数でラップし、onClick などのプログラム上のイベントに対する処理として呼び出します。応答を処理する必要もあります。また JavaScript を使用していない場合は、データを処理するために、JSON 文字列や MRSS 出力をパースして、ネイティブ オブジェクトにセットする必要があります。JSON は、特定の順序で確実にデータを返すとは限らないことに気をつけてください。使用したいフィールドを捕捉するために、JSON パーサーを使用することを推奨します。
Write API メソッドを使用すると、ご利用のコンテンツ管理システムに Video Cloud アカウントを統合するクライアント アプリケーションを作成できます。または、ローカルで実行され、クライアントと Video Cloud 間にサーバーを必要としないデスクトップ アプリケーションを作成できます。さらに、Flash の HTTP スタックを利用した Flash クライアントというアーキテクチャも可能です。また、Adobe の新しいデスクトップ クライアントである AIR を使用して、Flash によるデスクトップのアップローダ アプリケーションを作成できます。
find_all_videos などの基本的な読み取り API 呼び出しは、パラメータを付けることで、詳細な指定が可能です。「API リファレンス」に一覧がありますが、ここではできることをいくつかご紹介します。
create_video などの基本的な書き込み API 呼び出しには、作成しようとしている動画のメタデータを追加するためのパラメータがあります。書き込み API には、プレイリストを作成、更新、削除したり、キュー ポイント、画像、ロゴ オーバーレイを作成するためのメソッドもあります。
JSON 文字列の処理をするときには、適切な JSON 構文を使用してください。文字列値は引用符で囲みますが、数値やブール値は囲みません。以下の例では、create_video、token、および filename は文字列ですが、create_multiple_renditions はブール値です。
{"method": "create_video",
"params": {"token" : "riBfgveLvpRb-rHGiBBouSAXs-Q8NmphGxt0z04kE.",
"video" : {"id":38,"name":"Cookies!","shortDescription":"yumyumyumyum tasty!"},
"filename":"miamiMoon.mov",
"create_multiple_renditions" : true}}
使用するメソッドの正しいシグネチャについては、「Media API リファレンス」および「Media API サンプル」を確認してください。JSON の詳細については、json.org を参照してください。
パフォーマンス向上のため、API 呼び出しは Video Cloud サーバーにキャッシュされます。呼び出しが行われると、まずキャッシュをチェックします。その呼び出しがキャッシュされていない、またはキャッシュの期限が切れている場合は、呼び出しは直接データベースに送られます。そして Video Cloud は結果を送り返し、キャッシュに入れます。キャッシュは 5 分後に期限切れになります。この時間内に再度呼び出しを行うと、結果はデータベースではなく、キャッシュから返されます。
キャッシュでは、Video Cloud Studio やバッチ アップロードによりライブラリが変更されることを考慮していません。呼び出しに影響する変更がライブラリに対して行われても、キャッシュの期限が切れるまで、呼び出しの結果には反映されません。コードをテストする際には、このことを考慮してください。正しい結果が得られない場合でも、API は正しく機能していることがあります。
API では、video_id が存在しない、などのよくあるエラーを捕捉し、コーディングしやすい方法で処理しようとします。エラーのほとんどは以下のように、エラー パラメータとともに JSON 文字列で返されます。
{"error": "an unknown error occurred while processing your request","コード":100}
出力が MRSS の場合、エラーは、エラー コードとメッセージとともに <error> 要素に入ります。
エンド ユーザーに暗号めいたメッセージやブランク ページを見せることがないように、できるだけ、コーディングでエラーを適切に処理するよう努めてください。（応答を JSON でパースした後）結果オブジェクトの「エラー」パラメータを処理することによって、何が不都合なのかわかります。エンドユーザーのためにエラー メッセージを作成することにより、それに適切に対処できます。
Media API が返すエラー メッセージには、タイプによってエラーを分類する、数字のエラー コードが含まれています。詳細は、「エラー メッセージ リファレンス」を参照してください。
トークンがあるとライブラリにアクセスできてしまうため、トークンを安全に保管してください。クライアント サイドの API 呼び出しを検討している場合には、特に重要です。Web の訪問者は誰でも「ソースを見る」ことで、API トークンを見ることができます。トークンを利用するとメタデータを取得することができ、そこにはアセットへの直接のリンクが含まれている可能性もあります。
トークンを安全に保つための詳細や戦略については、「Media API: セキュリティのベスト プラクティス」 を参照してください。
一般に、Video Cloud Studio Media モジュールで動画またはプレイリストに対してできることはすべて、Media 書き込み API を使用しても可能です。ですが、少数の例外があります。動画の次のプロパティは、Media 書き込み API を使用して設定または修正することができません。
Media API を使用する様々な方法を示すために、「多くの Media API の例」を作成しました。「Media API リファレンス」にも使用例があります。
Media API の概要を把握できたので、Media API に関する別のドキュメントも確認してください。