通知API

リアルタイムの問題検知 - アセットの納品に失敗した場合や公開ステータスが変更された場合に即座に通知を受け取れるため、手動確認で数時間後や数日後に問題を発見するのではなく、すぐに対処できます。

APIオーバーヘッドの削減 - ステータスAPIを継続的にポーリングする必要がなくなり、最新情報を維持しながらインフラストラクチャコストとAPI呼び出し量を削減できます。

自動ワークフロー統合 - 通知を既存のシステム(AWSサービスまたはWebhook)に直接接続して、レスポンス、チケット作成、アラートワークフローを自動でトリガーでき、手動操作が不要となります。

イベントを包括的にカバー - 1つの通知システムから、すべてのタイトルと地域にわたるアセット納品ステータスと公開ステータスの両方を監視できます。

はじめに
通知を開始するには次の3つの手順が必要です:

1. ターゲットを登録する： 通知を受け取る場所を設定してください。AWSサービス(SQS、SNS、EventBridge)またはHTTPS Webhookから選択できます。
2. サブスクリプションを作成する: 監視したいイベントを登録済みターゲットにマッピングしてください。それぞれのサブスクリプションは1つのトピック(AssetStatusまたはOfferStatus)を対象としますが、サブスクリプションを行う場合はそのトピック内の複数のイベントタイプを扱えます。
3. 通知を受け取る: 構成が完了したら、イベントがリアルタイムで発生した際に自動的に通知が届きます。

トピックは関連するイベントをまとめてグループ化します。サブスクリプションを作成するときは、トピックを選択し、そのトピック内のどのイベントを監視するかを指定します。

LiveStatusUpdated
トピック
プライムVideoストアフロントでタイトルの公開ステータスが変更されたとき、つまり、タイトルが公開または非公開になったときに通知します。
この通知のトリガーは何ですか？ タイトルの公開/非公開ステータスがストアフロントで変更されたとき。ペイロード内のcallbackURLを使用し、オファーステータスAPI経由でオファーステータスの詳細をすべて取得します。

ペイロード：

AssetStatusUpdated
トピック：
アセットが最終的な納品結果に達すると通知します。アセットのステータスが次のいずれかになると、通知が送信されます。

• 履行済み — アセットが正常に納品された場合、または
• 失敗 — アセットを納品できなかった、または対応が必要な場合。

この通知のトリガーは何ですか？ アセット（ビデオ、オーディオ、字幕、アートワークなど）の納品ステータスが変更されたとき。callbackUrlを使用して、該当する場合は詳細なエラー情報を含む、アセットの納品ステータス全体を取得します。

ユースケース：

• 納品エラーをリアルタイムで検出し、自動再納品ワークフローを起動します。
• Asset Status APIをポーリングせずに、アセット処理が正常に完了したことを確認します。
• 社内のチケットシステムと統合し、問題を迅速に解決します。

ペイロード：

このセクションでは、開発者がパートナー通知APIをシステムに統合するための技術仕様について説明します。このリファレンスは、APIによって返されるリクエストフォーマット、レスポンス構造、およびデータタイプの理解に役立ちます。

ベースURL
すべてのAPIリクエストは、次のベースURLに対して行われます。リクエストを行う際には、関連するエンドポイントパスをこのURLに追加してください。

ターゲット管理
ターゲットとは、通知の送信先とするものです。これはAWSサービス(SQS、SNS、またはEventBridge)でもHTTP Webhookエンドポイントでもかまいません。サブスクリプションを作成する前に、少なくとも1つのターゲットを登録する必要があります。

ターゲットを登録

イベント通知を受け取る新しい通知ターゲットを作成します。

リクエスト本文:

レスポンス:

すべてのターゲットを一覧表示
このエンドポイントを使用して、組織に登録されている通知ターゲットの全リストを取得します。これは、現在の構成を監査したり、サブスクリプションの作成や更新を行うときに使用するターゲットIDを特定したりするのに役立ちます。

組織の登録済みターゲットをすべて取得します。

特定ターゲットを取得

特定ターゲットの詳細を取得します。

ターゲットを更新

既存のターゲット構成を更新します。

ターゲットを削除

構成からターゲットを削除します。

サブスクリプション管理
サブスクリプションは登録されたターゲットに1つ以上のイベントをマッピングし、どの通知を受け取るか、どこに配信するかを決定します。それぞれのサブスクリプションの対象範囲は1つのトピックですが、複数のサブスクリプションを作成して、ワークフローに関連するすべてのイベントをカバーできます。

サブスクリプションを作成

サブスクリプションを作成して、イベントをターゲットにマッピングします。

リクエスト本文:

レスポンス:

すべてのサブスクリプションを一覧表示

組織のすべてのサブスクリプションを取得します。

サブスクリプションを更新

既存のサブスクリプション構成を更新します。

サブスクリプションを削除

構成からサブスクリプションを削除します。

ターゲットタイプは、プライムVideoがシステムに通知を配信する方法を定義します。信頼性が高くスケーラブルな配信のためのAWSマネージドサービスから選ぶか、独自のエンドポイントで直接通知を受信するようにHTTPS Webhookを構成できます。

AWSターゲット（SQS、SNS、EventBridge）

必須フィールド：

• destination - AWSリソースのARN
• assumeRoleArn - 納品に関するIAMロール
• externalId – セキュリティ識別子（任意ですが推奨）

SQSの例：

SNSの例：

EventBridgeの例：

ベアラートークン：

APIキー：

HMAC（推奨）：

ペイロード構造
すべての通知ペイロードは一貫した構造に従います。

Webhookは、以下のペイロードを含むHTTP POSTリクエストを受信します：

認証ヘッダー:

• HMAC: Xシグネチャ: {signature}Xシグネチャ:{signature}
• APIキー： X-APIキー: {key}X-APIキー:{key}
• ベアラー: {token}ベアラ権限: ベアラー{token}

リクエストを完了できない場合、APIは問題の特定と解決に役立つ構造化されたエラーレスポンスを返します。レスポンスには、エラーコードと、人間が読める形式で問題を説明するメッセージが含まれます。

一般的なエラーコード:

• BAD_REQUEST - リクエストパラメータが無効です
• UNAUTHORIZED - 認証失敗
• NOT_FOUND - リソースが見つかりません
• CONFLICT - リソースはすでに存在しています

通知ターゲットとしてAWSサービス(SQS、SNS、またはEventBridge)を使用している場合は、AWSリソースに通知を配信する権限をプライムVideoに付与するIAM配信ロールを構成する必要があります。ターゲットを登録する前に、必要なIAMロールと権限ポリシーを以下の手順に従って設定します。

前提条件

• AWS送信先リソース(SQSキュー、SNSトピック、またはEventBridgeバス)
• 信頼ポリシーと権限ポリシーを含むIAM配信ロール

IAMロール設定

1.ロールを作成: AWSコンソール → IAM → ロール → ロールを作成 → カスタム信頼ポリシー

2.トラストポリシー

3.権限ポリシー （1つ選択）：

SQS:

SNS:

EventBridge: