このガイドでは、Live Linear プログラム Dataset API にアクセスして使用するために必要なすべてを網羅しています。
学習内容 |
|
[概要]
ライブリニアプログラムデータセットAPIは、プライム・Video ライブリニアチャンネルとFASTチャンネルのプログラムグレイン視聴者データを提供します。 各レコードは、1 つのチャンネルで予定されている 1 つの番組の 1 回の視聴セッションを表します。
データは、スケジュール修正用の is_deleted シグナルを含む変更ログとして配信されます。 チャンネル (リニア_プログラム_イベント_ログ) と FAST (fast_linear_program_event_log) の 2 つのフィードを使用できます。
このデータにより、次のことが可能になります。
- ステーション、地域、デバイス、時間をまたいで番組レベルの視聴者数（視聴時間、セッション）を追跡できます。
- ステーション、番組、シリーズ、コンテンツtype ごとにパフォーマンスを分析します。
- データの行が古くなることなく、スケジュールの修正を正確に行えます。
- ライブリニアビューアーシップを社内システムやデータソースと統合します。
主な機能
機能 |
詳細 |
|---|---|
プログラムグレインの詳細 |
視聴セッション、番組、スケジュールごとに 1 行。 タイトル、ステーション、シリーズ、放送ウィンドウ、総再生時間が含まれます。 |
削除シグナル |
置き換えられたスケジュールや取り消されたスケジュールは is_deleted = 1 で再送信され、無効になったことを知らせます。 |
安定したユニークキー |
すべての行にはセッションプログラム_スケジュール_IDが付けられます。 これを使用して重複排除とマージを行います。 |
取り込みが簡単になりました。 |
変更ログモデル。 定期的な通話をスケジュールしてから、統合します。 is_deleted = 0 の場合にアップサートします。 is_deleted = 1 の場合のハード削除またはソフト削除。 |
一貫性 |
すべての地域で標準化されたフォーマットを 1 つのソースにまとめました。 テリトリーごとのディメンションテーブルは不要です。 |
キーコンセプト
コンセプト |
Description |
|---|---|
セッション-プログラム-スケジュール行 |
スケジュールされた 1 つのスロットで 1 つの番組を視聴するセッション。 session_program_schedule_id によって識別されます。 |
変更ログモデル |
データは変更ログです。 行の属性が変更されると、同じ session_program_schedule_id と新しい last_update_time_utc を使用して新しいバージョンが公開されます。 |
プライマリキー |
セッション_プログラム_スケジュール_ID は固有の識別子です。 このフィールドは常に重複排除してください。 |
is_deleted シグナル |
is_deleted = 0 はスケジュールがアクティブであることを意味します。 is_deleted = 1 は、スケジュールがもはやアクティブでも有効でもないことを示します。 |
シグナルを適用してください。 |
is_deleted = 0: 行を挿入または更新します。 is_deleted = 1: 現在のデータにその行が表示されないようにします。 行をドロップするか、フラグを付けたままフィルターで除外します。 |
はじめに
オンボーディング方法ライブリニアプログラムデータセット API は Analytics API Suite の一部です。 Analytics API Suite にオンボーディングすると、Live Linear プログラム Dataset API（オンボーディング中にリクエストされた場合）を含む、そのスイート内で利用可能なすべての API にアクセスできるようになります。 オンボーディングの詳細な手順については、Analytics API オンボーディングページをご覧ください。
前提条件 API リクエストを行う前に
、次のものが必要です。
- Amazon (LWA) によるログイン (LWA) セキュリティProfile。 クライアントIDをCAMに送信して、PV内部管理ページに追加します。
- トークンをリクエストするための認証コード。
- すべての API リクエストのトークン。
ベース URI: https://videocentral.amazon.com/apis/v2
すべてリクエストには、認証ヘッダーに有効な LWA 認証トークンが含まれている必要があります。 トークンが欠落しているか有効期限が切れている場合、API は不正な例外を返します。 |
ページ分割すべて回答がページ分割されます。 ページ間を移動するには以下のパラメータを使用してください。
パラメーター |
デフォルト |
Description |
|---|---|---|
限定 |
10 |
1 ページあたりに返されるドキュメントのNumber。 最大 1,000 です。 |
オフセット |
0 |
最初の結果が出る前にスキップするドキュメントのNumber。 自分で計算するのではなく、次の URL をたどってください。 |
ページ分割すべて回答には、次のフィールドが含まれます。
フィールド |
Description |
|---|---|
合計 |
全ページのドキュメント総数。 |
次へ進みます |
次のページへの URL。 これが最後のページの場合は NULL。 |
データセットファイルの取得
Endpoint 次の curl
コマンドを使用して、ダウンロード可能なデータセットファイルリンクのリストを取得します。
curl -X GET \
-H "Authorization: Bearer Atza|auth_token" \
"https://videocentral.amazon.com/apis/v2/accounts/{ACADIA_ID}/{REPORT_GROUP}/{IDENTIFIER_ID}/datasets/{REPORT_ID}\
?startDateTime=YYYY-MM-DDThh:mm:ssZ\
&endDateTime=YYYY-MM-DDThh:mm:ssZ\
&offset=0&limit=1000"
注:このエンドポイントは、行を直接返すのではなく、ダウンロード可能な gzip 圧縮された CSV ファイルへのリンクを返します。 |
パラメーター
パラメーター |
Description |
|---|---|
ACADIA_ID |
あなたのスレートアカウント ID。 /v2/accounts で見つけてください。 |
REPORT_GROUP |
ビジネスラインセグメント。 チャンネルフィードにはチャンネルを、FAST フィードにはファストを使用してください。 GET /v2/アカウント/ {ACADIA_ID} で自分のものを見つけましょう。 |
識別子 ID |
識別子のエンドポイントから返される ID 値。 Channels の場合、これは不透明なハッシュです。 id フィールドは指定どおりに使用してください。 FAST の場合は、ハッシュされずに返されるベンダーコードです。 |
REPORT_ID |
どのレポートを取り込むか。 チャネルには linear_program_event_log を、FAST には fast_linear_program_event_log を使用してください。 |
開始日時 |
前回プルした時刻に設定します。 フォーマット:yyyy-mm-ddthh: MM: SSZ (UTC)。 |
終了日時 |
現在の時刻に設定します。 フォーマット:yyyy-mm-ddthh: MM: SSZ (UTC)。 |
限定 |
1 ページあたり最小 1 リンク、最大 1,000 リンク。 |
利用可能なレポート
2つのレポートが利用可能です。 データセット/ {REPORT_ID} パスセグメントにレポート ID を入力して、それぞれを個別に取得します。
レポート |
レポート ID |
コンテンツ |
|---|---|---|
チャネル |
リニア_プログラム_イベント_ログ |
SVOD/サブスクリプションリニア (3P_SUBS、該当する場合は FREE/PRIME)。 |
高速 |
高速_リニア_プログラム_イベント_ログ |
無料広告対応テレビ/広告対応 (AVOD) リニアチャンネル |
注:データの最大保持期間は 2 年間です。 2 年以上前のリクエストでは結果は返されません。 |
ディスカバリーエンドポイント
以下のエンドポイントを使用して、アカウント ID、レポートグループ、識別子、および利用可能なデータセットを検索してください。
エンドポイント |
返品 |
|---|---|
/v2/アカウントを取得 |
アクセスできるスレートアカウントのリスト。 |
/v2/アカウント/ {ACADIA_ID} を取得 |
ビジネスラインが利用可能 (たとえば、チャネル、ファスト)。 |
/v2/アカウント/ {ACADIA_ID} /チャネルを取得 |
利用可能なレポート ID。 各エントリには ID とわかりやすい名前があります。 |
/v2/accounts/ {ACADIA_ID} /channels/ {IDENTIFIER_ID} /datasets を取得 |
その識別子で利用できるデータセット。 |
データ列
linear_program_event_log (チャネル) フィードには以下の列があります。 fast_linear_program_event_log (FAST) フィードの形は同じで、ベンダーコードが追加され、サブスクリプション列は NULL として配信されます。
コラム |
Type |
NULL 設定可能 |
Description |
|---|---|---|---|
セッション_プログラム_スケジュール_ID |
ひも |
いいえ |
主キー。 ユニーク ID (セッション、プログラム、および放送ウィンドウをエンコード)。 このフィールドでは重複排除とマージを行います。 EPG メタデータの更新により番組や放送時間が変わると変更されます。 |
session_id |
ひも |
いいえ |
匿名化された固有の視聴セッション識別子。 |
is_deleted |
整数 |
いいえ |
ステータス信号。0 = スケジュールはアクティブ。1 = スケジュールはアクティブでなくなった (置き換えられたか取り消された)。 is_deleted = 1 行を現在のデータから除外します。 |
最終更新時刻:UTC |
タイムスタンプ |
いいえ |
バージョン時間を記録します。 重複排除には必ず使用してください。 指定した ID の最新の値を含む行を保存します。 |
create_time_utc |
タイムスタンプ |
いいえ |
行が最初に作成されたとき。 |
プログラム ID |
ひも |
いいえ |
プログラム識別子 (例:TMS ID) |
pv_title_id |
ひも |
はい |
番組のプライム・Video・グローバル・タイトルIdentifier（GTI）。 TVOD フィードの pv_title_id と同じです。 |
プログラムタイトル |
ひも |
はい |
プログラムタイトル。 |
ステーション名 |
ひも |
はい |
チャンネルまたはステーション名。 |
コンテンツタイプ |
ひも |
いいえ |
ライブ放送または定期テレビ放送。 |
UTC (放送開始) |
タイムスタンプ |
いいえ |
プログラム放送開始 (UTC) |
放送終了_UTC |
タイムスタンプ |
いいえ |
プログラム放送終了 (UTC) |
開始_セグメント_UTC |
タイムスタンプ |
いいえ |
視聴セッション開始 (UTC)。 |
終了_セグメント_UTC |
タイムスタンプ |
いいえ |
閲覧セッション終了 (UTC)。 |
秒単位の閲覧回数 |
長いです |
いいえ |
このセッションで閲覧された秒数。 |
vendor_sku |
ひも |
はい |
コンテンツ SKU (たとえば、グレースノート識別子)。 |
親チャンネルラベル |
ひも |
はい |
ハッシュされた親チャンネル識別子。 |
cid |
ひも |
はい |
チャンネル ID (有効)。 |
ベネフィットID |
ひも |
はい |
エンタイトルメント/ベネフィット ID。 |
サブスクリプションオファー ID |
ひも |
はい |
サブスクリプションオファー ID。 |
サブスクリプション_イベント_ID |
ひも |
はい |
サブスクリプションイベント ID。 |
サブスクリプションオファータイムゾーン |
ひも |
はい |
サブスクリプション提供のタイムゾーン。 |
マーケットプレイス ID |
整数 |
いいえ |
マーケットプレイス ID。 |
マーケットプレイス (desc) |
ひも |
はい |
マーケットプレイスの説明。 |
地域 |
ひも |
はい |
地域またはcountry コード (US GB 英国、ドイツ、AU など)。 |
デバイスクラス |
ひも |
はい |
デバイスカテゴリ。 |
デバイスサブクラス |
ひも |
はい |
デバイスサブカテゴリ。 |
接続タイプ |
ひも |
はい |
接続type (Wi-Fi、有線、その他) |
再生方法 |
ひも |
はい |
セッションの使用方法:オンライン (ストリーミング) またはオフライン (ダウンロード)。 ライブリニアは事実上常にオンラインです。 |
geo_dma |
ひも |
はい |
地理的DMA。 |
ストリームタイプ |
ひも |
いいえ |
常に LINEAR_TV。 |
高速フィードメモ:fast_linear_program_event_log フィードの形状は同じです。 ベンダーコード (パートナーコード) 列があります。 サブスクリプション列 (サブスクリプション_オファー_id、サブスクリプション_event_id、サブスクリプション_オファー_タイムゾーン) は NULL として配信されます。 |
理解は削除されました
含まれるすべての行は is_delete です。 スケジュールの状態に関するシグナルです。 次の 2 つの値があります。
Value |
意味 |
適用方法 |
|---|---|---|
0 |
スケジュールはアクティブです (現在のバージョン)。 |
このキーを挿入するか、このキーの既存の行を上書きしてください。 |
1 |
スケジュールはもはやアクティブではありません (置き換えられたか、取り消されました)。 |
現在のデータに表示されないようにしてください。 行をドロップするか、フラグを付けたままフィルターで除外します。 |
is_deleted = 1 はいつ発生しますか?
- スケジュール修正。 番組または放送時間が修正されました。 古い session_program_schedule_id は is_deleted = 1 として届きます。 新しい ID が is_deleted = 0 として届きます。 古い ID をアクティブでなくなったものとして適用し、新しい ID を挿入します。
- エアリングが削除されました。 放送は完全に中止されました。 その ID は is_deleted = 1 として届きます。
重要な注意事項
- 同じバッチでは、特定のセッション_プログラム_スケジュール ID が 0 と 1 の両方になることはありません。 エアリングを修正すると、別のキーになります。
- フィードの適格基準を満たしていない行は配信されません。 受信したことがない行が is_deleted = 1 になるとは思わないでください。
重複排除
同じ session_program_schedule_id を複数回受け取る場合があります。 これらは同じ行の更新バージョンです。 重複排除は次の 3 つのステップで処理されます。
- 各 ID の最新バージョンを保管してください。 ID ごとに、last_update_time_utc が最新の行のみを残し、古い行を削除します。 この値は前に進むだけなので、常に最新の値が優先されます。
SELECT *
FROM (
SELECT *,
ROW_NUMBER() OVER (
PARTITION BY session_program_schedule_id
ORDER BY last_update_time_utc DESC
) AS rn
FROM your_staging_table
) t
WHERE rn = 1;
- 重複排除された行をテーブルにマージします。 以下の MERGE パターンを使用してください。 データをロードするたびに is_deleted を処理してください。
MERGE INTO your_table AS target USING dedup_staging AS source ON target.session_program_schedule_id = source.session_program_schedule_id WHEN MATCHED AND source.is_deleted = 1 AND source.last_update_time_utc > target.last_update_time_utc THEN DELETE WHEN MATCHED AND source.is_deleted = 0 AND source.last_update_time_utc > target.last_update_time_utc THEN UPDATE SET program_title = source.program_title, seconds_viewed = source.seconds_viewed, airing_start_utc = source.airing_start_utc, airing_end_utc = source.airing_end_utc, last_update_time_utc = source.last_update_time_utc -- ... all other columns WHEN NOT MATCHED AND source.is_deleted = 0 THEN INSERT (session_program_schedule_id, session_id, program_id, ..., last_update_time_utc) VALUES (source.session_program_schedule_id, source.session_id, source.program_id, ..., source.last_update_time_utc);
一括挿入ではなく MERGE を使用してください。 すべてのファイルを新しい行として読み込むと、is_deleted = 1 行は適用されずにアクティブなデータとしてテーブルに残ります。 常にフラグに基づいて行動してください。 |
- ソフト削除の代替手段。 削除ブランチを UPDATE SET is_deleted = 1 に置き換えてから、クエリ内の WHERE is_deleted = 0 をフィルタリングします。 どちらの方法でも同じ結果が得られます。
推奨摂取頻度
新しいデータセットは、1 日を通して段階的に公開されます。
推奨事項 |
詳細 |
|---|---|
推奨ケイデンス |
1 日に 1 ～ 4 回、最新の情報を入手してください。 |
インクリメンタル戦略 |
StartDateTime を最後に取得したタイムスタンプに設定し、EndDateTime を現在の時刻に設定します。 返されたファイルをすべてDownload 処理し、マージします。 |
日次/週次消費者 |
日次または週次で取得する場合は、その期間のすべてのファイルを処理します。 これにより、更新や削除を見逃すことがなくなります。 |
注:各バッチでは、アクティブな行 (is_deleted = 0) とアクティブでなくなった行 (is_deleted = 1) が混在します。 これらは別々のファイルでは配信されません。 is_deleted 列はこれらを区別します。 |
API の使用例
アカウントの検出、レポートグループと識別子の特定、データセットファイルの取得を行うには、次の手順に従います。
ステップ 0: アカウントを一覧表示する GET /v2/accounts
を呼び出して、アクセスできるスレートアカウントを一覧表示します。 {
"total": 1,
"next": null,
"data": [
{ "id": "12345678", "name": "MGM" }
]
}
ステップ 1: アカウントのビジネスライン GET /v2/accounts/1234567 8
を呼び出して、利用可能なビジネスラインを確認してください。 {
"total": 2,
"next": null,
"data": [
{ "id": "channels", "name": "Channels" },
{ "id": "fast", "name": "FAST" }
]
}
id フィールドは、以降の呼び出しで使用する {REPORT_GROUP} パスセグメントです。
ステップ 2a: チャネル識別子が GET /v2/accounts/12345678/channels
を呼び出す? offset=0&limit=100 でチャンネル識別子を一覧表示します。 {
"total": 2,
"next": null,
"data": [
{ "id": "3f6c1b9d-8a2d-4e7f-9c31-0d5b7b2e6f14", "name": "MGM+" },
{ "id": "a91d4c21-57e0-4b8a-b6f3-2e9c0e1f8b77", "name": "MGM+ Espanol" }
]
}
ステップ 2b:
高速識別子コール GET /v2/accounts/12345678/fast? offset=0&limit=100 で高速識別子を一覧表示します。 {
"total": 1,
"next": null,
"data": [
{ "id": "ABC123", "name": "MGM FAST" }
]
}
ステップ 2c: Identifier 可能なデータセット GET /v2/Accounts/12345678/fast/ABC123/Datasets
を呼び出して、利用可能なデータセットを一覧表示します。 {
"total": 1,
"next": null,
"data": [
{ "id": "fast_linear_program_event_log", "name": "FAST Linear Program Event Log" }
]
}
ステップ 3a:
チャネルデータセットファイルチャネル識別子のデータセットファイルエンドポイントを呼び出します。 レスポンスは gzip 圧縮された CSV ファイルのダウンロード URL のリストを返します。 GET /v2/accounts/12345678/channels/3f6c1b9d-8a2d-4e7f-9c31-0d5b7b2e6f14
/datasets/linear_program_event_log
?startDateTime=2026-09-14T00:00:00Z&endDateTime=2026-09-15T00:00:00Z&offset=0&limit=1000
{
"total": 3,
"next": null,
"data": [
{ "downloadUrl": "https://pvreporting-datasets-prod.s3.amazonaws.com/linear_program_event_log/
3f6c1b9d.../2026/09/14/06/...linear_2f0c...e91a.csv.gz?X-Amz-Algorithm=..." },
{ "downloadUrl": "https://pvreporting-datasets-prod.s3.amazonaws.com/linear_program_event_log/
3f6c1b9d.../2026/09/14/14/...linear_7b41...03cd.csv.gz?..." },
{ "downloadUrl": "https://pvreporting-datasets-prod.s3.amazonaws.com/linear_program_event_log/
3f6c1b9d.../2026/09/14/22/...linear_c8d9...5e60.csv.gz?..." }
]
}
ステップ 3b: FAST データセットファイル FAST
識別子のデータセットファイルエンドポイントを呼び出します。 GET /v2/accounts/12345678/fast/ABC123/datasets/fast_linear_program_event_log
?startDateTime=2026-09-14T00:00:00Z&endDateTime=2026-09-15T00:00:00Z&offset=0&limit=1000
{
"total": 1,
"next": null,
"data": [
{ "downloadUrl": "https://pvreporting-datasets-prod.s3.amazonaws.com/fast_linear_program_event_log/
ABC123/2026/09/14/15/...fast_linear_c258fb25...758add.csv.gz?X-Amz-Algorithm=..." }
]
}
サンプルクエリ
これらのクエリは、データがすでにマージされていることを前提としています。 is_deleted 行を未加工のテーブルに保存している場合は、各クエリに WHERE is_deleted = 0 を追加してください。
一定期間の端末別の閲覧時間数 SELECT station_name,
COUNT(*) AS sessions,
SUM(seconds_viewed) / 3600.0 AS hours_viewed
FROM your_table
WHERE start_segment_utc BETWEEN '[START_DATE]' AND '[END_DATE]'
GROUP BY station_name
ORDER BY hours_viewed DESC;
視聴時間別の上位 X 番組 SELECT program_title, station_name,
SUM(seconds_viewed) / 3600.0 AS hours_viewed
FROM your_table
WHERE start_segment_utc BETWEEN '[START_DATE]' AND '[END_DATE]'
GROUP BY program_title, station_name
ORDER BY hours_viewed DESC
LIMIT [X];
1 日の視聴の概要 SELECT DATE(start_segment_utc) AS view_date,
COUNT(*) AS sessions,
SUM(seconds_viewed) / 3600.0 AS hours_viewed
FROM your_table
WHERE start_segment_utc BETWEEN '[START_DATE]' AND '[END_DATE]'
GROUP BY DATE(start_segment_utc)
ORDER BY view_date DESC;
地域別の閲覧時間 SELECT territory,
SUM(seconds_viewed) / 3600.0 AS hours_viewed
FROM your_table
WHERE start_segment_utc BETWEEN '[START_DATE]' AND '[END_DATE]'
GROUP BY territory
ORDER BY hours_viewed DESC;
ETL パイプライン
この 4 つのステップのパターンを使用して、ライブリニアプログラムデータセットの ETL パイプラインを構築します。
- 初期データプル。 API エンドポイントを使用して、希望の時間範囲内にチャンネルのすべてのファイルをプルします。 返されたファイルをすべてDownload します。 それぞれの行には gzip 圧縮された CSV 形式の行が含まれています。
- 重複排除。 プルしたファイルに同じ session_program_schedule_id のレコードが複数存在する場合は、last_update_time_utc が最新の行だけを残してください。 SQL パターン全体については、「重複排除」セクションを参照してください。
- デスティネーションに適用。 重複排除されたレコードを session_program_schedule_i d をキーとするデスティネーションテーブルにマージし、is_deleted = 0 でアップサートします。 is_deleted = 1 の場合、ID が現在のデータに表示されなくなります。 その行を完全に削除するか、行にフラグを付けたままフィルターで除外します。
- インクリメンタル処理。 ロードが進行中の場合は、最後にプルした時刻に設定し、endDateTime を現在の時刻に設定します。 返されたすべてのファイルを処理し、保存先に MERGE します。
startDateTime = {last_successful_pull_timestamp}
endDateTime = {current_utc_timestamp}
クイックヒント
API をパイプラインに統合するときは、以下のヒントを覚えておいてください。
- セッション_プログラム_スケジュール_IDはあなたのユニークなキーです。 重複排除には必ず last_update_time_utc を使用してください。
- 一括挿入ではなく MERGE を使用してください。 データをロードするたびに is_deleted シグナルを処理します。
- 1 日に 1 ～ 4 回プルして、最新のデータを取得します。
- StartDateTime を、インクリメンタルロードの最後の成功したプルタイムスタンプに設定します。
- 検出エンドポイントを使用して、アカウント、識別子、使用可能なデータセットを検索します。
- パートナーがチャネルとFASTフィードの両方を対象としている場合は、両方のフィードを取得してください。
- ソフト削除アプローチを使用する場合は、すべてのクエリに WHERE is_deleted = 0 追加してください。
- データの最大保存期間は 2 年間です。 履歴データを適宜計画してください。
知っていましたか？ |
プログラムレベルの視聴データにプログラムでアクセスできるため、カスタムレポートを作成したり、スケジューリングシステムにデータを入力したり、線形データを他のビジネスデータと組み合わせたりできます。 この API をワークフローに統合したパートナーは、プログラミングとコンテンツ取得について、より多くの情報に基づいた意思決定をより迅速に行えます。 視覚的な分析や迅速な分析については、Slate Analytics のリニアプログラミングダッシュボードをご覧ください。 |
