手順4： EPG同期タスクを実装する

電子番組表（EPG）同期タスクの設計ガイドライン

1. EPG同期タスクを実装する前に、Vegaヘッドレスタスクおよびサービスを確認してください。
2. クラウドカタログを使用してタスクを軽量化します。
3. getLastCommittedLineupVersion関数を活用して軽量なバージョンチェックを実行し、システムに既に最新のラインナップが統合されている場合は、統合をスキップします。コミットバージョンは不透明型の文字列で、開発者に最適なアルゴリズムを使用して設定できます。ラインナップのハッシュ、タイムスタンプ、その他のバージョン付け手法を使用できます。
4. タスクのメモリ使用量がシステムのしきい値を超えたりタスクが終了したりしないように、メモリ使用量を制限します。
   1. API統合に必要なデータのみをダウンロードします。
   2. HTTP 1.1 Rangeリクエストヘッダー（RFC 7233、セクション3）などの手法を使用して、バックエンドからデータをチャンクまたはページ単位でダウンロードします。
   3. EPGデータにはXMLデータスキーマを使用しないでください。JSで解析する場合、JSONスキーマの方が簡単でメモリ効率にも優れています。
5. EPG同期タスクが何らかの理由によってPromise.reject(error)で失敗した場合、システムは指数関数的バックオフを使用して最大8回まで再試行します。

Vega EPGプロバイダーAPIのガイドライン

1. 最適なパフォーマンスを実現し、最新の機能を利用するには、インターフェイスの最新バージョンを使用してください。インターフェイスには、名前の末尾にバージョンを表すサフィックスが付いています。たとえば、ProgramLineupProviderの推奨アップグレード版はProgramLineupProvider2です。インターフェイスやAPIに関する記述はすべて、最新バージョンを使用していることを前提としています。
2. ChannelLineupProviderインターフェイスは、チャンネルラインナップ全体を想定しています。これは、現在のリストの完全なセットまたは置き換えを表します。
3. LiveEventProviderインターフェイスは、ライブイベントのラインナップ全体を想定しています。これは、現在のリストの完全なセットまたは置き換えを表します。
4. ChannelLineupProviderインターフェイス、ProgramLineupProviderインターフェイス、LiveEventProviderインターフェイスはトランザクション型です。
   1. トランザクションを完了するには、最後にcommit APIを呼び出します。commit()の呼び出し後にオブジェクトを再利用することはできません。必要な場合は新しいオブジェクトを作成してください。
   2. commitを呼び出さずにChannelLineupProviderオブジェクト、ProgramLineupProviderオブジェクト、LiveEventProviderオブジェクトを破棄すると、トランザクションは終了されます。
   3. 番組を更新する（ProgramLineupProviderを使用する）前に、必要に応じて新しいチャンネルラインナップのcommitを実行します。チャンネルと番組の更新順序を入れ替えることはできません。
   4. 番組のChannelDescriptorに対応するチャンネルがコミットされていない場合、ProgramLineupProvider.upsert()操作は失敗します。
5. ラインナッププロバイダーの関数はスレッドセーフではないため、同一スレッドで呼び出す必要があります。
6. ChannelMetadata.nameフィールドは、Fire TVのカルーセルに表示されるチャンネルのマーケティング名を示します。ChannelMetadata.nameが指定されていないか空の文字列の場合、チャンネルの統合は失敗します。Fire TVでは最大25文字の英数字が表示されますが、文字数がこの制限を超えると、完全なチャンネル名は表示されません。この上限は、半角・全角のどちらの文字セットにも適用されます。例：
   1. The Walking Dead Universe（最大文字数内-表示される）。
   2. Ed's Purple Plane（最大文字数内-表示される）。
   3. How Sally Fell off her Horse and Learned to Play Piano on a Saturday（25文字を超えるため、最大文字数外-表示されない）。
   4. エドのパープルプレイン（最大文字数内-表示される）。
7. ProgramLineupProviderを使用する場合は、少なくとも48時間分のプログラムデータを提供します。
8. ユーザーがサブスクリプションパッケージをアップグレードまたはダウングレードすると、それに応じて視聴権限のあるチャンネルとライブイベントの数が変わります。これらの変更に対応するには、定期購入の変更時に、チャンネル、番組、ライブイベントを統合するAPIが呼び出されるようにします。該当するAPIは、それぞれingestChannelLineup()、ingestProgramLineup()、ingestLiveEvents()です。
9. ProgramLineupProviderを使用する場合は、少なくとも48時間分のプログラムデータを提供する必要があります。
10. ChannelMetadata.logoUrlを使用して、チャンネルロゴを表す120x68ピクセルのマルチトーン画像を指定します。

エラー処理

データ統合中のすべてのエラーをキャッチし、バックエンドにプッシュします。アラームを作成して、エラーにできるだけ早く対処できるようにします。

1. ProgramLineupProviderとLiveEventProviderでは、コミットの部分的な成功がサポートされ、コミットに失敗した番組とライブイベントに関するエラーフィードバックが提供されます。
   1. ProgramLineupProviderのupsertとLiveEventProviderのaddの各操作は、コミットキューに追加されなかったIUpsertProgramFailureオブジェクトまたはIAddLiveEventFailureオブジェクトのリストを返します。すべての番組またはライブイベントがコミットキューに正常に追加された場合、システムは空のリストを返します。
   2. 失敗した番組とライブイベントはバックエンドにプッシュし、アラームをトリガーして、次回の同期の前にすみやかに無効なデータの問題に対処します。
   3. 失敗時には、番組やライブイベントの統合プロセスを中止してエラーに対処してから再試行するか、成功した番組またはライブイベントを部分的にコミットします。
2. プロバイダーに割り当てられたストレージのサイズ制限を超えて書き込もうとすると、EPG同期タスク中にStorageLimitErrorエラーがスローされます。
   1. 統合を中止し、アラームをトリガーします。
   2. このエラーが発生した場合は、Amazonの担当者にお問い合わせください。
3. ChannelLineupProvider.add()を呼び出したときに、提供されたチャンネルのいずれかが無効な場合は、InvalidArgumentErrorエラーがスローされます。エラーメッセージには、失敗した挿入の合計数と、失敗した最初の5つのチャンネルの理由が含まれます。
   1. このエラーメッセージの形式は次のとおりです。

      コードをコピー クリップボードにコピーしました。

      Found 1 invalid channels in provided data, list some examples: [{"channelIdentifier":"xxx","channelMajorNumber":xx,"channelMinorNumber":xx,"errorMessage": "xxx"}]
      

4. すべての文字列フィールドにはサイズ制限があります。フィールドの制限を超えると、システムは文字列を切り詰めて末尾に「...」を追加するか、InvalidArgumentErrorエラーをスローします。各フィールドの詳細は、EPGプロバイダーのインターフェイスのインラインドキュメントに記載されています。
5. EPG同期タスクが何らかの理由によってPromise.reject(error)で失敗した場合、システムは指数関数的バックオフを使用して、最大8回まで自動的に再試行します。

クラウドカタログとオンデバイス統合

前提条件に記載されているように、AmazonカタログサービスやGracenoteなどのクラウドサービスとカタログを統合することをお勧めします。CDFやGracenote統合モデルを活用することには、いくつかの利点があります。

• 大規模な番組ラインナップや解析が難しい番組ラインナップを統合する必要がなくなります。
• チャンネルの統合時にChannelType以外のチャンネルメタデータを提供する必要がなくなります。残りはクラウドサービスが自動的に取得します。
• ユーザー数が増加したときのスケーラビリティが向上します。

CDFは最も直接的な統合です。これによってレイテンシが短縮されるため、将来の機能をより迅速に有効化できます。チャンネルごとに、クラウドベースのカタログを使用するか、オンデバイス番組ラインナップを通じて統合するかを選択できます。つまり、あるチャンネルでGracenote IDを使用し、別のチャンネルでCDFを使用し、3つ目のチャンネルでオンデバイス番組ラインナップによる統合を使用するといったことが可能です。

以下は、Fire TVの機能について、CDF、Gracenote、オンデバイス統合を機能レベルで比較したものです。

機能	CDF	Gracenote	オンデバイス番組表統合
専用カルーセルの閲覧
[ライブプロバイダー] 行	✓	✓	✓
App Peak	✓	✓	✓
混合カルーセルの閲覧
[視聴履歴]	✓	✓	✓
[ホーム] の [放映中のチャンネル]	✓	✓	✓
[ジャンル] 行	✓	✓	✓
閲覧
電子番組表	✓	✓	✓
検索
チャンネル	✓	✓	✓
番組	✓	✓
音声
チャンネル名でチューニング	✓	✓	✓
番組名によるチューニング（新着／ライブのみ）	✓	✓
スケジュールの更新方法
カタログ検索により自動	✓	✓
オンデバイス			✓

CDFステーションIDの指定（推奨）

CDFステーションIDを指定すると、情報がライブTVアプリを通じて毎日クラウドに同期されます。これらのステーションIDは、チャンネルを検索できるようにする方法を提供します。Fire TVカタログには最大14日間の番組情報が含まれ、[ホーム] タブ、[ライブ] タブ、番組表に表示されます。この情報は自動的に更新され、常に最新の状態に保たれます。また、検索機能やAlexaによる音声操作を通じて検出できます。

このデータソースに使用する対応する値については、データの種類のリファレンスページの外部IDセクションを参照してください。

Gracenote IDの指定

GracenoteチャンネルID（onTVまたはGVD（グローバルビデオデータ））を指定すると、情報がライブTVアプリを通じて毎日クラウドに同期されます。Gracenote IDがある場合、ユーザーはFire TVカタログでそのIDのチャンネルを検索できます。このカタログには最大14日間の番組情報が含まれ、[ホーム] タブ、[ライブ] タブ、番組表に表示されます。この情報は自動的に更新され、常に最新の状態に保たれます。また、検索機能やAlexaによる音声操作を通じて検出できます。

このデータソースに使用する対応する値については、データの種類のリファレンスページの外部IDセクションを参照してください。

オンデバイス番組表統合

チャンネルのCDFステーションIDまたはGracenoteチャンネルIDを指定しない場合は、以下を挿入してください。

• すべてのチャンネルメタデータ
• 使用するロゴのURL
• すべてのチャンネルの今後の番組情報（番組ラインナッププロバイダーを使用して定期的に配信）

Vegaサンプルアプリには、オンデバイス番組統合の例が示されています。

メタデータ値

チャンネル、番組、ライブイベントのさまざまなメタデータフィールドでサポートされている値については、データの種類のリファレンスページを参照してください。

チャンネルとライブイベントの順序

チャンネルの順序

チャンネルの順序によって、Fire TVデバイスのUIに表示されるチャンネルのランクが決まります。基本の順序はプロバイダーが決定します。ユーザーはコンテキストメニューやチャンネルマネージャーを使用して、チャンネルをお気に入りとして設定できます。それらのチャンネルは最も高い優先順位で表示されます。したがって、優先順位はお気に入り＞チャンネルの順序オプションとなります。

Fire TVには、次の種類のチャンネル順序が用意されています。

1. アルファベット順： Fire TV UIのチャンネルは、nameフィールドに基づいて昇順で表示されます。これはデフォルトの順序です。
2. カスタムのチャンネルの順序： Fire TV UIのチャンネルは、チャンネルの統合中に提供されたチャンネルメタデータのSortRankフィールド値に基づく順序で表示されます。開発者がSortRankを使用しない場合、チャンネルは一番下に配置されます。順位が同じ場合は、チャンネルのnameに従ってアルファベット順に並べられます。このチャンネル順序を使用する場合は、Amazonの担当者にお知らせください。
3. チャンネル番号順： Fire TV UIのチャンネルは、指定されているチャンネル記述子のメジャー番号とマイナー番号に従って昇順で表示されます。チャンネルは、最初にメジャー番号で並べ替えられ、次にマイナー番号で並べ替えられます。たとえば、チャンネル3.1はチャンネル3.10より前に表示されます。順位が同じ場合は、チャンネル名に従ってアルファベット順に並べられます。このチャンネル順序を使用する場合は、Amazonの担当者にお知らせください。

一貫性のあるエクスペリエンスを提供するために、アプリ内での順序に最も近いチャンネル順序を選択してください。オンボーディングプロセスの一環として、Amazonの担当者と協力し、チャンネル順序の決定方法を選択してください。

ライブイベントの順序

Fire TV UI上のライブイベントは、ライブイベントの統合中に提供されたLiveEventメタデータのSortRankフィールド値に基づく順序で表示されます。開発者がSortRankを使用しない場合、ライブイベントは一番下に配置されます。順位が同じ場合は、ライブイベントのタイトルに従ってアルファベット順に並べられます。最も重要なコンテンツは、最も目立つように先頭に配置してください。

最大ロールアウトレート

ユーザーに対するチャンネルの段階的ロールアウトは、1時間あたり最大50万のレートで実行されます。

この値は、チャンネルの視聴権限があるユーザーのFire TVデバイスの数を示します。チャンネルの視聴権限がある状態とは、Fire TV内のリニアTV統合のUXからワンクリックで全画面再生を行うことができる状態を指します。

例：

• ABCアプリはビデオオンデマンドを提供していますが、プレミアムアドオンとしてライブTV機能も備えています。この場合、ライブTVのアドオンを利用しているABCユーザーのみがロールアウトの対象となります。
• XYZアプリには、無料の基本チャンネルパッケージに加えて、さらに多くのチャンネルを視聴できる有料プランが用意されています。有料プランのチャンネルラインナップが更新された場合、その有料プランのユーザーのみがロールアウトの対象となります。

UXフィールドの一覧

メタデータフィールドは、Fire TV UXにおけるコンテキストを提供します。以下に、値の例をいくつか示します。

UXフィールド	説明	認定に必須（○/×）	関連メタデータフィールド
番組名	番組の名前。画面の左上に表示される大きなテキストです。	○	Program.title
再生時間	放送時間（例： 午後11:00～午前12:00）。番組名のすぐ下に表示されます。	○	Program.startTimeMs Program.endTimeMs
エピソード名	放映中のエピソードの名前。再生時間とバッジの下に太字で表示されます。	○	Program.subtitle
エピソードの説明	エピソードの説明。エピソード名の後に続くセクションに、表示可能な範囲で表示されます。	○	Program.description
シーズンとエピソードの情報	シリーズに共通の情報（ホームコメディなど）。この放送に関して提供されるシーズンとエピソードの情報です。この情報は、エピソード名の後に続くミニ詳細に含まれます。	×	Program.seriesInfo.season Program.seriesInfo.episode
レーティング	エピソードの地域のレーティング（バッジ形式）。再生時間と同じ行に表示されます。	×	Program.ratings
バッジに使用されるさまざまな属性	データの種類のリファレンスページの「属性」セクションを参照してください。	×	Program.attributes
番組画像	カルーセルタイルに表示される16:9の番組／映画の画像。768x432以上の解像度を使用してください。	○	Program.thumbnailUrl
背景画像	ミニ詳細セクションの隣にある右上隅のセクション全体に表示される16:9の番組／映画の画像。1280x720以上の解像度を使用してください。	○	Program.posterArtUrl
チャンネル名	カルーセル内のタイルに表示されるチャンネルの名前。表示名の制限に関するガイダンスについては、EPG統合のベストプラクティスを参照してください。	○	ChannelMetadata.name
チャンネルロゴ	EPGで使用される120x68のマルチトーン画像。チャンネルロゴがない場合は、（マーキー内の）チャンネル名にフォールバックされます。	○	ChannelMetadata.logoUrl または、ChannelMetadataにロゴのURLを指定できない場合は、Amazonの連絡先に連絡して情報を提供してください。
チャンネルジャンル	チャンネルにジャンルを割り当てると、Fire TV UIで追加の入り口となるポイントにチャンネルが表示されるようになります。	×	ChannelMetadata.genres

• 前へ - 手順3： タスクを定義する
• 次へ - 手順5： EPG同期タスクをスケジュールする

---

Last updated: 2026年1月22日