Video Central

Panoramica dell’API Dataset

L’API Dataset fa parte del nostro nuovo prodotto di dati per i partner, Slate Analytics. A differenza degli altri report di Slate, i set di dati consentono solo l’aggiunta (ogni file contiene nuovi dati), non sono disponibili per il download tramite l’interfaccia utente di Slate (ma sono accessibili esclusivamente tramite API) e sono progettati appositamente per consentire ai data engineer dei partner di usufruire di dati granulari e svolgere analisi. Questo argomento supporta i data engineer nella configurazione delle pipeline per il recupero dei set di dati, descrive i valori contenuti nei file dei set di dati e fornisce query di esempio e indicazioni su come i partner possono sfruttare al meglio questi dati.

Uso pratico dei set di dati

Forniamo set di dati ai consumatori sotto forma di changelog. Ogni evento viene pubblicato una sola volta. Tuttavia, se è necessario aggiornare i valori delle colonne per una riga fornita in precedenza, pubblicheremo una nuova versione del record per riflettere le modifiche nel successivo file disponibile. Il changelog consente solo l’aggiunta, per garantire che tutte le modifiche ai dati vengano registrate. I data engineer possono utilizzare questo changelog per aggiornare direttamente le tabelle di dati.

Quando elabori il changelog, è essenziale utilizzare sempre il record più recente per un determinato event_id, in base alla colonna last_update_time_utc. Questo assicura di avere sempre la versione più aggiornata di ogni record. Se è necessario eliminare un record, questa azione viene riportata nella colonna is_deleted. Il valore 1 indica che il record è stato eliminato, mentre il valore 0 rappresenta un record attivo. Questo approccio al changelog consente di gestire efficacemente dati nuovi e modificati, assicurando che le tabelle dei dati siano sempre accurate e aggiornate con le informazioni più recenti.

Informazioni preliminari sull’API Dataset

Prima di effettuare richieste all’API Dataset, è importante comprendere i requisiti base per l’autenticazione e l’impaginazione. Questa sezione spiega come accedere in modo sicuro all’API e come gestire efficacemente set di dati di grandi dimensioni.

Autenticazione
Per recuperare i set di dati è necessario quanto segue:

Un profilo di sicurezza Accedi con Amazon
Un codice di autorizzazione per richiedere un token
Un token per tutte le richieste curl

L’URI di base è: https://videocentral.amazon.com/apis/v2. Tutte le richieste devono includere un token di autenticazione LWA valido nell’intestazione di autorizzazione della richiesta. Ad esempio:

Se l’intestazione della richiesta non include il token o se il token è scaduto, l’API Dataset restituirà un’eccezione di accesso non autorizzato.

Impaginazione
Tutte le risposte dell’API Slate sono impaginate. I parametri di impaginazione vengono specificati tramite i parametri delle richieste.

Parametro richiesta	Valore predefinito	Descrizione
limit	10	Numero di documenti restituito in una singola pagina (la dimensione della pagina).
offset	0	Numero di pagine da ignorare (il numero di pagina).

Tutte le risposte impaginate contengono i seguenti campi.

Campo	Descrizione
total	Conteggio totale dei documenti in tutte le pagine.
next	URL alla pagina successiva. Null se è l’ultima pagina.

Uso dell’API Dataset

Per accedere programmaticamente ai set di dati, i clienti devono eseguire una serie di chiamate API che elencano le risorse disponibili, come account, gruppi, aziende e set di dati, prima di recuperare gli URL scaricabili per i file di dati. Questa sequenza è progettata per supportare l’automazione e può essere integrata in pipeline di dati ricorrenti o flussi di lavoro pianificati.

Elenca account
/v2/accounts

Questa risorsa restituisce l’elenco degli account Slate a cui l’utente può accedere. Il set di account è accessibile in Slate tramite l’elenco a discesa degli account, situato in alto a destra nel portale. Puoi inoltre usare questi link per trovare il tuo account_id o il tuo channel/studio_id.

Esempio di richiesta

Esempio di risposta

Elenca gruppi (linee di business)
/v2/accounts/{account_id}

Questa risorsa restituisce i gruppi di linee di business (come i canali) a cui l’utente può accedere.

Esempio di richiesta

Esempio di risposta

Elenca business
/v2/accounts/{account_id}/{group_id}

Questa risorsa restituisce un elenco dei business (ad esempio, nomi specifici di canali) disponibili per questo account, in base alla linea di business indicata.

Esempio di richiesta

Esempio di risposta

Elenca set di dati disponibili
/v2/accounts/{acccount_id}/{group_id}/{business_id}/datasets

Questa risorsa restituisce l’elenco dei set di dati disponibili per un determinato canale o studio. (L’elenco dei dataset disponibili e delle loro caratteristiche è riportato nella sezione Definizioni dei dataset, più avanti in questo argomento.) I set di dati attualmente disponibili per il download sono:

Iscrizione: eventi nel ciclo di vita del cliente, ad esempio quando un cliente si iscrive.
Riproduzione: eventi relativi alle sessioni di fruizione dei contenuti da parte dei clienti.
Catalogo: eventi che riflettono modifiche ai metadati del catalogo, come l’aggiunta di nuovi contenuti.

Esempio di richiesta

Esempio di risposta

Ottieni file di set di dati
/v2/accounts/{account_id}/{group_id}/{business_id}/datasets/{dataset_id}

Questa risorsa fornisce un elenco di file di set di dati. A seconda dell’intervallo di tempo richiesto, l’elenco può includere un numero elevato di file. Il campo total specifica il numero totale di file previsti. Dopo avere caricato tutti i dati precedenti, puoi rimanere aggiornato continuando a richiedere file con startDateTime pari all’ultimo timestamp ottenuto e endDateTime impostato sull’orario attuale.

Circa ogni 4 ore vengono pubblicati nuovi set di dati, che possono includere eventi verificatisi nelle 12 ore precedenti. Ti consigliamo di chiamare la nostra API più volte al giorno, circa ogni 4-6 ore, per assicurarti che i dati locali siano il più completi e aggiornati possibile. Qualora si verifichi un ritardo nella pubblicazione, provvederemo a comunicarlo tempestivamente via e-mail.

La tabella seguente descrive i parametri di richiesta disponibili per i file dei set di dati.

Parametro richiesta	Descrizione
startDateTime	Si raccomanda di impostare questo valore a partire dall’ultimo momento in cui i dati sono stati estratti. (Formato: YYYY-MM-DDTHH:MM:SSZ - timestamp in UTC)
endDateTime	Si raccomanda di impostare questo valore al momento della richiesta o all’ora corrente. (Formato: YYYY-MM-DDTHH:MM:SSZ - timestamp in UTC)
limit	Il limite massimo è 1000 link per pagina.

Nota: il periodo massimo di conservazione dei dati è pari a 2 anni. Le richieste di set di dati con timestamp antecedenti a due anni non forniranno alcun risultato.

Esempio di richiesta

Esempio di risposta

Note:

La dimensione massima del file zip è 300 MB. I file che superano tale limite verranno suddivisi in più file.
Il time-to-live (TTL) dell’URL prefirmato è di 60 minuti.

Definizioni dei set di dati

Le tabelle in questa sezione elencano le colonne, i tipi di dati e le definizioni per ciascuno dei 3 set di dati disponibili.

Set di dati Iscrizione

Colonna	Tipo	Definizione
subscription_event_id (pk)	stringa	L’ID univoco associato a ciascun evento di iscrizione riportato nel registro.
subscription_event_type	stringa	Il tipo di evento di iscrizione che si è verificato: Inizio: il cliente si è abbonato a un canale a cui non era precedentemente iscritto. Rinnovo: il cliente si è iscritto a un canale per cui era già attiva un’iscrizione prima dell’evento. Annullamento: il cliente ha annullato l’iscrizione. Attivo - AR ON: il cliente ha un’iscrizione attiva e ha attivato il rinnovo automatico. Attivo - AR OFF: il cliente ha un’iscrizione attiva, ma ha disattivato il rinnovo automatico.
subscription_event_time_utc	timestamp	L’ora in cui si è verificato l’evento di sottoscrizione, in formato UTC
subscription_event_time_zone	stringa	Il fuso orario del mercato in cui è avvenuta l’iscrizione.
cid	stringa	Identificativo del cliente anonimo (CID). Questo identificativo cliente resterà invariato per tutti gli eventi relativi a un singolo canale principale, per consentire i passaggi tra livelli e il tracciamento del ciclo di vita del cliente.
offer_id	stringa	L’ID dell’offerta di iscrizione specifica associata all’evento.
offer_name	stringa	Il nome dell’offerta in formato comprensibile all’utente.
offer_type	stringa	Il tipo di offerta.
offer_marketplace	stringa	Il mercato in cui l’offerta di iscrizione è stata resa disponibile.
offer_billing_type	stringa	Il tipo di pagamento richiesto per l’offerta: HO: offerta a pagamento; pagamento richiesto. FT: periodo d’uso gratuito; nessun pagamento richiesto.
offer_payment_amount	stringa	L’importo di fatturazione dell’offer_id.
benefit_id	stringa	L’ID del vantaggio Prime Video a cui è associata l’offerta.
channel_label	stringa	Il nome del canale a cui è associata l’offerta. Nota: se il valore in questa colonna è nullo e hai delle perplessità, ti invitiamo a contattare il tuo CAM o PsM.
channel_tier_label	stringa	Il nome del canale a cui è associata l’offerta. Nota: se il valore in questa colonna è nullo e hai delle perplessità, ti invitiamo a contattare il tuo CAM o PsM.
is_promo	int	Indica se un’offerta è in promozione al momento dell’evento (0 = nessuna promozione, 1 = promozione attiva).
create_time_utc	timestamp	L’ora in cui è stato creato il record del registro degli eventi di iscrizione, in formato UTC.
last_update_time_utc	timestamp	L’ora dell’ultimo aggiornamento del record del registro degli eventi di iscrizione, in formato UTC.
is_deleted	int	Indica se un record creato in precedenza deve essere eliminato (0 = da mantenere, 1= da eliminare).

Set di dati Riproduzione

Colonna	Tipo	Definizione
session_id (pk)	stringa	L’ID univoco della sessione di riproduzione.
marketplace_id	int	L’ID univoco del mercato in cui è avvenuta la riproduzione.
marketplace_desc	stringa	Una descrizione semplice e chiara del mercato in cui avviene la riproduzione.
cid	stringa	L’identificativo dell’utente, anonimizzato tramite UUID.
benefit_id	stringa	Il vantaggio associato al contenuto riprodotto in streaming.
catalog_id	stringa	Chiave esterna (FK) utilizzata per il collegamento alla tabella catalogo.
subscription_offer_id	stringa	L’offer_id dell’iscrizione attiva al momento dello streaming (Active o ApprovalPending).
subscription_event_id	stringa	Chiave esterna (FK) per collegarsi al registro degli eventi di iscrizione e ottenere lo stato esatto dell’iscritto al momento della riproduzione (Active)
start_segment_utc	timestamp	Inizio del segmento di riproduzione in UTC.
end_segment_utc	timestamp	Fine del segmento di riproduzione in UTC.
seconds_viewed	int	Durata in secondi della fruizione da parte dell’utente durante la riproduzione.
position_start	doppio	Secondo dello streaming in cui è iniziata la sessione di riproduzione.
position_end	doppio	Secondo dello streaming in cui è terminata la sessione di riproduzione.
connection_type	stringa	Connessione utilizzata dal cliente per guardare in streaming il contenuto.
stream_type	stringa	Differenziazione tra video-on-demand, streaming in diretta o Just After Broadcast (JAB).
device_class	stringa	Tipo di dispositivo (ad esempio soggiorno, mobile, web o altri).
device_sub_class	stringa	Tipologia specifica di dispositivo (ad esempio console di gioco, smart TV, roku).
geo_dma	stringa	Il codice di tre cifre dell’area di mercato designata a livello geografico (DMA) dell’area in cui lo streaming è stato generato.
playback_method	stringa	Specifica se la riproduzione avviene in modalità Online o Offline.
quality	stringa	Qualità della riproduzione (ad esempio 1080p o 4K)
event_type	stringa	La tipologia di evento distintiva (playback_segments)
create_time_utc	timestamp	Timestamp di quando il record è stato aggiunto alla tabella, in UTC.
last_update_time_utc	timestamp	Timestamp dell’ultima modifica del record, in UTC.
is_deleted	int	Contrassegno per indicare ai partner se il record va cancellato dal loro sistema.

Set di dati Catalogo

Colonna	Tipo	Definizione
id (pk)	stringa	L’ID univoco per il titolo.
marketplace_id	int	L’ID univoco per il mercato associato all’offerta.
benefit_id	stringa	Il vantaggio associato al contenuto esteso.
title	stringa	Il titolo della serie/del film.
vendor_sku	stringa	Un identificatore arbitrario che il fornitore genera per ciascuno dei suoi film o episodi.
season	intero	Il numero della stagione (per contenuti episodici).
episode	intero	Il numero dell’episodio.
episode_name	stringa	Il nome dell’episodio (opzionale).
runtime_minutes	intero	La durata del contenuto visualizzato.
live_linear_channel_name	stringa	Il nome del canale per i contenuti in diretta.
content_type	stringa	Serie TV o Film.
content_quality	stringa	HD o SD
content_group	stringa	3P_SUBS
create_time_utc	timestamp	Timestamp di quando il record è stato aggiunto alla tabella, in UTC.
last_update_time_utc	timestamp	Timestamp dell’ultima modifica del record, in UTC.
is_deleted	int	Contrassegno per indicare ai partner se il record va cancellato dal loro sistema.

Query di esempio

Il seguente esempio SQL dimostra come le tabelle del set di dati si collegano tra loro. I dati di riproduzione possono essere associati al registro degli eventi di iscrizione tramite la colonna subscription_event_id. Restituisce lo stato più recente dell’iscrizione prima dello streaming. In questo esempio, la colonna catalog_id nel set di dati di riproduzione viene unita al campo id in catalog_event_log per fornire tutti i metadati del catalogo.

Il seguente esempio SQL restituirà i primi 10 titoli visti per la prima volta dai clienti dopo l’inizio dell’iscrizione.

Esempio di gestione orchestrata

Se desideri automatizzare l’estrazione dei dati dall’API Dataset su base ricorrente, il seguente script Python di esempio mostra come effettuare chiamate API incrementali ogni 6 ore. Tiene traccia del timestamp dell’ultima richiesta completata con successo salvandolo localmente, e utilizza tale valore (a cui aggiunge un secondo) come startDateTime per la chiamata successiva. Lo script imposta endDateTime sull’ora corrente, costruisce i parametri della query appropriati e invia una richiesta GET con autenticazione. In questo modo, ci si assicura che i dati vengano estratti in modo continuo e senza sovrapposizioni tra le diverse finestre temporali, con la possibilità di pianificare le esecuzioni tramite cron o strumenti simili.