ApsaraVideo VOD は、HTTP (および HTTPS) コールバックと Simple Message Queue (formerly MNS) コールバックによるイベント通知をサポートしています。このトピックでは、イベントタイプ、コールバックメソッド、構成、プロトコル、共通パラメーター、検証、リトライポリシー、およびよくある質問 (FAQ) について説明します。
イベント通知の概要
ApsaraVideo VOD は複数のストレージリージョンをサポートしています。各リージョンでイベント通知用に一意のコールバックメソッドと Webhook アドレスを設定できます。ビデオがアップロードされて処理された後、ApsaraVideo VOD はそのリージョンに設定されたコールバックメソッドと Webhook アドレスに基づいて通知を送信します。
コールバック本文は HTTP URL のみを返します。HTTPS URL はサポートされていません。HTTPS URL の取得方法の詳細については、「イベント通知に関する FAQ」をご参照ください。
コールバックメソッド
ApsaraVideo VOD は、イベント通知を受信するために 2 つのメソッドをサポートしています: HTTP (および HTTPS) コールバックとSimple Message Queue (MNS) コールバックです。
HTTP (および HTTPS) コールバック:
HTTP コールバックは、ApsaraVideo VOD からイベント通知を受信するためのパッシブなメソッドです。このメソッドでは、HTTP サービスをデプロイしてコールバックメッセージを受信し、ApsaraVideo VOD で Webhook アドレスを設定します。イベントが発生すると、VOD サービスはこのアドレスに HTTP POST リクエストを送信し、イベント通知は HTTP 本文で配信されます。
Simple Message Queue (formerly MNS) コールバック:
Simple Message Queue (formerly MNS) コールバックは、ApsaraVideo VOD からイベント通知をプルできるアクティブなメソッドです。ApsaraVideo VOD に MNS へのアクセスを許可した後、Simple Message Queue (formerly MNS) で既存のキューを作成または使用し、ApsaraVideo VOD でイベント通知を設定できます。イベントが発生すると、ApsaraVideo VOD はコールバックコンテンツをキューに書き込みます。その後、Simple Message Queue (formerly MNS) キューからメッセージを取得する必要があります。Simple Message Queue (formerly MNS) コンソールでキューを作成してメッセージを受信する方法の詳細については、「キュー操作」をご参照ください。
HTTP コールバックと MNS コールバックの比較
項目 | HTTP コールバック | MNS コールバック (推奨) |
信頼性 | HTTP メッセージ受信サービスが異常な場合 (クラッシュや再起動など)、メッセージが失われる可能性があります。 | より信頼性が高い。適切な構成であれば、コールバックはほぼ確実に成功します。 |
セキュリティ | 誰でも Webhook アドレスにリクエストを送信できます。ただし、コールバック認証を使用して不正なリクエストをフィルターし、セキュリティを向上させることができます。 詳細については、「HTTP コールバック認証」をご参照ください。 | より安全。許可された関係者のみがメッセージキューの読み取りと書き込みを行えるためです。 |
利便性 | より便利に統合できます。メッセージ受信サービスをデプロイするだけです。 | Simple Message Queue (formerly MNS) をアクティブ化して設定する必要があります。また、メッセージを消費するためのプログラムを開発してデプロイする必要もあります。 |
コールバックプロトコル
共通コールバックパラメーター
パラメーター | タイプ | 説明 |
EventTime | String | イベントが発生した時刻 (UTC)。時刻は ISO 8601 標準に準拠し、yyyy-MM-ddTHH:mm:ssZ フォーマットです。 |
EventType | String | イベントタイプ。 |
VideoId | String | ビデオ ID。 |
Status | String | 処理ステータス。有効な値:
|
Extend | String | アップロードまたはジョブ送信 API 操作を呼び出すときに、UserData パラメーターを指定できます。このパラメーターに Extend フィールドが含まれている場合、カスタムユーザーデータが渡され、イベント完了コールバックで返されます。最大長は 512 バイトです。 |
コールバックの検証とリトライ
HTTP コールバック
ApsaraVideo VOD が HTTP コールバックを送信すると、受信サービスが HTTP ステータスコード 200 で応答した場合にコールバックは成功したと見なされます。ステータスコードが 200 でない場合、または応答が 5 秒後にタイムアウトした場合、コールバックは失敗したと見なされます。ApsaraVideo VOD は応答本文を無視し、HTTP ステータスコードのみに依存します。
不正な Webhook アドレスや受信サービスの異常など、構成エラーが原因でコールバックが失敗した場合、ApsaraVideo VOD はコールバックをさらに 2 回、最大 3 回リトライします。3 回の試行が失敗した後、メッセージは破棄されます。
Simple Message Queue (formerly MNS) コールバック
ApsaraVideo VOD が Simple Message Queue (formerly MNS) コールバックを送信すると、メッセージが Simple Message Queue (formerly MNS) キューに書き込まれた場合にコールバックは成功したと見なされます。それ以外の場合、コールバックは失敗したと見なされます。
構成エラーが原因で Simple Message Queue (formerly MNS) キューへのメッセージの書き込みが失敗した場合、ApsaraVideo VOD はさらに 2 回、最大 3 回リトライします。構成エラーの例としては、ApsaraVideo VOD へのアクセス権限を付与していない、インターネット上にないキューアドレスを使用している、または不正なキュー名を使用しているなどが挙げられます。3 回の試行が失敗した後、メッセージは破棄されます。
コールバックが失敗した後、ApsaraVideo VOD は 1 秒の間隔を置いてリトライします。合計 3 回の試行後もコールバックが失敗する場合、メッセージは破棄されます。信頼性の高い通知を保証するには、Simple Message Queue (formerly MNS) コールバックを使用してください。これらはより高い信頼性を提供し、適切に構成されていればほぼ確実に成功します。
コールバック構成
HTTP コールバックと MNS コールバックの構成手順は異なります。ApsaraVideo VOD コンソールまたは API/SDK を使用して両方を構成できます。手順と制限の詳細については、「HTTP コールバックの使用方法」および「MNS コールバックの使用方法」をご参照ください。
イベントタイプ
ApsaraVideo VOD は、次のイベント通知タイプをサポートしています:
イベントタイプ | リファレンス |
FileUploadComplete | |
ImageUploadComplete | |
StreamTranscodeComplete | |
TranscodeComplete | |
SnapshotComplete | |
DynamicImageComplete | |
AddLiveRecordVideoComplete | |
LiveRecordVideoComposeStart | |
UploadByURLComplete | |
UploadByURLComplete | |
CreateAuditComplete | |
VideoAnalysisComplete | |
UpdateMediaStorageClassComplete | |
RestoreMediaComplete | |
AttachedMediaUploadComplete | |
ProduceMediaComplete | |
DeleteMediaComplete | |
MediaBaseChangeComplete | |
SubmitMediaRefreshComplete | |
WorkflowTaskComplete |
よくある質問
コールバックから HTTPS URL を取得する方法や、複数の Webhook アドレスを実装する方法などの問題が発生した場合は、「イベント通知に関する FAQ」をご参照ください。