電子番組表（EPG）同期タスクの設計ガイドライン
- EPG同期タスクを実装する前に、Vegaヘッドレスタスクおよびサービスを確認してください。
- クラウドカタログを使用してタスクを軽量化します。
getLastCommittedLineupVersion関数を活用して軽量なバージョンチェックを実行し、システムに既に最新のラインナップが統合されている場合は、統合をスキップします。コミットバージョンは不透明型の文字列で、開発者に最適なアルゴリズムを使用して設定できます。ラインナップのハッシュ、タイムスタンプ、その他のバージョン付け手法を使用できます。- タスクのメモリ使用量がシステムのしきい値を超えたりタスクが終了したりしないように、メモリ使用量を制限します。
- API統合に必要なデータのみをダウンロードします。
- HTTP 1.1 Rangeリクエストヘッダー（RFC 7233、セクション3）などの手法を使用して、バックエンドからデータをチャンクまたはページ単位でダウンロードします。
- EPGデータにはXMLデータスキーマを使用しないでください。JSで解析する場合、JSONスキーマの方が簡単でメモリ効率にも優れています。
- EPG同期タスクが何らかの理由によって
Promise.reject(error)で失敗した場合、システムは指数関数的バックオフを使用して最大8回まで再試行します。
Vega EPGプロバイダーAPIのガイドライン
- 最適なパフォーマンスを実現し、最新の機能を利用するには、インターフェイスの最新バージョンを使用してください。インターフェイスには、名前の末尾にバージョンを表すサフィックスが付いています。たとえば、
ProgramLineupProviderの推奨アップグレード版はProgramLineupProvider2です。インターフェイスやAPIに関する記述はすべて、最新バージョンを使用していることを前提としています。 ChannelLineupProviderインターフェイスは、チャンネルラインナップ全体を想定しています。これは、現在のリストの完全なセットまたは置き換えを表します。LiveEventProviderインターフェイスは、ライブイベントのラインナップ全体を想定しています。これは、現在のリストの完全なセットまたは置き換えを表します。ChannelLineupProviderインターフェイス、ProgramLineupProviderインターフェイス、LiveEventProviderインターフェイスはトランザクション型です。- トランザクションを完了するには、最後に
commitAPIを呼び出します。commit()の呼び出し後にオブジェクトを再利用することはできません。必要な場合は新しいオブジェクトを作成してください。 commitを呼び出さずにChannelLineupProviderオブジェクト、ProgramLineupProviderオブジェクト、LiveEventProviderオブジェクトを破棄すると、トランザクションは終了されます。- 番組を更新する（
Commitを使用する）前に、必要に応じて新しいチャンネルラインナップのProgramLineupProviderを実行します。チャンネルと番組の更新順序を入れ替えることはできません。 - 番組の
ChannelDescriptorに対応するチャンネルがコミットされていない場合、ProgramLineupProvider.upsert()操作は失敗します。
- トランザクションを完了するには、最後に
- ラインナッププロバイダーの関数はスレッドセーフではないため、同一スレッドで呼び出す必要があります。
ChannelMetadata.nameフィールドは、Fire TVのカルーセルに表示されるチャンネルのマーケティング名を示します。ChannelMetadata.nameが指定されていないか空の文字列の場合、チャンネルの統合は失敗します。Fire TVでは最大25文字の英数字が表示されますが、文字数がこの制限を超えると、完全なチャンネル名は表示されません。この上限は、半角・全角のどちらの文字セットにも適用されます。例：- The Walking Dead Universe（最大文字数内-表示される）。
- Ed’s Purple Plane（最大文字数内-表示される）。
- How Sally Fell off her Horse and Learned to Play Piano on a Saturday（25文字を超えるため、最大文字数外-表示されない）。
- エドのパープルプレイン（最大文字数内-表示される）。
ProgramLineupProviderを使用してオンデバイス番組表を統合する場合は、ストレージ制限のエラーを回避するために、Amazonの担当者と相談して何日分の番組をプッシュするかを決定してください。これは、チャンネルと番組がいくつあるかによって異なります。- ユーザーがサブスクリプションパッケージをアップグレードまたはダウングレードすると、それに応じて視聴権限のあるチャンネルとライブイベントの数が変わります。これらの変更に対応するには、定期購入の変更時に、チャンネル、番組、ライブイベントを統合するAPIが呼び出されるようにします。該当するAPIは、それぞれ
ingestChannelLineup()、ingestProgramLineup()、ingestLiveEvents()です。 ChannelMetadata.logoUrlを使用して、チャンネルロゴを表す120x68ピクセルのマルチトーン画像を指定します。
エラー処理
データ統合中のすべてのエラーをキャッチし、バックエンドにプッシュします。アラームを作成して、エラーにできるだけ早く対処できるようにします。ProgramLineupProviderとLiveEventProviderでは、コミットの部分的な成功がサポートされ、コミットに失敗した番組とライブイベントに関するエラーフィードバックが提供されます。ProgramLineupProviderのupsertとLiveEventProviderのaddの各操作は、コミットキューに追加されなかったIUpsertProgramFailureオブジェクトまたはIAddLiveEventFailureオブジェクトのリストを返します。すべての番組またはライブイベントがコミットキューに正常に追加された場合、システムは空のリストを返します。- 失敗した番組とライブイベントはバックエンドにプッシュし、アラームをトリガーして、次回の同期の前にすみやかに無効なデータの問題に対処します。
- 失敗時には、番組やライブイベントの統合プロセスを中止してエラーに対処してから再試行するか、成功した番組またはライブイベントを部分的にコミットします。
- プロバイダーに割り当てられたストレージのサイズ制限を超えて書き込もうとすると、EPG同期タスク中に
StorageLimitErrorエラーがスローされます。- 統合を中止し、アラームをトリガーします。
- このエラーが発生した場合は、Amazonの担当者にお問い合わせください。
ChannelLineupProvider.add()を呼び出したときに、提供されたチャンネルのいずれかが無効な場合は、InvalidArgumentErrorエラーがスローされます。エラーメッセージには、失敗した挿入の合計数と、失敗した最初の5つのチャンネルの理由が含まれます。-
このエラーメッセージの形式は次のとおりです。
-
このエラーメッセージの形式は次のとおりです。
- すべての文字列フィールドにはサイズ制限があります。フィールドの制限を超えると、システムは文字列を切り詰めて末尾に「…」を追加するか、
InvalidArgumentErrorエラーをスローします。各フィールドの詳細は、EPGプロバイダーのインターフェイスのインラインドキュメントに記載されています。 - EPG同期タスクが何らかの理由によって
Promise.reject(error)で失敗した場合、システムは指数関数的バックオフを使用して、最大8回まで自動的に再試行します。
クラウドカタログとオンデバイス統合
前提条件に記載されているように、Amazonでは、カタログをAmazonカタログサービスやGracenoteなどのクラウドサービスと統合することをお勧めします。Amazonカタログ形式やGracenote統合モデルを活用することには、いくつかの利点があります。- 大規模な番組ラインナップや解析が難しい番組ラインナップを統合する必要がなくなります。
- チャンネルの統合時にChannelType以外のチャンネルメタデータを提供する必要がなくなります。残りはクラウドサービスが自動的に取得します。
- ユーザー数が増加したときのスケーラビリティが向上します。
AmazonカタログステーションIDの指定（推奨）
AmazonカタログステーションIDを指定すると、情報がライブTVアプリを通じて毎日クラウドに同期されます。これらのステーションIDにより、チャンネルを照会できるようになります。Fire TVカタログには最大14日間の番組情報が含まれ、[ホーム] タブ、[ライブ] タブ、番組表に表示されます。この情報は自動的に更新され、常に最新の状態に保たれます。また、検索機能やAlexaによる音声操作を通じて検出できます。 このデータソースに使用する対応する値については、データの種類のリファレンスページの外部IDセクションを参照してください。Gracenote IDの指定
GracenoteチャンネルID（onTVまたはGVD（グローバルビデオデータ））を指定すると、情報がライブTVアプリを通じて毎日クラウドに同期されます。Gracenote IDがある場合、ユーザーはFire TVカタログでそのIDのチャンネルを検索できます。このカタログには最大14日間の番組情報が含まれ、[ホーム] タブ、[ライブ] タブ、番組表に表示されます。この情報は自動的に更新され、常に最新の状態に保たれます。また、検索機能やAlexaによる音声操作を通じて検出できます。 このデータソースに使用する対応する値については、データの種類のリファレンスページの外部IDセクションを参照してください。オンデバイス番組表統合
チャンネルのAmazonカタログステーションIDまたはGracenoteチャンネルIDを指定しない場合は、以下を挿入してください。- すべてのチャンネルメタデータ
- 使用するロゴのURL
- すべてのチャンネルの今後の番組情報（番組ラインナッププロバイダーを使用して定期的に配信）
メタデータ値
チャンネル、番組、ライブイベントのさまざまなメタデータフィールドでサポートされている値については、データの種類のリファレンスページを参照してください。チャンネルとライブイベントの順序
チャンネルの順序
チャンネルの順序によって、Fire TVデバイスのUIに表示されるチャンネルのランクが決まります。基本の順序はプロバイダーが決定します。ユーザーはコンテキストメニューやチャンネルマネージャーを使用して、チャンネルをお気に入りとして設定できます。それらのチャンネルは最も高い優先順位で表示されます。したがって、優先順位はお気に入り＞チャンネルの順序オプションとなります。 Fire TVには、次の種類のチャンネル順序が用意されています。- アルファベット順： Fire TV UIのチャンネルは、
nameフィールドに基づいて昇順で表示されます。これはデフォルトの順序です。 - カスタムのチャンネルの順序： Fire TV UIのチャンネルは、チャンネルの統合中に提供されたチャンネルメタデータの
SortRankフィールド値に基づく順序で表示されます。開発者がSortRankを使用しない場合、チャンネルは一番下に配置されます。順位が同じ場合は、チャンネルのnameに従ってアルファベット順に並べられます。このチャンネル順序を使用する場合は、Amazonの担当者にお知らせください。 - チャンネル番号順： Fire TV UIのチャンネルは、指定されているチャンネル記述子のメジャー番号とマイナー番号に従って昇順で表示されます。チャンネルは、最初にメジャー番号で並べ替えられ、次にマイナー番号で並べ替えられます。たとえば、チャンネル3.1はチャンネル3.10より前に表示されます。順位が同じ場合は、チャンネル名に従ってアルファベット順に並べられます。このチャンネル順序を使用する場合は、Amazonの担当者にお知らせください。
ライブイベントの順序
Fire TV UI上のライブイベントは、ライブイベントの統合中に提供されたLiveEventメタデータのSortRankフィールド値に基づく順序で表示されます。開発者がSortRankを使用しない場合、ライブイベントは一番下に配置されます。順位が同じ場合は、ライブイベントのタイトルに従ってアルファベット順に並べられます。最も重要なコンテンツは、最も目立つように先頭に配置してください。
最大ロールアウトレート
ユーザーに対するチャンネルの段階的ロールアウトは、1時間あたり最大50万のレートで実行されます。 この値は、チャンネルの視聴権限があるユーザーのFire TVデバイスの数を示します。チャンネルの視聴権限がある状態とは、Fire TV内のリニアTV統合のUXからワンクリックで全画面再生を行うことができる状態を指します。 例：- ABCアプリはビデオオンデマンドを提供していますが、プレミアムアドオンとしてライブTV機能も備えています。この場合、ライブTVのアドオンを利用しているABCユーザーのみがロールアウトの対象となります。
- XYZアプリには、無料の基本チャンネルパッケージに加えて、さらに多くのチャンネルを視聴できる有料プランが用意されています。有料プランのチャンネルラインナップが更新された場合、その有料プランのユーザーのみがロールアウトの対象となります。
