FTP バッチ プロビジョニング：XML マニフェストのリファレンス

これは、FTP バッチ プロビジョニング XML マニフェスト ファイルのリファレンス ドキュメントです。XML マニフェストは、Video Cloud の FTP バッチ プロビジョニング機能を使用する際に作成する必要があります。このドキュメントには、XML マニフェスト ファイルに含める必要がある必須の XML 要素および属性の詳細仕様およびコード サンプルを記載しています。さらに、アセットのアップロード、動画の作成や更新、動画の再エンコードおよび他の多くのオプションなど、XML マニフェスト ファイルで様々な動作を行うための仕様が含まれています。

このトピックでは次の項目について説明します。

• なぜ FTP バッチ プロビジョニングを使用するのか
• 前提条件
  
• XML マニフェスト ファイルを検証する
• XML マニフェストの文書構造
  • XML 文書であることを明示する
  • XML マニフェスト ファイルの開始タグ
  • 通知電子メールまたは HTTP コールバックのアドレス
  • FTP バッチ プロビジョニング XML マニフェスト ファイルで行う一般的なアクション
    • アップロードするアセットを指定する
    • title 要素を使用して動画を作成または更新する
    • 既存の動画を再エンコードする
    • lineup 要素を使用してプレイリストを作成または更新する
    • キュー ポイントを作成する
    • アセット、動画、プレイリスト、またはキュー ポイントを削除する
  • XML マニフェスト ファイルの終了タグ 

なぜ FTP バッチ プロビジョニングを使用するのか

バッチ プロビジョニング機能を利用すると、XML マニフェスト ファイルと Video Cloud の FTP サーバーを使用して、多数の動画やプレイリストを一括アップロードし、プロビジョニングすることができます。パブリッシャは、FTP バッチ プロビジョニングを頻繁に使用し、Video Cloud での動画公開とコンテンツ管理システム（CMS）の統合、または Video Cloud の公開サービスに動画の初期取り込みを行います。

前提条件

先に進む前に、以下の前提条件を満たしていることを確認してください。

• FTP バッチ プロビジョニングが利用できるのは、Video Cloud Pro エディションと Enterprise エディションをご購入の方のみです。Video Cloud アカウントのアップグレードについては、ブライトコーブにお問い合わせください。
• XML に関してまだ学習中の場合、「FTP バッチ プロビジョニングを使用する」の基本リソースのリストを読むか、次の動画をご覧ください。
  動画チュートリアル：XML 紹介
• 概要情報と前提条件の詳細は、「FTP バッチ プロビジョニングを使用する」を参照してください。このドキュメントの右上側にある関連リンク リストも参照してください。
• FTP バッチ プロビジョニング XML マニフェスト ファイルの例。XML マニフェスト ファイルを使用して動画をアップロードする方法を確認するために、この簡単な例をダウンロードします。このファイルを開き、この記事を読みながら確認します。このファイルを使用する場合、自身のアカウントおよび環境設定で動作するように、ファイルを変更する必要があります。

XML マニフェスト ファイルを検証する

FTP バッチ プロビジョニング ドキュメント タイプ定義（DTD）と対照して XML マニフェスト ファイルを検証できます。バッチ プロビジョニング ドキュメント タイプ定義（DTD）をダウンロードします。

XML マニフェスト ファイルを検証する前に、エスケープする必要のある無効な文字が含まれていないようにすることは非常に重要です。このような文字が含まれている場合、アップロード プロセスが失敗し、使用できないアセットが発生するおそれがあります。XML マニフェストが「整形式の XML 文書」であるかどうかを検査するユーティリティを実行すると、このような文字が存在している場合に検出することができます。XML における無効な文字の XML マニフェスト内での記述方法を次に示します。

• & は && と記述します。
• < は &lt;、 > は &gt; と記述します。
• ' は &#39;、" は &quot; と記述します。

これらの制約事項が適用されるのは、XML 要素の属性値を指定する場合です。XML 要素の CDATA セクションでは、これらの文字をそのまま記述できます。次の例において、「Réné & moi」というフレーズが <title name > 属性、および <short-description> 要素の CDATA セクションでそれぞれどのように記述されているかを比較してください。

<title name="R&#233;n&#233; &amp; Moi" refid="myVideo" active="TRUE" video-full-refid="asset2">
<short-description>
<![CDATA[
Réné et moi remarquons qu'il est tellement romantique,
de manière énigmatique, de se tenir debout sur la terrasse
à Chichen Itza et d'observer la montée de la lune gibbeuse!
]]>
</short-description>
</title>

XML マニフェストの文書構造

次のセクションでは、XML マニフェスト ファイルの構造について説明します。また、必要な構文およびこのファイルと FTP バッチ プロビジョニング システムで実行できるオプションのアクションについて説明します。

XML 文書であることを明示する

必須。この先頭タグは、その文書が XML 文書であることを示すものであり、次の通りに記述します。

<?xml version="1.0" encoding="utf-8"?>

XML マニフェスト ファイルの開始タグ

必須。これは Video Cloud 固有のタグであり、アップロード マニフェストの開始を意味します。

例

<publisher-upload-manifest publisher-id="101" preparer="3rd Street Video" report-success="true">

publisher-upload-manifest タグの属性は次の通りです。

publisher-upload-manifest タグ内に、次の各要素を指定できます。それぞれの要素の詳細については、このトピックで後述します。

通知電子メールまたは HTTP コールバックのアドレス

任意。notify タグでは、通知電子メールの送信先となるアドレスを指定します。このタグは必須ではありませんが、エラーが発生した場合に、組織の誰かに通知されるようにすることはベストプラクティスです。デフォルトでは、電子メール通知はアップロード処理が失敗した場合にのみ送信されます。ただし、publisher-upload-manifest タグ内で report-success="TRUE" と指定すれば、アップロード処理が成功した場合にも送信されます。通知を複数の電子メール アドレスに送信するには、電子メール アドレスごとに notify タグを指定します。電子メール通知は、アドレス donotreply@brightcove.com から送信されます。そのアドレスからの電子メールがスパム フィルタを通過するようにしておいてください。

例

<notify email="you@example.com"/>
<notify email="me@example.com"/>

notify タグの属性は次の通りです。

notify タグの属性

電子メールによる通知を受信する他に、callback タグを使用して、Web ページにアップロード通知を送信できます。電子メール通知は、callback タグの entity-url 属性で指定した URL アドレスに、POST メソッドを使用して送信されます。POST メソッドで送信される情報は次の通りです。

referenceId=<the reference id provided in the manifest> 
id=<the id of the title, playlist, or asset in the database> 
entity=<VIDEO, LINEUP, or ASSET> 
action=<CREATE、DELETE、or UPDATE> 
status=<FAILED,SUCCESS> 
error=<an error message>

ステータスは、コールバック ポスト内に必ず追加されます。ステータスが FAILED の場合、その他の情報がコールバック ポスト内に追加されることがあります。追加されるかどうかは、処理が失敗した時点でその情報を取得できたかどうかで決まります。FTP バッチ プロビジョニング システムで HTTP コールバック機能を使用する方法のこの例を参照してください。PHP を使用して、FTP バッチ プロビジョニングによって生成されたデータからログ ファイルを作成します。

例

<callback entity-url="http://example.com/batch-callback.php"/>

callback の属性

FTP バッチ プロビジョニング XML マニフェスト ファイルで行う一般的なアクション

次のセクションでは、FTP バッチ プロビジョニング XML マニフェスト ファイルで行う様々なアクションについて説明します。コンテンツの必要に応じて、単一の XML マニフェスト ファイル内で、複数のアクションまたは単一のアクションを実行できます。

アップロードするアセットを指定する

任意。asset タグでは、XML マニフェスト ファイルを通じてアップロードするファイルを指定します。asset タグは、アップロードするファイルごとに指定します。

例

<asset filename="MyVideo.flv"
       refid="asset1"
       size="188812"
       hash-code="a4ade1e2b09d517ff7360f91527639b3"
       display-name="My Video (FLV)"
       type="VIDEO_FULL"/>

asset タグの属性は次の通りです。

asset タグの属性

リモート アセットを使用している場合には、アセットを識別するために asset タグではなくremote-asset タグを使用します。リモート アセットの使用および remote-asset タグの属性に関する詳細は、「リモート動画ファイルで動画を作成する」を参照してください。

title 要素を使用して動画を作成または更新する

任意。title タグでは、作成または更新したい動画を指定します。title タグは、XML マニフェストでアップロードする動画ごとに指定します。

例

<title name="My Title"
       refid="title1"
       active="TRUE"
       start-date="01/01/2007 12:00 AM"
       end-date="01/01/2007 12:00 AM"
       video-full-refid="asset2"
       thumbnail-refid="asset4"
       video-still-refid="asset5"
       flash-prebumper-refid="asset6"
       shared="true"
       economic-type="AD"
       ad-keys=";key=value;key=value" >
    <short-description>My  short description.</short-description>
    <long-description>My long description.</long-description>
    <related-link-url>http://your-company.com/</related-link-url>
    <related-link-text>Come learn about us!</related-link-text>
    <tag>funny</tag>
    <tag>entertaining</tag>
    <logo-overlay
         asset-refid="12345" 
         click-thru="http://www.example.com" 
         tooltip="Go to Example" alignment="bottom right" />
</title>

title タグ内では、属性と子要素を指定します。これらの属性および子要素は、Media モジュールの [Edit Video] ダイアログの各フィールドに対応しています。ただし、Video Cloud Studio で動画を編集することにより、常に広告リクエストを行うよう動画を設定することができますが、FTP バッチ プロビジョニングを使用してこの操作を行うことはできません。

title タグの属性

title タグの子要素

title タグ内で指定できる子要素は次の通りです。

logo-overlay タグの属性

任意。XML マニフェスト ファイルを使用して、ブランディングのため動画ウィンドウ上に配置する画像を指定したり、logo-overlay タグを通して指定された場所にトラフィックを誘導できます。ロゴ オーバーレイも参照してください。logo-overlay タグの属性は次の通りです。

既存の動画を再エンコードする

任意。XML マニフェスト ファイルを使用して、動画のメタデータをすべて保持しながら、動画の動画ファイルを再エンコードするよう Video Cloud に指示することができます。再エンコーディングのソースとして Video Cloud メディア ライブラリの既存のソース ファイルを使用したい場合は、トップ レベルの publisher-upload-manifest 要素の子として reencode-from-existing-source 要素を使用します。XML マニフェストで新しい（おそらくさらに高品質の）ソース ファイルを提供する場合は、reencode-from-new-source 要素を使用します。「既存動画の再エンコーディングについての詳細」をご覧ください。

reencode-from-existing-source 属性

<manual-lineup
    name="My Manual Lineup"
    refid="lineup1"
    thumbnail-refid="asset4"> <title-refid>title1</title-refid>
  <title-refid>title3</title-refid>
  <title-refid>title137</title-refid>
</manual-lineup>

<automatic-lineup name="My Automatic Lineup"
    refid="lineup2"
    type="NEWEST_TO_OLDEST"
    tag-filter="AND"
    title-limit="50"
    thumbnail-refid="asset4">
  <title-tag>sporty</title-tag>
</automatic-lineup>

<cuepoint name="My Cue" type="CODE" time="500000" video-refid="video001" />
<cuepoint name="My Other Cue" type="AD" time="50000" video-refid="video001" />
<cuepoint name="My Third Cue" type="AD" time="120000" video-refid="video001">
  <metadata>Something interesting about this cue point.</metadata>
</cuepoint>
<cuepoint name="My Fourth Cue" type="AD" time="270000" video-refid="video055">
  <metadata>
    <![CDATA[
This is a multi-line Set of metadata
    ]]>
  </metadata>
</cuepoint>

<delete-asset refid="RandomAssetsRefID"/>
<delete-title refid="RandomTitlesRefID"/>
<delete-lineup refid="RandomLineupsRefID"/>
<delete-cuepoint video-refid="video0001" id="0123456789"/>

</publisher-upload-manifest>