La nuova API Datasets di Prime Video Slate consente agli sviluppatori di creare client per recuperare le esportazioni event-gain (set di dati) e tutti i set di dati dimensionali correlati.
Importante: il nuovo endpoint qui documentato supporta sia l’abbonamento che la riproduzione. I set di dati di riproduzione sono disponibili solo tramite questo nuovo endpoint.
Panoramica dell’API Datasets
L’API Datasets fa parte del nostro nuovo prodotto di dati per i partner, Slate Analytics. A differenza di altri report Slate, i set di dati sono di sola aggiunta (ogni file contiene nuovi dati), non sono disponibili per il download nell’interfaccia utente di Slate (ma sono accessibili solo tramite API) e sono progettati esplicitamente per consentire ai data engineer partner di utilizzare dati granulari ed eseguire analisi. Questo argomento aiuta i data engineer a configurare le proprie pipeline per recuperare i set di dati, definisce i valori nei file del set di dati e fornisce esempi di query e suggerimenti sui modi ottimali in cui i partner possono utilizzare questi dati.
Uso pratico dei set di dati
Forniamo set di dati ai consumatori sotto forma di registro delle modifiche. Ogni evento viene pubblicato una sola volta. Tuttavia, se è necessario aggiornare i valori di colonna per una riga fornita in precedenza, pubblicheremo una nuova versione del record per riflettere le modifiche nel prossimo file disponibile. Il changelog è di sola aggiunta, per garantire che tutte le modifiche ai dati vengano acquisite. I data engineer possono utilizzare questo changelog per aggiornare direttamente le loro tabelle di dati.
Quando si elabora il changelog, è essenziale utilizzare sempre il record più recente per un determinato event_id, basato sulla colonna last_update_time_utc. Questo assicura di avere sempre la versione più aggiornata di ogni record. Se è necessario eliminare un record, questa azione si riflette nella colonna is_deleted. Il valore 1 indica che il record è stato eliminato, mentre il valore 0 rappresenta un record attivo. Questo approccio basato sul registro delle modifiche consente di gestire in modo efficace i dati nuovi e in evoluzione e garantisce che le tabelle di dati rimangano accurate e aggiornate con le informazioni più recenti.
Informazioni preliminari sull’API Datasets
Prima di effettuare richieste all’API Dataset, è importante comprendere i requisiti di base per l’autenticazione e l’impaginazione. Questa sezione spiega come accedere in modo sicuro all’API e navigare in modo efficiente in set di dati di grandi dimensioni.
Onboarding all’API Analytics
Per recuperare i set di dati devi prima effettuare l’onboarding alla suite di API Analytics. Maggiori dettagli possono essere trovati qui.
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: curl -X GET \
-H "Authorization: Bearer Atza|auth_token" \
https://videocentral.amazon.com/apis/v2/accounts/123456
Se l’intestazione della richiesta non include il token o se il token è scaduto, l’API Datasets restituirà un’eccezione non autorizzata.
Impaginazione Tutte
le risposte dell’API Slate sono impaginate. I parametri di impaginazione vengono specificati tramite i parametri delle richieste.
Parametro di richiesta |
Valore predefinito |
Description |
limite |
10 |
Il numero di documenti restituiti in una singola pagina (le dimensioni della pagina). |
offset |
0 |
Il numero di pagine da saltare (il numero di pagina). |
Tutti le risposte suddivise in pagine contengono i seguenti campi.
Campo |
Description |
totale |
Il numero totale di documenti in tutte le pagine. |
successivo |
L’URL della pagina successiva. Null se è l’ultima pagina. |
Usa l’API Datasets
Per accedere in modo programmatico ai set di dati, i client devono seguire una serie di chiamate API che enumerano 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.
Elenco 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 nell’angolo in alto a destra del portale. Puoi anche usare questi link per trovare il tuo account_id o il tuo canale/studio_id.
Richiesta di esempio |
|
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.
Richiesta di esempio |
|
Esempio di risposta |
|
Elenca le attività commerciali /v2/accounts/ {account_id}/{group_id}
Questa risorsa restituisce un elenco di attività (ad esempio nomi di canali specifici) disponibili per questo account, a seconda della linea di business specificata.
Richiesta di esempio |
|
Esempio di risposta |
|
Elenca i set di dati disponibili /v2/accounts/ {acccount_id}/{business_id} /datasets Questa risorsa restituisce l’elenco dei set di dati disponibili per un determinato canale o studio. (L’elenco dei set di dati disponibili e i relativi attributi sono inclusi nelle definizioni dei set di dati, più avanti in questo argomento.) I set di dati attualmente disponibili per il download sono:
- Abbonamento: eventi nel ciclo di vita del cliente, ad esempio quando un cliente si è abbonato.
- Riproduzione: eventi della sessione di riproduzione in cui i clienti interagiscono con i contenuti.
- Catalogo: eventi in cui i metadati del catalogo sono cambiati, ad esempio quando è stato aggiunto un nuovo titolo.
Richiesta di esempio |
|
Esempio di risposta |
|
Ottieni i file del 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 gran numero di file. Il campo totale indica quanti file aspettarsi. Dopo aver completato un backfill completo, puoi rimanere aggiornato continuando a richiedere i file utilizzando un valore startDateTime uguale all’ultimo timestamp recuperato e un valore EndDateTime impostato sull’ora corrente.
I nuovi set di dati vengono pubblicati all’incirca ogni 4 ore e possono contenere eventi che si sono verificati nelle 12 ore precedenti. Ti consigliamo di chiamare la nostra API più volte al giorno, all’incirca ogni 4-6 ore, per garantire che i dati locali siano il più completi e aggiornati possibile. Se riscontriamo un ritardo nella pubblicazione, lo comunicheremo via e-mail il prima possibile.
La tabella seguente descrive i parametri di richiesta disponibili per i file del set di dati.
Parametro di richiesta |
Description |
Data/ora di inizio |
Si consiglia di impostare a partire dall’ultima volta che è stata estratta. |
Data e ora di fine |
Si consiglia di impostare l’ora di tiraggio/l’ora corrente. |
limite |
Il limite massimo è 1000 link per pagina. |
Nota: la nostra conservazione massima dei dati è di 2 anni. Le richieste di set di dati con un timestamp precedente a 2 anni non restituiranno alcun risultato.
Richiesta di esempio |
|
|
Esempio di risposta |
Note:
|
|
Definizioni dei set di dati
Le tabelle di questa sezione elencano le colonne, i tipi di dati e le definizioni per ciascuno dei 3 set di dati disponibili.
Set di dati di abbonamento
Colonna |
Type |
Definizione |
subscription_event_id (pk) |
stringa |
L’ID univoco per ogni evento di sottoscrizione fornito tramite questo registro. |
tipo_evento di sottoscrizione |
stringa |
Il tipo di evento di abbonamento che si è verificato: Start: il cliente si è iscritto a un canale a cui non era iscritto in precedenza. |
iscrizione_event_time_utc |
timestamp |
L’ora in cui si è verificato l’evento di sottoscrizione, standardizzata in UTC. |
zona temporale_evento di sottoscrizione |
stringa |
Il fuso orario del marketplace degli abbonamenti. |
cid |
corda |
Identificatore del cliente (CID) anonimizzato. Questo identificativo del cliente persisterà per tutti gli eventi in un unico canale principale per consentire il movimento tra i livelli e il monitoraggio del ciclo di vita del cliente. |
id_offerta |
stringa |
L’ID dell’offerta di abbonamento specifica a cui si è verificato l’evento. |
nome_offerta |
stringa |
Il nome leggibile dall’uomo dell’offerta. |
tipo_offerta |
stringa |
Il tipo di offerta. |
offer_marketplace |
corda |
Il marketplace in cui era attiva l’offerta di abbonamento. |
tipo_di_fatturazione dell’offerta |
corda |
Il tipo di pagamento richiesto per l’offerta: HO: offerta rigida; pagamento richiesto. |
importa_pagamento_offerta |
stringa |
L’importo di fatturazione dell’offer_id. |
id_beneficio |
corda |
L’ID del vantaggio Prime Video in base al quale è configurata l’offerta. |
etichetta_canale |
corda |
Il nome del canale a cui si riferisce l’offerta. Nota: se questa colonna mostra un valore nullo e hai dei dubbi, contatta il tuo CAM o il PsM. |
etichetta del livello del canale |
corda |
Il nome del canale a cui si riferisce l’offerta. Nota: se questa colonna mostra un valore nullo e hai dei dubbi, contatta il tuo CAM o il PsM. |
è_promo |
int |
Indica se un’offerta è in promozione al momento dell’evento (0 = nessuna promozione, 1 = sì promozione). |
create_time_utc |
timestamp |
L’ora in cui è stato creato il record del registro degli eventi dell’abbonamento, standardizzato in UTC. |
last_update_time_utc |
timestamp |
L’ora in cui il record del registro degli eventi dell’abbonamento è stato aggiornato l’ultima volta, standardizzata in UTC. |
è_eliminato |
int |
Indica se un record creato in precedenza deve essere eliminato (0 = deve persistere, 1 = deve essere eliminato). |
Set di dati di riproduzione
Colonna |
Type |
Definizione |
session_id (pk) |
corda |
L’ID univoco per la sessione di riproduzione. |
marketplace_id |
int |
L’ID univoco per il marketplace di riproduzione. |
marketplace_desc |
corda |
Una descrizione intuitiva per il Playback Marketplace. |
cid |
corda |
L’identificatore utente, reso anonimo con UUID. |
id_beneficio |
corda |
Il vantaggio associato ai contenuti trasmessi in streaming. |
id_catalogo |
stringa |
Chiave esterna (FK) utilizzata per unirsi alla tabella del catalogo. |
id_offerta di sottoscrizione |
stringa |
Il cliente offer_id in abbonamento è abbonato al momento dello streaming (Attivo o ApprovalPending). |
iscrizione_event_id |
stringa |
Chiave esterna (FK) per accedere al registro degli eventi dell’abbonamento per ottenere lo stato esatto dell’abbonato al momento della riproduzione (Attivo) |
start_segment_utc |
timestamp |
Inizio del segmento di riproduzione in UTC. |
segmento_finale utc |
timestamp |
End del segmento di riproduzione in UTC. |
secondi_visti |
int |
Secondi i contenuti trasmessi dall’utente in streaming durante la riproduzione. |
posizione_inizio |
raddoppiare |
Secondo dello stream in cui è iniziata la sessione di riproduzione. |
posizione_fine |
raddoppiare |
Secondo dello streaming in cui è terminata la sessione di riproduzione. |
tipo_connessione |
corda |
Connessione utilizzata dal cliente per lo streaming del contenuto. |
tipo_flusso |
corda |
Classificazione tra stream Video-On-Demand, Live o Just After Broadcast (JAB). |
classe_dispositivo |
corda |
Type di dispositivo (ad esempio Living Room, Mobile, Web o Altro). |
sottoclasse del dispositivo |
corda |
Tipo di dispositivo granulare (ad esempio console di gioco, smart_tv, roku). |
geo_dma |
corda |
L’area geografica di mercato designata (DMA) a 3 cifre dell’area in cui è stato generato lo stream. |
metodo_riproduzione |
stringa |
Indica se la riproduzione è online o offline. |
qualità |
corda |
Qualità di riproduzione (ad esempio 1080p o 4K) |
tipo_evento |
stringa |
Il tipo di evento che definisce (playback_segments) |
create_time_utc |
timestamp |
Timestamp in cui il record è stato aggiunto alla tabella, in UTC. |
last_update_time_utc |
timestamp |
Ultimo timestamp aggiornato alla modifica del record, in UTC. |
è_eliminato |
int |
Contrassegno per indicare ai partner se il record deve essere eliminato dal loro sistema. |
Set di dati del catalogo
Colonna |
Type |
Definizione |
id (pk) |
corda |
L’ID univoco per il titolo. |
marketplace_id |
int |
L’ID univoco per il marketplace delle offerte. |
id_beneficio |
corda |
Il vantaggio associato al contenuto è stato esteso. |
titolo |
corda |
Il titolo della serie/film. |
vendor_sku |
stringa |
Un identificatore arbitrario generato dal fornitore per ciascuno dei suoi film o episodi. |
stagione |
numero intero |
Il numero della stagione (per i contenuti episodici). |
episodio |
numero intero |
Il numero dell’episodio. |
nome_episodio |
stringa |
Il nome dell’episodio (opzionale). |
runtime_minutes |
numero intero |
La durata del contenuto visualizzato. |
nome_canale_lineare_live |
stringa |
Il nome del canale per i contenuti live. |
tipo_contenuto |
corda |
TV o film. |
qualità_dei contenuti |
corda |
HD o SD |
gruppo_contenuti |
corda |
3P_SUBS |
create_time_utc |
timestamp |
Timestamp in cui il record è stato aggiunto alla tabella, in UTC. |
last_update_time_utc |
timestamp |
Ultimo timestamp aggiornato alla modifica del record, in UTC. |
è_eliminato |
int |
Contrassegno per indicare ai partner se il record deve essere eliminato dal loro sistema. |
Domande di esempio
Il seguente esempio SQL dimostra come si connettono le tabelle del set di dati. È possibile unire i dati di riproduzione al registro degli eventi di sottoscrizione nella colonna subscription_event_id. Ciò fornisce lo stato dell’abbonamento più recente prima dello stream. 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.
select*
from playback_event_log a
left join subscription_event_log b on a.subscription_event_id=b.subscription_event_id
left join catalog_event_log c on a.catalog_id=c.id
Il seguente esempio SQL restituirà i primi 10 titoli visti per la prima volta ai clienti che hanno pubblicato di aver sottoscritto un abbonamento.
with main as (select a.*,row_number() over
(partition by a.cid order by start_segment_utc asc) as rn
from playback_event_log a
inner join (select distinct cid from subscription_event_log
where subscription_event_type='Start' ) b on a.cid = b.cid
)
select c.id,c.title,c.episode_name,c.content_type,sum(seconds_viewed)
as total_seconds_viewed
from main a
inner join catalog_event_log c on a.catalog_id = c.id
where rn = 1
GROUP by c.id,c.title,c.episode_name,c.content_type
order by sum(seconds_viewed) desc
limit 10;
Orchestrazione dei campioni
Se desideri automatizzare l’estrazione dei dati dall’API Datasets in base a una pianificazione ricorrente, il seguente script Python di esempio dimostra come effettuare chiamate API incrementali ogni 6 ore. Tiene traccia del timestamp dell’ultima richiesta riuscita rendendola persistente localmente e utilizza quel valore, più un secondo, come startDateTime per la chiamata successiva. Lo script calcola EndDateTime come ora corrente, crea i parametri di query appropriati e invia una richiesta GET con autenticazione. Questo approccio garantisce il recupero continuo e non sovrapposto dei dati in tutte le finestre temporali e può essere pianificato tramite cron o un altro job scheduler.
import requests
import datetime
import os
# Constants for the API and token
AUTH_TOKEN = "Atza|auth_token"
ACCOUNT_URL = (
"https://videocentral.amazon.com/apis/v2/"
"accounts/123456/7890/abc123/datasets/data987"
)
# File where we persist the timestamp of the last successful API call
LAST_CALL_FILE = "last_call_time.txt"
def load_last_call_time():
"""
Reads the timestamp of the last API call from a local file.
If the file doesn't exist, defaults to a specific start time.
"""
if not os.path.exists(LAST_CALL_FILE):
# If no record exists, assume we're starting fresh from this date
return datetime.datetime(2023, 1, 1, 0, 0, 0, tzinfo=datetime.timezone.utc)
with open(LAST_CALL_FILE, "r") as f:
# Read and parse the ISO timestamp from the file
return datetime.datetime.fromisoformat(f.read().strip())
def save_current_call_time(dt):
"""
Saves the current timestamp to the local file so it can be used
as the starting point for the next API call.
"""
with open(LAST_CALL_FILE, "w") as f:
f.write(dt.isoformat())
def main():
# Current UTC time will be used as the end of the range
now = datetime.datetime.now(datetime.timezone.utc)
# Start time is one second after the last recorded call
start_time = load_last_call_time() + datetime.timedelta(seconds=1)
end_time = now
# Set the query parameters
params = {
"startDateTime": start_time.isoformat(),
"endDateTime": end_time.isoformat(),
"offset": 0,
"limit": 50
}
# Set the auth header
headers = {
"Authorization": f"Bearer {AUTH_TOKEN}"
}
# Make the GET request to the API
response = requests.get(ACCOUNT_URL, headers=headers, params=params)
# Check if the request was successful
if response.ok:
print("Data fetched successfully.")
# Persist the end time as the last successful call time
save_current_call_time(end_time)
else:
print(f"Error fetching data: {response.status_code} - {response.text}")
if __name__ == "__main__":
main()
