開発者コンソール

手順1: カタログファイルを作成する


手順1: カタログファイルを作成する

手順1では、アプリのメディアコンテンツ(映画、TV番組、特別番組、ミニシリーズ、番外編など)に関するメタデータ(タイトル、放映時間、公開年など)が格納されたカタログファイルを作成します。カタログファイルの作成では、カタログデータ形式(CDF)スキーマへの準拠が求められ、特定のXML構造に従ってメディアの記述を行わなければなりません。

カタログファイルの作成

自動プロセスを使用してファイルを作成します。それには、データベースから情報を取得し、そのデータをCDFに準拠したカタログファイルに変換するプログラムスクリプトを開発する必要があります。

一般に、ファイルを作成するには、まず、カタログXSLスキーマに関連するXMLとその概念についてよく理解する必要があります(カタログデータ形式(CDF)の概要を参照してください)。次に、CDFスキーマXSDファイルをダウンロードし、ロジックとルールをより詳細に理解します。また、要素のウェブページCDFサンプルZIPに含まれているコードサンプルを出発点として使用することもできます。ファイルを作成する際は、CDFリファレンスドキュメントを参照してください。

カタログファイルの例

以下の例では、項目(映画)を1つだけ格納し必須要素のみを使用するシンプルなカタログファイルを示します。

<?xml version="1.0" encoding="utf-8" ?>
    <Catalog xmlns="http://www.amazon.com/FireTv/2014-04-11/ingestion" version="FireTv-v1.11">
        <Partner>Everything Ever Made Filmworks</Partner>
        <Works>
            <Movie>
                <ID>MV-12345</ID>
                <Title locale="en-US">Edison Kinetoscopic Record of a Sneeze</Title>
                <Offers>
                    <SubscriptionOffer>
                        <Regions>
                            <Country>US</Country>
                        </Regions>
                    </SubscriptionOffer>
                </Offers>
            </Movie>
        </Works>
    </Catalog>

一般的なカタログファイルの構造

このセクションでは、CDFスキーマの構造とその要素について大まかに説明します(XMLに関する知識が十分にあることを前提として話を進めます)。

カタログファイルの最上位のアウトラインは、以下のように表すことができます。

<Catalog>
    <Partner> ... </Partner>
        <Works>
        ...
        </Works>
</Catalog>

Catalog(必須)は、全カタログファイルのルート要素です。

Partner(必須)は、コンテンツプロバイダーを識別する要素です。

Works(必須)は、ファイルの大部分を占める要素です。ライブラリ内のすべての映画やTV番組、各エントリに関して提供する情報、作品の視聴方法などの情報が含まれています。

Works要素には、子要素を必要な数だけ含めることができます(子要素は個別の作品(映画やTV番組)を表します)。Works要素に子要素がない場合は、利用できるコンテンツがなくなったと見なされ、インデックスから削除されます。

最も一般的な作品タイプの要素は以下のとおりです。

要素 説明
Movie 長編映画を表しますが、短編映画にも使用できます。
TvEpisode TvShowの単一のエピソード。通常、TvSeasonにも関連付けられます。
TvSeason TvSeasonは基本的な作品タイプの1つで、TvShowの単一のシーズンを表します。
TvShow シーズンとエピソードから成るテレビシリーズ。
TvSpecial テレビで放送されるイベントのうち、番組-シーズン-エピソードという従来のテレビ階層には該当しないイベント。
Extra クリップまたはトレーラー。単発の作品の場合もありますが、通常はほかの作品(外部の作品またはカタログ内の別の作品)に関連付けられます。

Movieは単独の要素です。TvShow、TvSeason、TvEpisodeは独立した要素ですが、IDで相互に関連付けられています(MiniSeriesとMiniSeriesEpisodeも同様です)。また、TvSpecialとExtraは単独の要素ですが、別の作品に関連付けることも可能です。詳細については、TV番組、シーズン、エピソードの関連付けを参照してください。

すべての作品に共通する要素

上記の作品タイプはいずれも、共通する要素を中心に構成されています。どのタイプでも、拡張に使用される固有の要素は1~5個程度です。共通する要素のうち、必須の要素はほんのわずかになります。

Work要素のアウトラインは、以下のように表すことができます。

<_WorkType_><Movie><TvSeason>など)
    <ID>
        <Title>
            <Offers>
</_WorkType_>

ID(必須)は作品の識別子で、開発者が指定します。各作品のIDはカタログ内で一意である必要があります。また、その作品を提供している間はIDを変更しないでください。ID要素は、TVエピソードをTV番組やシーズンの一部として指定する場合など、作品の要素どうしを関連付ける目的でも使用されます。

Title(必須)は作品のタイトルです(複数の言語で指定が可能)。

Offers(必須)には、ユーザーが作品を視聴できる方法(無料または定期購入)を指定します。時間やリージョンで制限を設けることも可能です。Offers要素には少なくとも1つの視聴方法を指定する必要があります。指定数に上限はありません。視聴方法には、以下の4つのタイプがあります。

視聴タイプ 説明
FreeOffer 作品をいつでも無料で視聴できます。視聴できる期間を指定することもできます。
SubscriptionOffer プロバイダーのサービスの会員が作品を視聴できます。

Offer要素のアウトラインは、以下のように表すことができます(省略可能な要素も含む)。

<_OfferType_><FreeOffer><SubscriptionOffer>など)
    <Regions>
        <WindowStart>
            <WindowEnd>
                <LaunchDetails>
                    <Price>(レンタルまたは購入のみ)
                        <Duration>(レンタルのみ)
</_OfferType_>

Regions(必須)には、設定した視聴方法を有効にする国を指定します。Regionsは必須要素です。少なくとも1つのCountryを指定してください。

WindowStartWindowEnd(どちらも省略可能)は、設定した視聴方法が有効な期間を指定する際に利用する要素です(どちらか一方または両方を使用してください)。WindowStartより前とWindowEndより後の期間中、設定した視聴方法はユーザーに表示されません。

LaunchDetails(省略可能)は、設定した視聴方法の画質、音声言語、字幕のオプションを指定する際に利用する要素です。また、これらのオプションを事前に構成した設定を使用して、作品を直接公開する際に利用できる特別なIDも定義することができます。

カタログに含まれる作品の利用可能状況に変更があった場合は、新しい視聴方法の情報と共に更新したカタログファイルを申請する必要があります。

映画、番外編、TV番組の詳細ページには、利用可能な視聴方法とコンテンツプロバイダーが表示されます。視聴方法は以下の順番で表示されます(変更の可能性あり)。

  • 無料コンテンツ
  • 定期購入型コンテンツ
  • 有料コンテンツ(購入またはレンタル)

すべての作品に共通する任意の要素

上記の必須および省略可能な共通要素を用いれば、有効なカタログファイルを作成することができます。

ただし、これらは利用できる要素全体の3分の1にすぎません。残りの共通要素の使用は任意で、より詳細な作品情報を提供する場合に役立つ要素になります。

たとえば、ジャンル、認定情報、キャスト・制作スタッフ、あらすじ、撮影スタジオ、画像、ユーザー評価などの情報を表示可能にする要素があります。すべての要素の一覧については、カタログデータ形式(CDF)スキーマリファレンスで確認することができます。

文字列についての留意事項

CDFスキーマでは、一部の文字列データ(作品のタイトルや説明など)がカスタマイズされたLocalizedStringタイプとして定義されています。ローカライズされた文字列を用意すれば、同じコンテンツをユーザーデバイスの言語設定に応じて提供することが可能です。このような文字列には、locale(標準型xsd:language)という必須属性が用いられます。以下に一例を示します。

<Title locale="en-US">Edison Kinetoscopic Record of a Sneeze</Title>

ローカライズされた文字列には、pronunciation(標準型xsd:string)という省略可能な属性もあります。この属性は、漢字を使用して文字列テキストを指定する日本語のカタログエントリ用です。日本語のソート順は、文字ではなく、(漢字からは特定できない)読み方に基づいて決まります。pronunciation属性には通常、発音の情報をひらがなで指定します。

作品タイプ固有の要素

作品タイプには、共通する要素に加えて、それぞれに固有の要素が1~5個あります。一般的に、これらの要素には2つの用途があります。 (1)最初の公開日または放送日を指定することと、(2)作品どうしを関連付けることです(TVのエピソードをTV番組に関連付けるなど)。

公開日は省略可能ですが、指定することをお勧めします。ReleaseDate(映画、TV番組、ミニシリーズの場合)またはOriginalAirDate(TVおよびミニシリーズのエピソードとTVの特別番組の場合)を利用すれば指定可能です。

番組、シーズン、エピソードを関連付ける要素は必須です。これについては次のセクションで詳しく説明します。

タイプ固有の要素の特記事項については、カタログデータ形式(CDF)スキーマリファレンスを参照してください。

TV番組、シーズン、エピソードの関連付け

TVエピソードは特定のTV番組の1シーズンの間に放映され、ミニシリーズは個別のエピソード(複数)で構成されています。番外編は、映画の予告編や舞台裏に関する情報を指します。TV特別番組はTV番組と関連はありますが、通常の連続物には含まれません。

CDFには、これらを関連付けるための要素が用意されています。Fire TVユーザーがTV番組を閲覧したときに、その番組がシーズン単位で整理され、各エピソードがシーズン内で順序立って表示されるのは、これらの要素が使用されているためです。

通常、作品どうしを関連付けるにはIDまたはタイトルを使用します。IDはカタログに含まれる対象作品のIDと一致する必要がありますが、対象作品がカタログにない場合は、IDの代わりにタイトルを使用してください。カタログ内でのマッチングにタイトルは必要ありません。タイトルは、作品をグループ化する目的でのみ使用されます。 

以下の表に、作品タイプごとの要素を示します。

作品タイプ 関連付けの要素
TvEpisode ShowIDまたはShowTitle
SeasonIDまたはSeasonInShow
TvEpisodeにはSeasonTitle要素もありますが、この要素はグループ化には使用されません。
TvSeason ShowIDまたはShowTitle
TvShow なし
TvSpecial ShowIDまたはShowTitle
MiniSeries なし
MiniSeriesEpisode MiniSeriesIDまたはMiniSeriesTitle
Extra RelatesToIDまたはRelatesToExternalID
Movie なし

カタログに含まれていないシーズンを指定する場合、TvEpisodeではタイトルではなく番号を使用します。ExtraではIMDbなど、外部のIDスキーマへのリンクを使用します。また、TvEpisodeTvSeasonMiniSeriesEpisodeでは、上記の関連付け要素の各ペアのうち、どちらか一方が必須となるので、必ず指定してください。TvSpecialExtraは単独の作品として扱うことができるため、関連付けの値は省略可能です。

以下の図は、TV番組向けにIDを使用した際に、さまざまな要素と値がどのようにマッチされるかを示すものです。

TV番組、シーズン、エピソード、特別番組の各IDにおける関係図

たとえば、TvShowのIDがTV-123456の場合、TvEpisodeTvSeasonShowID値も同じくTV-123456になります。カタログの完全な実装例を確認する場合は、カタログデータ形式のサンプルをダウンロードしてください。

ボックスアート画像(ImageUrl)の要件

ImageUrl要素はすべての作品に共通する省略可能な要素の1つで、作品を表す画像のURLを指定するものです。この画像は「ボックスアート」とも呼ばれています。 ImageUrlが未指定の場合、マッチングがうまくいけばIMDbなどのソースから利用可能な画像が選ばれ、使用されます。マッチングができなければ、汎用的なプレースホルダー画像が使用されます。

画像の要件

要件 画像 説明
タイプ JPG(推奨)またはPNG これ以外の画像タイプは使用できません。
アスペクト比 16 X 9 フィード内の画像は、アスペクト比16 x 9に従う必要があります。
サイズ 高さが240ピクセル以上(推奨は480ピクセル) 画像の高さが480ピクセル未満の場合、統合レポートに警告が生成されますが、高さが240~480ピクセルの画像も使用可能です。高さが240ピクセル未満の画像は使用できません。最適な品質を維持するために、必要に応じてサイズ変更が可能な大きい画像の使用をお勧めします。画像サイズに上限はありません。

: アスペクト比が理由で画像がトリミングされる場合でも、元のサイズにかかわらず、高さの要件を満たしている必要があります。

少なくとも、上記の仕様を満たす画像を使用してください。この仕様は、作品自体ではなく、ボックスアート画像に適用されるものです。

CDFに関するよくある質問(FAQ)

Q: カタログファイルの作成方法を教えてください。
A: CDF形式に準拠したXMLファイルにメタデータをエクスポートし、プログラムでファイルを作成します。
Q: シーズンとエピソードを含むTV番組の場合、どのコンテンツタイプを使用して分類すればよいですか?
A: TvShowTvSeasonTvEpisodeを使用してください。
Q: シーズン形式ではないTV番組で、連続エピソードを含む場合、どのコンテンツタイプを使用すればよいですか?
A: MiniSeriesおよびMiniSeriesEpisodeタイプを使用してください。エピソードの順序を表すためにEpisodeInSeriesの値を指定する必要があります。
Q: シーケンス番号がない連続エピソードを含むTV番組なので、放送日でエピソードの順序付けをしています。この場合もコンテンツタイプとしてMiniSeriesを使用できますか? 使用できない場合は、どのコンテンツタイプを使用すればよいですか?
A: TVShowおよびTVSpecialタイプを使用してください。TVSpecialでは、ShowIDまたはShowTitleフィールドを使用してTVShowにリンクさせ、さらに必須の放送日を追加してください。
Q: 扱っているニュース系コンテンツには複数のエピソードがありますが、シーズン形式ではなく、放送日でエピソードの順序を決めています。どのコンテンツタイプを使用すればよいですか?
A: TVShowおよびTVSpecialタイプを使用してください。TVSpecialでは、ShowIDまたはShowTitleフィールドを使用してTVShowにリンクさせ、さらに必須の放送日を追加してください。
Q: シーズン形式の番組でも、シーズンに値が指定されていない場合、どうすればよいですか?
A: シーズン形式の番組の場合、必ずシーズン値を指定してください。指定しない場合、ユーザーエクスペリエンスに悪影響を及ぼしかねません。シーズン情報を取得するには、IMDbのような信頼性の高いカタログを確認します。快適な視聴体験を維持するため、シーズン値が指定されていないシーズン形式のコンテンツは、カタログに含めないことをお勧めします。
Q: シーズンやエピソードに関する情報がないシリーズものの場合は、どうすればよいですか? 仮の値を決めるべきですか?
A: カタログに仮のSeason番号やEpisode番号は指定しないでください。この場合はTvEpisodeエントリタイプではなく、TvSpecialを使用してください。引き続き各エントリ(TvSpecial)をTvShowにマッピングすることで、エントリどうしがTvShowを通じて関連付けられるようになります。ただし、TvSpecialではOriginalAirDateが必須フィールドであることに注意してください。このフィールドを使用することで、TvShow内のエピソードを適切にマッチングしたり、正しい順序に並べたりすることができます。ほかの情報源を利用してSeason番号とEpisode番号を特定することも可能です。
Q: ルールがたくさんありますが、各ルールの細かな違いを覚えずに適切な判断を下すにはどうすればよいですか?
A: 想定されるユーザーの期待値に基づいて判断することをお勧めします。たとえば、TVシリーズが毎晩放送されるトーク番組の場合、おそらくユーザーはシーズン形式の番組だとは思わないはずです。そしてこの場合、最も重要なのは放送日です。一方、ユーザーが一気に視聴する傾向にある人気シリーズの場合は、Season番号やEpisode番号がより重要になるはずです。
Q: カタログファイルを作成しましたが、次に何をすればよいでしょうか? このままファイルをAmazon S3にアップロードできますか?
A: Amazon S3にカタログファイルをアップロードする前に、ファイル内のXMLを検証することを強く推奨します。CDFに不完全または無効なXMLが含まれていると、そのファイルは却下されてしまいます。詳細については、手順2: カタログファイルを検証するを参照してください。

次のステップ

カタログファイルを作成したら、手順2: カタログファイルを検証するに進んでください。