A利用状況 APIは、外部からアクセス可能なAPI用の統合インターフェースを提供するパートナーAPIフレームワークに基づいて構築されています。 このフレームワークにより、スタジオ、ポストプロダクション会社、その他のフルフィルメントパートナーは、プライム・ビデオのビデオカタログをプログラム的に管理できます。
始めましょう
A利用状況 API にアクセスするには、MTLS 証明書と API キーが必要です。 このセクションでは、証明書署名リクエスト (CSR) を生成し、MTLS 証明書をリクエストし、A利用状況 API に API リクエストを行う手順について説明します。
ステップ 1: クライアントは openssl を使用して秘密鍵と証明書署名要求 (CSR) を作成します。
openssl genrsa -out client.key 2048
openssl req -new -key client.key -out client.csr
ステップ 2: クライアントは、client.csr を添付したメールを pv-partner-apis-support@amazon.com に送信します。 (チームから 1 営業日以内に証明書が送付されます) 以下のコードスニペットは推奨例です。 EMAIL TEMPLATE
Partner Details
PartnerName :
Partner Alias :
Partner Resource Access : [Avails-Read,Avails-Write]
Request Limit :
Attachment
Partner Certificate signing request (client.csr).
ステップ 3: クライアントはパートナー API チームから公開証明書、cacert、および API キーを受け取ります。 次のコードスニペットは、受信するメッセージの例を示しています。 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)
ステップ 4: クライアントは、PublicKey、パートナー公開証明書、および API キーを使用して API を呼び出します。
ここでは、さまざまなテクノロジーを使用したインテグレーションの例をいくつか紹介します。
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) => {
// ...
});
MTLS 証明書アクセスを取り消す
MTLS 証明書を取り消す必要がある場合があります。 証明書のいずれかを取り消す必要がある場合は、次の例に示す情報を pv-partner-apis-support@amazon.com に電子メールで送信してください。 EMAIL TEMPLATE
Partner Details
PartnerName :
Partner Alias :
Owner Email Id :
Certificate Serial Number :
ApiKey :
MDDFからEMAへのスキーママッピングが利用可能
JSONのMDDFアベイルスキーマを使用しています。 スキーマの図は、MovieLabs の次のリンクから入手できます。https://www.movielabs.com/md/avails/v2.6/avails-v2.6.1/avails-v2.6.1.html#Link2 次の表は、サポートされている MDDF Avail プロパティと属性の EMA からのマッピングを示しています。
プライム・ビデオ MDDF JSON |
プライム・ビデオ EMA スプレッドシート |
.互換性.スペックバージョンあり |
1.7.3 |
利用可能です。有効 |
有効 |
「使用可能」「処理」「エントリタイプ」 |
エントリタイプ |
「使用可能」「ライセンス」「表示名」 |
ディスプレイネーム |
「使用可能」「アセット」。 _コンテンツ ID |
有効 |
「使用可能」「アセット」「作業タイプ」 |
ワークタイプ |
[アセット]、[メタデータ]、[タイトル]、[内部エイリアス] |
タイトル:内部エイリアス |
「使用可能」「アセット」「エピソードメタデータ」「タイトル内部エイリアス」 |
エピソードタイトル:内部エイリアス |
利用可能.アセット.エピソードメタデータ.エピソード番号.番号 |
エピソード番号 |
AVAILABLE.Asset. Episode Metadata.SeasonMetadata.SeasonTitle 内部エイリアス |
シーズンタイトル内部エイリアス |
Avail.asset.EpisodeMetadata.SeasonMetadata.SeasonContentID |
シーズン ID |
アセット. エピソードメタデータ. シーズンメタデータ. シーズンメタデータ. シーズン番号. 番号 |
シーズン番号 |
利用可能.アセット. エピソードメタデータ. シーズンメタデータ. エピソード数 |
エピソード数 |
利用可能.アセット. エピソードメタデータ. シリーズメタデータ. シリーズコンテンツ ID |
シリーズ ALD ID |
Avail.asset.EpisodeMetadata.Series Metadata.Series Title. SeriesTitle 内部エイリアス |
シリーズタイトル内部エイリアス |
利用可能.アセット. エピソードメタデータ. シリーズメタデータ. シーズン数 |
シーズン数 |
利用可能.アセット.シーズンメタデータ.シーズンタイトル内部エイリアス |
シーズンタイトル:内部エイリアス |
アベイラブル. アセット. シーズンメタデータ. シーズンコンテンツ ID |
シーズン ID |
「利用可能資産」「シーズンメタデータ」「シーズン番号」「番号」 |
シーズン番号 |
「使用可能」「資産」「シーズンメタデータ」「エピソード数」 |
エピソード数 |
Avail.asset.SeasonMetadata.Series Metadata.Series ContentID |
シリーズ ALID |
avail.asset.seasonメタデータ. シリーズメタデータ. シリーズメタデータ. シリーズタイトル内部エイリアス |
シリーズタイトル内部エイリアス |
Avail.asset.Seasonメタデータ. シリーズメタデータ. シーズン数 |
シーズン数 |
「利用可能」「トランザクション」「ライセンスタイプ」 |
ライセンスタイプ |
「利用可能」、「取引」、「地域」、「国」 |
地域 |
「利用可能」「トランザクション」「開始」 |
開始 |
[利用可能]、[トランザクション]、[終了] |
終了 |
「使用可能」「トランザクション」>「許可された言語」 |
許可されている言語 |
「使用可能」「トランザクション」「ホールドバック言語」 |
ホールドバック言語 |
利用可能.トランザクション.アセット言語.価値 |
アセット言語 |
「使用可能」「トランザクション」「アセットの言語」。 _asset |
ローカリゼーションタイプ |
「利用可能」「トランザクション」「ライセンス」>「権利」>「説明」 |
ライセンス/権利/説明 |
Avail.transaction.format /プロファイル |
フォーマット/プロファイル |
「利用可能」「トランザクション」「契約 ID」 |
契約 ID |
「利用可能」「取引」「その他の指示」 |
その他の指示 |
「使用可能」「トランザクション」。 _トランザクション ID |
使用可能 ID |
「利用可能」「トランザクション」「期間」。 _用語名. チャネル ID |
グループ ID |
「利用可能」、「トランザクション」、「期間」。 _用語名. 発表日 |
発表日 |
「利用可能」、「トランザクション」、「期間」。 _用語名. 抑制解除日 |
抑制解除日 |
「使用可能」、「取引」、「期間」。 _用語名. レンタル期間 |
レンタル期間 |
「利用可能」、「トランザクション」、「期間」。 _用語名. 視聴時間 |
視聴時間 |
「利用可能」、「トランザクション」、「期間」。 _用語名. ダウンロード |
ダウンロード |
「利用可能」「トランザクション」「期間」。 _用語名. 階層 |
価格タイプ |
「利用可能」、「取引」、「期間」。 _用語名. カテゴリ |
価格タイプ |
「利用可能」、「取引」、「期間」。 _用語名.WSP |
価格タイプ |
「利用可能」、「取引」、「期間」。 _用語名.srp |
SRP |
Avail.Transaction.Term.Money.Value |
価格 |
利用可否、取引、期間、金額。 _通貨 |
価格/通貨 |
「利用可能」、「取引」、「期間」、「独占権」 |
独占権 |
利用可能.transaction.term.ExclusiveAttributes |
エクスクルーシブアトリビュート |
使用可能.共有タイトル.ecosystemID |
DMA_ID |
利用可能.共有権限.エコシステム |
DMA_ID |
メソッド
以下のセクションでは、Avails API で使用できるさまざまな API リクエストメソッドについて、その特定のエンドポイント、および各リクエストとレスポンスの本文がどのようなものになるかを説明します。
カテゴリ:完全抽出
GET:- エンドポイント:
/avails/ {ライセンサー} /完全抽出/ {ALID}? territory= {地域} &BusinessLine= {BusinessLine} - リクエストボディ:-
- ResponseBody: 1 つのスコープのトランザクションで利用可能
プット:
- エンドポイント:
/avails/ {ライセンサー} /完全抽出/ {ALID}
リクエストボディ:{... 使用可能データ}- レスポンスボディ:成功/失敗レスポンス
削除:
- エンドポイント:
/avails/ {ライセンサー} /完全抽出/ {ALID}? territory= {territory} & BusinessLine = {BusinessLine} &ContractId = {CPH | FIXED_FEE} &ChannelIdentity = {ChannelIdentity} - リクエストボディ:-
- レスポンスボディ:成功/失敗レスポンス
投稿:
- エンドポイント:
/avails/ {ライセンサー} /完全抽出/ {ALID} /検証
リクエストボディ:{... 使用可能データ}- レスポンスボディ:成功/失敗レスポンス
カテゴリ:
バッチサブカテゴリ:完全抽出 POST:
- エンドポイント:
/avails/完全抽出/バッチ/取得 - リクエストボディ:
{ [ { 'requestId': '<RequestId>', 'path':'/avails/{licensor}/full-extract/{ALID}?territory={territory}&businessLine={businessLine}' }... ] } - レスポンスボディ:
[ { 'requestItemId':'<requestId>', 'success':'<true | false>', 'avail':'<responseBody>', 'errorMessage':'<errorMessage>' }... ]
投稿:
- エンドポイント:
/使用可能/完全抽出/バッチ/プット - リクエストボディ:
{ [ { 'requestId': '<RequestId>', 'path':'/avails/{licensor}/full-extract/{ALID}' 'body': { avails: [<Avail data>] } }... ] } - レスポンスボディ:
[ { 'requestId':'<requestId>', 'statusCode':'<statusCode>', 'body':'<responseBody>', 'errorMessage':'<errorMessage>' }... ]
投稿:
- エンドポイント:
/使用可能/完全抽出/バッチ/削除 - リクエストボディ:
{ [ { 'requestId': '<RequestId>', 'path':'/avails/{licensor}/full-extract/{ALID}?territory={territory}&businessLine={businessLine}&contractId={CPH | FIXED_FEE}&channelIdentity={channelIdentity}' }... ] } - レスポンスボディ:
[ { 'requestId':'<requestId>', 'statusCode':'<statusCode>', 'body':'<responseBody>', 'errorMessage':'<errorMessage>' }... ]
投稿:
- エンドポイント:
/利用可能/完全抽出/バッチ/検証 - リクエストボディ:
{ [ { 'requestId': '<RequestId>', 'path':'/avails/{licensor}/full-extract/{ALID}/validate' 'body': { avails: [<Avail data>] } }... ] } - レスポンスボディ:
[ { 'requestId':'<requestId>', 'statusCode':'<statusCode>', 'body':'<responseBody>', 'errorMessage':'<errorMessage>' }... ]
ビジネスライン
Full Extractでは、ビジネスライン+テリトリーのすべてのA利用状況をまとめて配信する必要があります。 以下のビジネスラインがサポートされています。
- プライム_サブスクリプション
- TVOD
- VOD
- チャネル
ビジネスラインの値は、以下の表に示すように、ライセンスタイプとベネフィットIDの組み合わせによって決定できます。
ライセンスタイプ |
ベネフィット ID |
ビジネスライン |
EST |
- |
TVOD |
VOD |
- |
TVOD |
ポスト |
- |
TVOD |
SVOD |
プライム |
プライム_サブスクリプション |
SVOD |
4K |
プライム_サブスクリプション |
SVOD |
任意 (プライムまたは A4K 以外) |
チャネル |
VOD |
任意 |
VOD |
