ApsaraVideo VOD:HTTP コールバック

仕組み

1. コールバックメッセージを受信するための HTTP サービスをデプロイし、ApsaraVideo VOD でコールバック URL を設定します。

2. イベントが発生すると、ApsaraVideo VOD サーバーはこの URL に HTTP POST リクエストを送信します。イベント通知の内容はリクエストボディに含まれます。

3. ご利用の HTTP サービスで、受信した HTTP POST リクエストの署名を認証します。認証が成功した場合、サービスはステータスコード 200 を応答して、コールバックが成功したことを示す必要があります。その他のステータスコードが返された場合や応答がタイムアウトした場合は、コールバックの失敗とみなされます。認証の仕組みの詳細については、「コールバック認証の仕組み」をご参照ください。

4. コールバックが成功すると、設定したコールバック URL が対応するイベント通知を受信します。コールバックが失敗した場合、ApsaraVideo VOD はリクエストをさらに 2 回リトライし、合計で 3 回試行します。3 回の試行がすべて失敗した場合、ApsaraVideo VOD はそのイベント通知を破棄します。コールバックの判定とリトライロジックの詳細については、「コールバックの判定とリトライ」をご参照ください。

HTTP コールバックの使用方法

前提条件

• コールバックメッセージを受信するための HTTP または HTTPS サービスをデプロイ済みであること。

• Alibaba Cloud アカウントが作成され、本人確認が完了していること。Alibaba Cloud アカウントを作成するには、Alibaba Cloud 公式サイトにアクセスしてください。詳細については、「Alibaba Cloud アカウントの作成」をご参照ください。

• ApsaraVideo VOD が有効化されていること。詳細については、「ApsaraVideo VOD の有効化」をご参照ください。

使用方法

• ApsaraVideo VOD は複数のサービスリージョンで利用できます。イベント通知の設定はリージョンごとに独立しています。サービスリージョンごとに個別のコールバックメソッドとコールバック URL を設定できます。

• さまざまな開発環境のニーズに対応するために、複数のコールバック URL を設定できます。詳細については、「複数のコールバック URL の設定」をご参照ください。

操作手順

1. ApsaraVideo VOD で HTTP コールバックのイベント通知を設定します。

   説明

   ApsaraVideo VOD コンソールで設定されたコールバック設定はグローバルに適用されます。API を使用してグローバルコールバックを設定したり、1 回のリクエストでのオーバーライドを実装したりすることもできます。

   コンソール

   1. ApsaraVideo VOD コンソールにログインします。

   2. 左側のナビゲーションウィンドウで、[設定管理] > [メディア処理] > [コールバック] を選択します。

   3. 上部のナビゲーションバーで、[ワークベンチ] の横にあるドロップダウンリストからサービスリージョンを選択します。

   4. コールバックの設定 を行います。[コールバック認証] セクションで、認証を有効にし、[認証キー] を設定できます。

      1. コールバックの設定 の横にある 変更 をクリックします。

      2. コールバックパラメーターを設定します。

         パラメーター	説明
         コールバックメソッド	HTTP リクエスト を選択します。
         コールバック URL	コールバックメッセージを受信する URL を入力します。コールバックイベントが発生すると、ApsaraVideo VOD サーバーはこの URL に HTTP POST リクエストを送信します。 URL の長さは 256 バイトまでです。URL は 1 つだけ指定できます。
         イベント	通知を受信したいイベントタイプを選択します。サポートされているイベントタイプとその意味の詳細については、「イベントリスト」をご参照ください。 説明 AI 処理が完了しました を選択した場合、AIMediaAuditComplete、AIMediaDNAComplete、AIVideoTagComplete などの AI イベントのいずれかが完了すると、すべての AI イベントに対して通知が送信されます。

      3. 決定 をクリックしてコールバック設定を保存します。

   5. 任意：コールバック認証 を設定します。

      コールバックメソッドが HTTP リクエスト の場合、HTTP または HTTPS ヘッダーに認証パラメーターを追加できます。これにより、コールバック受信側でリクエストの署名を検証し、不正または無効なリクエストを防ぐことができます。

      1. コールバック認証のスイッチをオンにするか、コールバック認証 の横にある 変更 をクリックします。

      2. 認証キーを設定します。

         このキーは、署名アルゴリズムの AuthKey フィールドに対応します。詳細については、「署名アルゴリズム」をご参照ください。キーはユーザー定義で、長さは 32 文字まで、大文字、小文字、数字を含む必要があります。

      3. 決定 をクリックして設定を保存します。

      4. コールバック認証を有効にした後、コールバックを受信する HTTP または HTTPS サービスに対応する認証ロジックを実装する必要があります。詳細については、「コールバック認証の仕組み」をご参照ください。

   API

   さまざまな API オペレーションを呼び出して、グローバルコールバックを設定したり、1 回のリクエストでのオーバーライドを使用したりできます。

   • グローバル設定：SetMessageCallback オペレーションを呼び出します。CallbackType パラメーターを HTTP に設定し、CallbackURL や EventTypeList などの他のパラメーターを設定します。

   • 1 回のリクエストでのオーバーライド：API を呼び出してメディアアセットをアップロードしたり、メディア処理ジョブを開始したりするときに、UserData パラメーターの MessageCallback フィールドを指定することで、その特定のリクエストのコールバックアドレスを設定できます。これは、次の API オペレーションに適用されます：

     • CreateUploadVideo

     • CreateUploadImage

     • CreateUploadAttachedMedia

     • UploadMediaByURL

     • RegisterMedia

     • SubmitTranscodeJobs

     • SubmitSnapshotJob

     • SubmitAIMediaAuditJob

     • ProduceEditingProjectVideo

   説明

   MessageCallback フィールドの UserData パラメーターを使用して 1 回のリクエストでのオーバーライドを行うには、まず ApsaraVideo VOD でグローバルイベント通知を有効にし、対応するイベントタイプを設定する必要があります。そうしないと、オーバーライド設定は有効になりません。

2. コールバックイベントをトリガーします。

   イベント通知を設定した後、ApsaraVideo VOD で操作を実行してイベントをトリガーします。たとえば、メディアファイル (音声、動画、または画像) をアップロードしたり、トランスコードやスナップショット作成などのメディア処理ジョブを開始したりします。

3. コールバックイベントを受信します。

   コールバックイベントが発生した後、コールバックが成功すれば、コールバック受信側でイベント通知を表示できます。

コールバック認証の仕組み

コールバックメソッドが HTTP リクエスト の場合、HTTP または HTTPS ヘッダーに認証パラメーターを追加できます。これにより、コールバック受信側でリクエストの署名を検証し、不正または無効なリクエストを防ぐことができます。

使用方法

• HTTP コールバック認証を有効にするかどうかを選択できます (推奨)。AuthKey (認証キー) を設定すると、すべてのコールバックリクエストに必要な認証ヘッダーが含まれるようになり、コールバック受信側で検証に使用できます。AuthKey を設定しても既存の機能には影響しません。受信側で検証を強制するかどうかはユーザーが決定します。

• AuthKey を設定しない場合でも、HTTP コールバック機能は通常どおり動作します。

認証パラメーター

署名アルゴリズム

MD5Content = コールバック URL|X-VOD-TIMESTAMP|AuthKey
X-VOD-SIGNATURE = md5sum(MD5Content)

X-VOD-SIGNATURE = md5sum(https://www.example.com/your/callback|1519375990|Test123) = c72b60894140fa98920f1279219b****

受信側の検証ルール

• コールバック受信側は、設定したコールバック URL、受信した X-VOD-TIMESTAMP の値、および保存されている AuthKey を連結して文字列を再構築します。次に、この文字列の MD5 ハッシュを計算し、X-VOD-SIGNATURE ヘッダーの値と比較します。値が一致しない場合、リクエストは無効です。

• リプレイ攻撃を防ぐために、コールバック受信側は現在の時刻と X-VOD-TIMESTAMP ヘッダーの時刻を比較できます。差が指定されたしきい値 (たとえば 5 分) を超える場合、リクエストを無効と見なすことができます。

  説明

  サーバー間のクロックのずれの可能性があるため、この時間ベースのチェックは信頼できない場合があります。このチェックを実装するかどうかは、ユーザーが決定できます。

キーのローテーション

AuthKey をローテーションする場合、シームレスな移行を確保し、コールバックの失敗を防ぐために、コールバック受信側は一時的に新旧両方のキーをサポートする必要があります。受信側でこのデュアルキー検証ロジックを処理する必要があります。

関連ドキュメント

• HTTP コールバックと MNS コールバックの比較については、「HTTP コールバックと MNS コールバックの比較」をご参照ください。

• 問題が発生した場合は、「イベント通知に関するよくある質問」をご参照ください。