通知APIを使用すると、Prime Videoのさまざまなコンテンツイベントの通知をリアルタイムで受け取れるため、ステータスAPIを繰り返しポーリングする必要がなくなります。アセット納品の更新やオファーステータスの変更に即座に対応する自動ワークフローを設定することで、問題をより迅速に解決し、カタログを最新の状態に保てます。
通知APIを使用する理由
- リアルタイムの問題検知 - アセット納品が失敗したり、オファーステータスが変化したりすると、すぐに通知を受け取れ、問題に即時に対処できるため、手動での確認により数時間後や数日後に問題を発見するということがありません。
- APIオーバーヘッドの削減 - ステータスAPIを継続的にポーリングする必要がなくなり、最新情報を維持しながらインフラストラクチャコストとAPI呼び出し量を削減できます。
- 自動ワークフロー統合 - 通知を既存のシステム(AWSサービスまたはWebhook)に直接接続して、レスポンス、チケット作成、アラートワークフローを自動でトリガーでき、手動操作が不要となります。
- イベントを包括的にカバー - すべてのタイトルとテリトリーに渡るアセット納品ステータスとオファー利用可能状況の両方を1つの通知システムから監視できます。
はじめに
通知を開始するには次の3つの手順が必要です:
- ターゲットを登録する: 通知を受け取る場所を設定してください。AWSサービス(SQS、SNS、EventBridge)またはHTTPS Webhookから選択できます。
- サブスクリプションを作成する: 監視したいイベントを登録済みターゲットにマッピングしてください。それぞれのサブスクリプションは1つのトピック(AssetStatusまたはOfferStatus)を対象としますが、サブスクリプションを行う場合はそのトピック内の複数のイベントタイプを扱えます。
- 通知を受け取る: 構成が完了したら、イベントがリアルタイムで発生した際に自動的に通知が届きます。
ターゲット管理
ターゲットとは、通知の送信先とするものです。これはAWSサービス(SQS、SNS、またはEventBridge)でもHTTP Webhookエンドポイントでもかまいません。サブスクリプションを作成する前に、少なくとも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"],
"OfferStatusUpdated": ["target-id-2"]
}
}
レスポンス:{
"subscriptionId": "subscription-id-1",
"status": "ACTIVE"
}
すべてのサブスクリプションを一覧表示
GET /{licensor}/notifications/subscriptions
組織のすべてのサブスクリプションを取得します。
サブスクリプションを更新
PUT /{licensor}/notifications/subscriptions/{id}
既存のサブスクリプション構成を更新します。
サブスクリプションを削除
DELETE /{licensor}/notifications/subscriptions/{id}
構成からサブスクリプションを削除します。
ターゲットタイプ
ターゲットタイプは、Prime Videoがシステムに通知を配信する方法を定義します。信頼性が高くスケーラブルな配信のためのAWSマネージドサービスから選ぶか、独自のエンドポイントで直接通知を受信するようにHTTPS Webhookを構成できます。
AWS Targets (SQS、SNS、EventBridge) - 必須フィールド:
- destination - 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}"
}
}
EventBridgeの例:{
"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}"
}
}
Webhookターゲット - ベアラートークン:{
"type": "WEBHOOK",
"destination": "https://your-api.example.com/webhooks",
"auth": {
"type": "bearer",
"bearerToken": "your-token"
}
}
Webhookターゲット - APIキー:{
"type": "WEBHOOK",
"destination": "https://your-api.example.com/webhooks",
"auth": {
"type": "apiKey",
"apiKey": "your-key",
"apiKeyHeader": "X-API-Key"
}
}
Webhookターゲット - HMAC (推奨):{
"type": "WEBHOOK",
"destination": "https://your-api.example.com/webhooks",
"auth": {
"type": "hmac",
"hmacSecret": "your-secret",
"hmacAlgorithm": "HmacSHA256",
"hmacHeader": "X-Signature"
}
}
ペイロード
Webhookは、以下のペイロードを含むHTTP POSTリクエストを受信します:{
"alid": "partner-listing-id",
"territory": "US",
"marketplace": "US",
"eventType": "LiveStatusUpdated",
"callbackUrl": "https://callback-url.com",
"eventTimestamp": "2024-01-01T00:00:00.000Z"
}
認証ヘッダー:
- HMAC: Xシグネチャ:{signature}
- APIキー: X-APIキー: {key}
- ベアラー: 認可: ベアラー{token}
AWSターゲット設定ガイド
通知ターゲットとしてAWSサービス(SQS、SNS、またはEventBridge)を使用している場合は、AWSリソースに通知を配信する権限をPrime Videoに付与するIAM配信ロールを構成する必要があります。ターゲットを登録する前に、必要なIAMロールと権限ポリシーを以下の手順に従って設定します。
前提条件
- AWS送信先リソース(SQSキュー、SNSトピック、またはEventBridgeバス)
- 信頼ポリシーと権限ポリシーを含むIAM配信ロール
IAMロール設定
1.ロールを作成: AWSコンソール → IAM → ロール → ロールを作成 → カスタム信頼ポリシー
2.トラストポリシー{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::687801838843:role/PVPartnerApiNotificationP-EcsTaskInstanceRoleE38DB4-qWjKHaQBhouq"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"sts:ExternalId": "{external-id}"
}
}
}]
}
3.権限ポリシー(次のいずれかを選んでください)
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}"
}]
}
EventBridge: {
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": "events:PutEvents",
"Resource": "arn:aws:events:{region}:{account-id}:event-bus/{bus-name}"
}]
}
