L’API Asset Status ti consente di verificare quali consegne sono necessarie per pubblicare il tuo titolo e lo stato attuale di ciascuna consegna (ad esempio riuscita, non riuscita, mancante) e, in caso contrario, perché. Centralizza i dati sulla distribuzione degli asset nei tuoi sistemi anziché controllare manualmente Slate, offrendoti visibilità in tempo reale su tutte le consegne e i tipi di asset. Puoi utilizzare l’API Asset Status per visualizzare tutti i dati attualmente disponibili nella scheda Assets di Slate.
Perché usare l’API Asset Status?
- Operazioni centralizzate: inserisci i dati di distribuzione degli asset direttamente nei tuoi sistemi insieme agli altri canali di distribuzione, senza bisogno di accedere a Slate per ogni controllo dello stato
- Risoluzione più rapida dei problemi: rileva immediatamente i problemi di consegna e scopri cosa impedisce la pubblicazione dei tuoi titoli, riducendo i tempi di risoluzione
- Gestione proattiva degli asset: monitora l’intero catalogo in modo programmatico in tutti i territori e i tipi di asset, consentendoti di scalare le operazioni man mano che la tua azienda cresce
- Verifica della distribuzione in tempo reale: scopri immediatamente quando gli asset vengono consegnati con successo o se ci sono errori che richiedono un intervento
Schemi di richiesta e risposta
Questa sezione fornisce le specifiche tecniche per gli sviluppatori per integrare l’API Asset Status nei loro sistemi. Utilizza questo riferimento per comprendere il formato della richiesta, la struttura della risposta e i tipi di dati restituiti dall’API.
Formato della richiesta
L’API Asset Status utilizza un semplice recupero tramite la struttura di richiesta GET in cui tutti i parametri di query vengono passati attraverso l’URL: non è richiesto il corpo della richiesta. Ciò semplifica l’integrazione nei sistemi e i test utilizzando client HTTP standard o strumenti da riga di comando. È sufficiente creare l’URL con l’identificatore del titolo e i filtri opzionali, quindi inviare una richiesta GET per recuperare lo stato attuale delle consegne degli asset.
https://partnerapi.primevideo.com/v1/assets/{licensor}/status/{ALID}?marketplace={marketplace}
Questa tabella definisce i parametri che è possibile utilizzare per interrogare le informazioni sullo stato degli asset.
Parametro |
Type |
È obbligatorio |
Description |
licenziante |
corda |
sì |
L’identificativo della tua organizzazione fornito da Prime Video durante l’onboarding |
ALID |
Stringa |
sì |
Identificatore del titolo (ALID o SKU) corrispondente al tuo contributo |
mercato |
Stringa |
No |
L’Amazon Marketplace a cui è stato inviato il titolo. Il valore predefinito è GLOBAL e non è necessario che venga fornito. Se stai cercando un titolo nel tuo catalogo Classic Marketplace, indica quale come parametro. Valori consentiti: GLOBAL, US, DE, JP, GB |
Richieste di esempio
https://partnerapi.primevideo.com/v1/assets/mgm/status/skuabc123?marketplace=global
https://partnerapi.primevideo.com/v1/assets/mgm/status/skuabc123
Nota: più specifici sono i parametri della richiesta, più mirata sarà la risposta. Se ometti il parametro marketplace opzionale, l’API restituirà informazioni sullo stato per tutti gli ambiti applicabili associati a quell’ALID.
Schema di risposta
Lo schema di risposta definisce la struttura dei dati restituiti dall’API Asset Status. La comprensione di questi tipi di dati vi aiuterà ad analizzare la risposta e a integrare efficacemente le informazioni sullo stato nei vostri sistemi.
ProductStatus
La risposta di primo livello contenente informazioni sullo stato delle risorse per il titolo richiesto. Ogni risposta include dati sullo stato filtrati in base ai parametri della richiesta, che consentono di comprendere lo stato di consegna tra diversi tipi di risorse e requisiti.
Nome campo |
Type |
È obbligatorio |
Description |
Fonte |
Piattaforma di consegna |
sì |
Piattaforma di distribuzione del codice sorgente. Nota che questo dovrebbe essere sempre Prime Video. |
Destinazione |
Editore di Delivery |
sì |
L’alias del partner per il titolo che riceve gli asset. |
Ambito |
Ambito di consegna |
sì |
Informazioni sull’ambito di fornitura |
ID della piattaforma |
Identificatori della piattaforma |
sì |
Identificatori della piattaforma |
Codice di avanzamento generale |
Codice di avanzamento |
sì |
Codice di avanzamento complessivo: Pronto, Emesso, In corso, Mancante |
Dettagli sull’avanzamento |
ProgressDetailItem [] |
sì |
Elenco dei dettagli sullo stato di avanzamento |
Stato della parte del titolo |
TitlePartStatus del prodotto [] |
sì |
Informazioni sullo stato della parte del titolo |
Istruzioni |
Istruzioni per la consegna del prodotto [] |
No |
Istruzioni per la consegna |
DeliveryPlatform Type Informazioni sulla piattaforma di distribuzione di
origine.
Nome campo |
Type |
È obbligatorio |
Description |
Piattaforma |
Stringa |
sì |
Piattaforma di distribuzione del codice sorgente. Nota che questo dovrebbe essere sempre Prime Video. |
DeliveryPublisher Type Informazioni sull’editore di
destinazione. In questo modo l’organizzazione viene identificata come destinataria del contenuto.
Nome campo |
Type |
È obbligatorio |
Description |
Editore |
Stringa |
sì |
L’alias del partner per il titolo che riceve gli asset. |
DeliveryScope Type Delivery: informazioni sull’ambito di
consegna che definiscono il contesto della query sullo stato dell’asset.
Nome campo |
Type |
È obbligatorio |
Description |
ALID |
Stringa |
sì |
Asset Logical Identifier o SKU |
Marketplace |
Stringa |
sì |
L’Amazon Marketplace a cui è stato inviato il titolo. Il valore predefinito è GLOBAL e non è necessario che venga fornito. |
Region |
Stringa |
No |
Region o territorio |
FormatProfile |
Stringa |
No |
Qualità del video utilizzato. Valori consentiti: SD, HD, UHD, MAX |
LICENSETYPE |
Stringa |
No |
Valori consentiti: SVOD, VOD, EST, POEST, VOD |
ID del vantaggio |
Stringa |
No |
Identifier per un canale o un abbonamento (richiesto per le offerte SVOD) |
PlatformIdentifiers
Type Struttura degli identificatori di piattaforma contenente gli identificatori del titolo.
Nome campo |
Type |
Richiesto |
Description |
GTI |
Stringa |
sì |
Identifier globale del titolo |
ID dell’editore |
Identificatore dell’editore [] |
sì |
Identificatori dell’editore |
PublisherIdentifier
Type L’elenco degli ID forniti dal partner.
Nome campo |
Type |
Richiesto |
Description |
ALID |
Stringa |
sì |
Identifier del titolo |
Marketplace |
Stringa |
sì |
L’Amazon Marketplace a cui è stato inviato il titolo. Il valore predefinito è GLOBAL e non è necessario che venga fornito. |
ProgressCode Type Valori di enumerazione del codice di
avanzamento che indicano lo stato generale della consegna delle risorse.
Value |
Description |
Pronto |
Le risorse sono state ingerite |
Problema |
C’è un problema con la consegna o l’elaborazione delle risorse |
In corso |
Le risorse vengono consegnate ed elaborate |
Mancante |
Una risorsa specifica non è stata ancora consegnata |
ProgressDetailItem Type
Progress Struttura degli elementi di dettaglio che fornisce statistiche di riepilogo.
Nome campo |
Type |
Richiesto |
Description |
Progresso |
Codice di avanzamento |
sì |
Codice di avanzamento |
Totale |
Lungo |
sì |
Numero totale di asset |
Azione necessaria |
Lungo |
sì |
Numero di asset dal conteggio totale che richiedono un’azione |
ProductTitlePartStatus
Type La struttura dati principale che rappresenta lo stato di una singola fornitura di asset richiesta. Ciò include lo stato di consegna, i requisiti di azione e i dati dettagliati a livello di transazione.
Nome campo |
Type |
È obbligatorio |
Description |
Tipo primario |
Stringa |
sì |
Il Type principale dell’asset |
Tipo secondario |
Stringa |
sì |
Tipo secondario: ad esempio, se il tipo principale era IMAGE, il sottotipo potrebbe essere 2x3 o Poster |
FormatProfile |
Stringa |
No |
Formatta il profilo o la qualità |
Locale |
Stringa |
No |
Locale - ex en-US o es-419 |
Contesti di offerta |
Ambito di consegna [] |
sì |
Ogni OfferContext rappresenta una configurazione specifica dell’offerta (regione, tipo di licenza, profilo di formato, ecc.) che utilizza la risorsa |
Parti del titolo condizionale |
Parte del titolo condizionale del prodotto [] |
No |
Parti condizionali del titolo |
Tipo di regola |
Stringa |
sì |
Tipo di regola: obbligatorio, consigliato, condizionale |
Tipo di azione |
Stringa |
sì |
type di azione |
Fonti delle regole |
Stringa [] |
sì |
Fonti delle regole |
Ultima consegna |
Consegna del prodotto |
No |
Informazioni sull’ultima consegna |
Consegna precedente avvenuta con successo |
Consegna del prodotto |
No |
Informazioni precedenti sulla consegna avvenuta con successo |
Data della prima consegna |
Stringa |
No |
Data della prima consegna |
Progresso |
Codice di avanzamento |
sì |
Codice di avanzamento: Pronto, Emesso, In corso, Mancante |
Data prevista |
Stringa |
No |
Data di consegna prevista |
Data di inizio più vicina |
Stringa |
No |
Data di inizio più vicina |
Valori primaryType comuni
Il campo PrimaryType identifica la categoria di asset da consegnare.
Value |
Description |
METADATI |
Metadati del titolo (descrizioni, cast, troupe, ecc.) |
VIDEO |
File video mezzanine |
IMMAGINE |
Opere d’arte (cofanetto, copertina, immagini di eroi, poster) |
AUDIO |
Tracce audio |
TIMED_TEXT |
Sottotitoli e didascalie |
Valori ActionType comuni
Il campo ActionType indica se è necessario intervenire sulla consegna di una specifica risorsa.
Value |
Description |
AZIONE NECESSARIA |
La risorsa è mancante o presenta errori che devono essere risolti per la pubblicazione del titolo |
AZIONE_CONSIGLIATA |
La risorsa non è obbligatoria ma consigliata per una migliore esperienza del cliente |
NESSUNA AZIONE NECESSARIA |
L’asset è stato consegnato correttamente, non è richiesta alcuna azione |
Valori RuleType comuni
Il campo RuleType definisce se una risorsa è obbligatoria o facoltativa per la pubblicazione del titolo.
Value |
Description |
richiesto |
Deve essere consegnato affinché il titolo possa essere pubblicato |
consigliato |
Non richiesto ma migliora l’esperienza del cliente |
condizionale |
Richiesto solo se sono soddisfatte determinate condizioni |
ProductConditionalTitlePart
Type Struttura condizionale delle parti del titolo che definisce i requisiti condizionali per la consegna degli asset.
Nome campo |
Type |
È obbligatorio |
Description |
Tipo di regola |
Stringa |
sì |
Tipo di regola |
Regioni |
Stringa [] |
sì |
Elenco di regioni o territori |
Parti del titolo |
Titolo del prodotto Descrittore della parte [] |
sì |
Parti del titolo |
Valori RuleType
Il campo RuleType definisce la relazione logica tra le parti condizionali del titolo.
Value |
Description |
ANNIDATO |
Tutti gli elementi del titolo nella struttura devono essere soddisfatti (e logicamente) |
SINGOLO |
Qualsiasi parte del titolo soddisfa il requisito (logica OR) |
ProductTitlePartDescriptor
Type Struttura del descrittore della parte Titolo che definisce un requisito specifico della parte del titolo.
Nome campo |
Type |
È obbligatorio |
Description |
Tipo primario |
Stringa |
sì |
Il Type principale dell’asset |
Tipo secondario |
Stringa |
sì |
Tipo secondario: ad esempio, se il tipo principale era IMAGE, il sottotipo potrebbe essere 2x3 o Poster |
FormatProfile |
Stringa |
No |
Formatta il profilo o la qualità |
Locale |
Stringa |
No |
Locale - ex en-US o es-419 |
Tipo di consegna
del prodotto Informazioni sulla consegna del prodotto che forniscono informazioni dettagliate sulla consegna di un asset. Questo campo sarà nullo se l’asset non è stato ancora consegnato.
Nome campo |
Type |
È obbligatorio |
Description |
Stato |
Stringa |
No |
Stato della spedizione: NOT_DELIVERED o SUCCESSFULLY_DELIVERED |
Nome del file |
Stringa |
No |
Nome del file |
Hash |
Stringa |
No |
Hash o checksum del file |
Data di consegna |
Stringa |
No |
Data di consegna in formato ISO 8601 |
Locale |
Stringa |
No |
Locale |
ServiceProvider |
Stringa |
No |
Fornitore di servizi o account di consegna |
Tipo di presentazione |
Stringa |
No |
Presentation type |
Tipo di intervallo dinamico |
Stringa |
No |
tipo di range dinamico |
Istruzioni |
Istruzioni per la consegna del prodotto [] |
No |
Istruzioni o errori di consegna |
Valori di stato comuni
Il campo Stato indica se la consegna di un asset è stata ricevuta ed elaborata correttamente.
Value |
Description |
_CONSEGNATO CON SUCCESSO |
La risorsa è stata consegnata ed elaborata con successo |
NOT_CONSEGNATO |
La risorsa non è stata ricevuta |
ProductDeliveryInstruction
Type Struttura delle istruzioni di consegna del prodotto che fornisce codici di errore e informazioni sullo stato. Le istruzioni possono essere visualizzate nella risposta di primo livello (che riassume tutti i problemi di consegna) o all’interno degli oggetti ProductDelivery (specifici per le consegne di singole risorse).
Nome campo |
Type |
È obbligatorio |
Description |
Parte del titolo |
Titolo del prodotto Part Descriptor |
No |
Descrittore della parte del titolo |
Stato della parte del titolo |
Stringa |
No |
Stato di consegna della parte del titolo |
Codice di errore |
Stringa |
No |
Codice di errore |
Regioni |
Stringa [] |
No |
Elenco di regioni o territori |
Valori TitlePartStatus comuni
Il campo TitlePartStatus indica lo stato di consegna di una risorsa all’interno dei messaggi di istruzioni.
Value |
Description |
NOT_DELIVERED |
L’asset non è stato consegnato |
_CONSEGNATO CON SUCCESSO |
L’asset è stato consegnato con successo |
Nota: gli schemi sopra riportati rappresentano l’attuale struttura di risposta dell’API e potrebbero essere migliorati nelle versioni future.
Esempio di risposta
Gli esempi seguenti illustrano le risposte API tipiche per diversi scenari. Usali per comprendere la struttura della risposta e come interpretare le informazioni sullo stato.
Esempio 1: Tutti gli asset consegnati correttamente
Questo esempio dimostra una tipica risposta API per il titolo di un film in cui tutte le risorse richieste sono state consegnate correttamente. La risposta mostra lo stato Pronto senza che sia necessaria alcuna azione.
{
"Destination": {
"Publisher": "TheDogChannel"
},
"Instructions": [],
"OverallProgressCode": "Ready",
"PlatformIDs": {
"GTI": "amzn1.dv.gti.e627fc28-5fde-435f-bc4e-44a9bad712df",
"PublisherIDs": [
{
"ALID": "FunWithTennisBalls",
"Marketplace": "GLOBAL"
}
]
},
"ProgressDetail": [
{
"ActionNeeded": 0,
"Progress": "Ready",
"Total": 11
}
],
"Scope": {
"ALID": "FunWithTennisBalls",
"BenefitID": "dogchannel",
"FormatProfile": null,
"LicenseType": null,
"Marketplace": "GLOBAL",
"Region": null
},
"Source": {
"Platform": "Prime Video"
},
"TitlePartStatus": [
{
"ActionType": "NO_ACTION_NEEDED",
"ConditionalTitleParts": [
{
"Regions": ["US"],
"RuleType": "NESTED",
"TitleParts": [
{
"FormatProfile": null,
"Locale": null,
"PrimaryType": "METADATA",
"SecondaryType": "NONE"
}
]
}
],
"EarliestStartDate": "Wed Jun 01 04:00:00 UTC 2022",
"ExpectedDate": null,
"FirstDeliveryDate": null,
"FormatProfile": null,
"LastDelivery": {
"DeliveredDate": "Mon Feb 26 22:56:53 UTC 2024",
"DynamicRangeType": null,
"FileName": "passionflix_82_this-side-of-heaven_v5_MEC.xml",
"Hash": "3f73286984d4c71fd7a341c9b16be3ff",
"Instructions": null,
"Locale": "en-us",
"PresentationType": null,
"ServiceProvider": "stockholmstream",
"Status": "SUCCESSFULLY_DELIVERED"
},
"Locale": null,
"OfferContexts": [
{
"ALID": "FunWithTennisBalls",
"BenefitID": "dogchannel",
"FormatProfile": "HD",
"LicenseType": "SVOD",
"Marketplace": "GLOBAL",
"Region": "US"
}
],
"PrimaryType": "METADATA",
"PriorSuccessfulDelivery": {
"DeliveredDate": "Wed May 31 04:32:00 UTC 2023",
"DynamicRangeType": null,
"FileName": "fun_with_v4_MEC.xml",
"Hash": null,
"Instructions": null,
"Locale": "en-us",
"PresentationType": null,
"ServiceProvider": "thepound",
"Status": null
},
"Progress": "Ready",
"RuleSources": ["PUBLISHING_SPEC"],
"RuleType": "REQUIRED",
"SecondaryType": "NONE"
},
{
"ActionType": "NO_ACTION_NEEDED",
"ConditionalTitleParts": [
{
"Regions": ["US"],
"RuleType": "NESTED",
"TitleParts": [
{
"FormatProfile": "HD",
"Locale": null,
"PrimaryType": "VIDEO",
"SecondaryType": "MEZZ"
}
]
}
],
"EarliestStartDate": "Wed Jun 01 04:00:00 UTC 2022",
"FormatProfile": "HD",
"LastDelivery": {
"DeliveredDate": "Mon Feb 27 14:59:03 UTC 2023",
"DynamicRangeType": "SDR",
"FileName": "fun_with_tennis_mwf5.mp4",
"Hash": "88cbed6edabce11b9b503130081e7bd8",
"Instructions": null,
"Locale": "en-us",
"PresentationType": "MAIN",
"ServiceProvider": "thepound",
"Status": "SUCCESSFULLY_DELIVERED"
},
"Locale": null,
"OfferContexts": [
{
"ALID": "FunWithTennisBalls",
"BenefitID": "dogchannel",
"FormatProfile": "HD",
"LicenseType": "SVOD",
"Marketplace": "GLOBAL",
"Region": "US"
}
],
"PrimaryType": "VIDEO",
"Progress": "Ready",
"RuleType": "REQUIRED",
"SecondaryType": "MEZZ"
}
]
}
Esempio 2: risorse obbligatorie mancanti
Questo esempio dimostra una risposta API quando mancano gli asset richiesti, mostrando come l’API indichi lo stato ACTION_NEEDED e fornisca informazioni sull’errore.
{
"Destination": {
"Publisher": "1cendgametestpartner1"
},
"Instructions": [
{
"ErrorCode": null,
"Regions": null,
"TitlePart": {
"FormatProfile": "SD",
"Locale": null,
"PrimaryType": "VIDEO",
"SecondaryType": "MEZZ"
},
"TitlePartStatus": "NOT_DELIVERED"
},
{
"ErrorCode": null,
"Regions": null,
"TitlePart": {
"FormatProfile": "HD",
"Locale": null,
"PrimaryType": "VIDEO",
"SecondaryType": "MEZZ"
},
"TitlePartStatus": "NOT_DELIVERED"
},
{
"ErrorCode": "mec-validation-waiting-for-parent-sku-warning",
"Regions": [],
"TitlePart": {
"FormatProfile": null,
"Locale": "ja",
"PrimaryType": "METADATA",
"SecondaryType": "NONE"
},
"TitlePartStatus": "SUCCESSFULLY_DELIVERED"
}
],
"OverallProgressCode": "Issue",
"ProgressDetail": [
{
"ActionNeeded": 0,
"Progress": "Ready",
"Total": 8
},
{
"ActionNeeded": 2,
"Progress": "Missing",
"Total": 2
}
],
"Scope": {
"ALID": "TLCPVAPITVSKU001EP4",
"BenefitID": null,
"FormatProfile": null,
"LicenseType": null,
"Marketplace": "GLOBAL",
"Region": null
},
"TitlePartStatus": [
{
"ActionType": "ACTION_NEEDED",
"ConditionalTitleParts": [
{
"Regions": ["DE", "PR", "AU", "JP", "GB", "US", "CA"],
"RuleType": "NESTED",
"TitleParts": [
{
"FormatProfile": "SD",
"Locale": null,
"PrimaryType": "VIDEO",
"SecondaryType": "MEZZ"
}
]
}
],
"EarliestStartDate": "Thu Jan 09 15:00:00 UTC 2025",
"FormatProfile": "SD",
"LastDelivery": null,
"Locale": null,
"OfferContexts": [
{
"ALID": "TLCPVAPITVSKU001EP4",
"BenefitID": "Prime",
"FormatProfile": "SD",
"LicenseType": "SVOD",
"Marketplace": "GLOBAL",
"Region": "US"
}
],
"PrimaryType": "VIDEO",
"PriorSuccessfulDelivery": null,
"Progress": "Missing",
"RuleSources": ["PUBLISHING_SPEC"],
"RuleType": "REQUIRED",
"SecondaryType": "MEZZ"
},
{
"ActionType": "NO_ACTION_NEEDED",
"LastDelivery": {
"DeliveredDate": "Tue Sep 24 01:04:20 UTC 2024",
"FileName": "1cendgametestpartner1-TLCPVAPITVSKU001EP4_MEC.xml",
"Instructions": [
{
"ErrorCode": "mec-validation-waiting-for-parent-sku-warning",
"Regions": [],
"TitlePart": null,
"TitlePartStatus": null
}
],
"Locale": "ja-jp",
"ServiceProvider": "1cendgametestpartner",
"Status": "SUCCESSFULLY_DELIVERED"
},
"Locale": "ja",
"PrimaryType": "METADATA",
"Progress": "Ready",
"RuleType": "RECOMMENDED",
"SecondaryType": "NONE"
},
{
"ActionType": "NO_ACTION_NEEDED",
"ConditionalTitleParts": [
{
"Regions": ["DE"],
"RuleType": "SINGLE",
"TitleParts": [
{
"FormatProfile": null,
"Locale": "de",
"PrimaryType": "METADATA",
"SecondaryType": "NONE"
},
{
"FormatProfile": null,
"Locale": "en",
"PrimaryType": "METADATA",
"SecondaryType": "NONE"
}
]
}
],
"LastDelivery": {
"DeliveredDate": "Tue Sep 24 01:04:20 UTC 2024",
"FileName": "1cendgametestpartner1-TLCPVAPITVSKU001EP4_MEC.xml",
"Instructions": [
{
"ErrorCode": "mec-validation-waiting-for-parent-sku-warning",
"Regions": [],
"TitlePart": null,
"TitlePartStatus": null
}
],
"Locale": "de-de",
"ServiceProvider": "1cendgametestpartner",
"Status": "SUCCESSFULLY_DELIVERED"
},
"Locale": "de",
"PrimaryType": "METADATA",
"Progress": "Ready",
"RuleType": "RECOMMENDED",
"SecondaryType": "NONE"
}
]
}
FAQs
Le seguenti sezioni forniscono risposte a domande comuni sull’utilizzo dell’API Asset Status.