Die Avails-API basiert auf dem Partner API Framework, das eine einheitliche Schnittstelle für extern zugängliche APIs bietet. Dieses Framework ermöglicht es Studios, Postproduktionshäusern und anderen Fulfillment-Partnern, ihren Videokatalog auf Prime Video programmgesteuert zu verwalten.
Fangen Sie an
Für den Zugriff auf die Avails-API benötigen Sie ein MTLS-Zertifikat und einen API-Schlüssel. In diesem Abschnitt werden die Schritte zum Generieren einer Certificate Signing Request (CSR), zum Anfordern eines MTLS-Zertifikats und zum Stellen von API-Anfragen an die Avails-API beschrieben.
Schritt 1: Der Client erstellt seinen privaten Schlüssel und seine Certificate Signing Request (CSR) mit openssl.
openssl genrsa -out client.key 2048
openssl req -new -key client.key -out client.csr
Schritt 2: Der Kunde sendet eine E-Mail an pv-partner-apis-support@amazon.com mit angehängter client.csr. (Das Team wird innerhalb eines Werktages mit einem Zertifikat antworten.) Der folgende Codeausschnitt ist ein empfohlenes Beispiel. EMAIL TEMPLATE
Partner Details
PartnerName :
Partner Alias :
Partner Resource Access : [Avails-Read,Avails-Write]
Request Limit :
Attachment
Partner Certificate signing request (client.csr).
Schritt 3: Der Kunde erhält ein öffentliches Zertifikat, Cacert und einen API-Schlüssel vom Partner-API-Team. Der folgende Codeausschnitt enthält ein Beispiel für die Nachrichten, die Sie möglicherweise erhalten. Prod EMAIL TEMPLATE
Hi <Name/s>
Attached you’ll find your MTLS cert for PartnerApi Production environment. It will be usable only with the client.key you used to create client.csr that you sent us
Your ApiKey is: XxXxXxXxXxXxXxXxXxXxXxXxXxXxXxX. Include it in your requests as http header ‘x-api-key’
Requests with a body must have Content-Type=application/json header
The base url is https://partnerapi.primevideo.com
MTLS certs and ApiKeys provided for Sandbox environment will not work for Prod environment. You will need to request a separate MTLS cert and ApiKey to make requests against our Prod environment when you are ready
We have given you a rate limit of 10 TPS and 5 burst TPS (meaning you can have up to 5 open concurrent connections/requests at a time).
As a place to start, I would suggest doing a request to make sure you’re able to get an authenticated response. Try a GET request to https://partnerapi.primevideo.com/v1/avails/<licensor>/full-extract/some-test-alid?territory=US&businessLine=PRIME_SUBSCRIPTION. You should get a 404 status code with a response body indicating ‘Title not found for ALID some-test-alid and Licensor <licensor>’
Please let us know if you have any questions/problems!
PV PartnerApi Team
Attachment
Partner public Certificate (clientCert.pem)
CertificateAuthority public certificate (cacert.pem)
SANDBOX EMAIL TEMPLATE
Hi <Name/s>
Attached you’ll find your MTLS cert for PartnerApi Sandbox environment. It will be usable only with the client.key you used to create client.csr that you sent us.
We have created a new sandbox only vendorAlias of api_sandbox_<licensor> that you will use as vendorAlias/licensor for all your sandbox API requests.
Your ApiKey is: XxXxXxXxXxXxXxXxXxXxXxXxXxXxXxX. Include it in your requests as http header ‘x-api-key’.
Requests with a body must have Content-Type=application/json header.
Sandbox offers the exact same endpoints offered by our Prod api but with a different base url. The base url for Sandbox is https://sandbox.partnerapi.primevideo.com
The MTLS cert and ApiKey provided here will only work in the Sandbox environment. You will need to request a separate MTLS cert and ApiKey to make requests against our Prod environment when you are ready.
When creating Avails in the sandbox environment, you may use whatever ALID/SKU you want. These will not be connected nor linked to any prod titles and need not be coordinated with any real title ALID/SKU you have created in your account. Additionally, in the Sandbox you may safely use the same ALID/SKU as real titles in your prod account if you wish.
We have given you a rate limit of 4 TPS and 2 burst TPS (burst meaning you can have up to 2 open concurrent connections/requests at a time).
Note that this sandbox is not intended for long-term storage. Lifetime of a sandbox Avail is intended to be less-than 30 days.
As a place to start, I would suggest doing a request to make sure you’re able to get an authenticated response. Try a GET request to https://sandbox.partnerapi.primevideo.com/v1/avails/api_sandbox_<licensor>/full-extract/some-test-alid?territory=US&businessLine=PRIME_SUBSCRIPTION. You should get a 404 status code with a response body indicating ‘Title not found for ALID some-test-alid and Licensor api_sandbox_<licensor>’
Please let us know if you have any questions/problems!
PV PartnerApi Team
Attachment
Partner public Certificate (clientCert.pem)
CertificateAuthority public certificate (cacert.pem)
Schritt 4: Der Client verwendet PublicKey, das öffentliche Partnerzertifikat und den API-Schlüssel für den Aufruf der API.
Hier sind einige Beispielintegrationen, die verschiedene Technologien verwenden.
Bash
curl --location --request PUT 'https://partnerapi.primevideo.com/v1/avails/{partnerAlias}/full-extract/{ALID}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'x-api-key: <api key>' \
--data-raw '{ "avail": <Avail json> }' \
--key ./private_key.txt --cert ./certificate.pem
Python https://requests.readthedocs.io/en/master/user/advanced/#client-side-certificates
requests.put(f'https://partnerapi.primevideo.com/v1/avails/{partnerAlias}/full-extract/{ALID}',
data={'{ "avail": <Avail json> }'},
cert=('/path/client.cert', '/path/client.key'),
headers={'x-api-key':'<api key>','Content-Type':'application/json'})
Nodejs https://nodejs.org/api/https.html#https_https_request_options_callback
const options = {
hostname: `https://partnerapi.primevideo.com/v1/avails/{partnerAlias}/full-extract/{ALID}`,
port: 443,
path: `/v1/avails/{partnerAlias}/full-extract/{ALID}`,
method: 'PUT',
headers: {
'Content-Type':'application/json',
'x-api-key':'<api key>'
},
key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),
cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem'),
agent: false
};
const req = https.request(options, (res) => {
// ...
});
Widerrufen Sie den Zugriff auf das MTLS-Zertifikat
Gelegentlich muss ein MTLS-Zertifikat möglicherweise gesperrt werden. Wenn Sie möchten, dass eines ihrer Zertifikate gesperrt wird, senden Sie die im folgenden Beispiel gezeigten Informationen per E-Mail an pv-partner-apis-support@amazon.com. EMAIL TEMPLATE
Partner Details
PartnerName :
Partner Alias :
Owner Email Id :
Certificate Serial Number :
ApiKey :
Schemazuordnung von MDDF zu EMA Avail
Wir verwenden das MDDF Avail-Schema in JSON. Ein Diagramm des Schemas ist bei MovieLabs unter dem folgenden Link verfügbar: https://www.movielabs.com/md/avails/v2.6/avails-v2.6.1/avails-v2.6.1.html#Link2. Die folgende Tabelle zeigt die Zuordnung von EMA für die unterstützten MDDF-Avail-Eigenschaften und -Attribute.
Prime Video MDDF JSON |
Prime Video EMA-Tabelle |
Avail.Compatibility.SpecVersion |
1.7.3 |
verfügbar.ALID |
GÜLTIG |
Avail.Disposition.EntryType |
Typ des Eintrags |
Avail.Licensor.DisplayName |
Anzeigename |
Verfügbares Asset. _Inhalts-ID |
GÜLTIGE |
avail.asset.workType |
Arbeitstyp |
avail.asset.metadata.titleInternal Alias |
TitleInterner Alias |
avail.asset.episodeMetadata.titleInternalAlias |
Interner Alias des Episodentitels |
avail.asset.EpisodeMetadata.EpisodeNumber.Number |
Nummer der Folge |
avail.asset.EpisodeMetadata.SeasonMetadata.SeasonTitleInterner Alias |
Interner Alias für den Titel der Staffel |
avail.asset.EpisodeMetadata.SeasonMetadata.SeasonContentId |
Saisonale ID |
avail.asset.EpisodeMetadata.SeasonMetadata.SeasonNumber.Number |
Nummer der Staffel |
avail.asset.episodeMetadata.SeasonMetadata.NumberOfEpisodenanzahl |
Anzahl der Folgen |
avail.asset.EpisodeMetadata.SeriesMetadata.SeriesContentId |
Serie ALDID |
avail.asset.EpisodeMetadata.SeriesMetadata.SeriesTitleInterner Alias |
Interner Alias für Serientitel |
avail.asset.EpisodeMetadata.SeriesMetadata.NumberOfStaffeln |
Anzahl der Staffeln |
avail.asset.seasonMetadata.SeasonTitleInternal Alias |
Interner Alias für den Saisontitel |
avail.asset.SeasonMetadata.SeasonContentId |
Saisonale ID |
avail.asset.seasonMetadata.seasonNumber.Number |
Nummer der Saison |
avail.asset.seasonMetadata.Anzahl der Folgen |
Anzahl der Folgen |
avail.asset.seasonMetadata.seriesMetadata.SeriesContentId |
Serie ALDID |
avail.asset.seasonMetadata.seriesMetadata.SeriesTitleInterner Alias |
Interner Alias für Serientitel |
avail.asset.SeasonMetadata.SeriesMetadata.NumberOfSeasons |
Anzahl der Staffeln |
avail.transaction.LicenseType |
Lizenztyp |
Avail.Transaction.Territory.Country |
Gebiet |
Verfügbar.Transaktion.Start |
Starten |
Verfügbar.Transaktion.Ende |
Ende |
Avail.Transaction.AllowedLanguage |
Zulässige Sprachen |
Sprache avail.transaction.holdback |
HoldBack-Sprache |
avail.transaction.assetLanguage.Value |
Sprache der Anlage |
avail.transaction.assetLanguage. _Anlage |
Lokalisierungstyp |
Beschreibung der Avail.Transaction.LicenseRights |
Beschreibung der Lizenzrechte |
Avail.Transaction.FormatProfile |
Profil formatieren |
avail.transaction.contractId |
Vertrags-ID |
Avail.Transaction.Andere Anweisungen |
Andere Anweisungen |
Verfügbare Transaktion. _Transaktions-ID |
Eine gültige ID |
Verfügbar.Transaktion.Laufzeit. _Begriffname. Kanalidentität |
Gruppenidentität |
Verfügbar.Transaktion.Laufzeit. _Begriff.Angekündigtes Datum |
Datum angekündigt |
Verfügbar.Transaktion.Laufzeit. _Begriffsname.SuppressionLiftDate |
SuppressionLiftDate |
Verfügbar.Transaktion.Laufzeit. _TermName.Mietdauer |
Dauer der Ausleihe |
Verfügbar.Transaktion.Laufzeit. _TermName.WatchDuration |
Dauer der Uhr |
Verfügbar.Transaktion.Laufzeit. _Begriff.Herunterladen |
Herunterladen |
Verfügbar.Transaktion.Laufzeit. _Begriffsname.Stufe |
Art des Preises |
Verfügbar.Transaktion.Laufzeit. _Begriff.Kategorie |
Art des Preises |
Verfügbar.Transaktion.Laufzeit. _Begriffname.WSP |
Art des Preises |
Verfügbar.Transaktion.Laufzeit. _Begriffname.SRP |
SRP |
Avail.Transaction.Term.Money.Value |
Preis |
Verfügbarkeit.Transaktion.Laufzeit.Geld. _Währung |
Preis Währung |
Verfügbarkeit. Transaktion. Laufzeit. Exklusivität |
Exklusivität |
avail.transaction.term.Exclusive-Attribute |
Exklusive Attribute |
avail.sharedEntitlement.ecosystemId |
DMA_ID |
avail.sharedEntitlement.ecosystem |
DMA_ID |
Methoden
In den folgenden Abschnitten werden die verschiedenen API-Anforderungsmethoden beschrieben, die Sie mit der Avails-API verwenden können, einschließlich ihrer spezifischen Endpunkte, und wie der Hauptteil jeder Anfrage und Antwort aussehen sollte.
Kategorie: Vollständiger Auszug
GET:
- Endpunkt:
/avails/ {licensor} /full-extract/ {ALID}? territory= {territory} &BusinessLine= {BusinessLine} - Hauptteil der Anfrage: -
- responseBody: Verfügbar für Transaktionen für einen Bereich
GEBEN SIE AN:
- Endpunkt:
/avails/ {licensor} /full-extract/ {ALID}
Hauptteil der Anfrage: {... Daten verfügbar}- responseBody: Antwort auf Erfolg/Fehlschlag
LÖSCHEN:
- Endpunkt:
/avails/ {licensor} /full-extract/ {ALID}? territory= {territory} &BusinessLine= {BusinessLine} &ContractID= {CPH | FIXED_FEE} &ChannelIdentity= {ChannelIdentity} - Hauptteil der Anfrage: -
- responseBody: Antwort auf Erfolg/Fehlschlag
BEITRAG:
- Endpunkt:
/avails/ {licensor} /full-extract/ {ALID} /validate
Hauptteil der Anfrage: {... Daten verfügbar}- responseBody: Antwort auf Erfolg/Fehlschlag
Kategorie:
Batch-Unterkategorie: Vollständiger Extrakt POST:
- Endpunkt:
/avails/full-extract/batch/get - Hauptteil der Anfrage:
{ [ { 'requestId': '<RequestId>', 'path':'/avails/{licensor}/full-extract/{ALID}?territory={territory}&businessLine={businessLine}' }... ] } - Hauptteil der Antwort:
[ { 'requestItemId':'<requestId>', 'success':'<true | false>', 'avail':'<responseBody>', 'errorMessage':'<errorMessage>' }... ]
BEITRAG:
- Endpunkt:
/avails/full-extract/batch/put - Hauptteil der Anfrage:
{ [ { 'requestId': '<RequestId>', 'path':'/avails/{licensor}/full-extract/{ALID}' 'body': { avails: [<Avail data>] } }... ] } - Hauptteil der Antwort:
[ { 'requestId':'<requestId>', 'statusCode':'<statusCode>', 'body':'<responseBody>', 'errorMessage':'<errorMessage>' }... ]
BEITRAG:
- Endpunkt:
/avails/full-extract/batch/delete - Hauptteil der Anfrage:
{ [ { 'requestId': '<RequestId>', 'path':'/avails/{licensor}/full-extract/{ALID}?territory={territory}&businessLine={businessLine}&contractId={CPH | FIXED_FEE}&channelIdentity={channelIdentity}' }... ] } - Hauptteil der Antwort:
[ { 'requestId':'<requestId>', 'statusCode':'<statusCode>', 'body':'<responseBody>', 'errorMessage':'<errorMessage>' }... ]
BEITRAG:
- Endpunkt:
/avails/full-extract/batch/validate - Hauptteil der Anfrage:
{ [ { 'requestId': '<RequestId>', 'path':'/avails/{licensor}/full-extract/{ALID}/validate' 'body': { avails: [<Avail data>] } }... ] } - Hauptteil der Antwort:
[ { 'requestId':'<requestId>', 'statusCode':'<statusCode>', 'body':'<responseBody>', 'errorMessage':'<errorMessage>' }... ]
Geschäftsbereiche
Für Full Extract müssen alle Avails für ein Geschäftsfeld und ein Gebiet zusammen geliefert werden. Die folgenden Geschäftsbereiche werden unterstützt:
- PRIME_SUBSCRIPTION
- TVOD
- FVOD
- KANÄLE
BusinessLine-Werte können anhand der Kombination von LicenseType und BenefitID bestimmt werden, wie in der folgenden Tabelle dargestellt.
Art der Lizenz |
Vorteils-ID |
Geschäftsbereich |
EST |
- |
TVOD |
VOD |
- |
TVOD |
DICHTER |
- |
TVOD |
SVOD |
PRIME |
PRIME_ABONNEMENT |
SVOD |
A4 K |
PRIME_ABONNEMENT |
SVOD |
BELIEBIG (nicht PRIME oder A4K) |
KANÄLE |
FVOD |
IRGENDEIN |
FVOD |
