Video Central

データセットAPIの概要

データセットAPIは、当社の新しいパートナーデータ製品であるSlate Analyticsの一部です。他のSlateレポートとは異なり、データセットは追加のみであり（各ファイルに新しいデータがあります）、Slate UIではダウンロードできず（ただし、API経由でのみアクセスできます）、パートナーのデータエンジニア向けに明確に構築されており、詳細なデータを使用して分析を実行できます。このトピックは、データエンジニアがデータセットを取得するためのパイプラインを設定し、データセットファイル内の値を定義するのに役立ちます。また、サンプルクエリを提供し、パートナーがこのデータを使用する最適な方法を提案します。

データセットの実用的な利用

変更ログの形式で消費者にデータセットを提供します。各イベントは1回のみ公開されます。ただし、以前に提供された行の列値を更新する必要がある場合は、次の利用可能なファイルに変更を反映するために、レコードの新しいバージョンを公開します。すべてのデータ変更が確実に確保されるように、変更ログは追加のみとなります。データエンジニアは、この変更ログを使用してデータテーブルを直接更新できます。

変更ログを処理するときは、last_update_time_utc列に基づいて、特定のevent_idの最新のレコードを常に使用することが不可欠です。これにより、各レコードの最新バージョンが常に保持されます。レコードを削除する必要がある場合、このアクションはis_deleted列に反映されます。1の値はレコードが削除されたことを示し、0の値はアクティブなレコードを表します。この変更ログアプローチにより、新規データと変更データを効果的に管理し、データテーブルが常に正確で最新の情報に保たれることが保証されます。

データセットAPIの準備

データセットAPIにリクエストを行う前に、認証とページ設定の基本要件を理解することが重要です。このセクションでは、APIに安全にアクセスし、大規模なデータセットを効率的に管理する方法について説明します。

認証
データセットを取得するには、次のものが必要です。

Amazonセキュリティプロファイルを使用したログイン
トークンを要求するための認証コード
すべてのcurlリクエスト用のトークン

ベースURIはhttps://videocentral.amazon.com/apis/v2です。すべてのリクエストに、リクエスト認証ヘッダーに有効なLWA認証トークンを含める必要があります。例：

リクエストヘッダーにトークンが含まれていないか、トークンが期限切れの場合、データセットAPIは不正な例外を返します。

ページ設定
すべてのSlate API応答はページ分割されます。ページ設定パラメーターは、リクエストパラメーターによって指定されます。

リクエストパラメーター	デフォルト値	説明
制限	10	1ページに返されるドキュメントの数（または、ページサイズ）。
オフセット	0	スキップするページ数（または、ページ番号）。

すべてのページ分割応答には、以下のフィールドが含まれます。

フィールド	説明
合計	すべてのページの合計ドキュメント数。
次	次のページへのURL。最後のページの場合はNull

データセットAPIを使用する

プログラムによってデータセットへアクセスするには、クライアントは、アカウント、グループ、事業、データセットなどの利用可能なリソースを列挙する一連のAPI呼び出しに従い、その後、データファイルのダウンロード用URLを取得する必要があります。この手順は自動化に対応するために設計されており、反復的なデータパイプラインや予定されたワークフローへの統合が可能です。

リストアカウント
/v2/accounts

このリソースは、ユーザーがアクセスできるSlateアカウントのリストを返します。Slateでは、ポータルの右上隅付近にあるアカウントのドロップダウンリストから一連のアカウントにアクセスできます。また、これらのリンクを使用して、account_idまたはchannel/studio_idを検索することもできます。

リクエストの例

応答の例

リストグループ（事業分野）
/v2/accounts/{account_id}

このリソースは、ユーザーがアクセスできる事業分野（チャンネルなど）のグループを返します。

リクエストの例

応答の例

事業のリスト
/v2/accounts/{account_id}/{group_id}

このリソースは、特定の事業分野に応じて、このアカウントで利用できる事業（特定のチャンネル名など）のリストを返します。

リクエストの例

応答の例

使用可能なデータセットのリスト
/v2/accounts/{acccount_id}/{group_id}/{business_id}/datasets

このリソースは、特定のチャンネルまたはスタジオで使用可能なデータセットのリストを返します。（使用可能なデータセットとその属性のリストは、このトピックの後半の「データセット定義」に含まれています。）現在ダウンロードできるデータセットは以下のとおりです。

サブスクリプション：お客様による登録など、顧客ライフサイクルにおけるイベント。
再生：お客様がコンテンツにアクセスしたセッションイベントを再生します。
カタログ：新しいタイトルが追加されたときなど、カタログのメタデータが変更されたイベント。

リクエストの例

応答の例

データセットファイルを取得
/v2/accounts/{account_id}/{group_id}/{business_id}/datasets/{dataset_id}

このリソースは、データセットファイルのリストを提供します。リクエストした時間範囲によっては、リストに多数のファイルが含まれる場合があります。合計フィールドは、予想されるファイルの総数を示します。完全なバックフィルを完了した後は、最後に取得したタイムスタンプをstartDateTimeに、現在の時刻をendDateTimeに設定してファイルをリクエストし続けることで、最新の状態を維持できます。

新しいデータセットは約4時間ごとに公開され、過去12時間以内に発生したイベントを含む場合があります。最新かつ完全なローカルデータを維持するために、1日に複数回、4〜6時間ごとを目安にAPIを呼び出すことを推奨します。公開に遅延が発生した場合は、可能な限り速やかにEメールでご連絡いたします。

次の表では、データセットファイルで使用できるリクエストパラメーターについて説明します。

リクエストパラメーター	説明
startDateTime	前回の取得時刻を基準に設定することを推奨します。（フォーマット：YYYY-MM-DDTHH:MM:SSZ - タイムスタンプUTC）
endDateTime	前回の取得時刻/現在時刻を基準に設定することを推奨します。（フォーマット：YYYY-MM-DDTHH:MM:SSZ - タイムスタンプUTC）
制限	1ページあたりのリンク数の上限は1000件です。

注：当社のデータのリテンションは最長で2年間です。タイムスタンプが2年以上前のデータセットに対するリクエストには、結果が返されません。

リクエストの例

応答の例

注：

ZIPファイルサイズの上限は最大300MBです。ファイルがその上限を超える場合は、複数のファイルに分割されます。
署名付きURLのTime to live（TTL）は60分です。

データセットの定義

このセクションの表は、使用可能な3つのデータセットそれぞれの列、データタイプ、定義を一覧表示しています。

サブスクリプションのデータセット

列	タイプ	定義
subscription_event_id（pk）	文字列	このログを通じて提供される各サブスクリプションイベントの固有ID。
subscription_event_type	文字列	発生したサブスクリプションイベントのタイプ：開始：顧客が以前に登録していなかったチャンネルに登録しました。更新：顧客はチャンネルに登録していて、サブスクリプションイベントの前にそのチャンネルですでにアクティブになっていました。キャンセル：顧客がサブスクリプションをキャンセルしました。アクティブ - ARオン：顧客はアクティブで、自動更新がオンになっています。アクティブ - ARオフ：顧客はアクティブですが、自動更新がオフになっています。
subscription_event_time_utc	タイムスタンプ	サブスクリプションイベントが発生した時刻（UTCに標準化）。
subscription_event_time_zone	文字列	サブスクリプションマーケットプレイスのタイムゾーン。
CID	文字列	匿名化された顧客識別子（CID）。この顧客識別子は、1つの親チャンネルの下にあるすべてのイベントに対して保持され、階層間の移動と顧客ライフサイクルの追跡が可能になります。
offer_id	文字列	イベントが発生した特定のサブスクリプションオファーのID。
offer_name	文字列	人間が読める形式でのオファーの名前。
offer_type	文字列	オファーのタイプ。
offer_marketplace	文字列	サブスクリプションオファーが提供されていたマーケットプレイス。
offer_billing_type	文字列	オファーに必要な支払いの種類: HO：ハードオファー。支払いが必要です。 FT：無料体験。支払いは不要です。
offer_payment_amount	文字列	offer_idの請求金額。
benefit_id	文字列	オファーが設定されているPrime Video特典のID。
channel_label	文字列	オファーが提供されているチャンネルの名前。注：この列にnull値が表示され、懸念がある場合は、担当のCAMまたはPSMにお問い合わせください。
channel_tier_label	文字列	オファーが提供されているチャンネルの名前。注：この列にnull値が表示され、懸念がある場合は、担当のCAMまたはPSMにお問い合わせください。
is_promo	int	イベント時にオファーがプロモーションの対象になっているかどうかを示します（0=プロモーション対象、1=プロモーション非対象）。
create_time_utc	タイムスタンプ	サブスクリプションイベントログレコードが作成された時刻（UTCに標準化）。
last_update_time_utc	タイムスタンプ	サブスクリプションイベントログレコードが最後に更新された時刻（UTCに標準化）。
is_deleted	int	以前に作成されたレコードを削除するかどうかを示します（0=保持、1=削除）。

再生データセット

列	タイプ	定義
session_id（pk）	文字列	再生セッションの固有ID。
marketplace_id	int	再生マーケットプレイスの固有ID。
marketplace_desc	文字列	再生マーケットプレイスのわかりやすい説明。
CID	文字列	UUIDで匿名化されたユーザー識別子。
benefit_id	文字列	ストリーミング再生されたコンテンツに関連付けられている特典。
catalog_id	文字列	カタログテーブルへの結合に使用される外部キー（FK）。
subscription_offer_id	文字列	ストリーミング再生の時点で顧客が登録しているサブスクリプションのoffer_id（ActiveまたはApprovalPending）。
subscription_event_id	文字列	再生時点における登録者の正確なステータスを取得するために、サブスクリプションイベントログと結合するための外部キー（FK）（Active）
start_segment_utc	タイムスタンプ	再生セグメントの開始時刻（UTC）。
end_segment_utc	タイムスタンプ	再生セグメントの終了時刻（UTC）。
seconds_viewed	int	再生中にユーザーがコンテンツをストリーミング再生した秒数。
position_start	ダブル	再生セッションが開始されたストリーミングの秒数。
position_end	ダブル	再生セッションが終了したストリーミングの秒数。
connection_type	文字列	顧客がコンテンツのストリーミングに使用する接続。
stream_type	文字列	ビデオオンデマンド、ライブ、または放送直後（JAB）でのストリーム種別の分類。
device_class	文字列	デバイスのタイプ（リビングルーム、モバイル、ウェブ、その他など）。
device_sub_class	文字列	デバイスのタイプの詳細な分類（ゲーム機、smart_tv、Rokuなど）。
geo_dma	文字列	ストリーミングが生成された地域の3桁の地理指定マーケット地域（DMA）。
playback_method	文字列	再生がオンラインかオフラインかを示します。
品質	文字列	再生品質（1080pまたは4Kなど）
event_type	文字列	定義しているイベントタイプ（playback_segments）
create_time_utc	タイムスタンプ	レコードがテーブルに追加されたときのタイムスタンプ（UTC）。
last_update_time_utc	タイムスタンプ	レコードが変更されたときの最終更新タイムスタンプ（UTC）。
is_deleted	int	パートナーのシステムでレコードを削除する必要があるかどうかをパートナーに伝えるフラグ。

カタログデータセット

列	タイプ	定義
ID（pk）	文字列	タイトルの固有ID。
marketplace_id	int	オファーが提供されているマーケットプレイスの固有ID。
benefit_id	文字列	コンテンツに関連付けられた特典が拡張されました。
タイトル	文字列	シリーズ/映画のタイトル。
vendor_sku	文字列	ベンダーが映画やエピソードごとに生成する任意の識別子。
シーズン	整数	シーズン番号（エピソードコンテンツ用）。
エピソード	整数	エピソード番号。
episode_name	文字列	エピソード名（任意）。
runtime_minutes	整数	視聴したコンテンツの再生時間。
live_linear_channel_name	文字列	ライブコンテンツのチャンネル名。
content_type	文字列	TVか映画のいずれか。
content_quality	文字列	HD（高画質）またはSD（標準画質）
content_group	文字列	3P_SUBS
create_time_utc	タイムスタンプ	レコードがテーブルに追加されたときのタイムスタンプ（UTC）。
last_update_time_utc	タイムスタンプ	レコードが変更されたときの最終更新タイムスタンプ（UTC）。
is_deleted	int	パートナーのシステムでレコードを削除する必要があるかどうかをパートナーに伝えるフラグ。

サンプルクエリ

次のSQL例は、データセットテーブルの接続方法を示しています。subscription_event_id列のサブスクリプションイベントログに再生データを結合できます。これにより、そのストリーミングより前の最新のサブスクリプションステータスが提供されます。この例では、再生データセットのcatalog_id列がcatalog_event_logのidフィールドに結合され、すべてのカタログメタデータが提供されます。

次のSQL例は、サブスクリプションを開始後に顧客が最初に視聴したタイトルのうち、上位10件を返します。

サンプルオーケストレーション

データセットAPIからのデータ抽出を定期的に自動化したい場合、以下のサンプルのPythonスクリプトは、6時間ごとに増分のAPI呼び出しを行う方法を示しています。これは、最後に成功したリクエストのタイムスタンプをローカルに保持することによって追跡し、その値に1秒を足した値を、次の呼び出しのstartDateTimeとして使用します。スクリプトはendDateTimeを現在時刻として計算し、適切なクエリパラメータを構築したうえで、認証付きのGETリクエストを送信します。この方法により、期間をまたがるデータ取得が継続的かつ重複なく実行され、cronや他のジョブ管理システムを使用してスケジュールすることができます。