Video Central

Gli schemi descritti in questo argomento sono destinati agli sviluppatori per l’integrazione con le API Avails. Questi schemi saranno organizzati all’interno di un pacchetto dedicato per semplificare la governance. Gli schemi di payload sono conformi allo standard MDDF API v2.6; tuttavia, non tutti gli attributi dell’API MDDF v2.6 sono supportati da Prime Video. Gli attributi non supportati possono ancora essere inclusi nel payload, ma Prime Video li ignorerà.

Codifica

I payload verranno codificati in formato JSON. La codifica XML può essere presa in considerazione per l’implementazione futura.

Come viene convertito l’XML MDDF in JSON

L’API Avails MDDF definisce il suo schema in formato XML, ma supporta payload sia in XML che in JSON. Le API dei partner Prime Video utilizzeranno payload con codifica JSON. Il processo per convertire l’XML MDDF in JSON è descritto qui:

Quando si generano i nomi degli attributi JSON, gli spazi dei nomi vengono omessi.
Il contenuto di testo degli elementi viene assegnato direttamente al valore dell’oggetto JSON corrispondente.

diventa
Gli elementi nidificati diventano proprietà nidificate.

diventa
Più elementi con lo stesso nome e allo stesso livello diventano elementi della matrice.

diventa
I contenuti misti (elementi e nodi di testo) allo stesso livello diventano elementi della matrice.

diventa
Gli attributi vanno nelle proprietà e i nomi degli attributi sono preceduti da un trattino basso.

diventa

Gestione delle versioni

Ogni versione dello schema di payload verrà mantenuta in un file Smithy separato. Questa pagina sarà la fonte autorevole per la versione specifica dello schema API Avails.

Tipi comuni

Lo schema API Avails supporta i seguenti tipi di dati, che richiedono una revisione della governance per garantire la standardizzazione in tutti i server di risorse.

Il numero massimo di elementi consentiti nelle richieste batch è limitato a 100.

Tipo	Descrizione
Boolean	Tipo booleano. Valori consentiti: true, false
Integer	Numero intero con segno a 32 bit.
LongInteger	Numero intero con segno a 64 bit.
Decimal	Numero in virgola mobile.
String	Una matrice di caratteri.
Timestamp	Timbro di data e ora ISO.
Enum	Una stringa enumerata con un set predefinito di valori consentiti.
Struct	La struttura funge da aggregatore per altri attributi.
Array	Raccolta di elementi di tipo ASME. Designato da [].

Schemi

Tipo PutAvailsAPIRequest

Attributo	Tipo	È obbligatorio	Descrizione
avail	Avail	Sì	Dati di disponibilità

Tipo PutAvailsAPIResponse

Attributo	Tipo	È obbligatorio	Descrizione
success	Boolean	Sì	Stato dell’operazione
errors	Error[]	No	Elenco degli errori in caso di errore

Tipo ValidateAvailsAPIRequest

Attributo	Tipo	È obbligatorio	Descrizione
avail	Avail	Sì	Dati di disponibilità

Tipo ValidateAvailsAPIResponse

Attributo	Tipo	È obbligatorio	Descrizione
success	Boolean	Sì	Stato dell’operazione
errors	Error[]	No	Elenco degli errori in caso di errore

Tipo DeleteAvailsAPIResponse

Attributo	Tipo	È obbligatorio	Descrizione
success	Boolean	Sì	Stato dell’operazione
errors	Error[]	No	Elenco degli errori in caso di errore

Tipo GetAvailsAPIResponse

Attributo	Tipo	È obbligatorio	Descrizione
avail	Avail	Sì	Dati di disponibilità
success	Boolean	Sì	Stato dell’operazione
errors	Error[]	No	Elenco degli errori in caso di errore

Tipo PutAvailsBatchAPIRequest

Attributo	Tipo	È obbligatorio	Descrizione
requestItems	PutAvailsBatchAPIRequestItem[]	Sì	Elenco delle singole richieste

Tipo PutAvailsBatchAPIResponse

Attributo	Tipo	È obbligatorio	Descrizione
responseItems	PutAvailsBatchAPIResponseItem[]	Sì	Elenco degli elementi di risposta

Tipo PutAvailsBatchAPIRequestItem

Attributo	Tipo	È obbligatorio	Descrizione
requestItemId	String	Sì	Identificatore univoco dell’elemento nella richiesta batch
path	String	Sì	Percorso a una risorsa per questo elemento di richiesta. Per il modello Full Extract il formato è: /avails/{licensor}/full-extract/{ALID} Per il modello Partial Extract il formato è: /avails/{licensor}/partial-extract/transactions/{transactionID}
body	PutAvailsBatchAPIRequestItemBody	Sì	Dati di disponibilità

Tipo PutAvailsBatchAPIRequestItemBody

Attributo	Tipo	È obbligatorio	Descrizione
avail	Avail	Sì	Dati di disponibilità

Tipo PutAvailsBatchAPIResponseItem

Attributo	Tipo	È obbligatorio	Descrizione
requestItemId	String	Sì	Identificatore univoco dell’elemento nella richiesta batch
success	Boolean	Sì	Stato dell’operazione
errors	Error[]	No	Elenco degli errori in caso di errore

Tipo ValidateAvailsBatchAPIRequest

Attributo	Tipo	È obbligatorio	Descrizione
requestItems	ValidateAvailsBatchAPIRequestItem[]	Sì	Elenco delle singole richieste

Tipo ValidateAvailsBatchAPIResponse

Attributo	Tipo	È obbligatorio	Descrizione
responseItems	ValidateAvailsBatchAPIResponseItem[]	Sì	Elenco degli elementi di risposta

Tipo ValidateAvailsBatchAPIRequestItem

Attributo	Tipo	È obbligatorio	Descrizione
requestItemId	String	Sì	Identificatore univoco dell’elemento nella richiesta batch
path	String	Sì	Percorso a una risorsa per questo elemento di richiesta Per il modello Full Extract il formato è: /avails/{licensor}/full-extract/{ALID}/validate Per il modello Partial Extract il formato è: /avails/{licensor}/partial-extract/transactions/{transactionID}/validate
body	ValidateAvailsBatchAPIRequestItemBody	Sì	Corpo della richiesta

Tipo ValidateAvailsBatchAPIRequestItemBody

Attributo	Tipo	È obbligatorio	Descrizione
avail	Avail	Sì	Dati di disponibilità

Tipo ValidateAvailsBatchAPIResponseItem

Attributo	Tipo	È obbligatorio	Descrizione
requestItemId	String	Sì	Identificatore univoco dell’elemento nella richiesta batch
success	Boolean	Sì	Stato dell’operazione
errors	Error[]	No	Elenco degli errori in caso di errore

Tipo DeleteAvailsBatchAPIRequest

Attributo	Tipo	È obbligatorio	Descrizione
requestItems	DeleteAvailsBatchAPIRequestItem[]	Sì	Elenco delle singole richieste

Tipo DeleteAvailsBatchAPIResponse

Attributo	Tipo	È obbligatorio	Descrizione
responseItems	DeleteAvailsBatchAPIResponseItem[]	Sì	Elenco degli elementi di risposta.

Tipo DeleteAvailsBatchAPIRequestItem

Attributo

Tipo

È obbligatorio

Descrizione

requestItemId

String

Sì

Identificatore univoco dell’elemento nella richiesta batch

path

String

Sì

Percorso a una risorsa per questo elemento di richiesta

Per il modello Full Extract il formato è:
/avails/{licensor}/full-extract/{ALID}?territory={Territory}&businessLine={BusinessLine}&contractID={CPH|FIXED_FEE}&channelIdentity={Channel}

Per il modello Partial Extract il formato è:
/avails/{licensor}/partial-extract/transactions/{transactionID}

DeleteAvailsBatchAPIResponseItem type

Attributo	Tipo	È obbligatorio	Descrizione
requestItemId	String	Sì	Identificatore univoco dell’elemento nella richiesta batch
success	Boolean	Sì	Stato dell’operazione
errors	Error[]	No	Elenco degli errori in caso di errore

GetAvailsBatchAPIRequest

Attributo	Tipo	È obbligatorio	Descrizione
requestItems	GetAvailsBatchAPIRequestItem[]	Sì	Elenco delle singole richieste

GetAvailsBatchAPIResponse

Attributo	Tipo	È obbligatorio	Descrizione
responseItems	GetAvailsBatchAPIResponseItem[]	Sì	Elenco degli elementi di risposta.

GetAvailsBatchAPIRequestItem

Attributo

Tipo

È obbligatorio

Descrizione

requestItemId

String

Sì

Identificatore univoco dell’elemento nella richiesta batch

path

String

Sì

Percorso a una risorsa per questo elemento di richiesta.

Per il modello Full Extract il formato è:
/avails/{licensor}/full-extract/{ALID}?territory={Territory}&businessLine={BusinessLine}

Per il modello Partial Extract il formato è:
/avails/{licensor}/partial-extract/transactions/{transactionID}

GetAvailsBatchAPIResponseItem

Attributo	Tipo	È obbligatorio	Descrizione
requestItemId	String	Sì	Identificatore univoco dell’elemento nella richiesta batch
success	Boolean	Sì	Stato dell’operazione
errors	Error[]	No	Elenco degli errori in caso di errore
avail	Avail	No	Oggetto Avail

Tipo Error

Attributo

Tipo

È obbligatorio

Descrizione

code

String

Sì

Una stringa che descrive il tipo di errore.

Codici di errore di convalida: APIV{number}, CRMSV{number}
Codici di errore di servizio: APIE{number}, CRMSE{number}

Esempi: APIV400, CRMSE500

message

String

Sì

Descrizione leggibile dell’errore

Tipo Avail

Attributo	Tipo	Obbligatorio	Note
ALID	String	Sì	Specifica l’identificatore del titolo. Deve corrispondere all’ALID specificato nel contributo di metadati.
Disposition	AvailDisposition	Sì	Specifica la granularità del modello di estrazione.
Licensor	Publisher	Sì	Specifica le informazioni sull’entità che concede la licenza a Prime Video.
Asset	AvailAsset[]	Sì	Informazioni sulla risorsa. Nell’elenco deve essere specificata una sola risorsa.
Transaction	AvailTrans[]	Sì	Informazioni sulla transazione.
SharedEntitlement	AvailSharedEntitlement[]	No	Informazioni sui diritti per altri servizi.

Tipo AvailDisposition

Attributo	Tipo	Obbligatorio	Note
EntryType	Enum	Sì	Valori consentiti: FullExtract, FullDelete, PartialExtract, PartialDelete

Tipo Publisher

Attributo	Tipo	Obbligatorio	Note
DisplayName	String	Sì	Specifica il nome del partner Prime Video. Questo valore verrà fornito ai partner da Prime Video. Deve essere lo stesso valore utilizzato nei file EMA.

Tipo AvailAsset

Attributo	Tipo	Obbligatorio	Note
_contentID	String	Sì	Specifica l’ID del contenuto di questa risorsa. Questo valore verrà fornito ai partner da Prime Video. Deve essere lo stesso valore utilizzato nei file EMA. Deve essere uguale al valore ALID fornito in avail.
WorkType	Enum	Sì	Valori consentiti: Movie, Short, Episode, Season, Supplemental
Metadata	AvailUnitMetadata	No	Descrive i metadati per Movie o Short. Obbligatorio quando WorkType è Movie o Short.
EpisodeMetadata	AvailEpisodeMetadata	No	Descrive i metadati per Episode. Obbligatorio quando WorkType è Episode.
SeasonMetadata	AvailSeasonMetadata	No	Descrive i metadati per Season. Obbligatorio quando WorkType è Season.

Tipo AvailSharedEntitlement

Attributo	Tipo	Obbligatorio	Note
_ecosystem	Enum	Sì	Valori consentiti: DMA
EcosystemID	String	Sì	Identificatore del titolo specifico dell’ecosistema

Tipo AvailUnitMetadata

Attributo	Tipo	Obbligatorio	Note
TitleInternalAlias	String[]	Sì	Nome del titolo. Nell’elenco deve essere specificato un solo nome di titolo.

Tipo AvailEpisodeMetadata

Attributo	Tipo	Obbligatorio	Note
TitleInternalAlias	String[]	Sì	Nome del titolo per Episode. Nell’elenco deve essere specificato un solo nome di titolo.
EpisodeNumber	ContentSequenceInfo	Sì	Numero di questo episodio all’interno della stagione.
SeasonMetadata	AvailSeasonMetadata	Sì	Descrive i metadati per Season. Obbligatorio quando WorkType è Episode o Season.
SeriesMetadata	AvailSeriesMetadata	Sì	Descrive i metadati per Series. Obbligatorio quando WorkType è Episode o Season.

Tipo AvailSeasonMetadata

Attributo	Tipo	Obbligatorio	Note
SeasonContentID	String	Sì	ALID per la stagione.
SeasonTitleInternalAlias	String[]	No	Nome del titolo per Season. Nell’elenco deve essere specificato un solo nome di titolo.
SeasonNumber	ContentSequenceInfo	Sì	Numero di questa stagione all’interno della serie.
NumberOfEpisodes	Integer	Sì	Numero di episodi in questa stagione.
SeriesMetadata	AvailSeriesMetadata	No	Descrive i metadati per Series. Obbligatorio quando WorkType è Season.

Tipo AvailSeriesMetadata

Attributo	Tipo	Obbligatorio	Note
SeriesContentID	String	Sì	ALID per la serie.
SeriesTitleInternalAlias	String[]	No	Nome del titolo per Series. Nell’elenco deve essere specificato un solo nome di titolo.
NumberOfSeasons	Integer	No	Numero di stagioni in questa serie.

Tipo AvailTrans

Attributo	Tipo	Obbligatorio	Note
_TransactionID	String	No	Identificatore univoco della finestra di disponibilità. Obbligatorio quando si utilizza PartialExtract. Facoltativo quando si utilizza FullExtract.
LicenseType	Enum	Sì	Valori consentiti: SVOD, FVOD, EST, POEST, VOD
Territory	Region[]	Sì	Territorio in cui è consentita la distribuzione. È necessario fornire un solo elemento territorio. Tutte le transazioni all’interno di un singolo oggetto Avail devono avere lo stesso territorio.
Start	DateTime	Sì	Data e ora di inizio della distribuzione in formato ISO.
End	DateTime	No	Data e ora di fine distribuzione in formato ISO. Se non viene fornita, la distribuzione ha durata illimitata.
AssetLanguage	AssetLanguage[]	No	Lingua della risorsa espressa come codice di lingua ISO con il tipo di risorsa. Tipi di risorse consentite: subtitle, audio, subdub, sub, dub, ov, mta, any
AllowedLanguage	AssetLanguage[]	No	Codice della lingua ISO con il tipo di risorsa. Tipi di risorse consentite: subtitle, audio, sub, dub, subdub, any
HoldbackLanguage	AssetLanguage[]	No	Codice della lingua ISO con il tipo di risorsa. Tipi di risorse consentite: subtitle, audio, sub, dub, subdub, any
LicenseRightsDescription	String	No	Usato per specificare la priorità di pubblicazione.
FormatProfile	AvailFormatProfile	Sì	Qualità del video disponibile. Valori consentiti: SD, HD, UHD
ContractID	String	No	Specifica le informazioni contrattuali. Valori consentiti: - CPH - FIXED_FEE - FIXED_FEE:{Deal ID} Quando si inviano le informazioni sulla disponibilità, le opzioni FIXED_FEE sono limitate dal licensor.
Terms	AvailTerms[]	Sì	Specifica l’elenco dei termini commerciali per la finestra di disponibilità.
OtherInstructions	String	No	Istruzioni di elaborazione aggiuntive per la finestra di disponibilità.

Tipo Region

Attributo	Tipo	Obbligatorio	Note
country	String	Sì	Codice paese ISO 3166-1 di 2 lettere

Tipo AssetLanguage

Attributo

Tipo

Obbligatorio

Note

value

String

Sì

Lingua della risorsa espressa come codice di lingua RFC 5646 con il tipo di risorsa.

_asset

String

Sono ammessi diversi set di valori, a seconda dell’attributo language del tipo AvailTrans.

Valori consentiti per AvailTrans.AssetLanguage:
subtitle, audio, subdub, sub, dub, ov, mta, any.
Questo attributo richiede la stessa risorsa inviata per tutte le lingue.

Valori consentiti per AvailTrans.AllowedLanguage e AvailTrans. HoldbackLanguage:
subtitle, audio, sub, dub, subdub, any.
Quando il valore della risorsa è “subdub”, “any” o il valore è assente, si estenderà a due risorse: “subtitle” e “audio”.

Le risorse “sub” e “dub” vengono convertite nel loro equivalente “subtitle” e “audio” MDDF.

Tipo AvailFormatProfile

Attributo	Tipo	Obbligatorio	Note
value	Enum	Sì	Qualità del video disponibile. Valori consentiti: SD, HD, UHD

Tipo AvailTerms

Attributo	Tipo	Obbligatorio	Note
_termName	String	Sì	Identifica il termine. Il valore non fa distinzione tra maiuscole e minuscole. Per un elenco dei valori consentiti, vedere di seguito.
Money	Money	No	Per maggiori dettagli, vedere di seguito.
Text	String	No	Per maggiori dettagli, vedere di seguito.
Event	DateTime	No	Per maggiori dettagli, vedere di seguito.
Boolean	Boolean	No	Per maggiori dettagli, vedere di seguito.
Duration	String	No	Per maggiori dettagli, vedere di seguito.
Number	Integer	No	Per maggiori dettagli, vedere di seguito.

Termini supportati

Nome del termine	Attributo	Obbligatorio	Note
ChannelIdentity	Text	Sì	Identificatore di un canale o di un’iscrizione.
Tier	Text	Condizionale	Fascia di prezzo. Obbligatorio se il tipo di licenza è POEST.
SRP	Money	Condizionale	Prezzo di vendita suggerito. Obbligatorio se il tipo di licenza è POEST.
WSP	Money	Condizionale	Prezzo all’ingrosso. Obbligatorio se il tipo di licenza è POEST.
Category	Text	Condizionale	Categoria di prezzo. Obbligatorio se il tipo di licenza è POEST.
AnnounceDate	Event	No	Data in cui il rivenditore è autorizzato ad annunciare la data di inizio disponibilità del titolo all’interno del territorio disponibile.
SuppressionLiftDate	Event	Condizionale	La prima data in cui un titolo potrebbe essere annunciato pubblicamente come disponibile in una specifica data futura nel territorio di disponibilità. Obbligatorio se il tipo di licenza è POEST.
RentalDuration	Duration	Condizionale	Durata del periodo di noleggio in ore. Obbligatorio se il tipo di licenza è SVOD.
WatchDuration	Duration	Condizionale	Tempo a disposizione dell’utente per completare la visualizzazione una volta iniziata, in ore. Obbligatorio se il tipo di licenza è SVOD.
Download	Text	No	La licenza include il permesso di download. I valori validi sono Yes e No. Se il tipo di licenza è SVOD, è necessario specificare sia la durata del noleggio che la durata della visione..
Exclusive	Boolean	No	Le risorse sono esclusive nell’ambito della transazione.
ExclusiveAttributes	Text	No	Specifica il tipo di esclusività. Considerato solo quando Exclusive è true. Se non viene fornito, verrà utilizzato un valore predefinito quando Exclusive è true.
BrandingRights	Boolean	No	Indica l’intenzione del partner di visualizzare il marchio.
BrandingRightsAttributes	Text	No	Specifica il testo del marchio. Considerato solo quando BrandingRights è true. Se non viene fornito, verrà utilizzato un valore predefinito quando BrandingRights è true.
allowAds	Boolean	No	Determina se gli annunci sono consentiti o vietati. Questo termine può comparire una sola volta.
allowedAdPlacement	Text	Condizionale	Specifica la posizione nel rullo in cui è possibile inserire gli annunci. I valori consentiti sono: PreRoll, MidRoll, PostRoll, Overlays, PauseAds, Squeezebacks. Consentito solo quando allowAds è true. Questo termine può comparire più di una volta. È possibile specificare AllowedAdPlacement o ProhibitedAdPlacement, ma non entrambi.
prohibitedAdPlacement	Text	Condizionale	Specifica la posizione nel rullo in cui non è possibile inserire gli annunci. I valori consentiti sono: PreRoll, MidRoll, PostRoll,Overlays, PauseAds, Squeezebacks. Questo termine può comparire più di una volta. Consentito solo quando allowAds è true. È possibile specificare AllowedAdPlacement o ProhibitedAdPlacement, ma non entrambi.
cuepointDeliveryAndUsage	Text	No	Specifica gli obblighi di invio e utilizzo dei cuepoint. Valori consentiti: PartnerWillDeliverAndPrimeVideoMustUse, PrimeVideoWillUseIfDelivered, NoDeliveryOrUsageObligations, TalentObligated. Consentito solo quando allowAds è true.
blindBasisSelling	Text	No	Valori consentiti: GuaranteedImpressions, NoGuaranteedImpressions Questo attributo deve essere presente solo se allowAds è impostato su true.
sponsorships	Text	No	Valori consentiti: Permitted, Prohibited, PermittedWithRestrictions. Questo attributo deve essere presente solo se allowAds è impostato su true.
sponsorshipsRestrictions	Text	Condizionale	Testo in formato libero Questo attributo deve essere presente solo se sponsorships è impostato su AllowedWithRestrictions.
talentAndAmazonAdGuidelines	Text	No	Valori consentiti: NoRestrictions, ConsultationRequired Questo attributo deve essere presente solo se allowAds è impostato su true.
talentRestrictions	Text	Condizionale	Testo in formato libero Questo attributo deve essere presente solo se talentAndAmazonAdGuidelines è impostato su ConsultationRequired.
adLoadLimit	Text	No	Numero di minuti di pubblicità all’ora. Il valore deve essere un numero intero valido. Questo attributo deve essere presente solo se allowAds è impostato su true.

Tipo Money

Attributo	Tipo	Obbligatorio	Note
value	Decimal	No	Valore monetario, richiesto per alcuni tipi di prezzo
_currency	String	Sì	Codice di valuta ISO

Tipo ContentSequenceInfo

Attributo	Tipo	Obbligatorio	Note
Number	Integer	Sì	Numero di sequenza del contenuto, come il numero dell’episodio o della stagione

Enumerazione BusinessLine

Valore enumerato	Descrizione
TVOD	TVOD significa acquisto o noleggio. Tipi di licenza correlati: EST, VOD, POEST
PRIME_SUBSCRIPTION	Iscrizione Amazon Prime o Amazon Kids+. Tipi di licenza correlati: SVOD
CHANNELS	Iscrizione a canali di terze parti. Tipi di licenza correlati: SVOD
FVOD	Contenuto gratuito. Tipi di licenza correlati: FVOD

Schemi di payload dell’API Avails

Codifica

Come viene convertito l’XML MDDF in JSON

Gestione delle versioni

Tipi comuni

Schemi