ApsaraVideo VOD:HTTP コールバック

HTTP コールバックの仕組み

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

2. イベントが発生すると、ApsaraVideo VOD サーバーはコールバック URL に HTTP POST リクエストを送信します。イベント通知は HTTP 本文で配信されます。

3. ご利用の HTTP サービスは、HTTP POST リクエストの署名を認証します。認証が成功した場合、サービスは HTTP ステータスコード 200 を返し、コールバックが成功したことを示します。別のステータスコードが返された場合、またはリクエストがタイムアウトした場合、コールバックは失敗となります。認証プロセスの詳細については、「HTTP コールバック認証プロセス」をご参照ください。

4. コールバックが成功すると、設定したコールバック URL がイベント通知を受信します。コールバックが失敗した場合、ApsaraVideo VOD はコールバックを 2 回再試行します。3 回すべての試行が失敗した場合、ApsaraVideo VOD はイベント通知を破棄します。コールバックの検証と再試行の詳細については、「コールバックの検証と再試行」をご参照ください。

利用方法

前提条件

• コールバックメッセージを受信するための HTTP または HTTPS サービスがデプロイされていること。

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

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

注意事項

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

• HTTP コールバックは、さまざまな開発環境をサポートするために、複数の Webhook アドレスをサポートしています。詳細については、「複数の Webhook アドレスの設定」をご参照ください。

操作手順

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

   説明

   ApsaraVideo VOD コンソールで設定されたコールバックは、サービスのグローバル設定です。OpenAPI を使用してグローバルコールバックを設定したり、単一リクエストの設定をオーバーライドしたりできます。

   コンソールでの HTTP コールバックの設定

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

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

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

   4. コールバックの設定 を設定します。

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

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

         パラメーター名	説明
         コールバックメソッド	HTTP リクエスト を選択します。
         コールバック URL	コールバックメッセージを受信する Webhook アドレスを設定します。コールバックイベントが発生すると、ApsaraVideo VOD サーバーはこのアドレスに HTTP POST リクエストを送信します。 URL の長さは最大 256 バイトです。複数の URL はサポートされていません。
         コールバックイベント	必要に応じて、通知を受け取りたいイベントタイプを選択します。ApsaraVideo VOD がサポートするイベントタイプと各イベント通知の詳細については、「イベントリスト」をご参照ください。 説明 AI 処理が完了しました を選択すると、AIMediaAuditComplete、AIMediaDNAComplete、AIVideoTagComplete など、すべての AI イベントに対して通知がトリガーされます。

      3. 決定 をクリックします。

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

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

      1. コールバック認証 セクションで、変更 をクリックします。

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

         この認証キーは、署名アルゴリズムの AuthKey フィールドです。詳細については、「署名アルゴリズム」をご参照ください。キーの長さは最大 32 文字で、数字、大文字、小文字を含める必要があります。

      3. 決定 をクリックして設定を完了します。

      4. コールバック認証を有効にした後、受信側の HTTP または HTTPS サーバーに対応する認証ロジックを設定します。詳細については、「HTTP コールバック認証プロセス」をご参照ください。

   OpenAPI を使用した HTTP コールバックの設定

   さまざまな操作を呼び出して、グローバルコールバックを設定したり、単一リクエストの設定をオーバーライドしたりできます。

   • グローバル設定：イベント通知設定操作を呼び出し、リクエストパラメーター CallbackType を HTTP に設定し、CallbackURL や EventTypeList などの他のパラメーターを設定します。

   • リクエストごとのオーバーライド：UserData リクエストパラメーターの MessageCallback フィールドを指定することで、単一のリクエストに対して Webhook アドレスを設定できます。この機能は、メディアファイルのアップロードやメディア処理ジョブの送信のために以下の操作を呼び出す際に利用できます。

     • 音声・動画のアップロード URL と認証情報の取得

     • 画像アップロード URL と認証情報の取得

     • 補助メディアアセットのアップロード URL と認証情報の取得

     • UploadMediaByURL

     • RegisterMedia

     • ApsaraVideo Media Processing ジョブの送信

     • メディアスナップショットジョブの送信

     • 音声・動画の自動レビュー ジョブの送信

     • 動画合成

   説明

   MessageCallback の UserData フィールドを使用してコールバックを設定する場合、まず ApsaraVideo VOD のグローバルイベント通知を有効にし、対応するコールバックイベントタイプを設定して、コールバック設定を有効にする必要があります。

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

   イベント通知を設定した後、ApsaraVideo VOD でメディアアセット (音声、動画、画像) のアップロードやメディア処理ジョブ (トランスコーディングやスナップショット) の送信などの操作を実行して、コールバックイベントをトリガーします。

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

   コールバックイベントがトリガーされた後、コールバックが成功した場合、デプロイしたコールバック受信サービスでイベント通知を表示できます。

HTTP コールバック認証の原則

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

注意事項

• HTTP コールバック認証の有効化は任意ですが、推奨されます。認証キー (AuthKey) を設定すると、コールバックには受信サーバーが認証を実行するために必要なすべての情報が含まれます。AuthKey を設定しても既存の機能には影響せず、サーバーで検証を実行するかどうかはユーザーが決定できます。

• AuthKey を設定しない場合でも、HTTP コールバック機能に影響はありません。

認証パラメーター

署名アルゴリズム

MD5Content = Callback 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 の切り替え

AuthKey を切り替える際、コールバック受信サーバーは、コールバック機能に影響が出ないように、古い AuthKey と新しい AuthKey の両方をサポートすることで、スムーズな移行をサポートする必要があります。つまり、一定期間、サーバーは古い AuthKey と新しい AuthKey の両方での認証をサポートする必要があります。この移行の処理は、コールバック受信サーバーが担当します。

参考資料

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

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