Video Central

Datasets APIの概要

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

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

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

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

Datasets APIの準備

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

Analytics APIへのオンボーディング
データセットを取得するには、まずAnalytics APIスイートにオンボーディングする必要があります。詳しくは、こちらをご覧ください。

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

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

ページネーション
すべてのSlate APIのレスポンスはページネーションされます。ページネーションパラメーターは、リクエストパラメーターによって指定されます。

リクエストパラメーター	デフォルト値	説明
limit	10	1ページに返されるドキュメントの数(ページサイズ)。
offset	0	スキップするページ数(ページ番号)。

すべてのページネーションされたレスポンスには、以下のフィールドが含まれます。

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

Dataset 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}

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

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

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

リクエストパラメーター	説明
startDateTime	前回取得した時間から設定することを推奨します。 (形式: YYYY-MM-DDTHH:MM:SSZ - timestamp UTC)
endDateTime	取得時間または現在の時間に設定することを推奨します。 (形式: YYYY-MM-DDTHH:MM:SSZ - timestamp UTC)
limit	最大制限は1ページあたり1,000リンクです。

注: 最大データ保持期間は2年です。タイムスタンプが2年以上前のデータセットに対するリクエストには、結果が返されません。

リクエスト例

レスポンス例

注意:

ZIPファイルサイズの上限は300MBです。この上限を超えるファイルは複数のファイルに分割されます。
署名済みURLの有効期間(TTL)は60分です。

データセットの定義

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

チャンネル登録のデータセット

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

再生データセット

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

カタログデータセット

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

サンプルクエリ

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

次のSQL例は、チャンネル登録を開始後に顧客が最初に視聴したタイトルのうち、上位10件を返します。

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

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