通知 API を使用すると、プライム・Video さまざまなコンテンツイベントの通知をリアルタイムで受け取ることができるため、ステータス API を繰り返しポーリングする必要がなくなります。 アセット配信の更新やライブステータスの変更に即座に対応する自動ワークフローを設定することで、問題をより迅速に解決し、カタログを最新の状態に保つことができます。
リアルタイムの問題検出 — アセットの配送が失敗したり、ライブステータスが変更されたりするとすぐに通知が届きます。これにより、数時間または数日後に手動でチェックして問題を発見する代わりに、すぐに対処できます。
API オーバーヘッドの削減 — ステータス API を継続的にポーリングする必要がなくなるため、最新の情報を維持しながら、インフラストラクチャのコストと API 呼び出しの量を削減できます。
自動ワークフロー統合 — 通知を既存のシステム (AWS サービスまたは Webhook) に直接接続して、手動による介入なしに自動応答、チケット作成、アラートワークフローを起動します。
包括的なイベント対応 — 単一の通知システムから、すべてのタイトルと地域のアセット配信ステータスとライブステータスの両方を監視できます。
始めよう通知を使い始めるには、次の 3 つのステップが必要です。
- ターゲットを登録:通知を受け取りたい場所を設定します。 AWS サービス (SQS、SNS、イベントブリッジ) または HTTPS ウェブフックから選択できます。
- サブスクリプション作成:監視したいイベントを登録済みのターゲットにマッピングします。 各サブスクリプションは 1 つのトピック (AssetStatus または OfferStatus) を対象としていますが、そのトピック内の複数のイベントタイプをサブスクライブできます。
- 通知を受け取る:設定が完了すると、イベントがリアルタイムで発生すると自動的に通知が届きます。
利用可能なトピックとイベント
トピックは関連するイベントをグループ化します。 サブスクリプションを作成するときは、トピックを選択し、そのトピック内のどのイベントをモニタリングするかを指定します。
ライブステータス更新トピック
:OfferStatus
Prime Videoのストアフロントで本のライブステータスが変わったとき、つまりタイトルがライブになったとき、またはライブにならないときに通知します。
この通知のトリガーとなるのは何ですか？ ストアフロントでタイトルのライブ/非ライブステータスが変わります。 ペイロードの callbackURL を使用して、オファーステータス API を介してオファーステータスの詳細をすべて取得します。
ペイロード:{
"alid": "partner-listing-id",
"territory": "US",
"marketplace": "US",
"partnerAlias": "partner-alias",
"eventType": "LiveStatusUpdated",
"callbackUrl": "https://partnerapi.primevideo.com/v1/avails/{partnerAlias}/status/{alid}?marketplace={marketplace}&territory={territory}",
"eventTimestamp": "2024-01-01T00:00:00.000Z"
}
資産状況更新トピック:AssetStatus
アセットが最終的な配信結果に達すると通知します。 アセットのステータスが以下のようになると通知が送信されます。
- 発送済み — アセットは正常に配送されました。または
- 失敗 — 納品できなかったか、対応が必要です。
この通知のトリガーは何か? アセットの配信状況の変化 (ビデオ、オーディオ、字幕、アートワークなど)。 callbackURL を使用すると、該当する場合は詳細なエラー情報を含め、アセットの配信状況全体を取得できます。
ユースケース:
- 配信エラーをリアルタイムで検出し、自動再配信ワークフローを起動します。
- アセットステータス API をポーリングせずにアセット処理が成功したことを確認する
- 社内のチケットシステムと統合して、問題を即座に解決できます。
ペイロード:{
"alid": "partner-listing-id",
"marketplace": "US",
"partnerAlias": "partner-alias",
"eventType": "AssetStatusUpdated",
"callbackUrl": "https://partnerapi.primevideo.com/v1/assets/{partnerAlias}/status/{alid}?marketplace={marketplace}",
"eventTimestamp": "2024-01-01T00:00:00.000Z"
}
リクエストスキーマとレスポンススキーマ
このセクションでは、開発者がパートナー通知 API をシステムに統合するための技術仕様を提供します。 このリファレンスを使って、API によって返されるリクエストフォーマット、レスポンス構造、データ型を理解してください。
ベース URL
すべて API リクエストは、次のベース URL に対して行われます。 リクエストを行うときは、関連するエンドポイントパスをこの URL に追加します。
https://partnerapi.primevideo.com/v1
ターゲット管理ターゲットは通知を受け取りたい宛先です。これは AWS サービス (SQS、SNS、または EventBridge) でも HTTPS ウェブフックエンドポイントでもかまいません。 サブスクリプションを作成する前に、少なくとも 1 つのターゲットを登録する必要があります。
ターゲットを登録
POST /{licensor}/notifications/targets
イベント通知を受け取る新しい通知ターゲット作成。
リクエストボディ:
{
"type": "SQS|SNS|EVENTBRIDGE|WEBHOOK",
"destination": "target-destination",
"auth": { /* varies by type */ }
}
応答:
{
"targetId": "target-id-1",
"status": "ACTIVE"
}
すべて
ターゲットを一覧表示このエンドポイントを使用して、組織に登録されている通知ターゲットの全リストを取得します。 これは、現在の設定を監査したり、サブスクリプションを作成または更新するときに使用するターゲット ID を特定したりするのに役立ちます。
GET /{licensor}/notifications/targets
組織の登録済みターゲットをすべて取得します。
特定のターゲットを取得
GET /{licensor}/notifications/targets?targetId={id}
特定のターゲットの詳細を取得します。
ターゲットを更新
PUT /{licensor}/notifications/targets/{targetId}
既存のターゲット設定を更新します。
ターゲットを削除します。
DELETE /{licensor}/notifications/targets/{targetId}
設定からターゲットを削除します。
サブスクリプション管理サブスクリプションは、1 つ以上のイベントを登録済みのターゲットにマップし、受信する通知と配信先を決定します。 各サブスクリプションは 1 つのトピックを対象としていますが、ワークフローに関連するすべてのイベントを対象とするサブスクリプションを複数作成することもできます。
購読作成
POST /{licensor}/notifications/subscriptions
サブスクリプション作成して、イベントをターゲットにマッピングします。
リクエストボディ:
{
"topic": "OfferStatus",
"eventTargetMapping": {
"LiveStatusUpdated": ["target-id-1"]
}
}
応答:
{
"subscriptionId": "subscription-id-1",
"status": "ACTIVE"
}
すべて購読を一覧表示
GET /{licensor}/notifications/subscriptions
組織のすべてのサブスクリプションを取得します。
購読を更新
PUT /{licensor}/notifications/subscriptions/{id}
既存のサブスクリプション設定を更新します。
サブスクリプションを削除します。
DELETE /{licensor}/notifications/subscriptions/{id}
設定からサブスクリプションを削除します。
ターゲットタイプ
ターゲットタイプは、Prime Videoがシステムに通知を配信する方法を定義します。 信頼性が高くスケーラブルな配信を実現する AWS マネージドサービスから選択することも、HTTPS ウェブフックを設定して独自のエンドポイントで直接通知を受信することもできます。
AWS ターゲット (SQS、SNS、イベントブリッジ)
必須フィールド:
- デスティネーション — AWS リソースの ARN
- AssumeRoLearn — デリバリー用の IAM ロール
- ExternalID — セキュリティ識別子 (オプションですが推奨)
SQS の例:{
"type": "SQS",
"destination": "arn:aws:sqs:{region}:{account-id}:{queue-name}",
"auth": {
"assumeRoleArn": "arn:aws:iam::{account-id}:role/{role-name}",
"externalId": "{external-id}"
}
}
SNS の例:{
"type": "SNS",
"destination": "arn:aws:sns:{region}:{account-id}:{topic-name}",
"auth": {
"assumeRoleArn": "arn:aws:iam::{account-id}:role/{role-name}",
"externalId": "{external-id}"
}
}
イベントブリッジの例:{
"type": "EVENTBRIDGE",
"destination": "arn:aws:events:{region}:{account-id}:event-bus/{bus-name}",
"auth": {
"assumeRoleArn": "arn:aws:iam::{account-id}:role/{role-name}",
"externalId": "{external-id}"
}
}
ベアラートークン:{
"type": "WEBHOOK",
"destination": "https://your-api.example.com/webhooks",
"auth": {
"type": "bearer",
"bearerToken": "your-token"
}
}
API キー:{
"type": "WEBHOOK",
"destination": "https://your-api.example.com/webhooks",
"auth": {
"type": "apiKey",
"apiKey": "your-key",
"apiKeyHeader": "X-API-Key"
}
}
HMAC (推奨): {
"type": "WEBHOOK",
"destination": "https://your-api.example.com/webhooks",
"auth": {
"type": "hmac",
"hmacSecret": "your-secret",
"hmacAlgorithm": "HmacSHA256",
"hmacHeader": "X-Signature"
}
}
ペイロード
ペイロード構造すべて通知ペイロードは一貫した構造に従います。
フィールド |
Description |
|---|---|
有効 |
パートナーリスティングID (タイトル識別子) |
地域 |
地域コード (例:US、GB) |
マーケットプレイス |
マーケットプレイスコード |
パートナーエイリアス |
パートナー識別子 |
イベントタイプ |
発生した特定のイベント。 |
コールバック URL |
ステータスの詳細情報を取得するための URL |
イベント/タイムスタンプ |
イベントの ISO 8601 タイムスタンプ。 |
ウェブフックは以下のペイロードを含む HTTP POST リクエストを受信します。{
"alid": "partner-listing-id",
"territory": "US",
"marketplace": "US",
"partnerAlias": "partner-alias",
"eventType": "LiveStatusUpdated",
"callbackUrl": "https://callback-url.com",
"eventTimestamp": "2024-01-01T00:00:00.000Z"
}
認証ヘッダー:
- HMAC: X シグネチャ:{シグネチャ} X シグネチャ:{シグネチャ}
- API キー:X-API キー:{キー} X-API キー:{キー}
- ベアラー:ベアラー {トークン} 認証:ベアラー {トークン}
AWS ターゲットセットアップガイド
通知ターゲットとして AWS サービス (SQS、SNS、または EventBridge) を使用している場合は、IAM 配信ロールを設定して、Prime Video に通知を AWS リソースに配信する権限を付与する必要があります。 ターゲットを登録する前に、以下の手順に従って必要な IAM ロールと権限ポリシーを設定します。
前提条件
- AWS デスティネーションリソース (SQS キュー、SNS トピック、またはイベントブリッジバス)
- 信頼ポリシーと権限ポリシーを含む IAM デリバリーロール
IAM ロールセットアップ
1. ロール作成:AWS コンソール → IAM → ロール → ロール作成 → カスタム信頼ポリシー 2. 信頼ポリシー {
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::687801838843:root"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"sts:ExternalId": "{external-id}"
},
"ArnLike": {
"aws:PrincipalArn": "arn:aws:iam::687801838843:role/PVPartnerApiNPS-ExecutionRole-*"
}
}
}
]
}
3. 権限ポリシー (1 つ選択):
SQS:
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": ["sqs:SendMessage", "sqs:GetQueueUrl"],
"Resource": "arn:aws:sqs:{region}:{account-id}:{queue-name}"
}]
}
SNS: {
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": "sns:Publish",
"Resource": "arn:aws:sns:{region}:{account-id}:{topic-name}"
}]
}
イベントブリッジ:{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": "events:PutEvents",
"Resource": "arn:aws:events:{region}:{account-id}:event-bus/{bus-name}"
}]
}
