ApsaraVideo VOD supports HTTP callbacks (HTTPS compatible) and Simple Message Queue (formerly MNS) callbacks. This topic describes the event types, callback methods, callback configurations, callback protocols, and common callback parameters for event notifications. This topic also describes the retry rules upon callback failures, FAQ, and how to determine successful callbacks.
Introduction
ApsaraVideo VOD supports event notifications for multiple regions. You can specify callback methods and callback URLs for event notifications for each region. You can upload and store videos in different regions. After the videos are processed, ApsaraVideo VOD notifies you of the processing results based on the callback method and callback URL that you specified for the region.
Only HTTP URLs are returned in the callback body. HTTPS URLs are not supported. If you want HTTPS URLs to be returned, see the solution described in the FAQ about event notifications topic.
Callback methods
HTTP callbacks (HTTPS compatible):
HTTP callbacks are automatically returned for you to obtain event notifications in ApsaraVideo VOD. You must deploy an HTTP service to receive callback messages and specify a callback URL in the ApsaraVideo VOD console. When an event occurs, ApsaraVideo VOD sends an HTTP POST request to the specified callback URL. Then, the notification content is returned in the HTTP response body.
Simple Message Queue (formerly MNS) callbacks:
If you use SMQ callbacks, you must receive event notifications in Simple Message Queue (formerly MNS). You must authorize ApsaraVideo VOD to access SMQ, create a queue or use an existing queue in the SMQ console, and then configure event notifications in ApsaraVideo VOD. When an event occurs, ApsaraVideo VOD pushes the callback message to the queue. You must obtain the callback message from SMQ. For more information about how to create a queue and receive callback messages in the SMQ console, see Manage queues in the console.
Comparison between HTTP callbacks and SMQ callbacks
Item | HTTP callback | SMQ callback (recommended) |
Reliability | If the HTTP message receiving service is abnormal, messages may be lost. For example, messages may be lost if the service is interrupted or restarts. | SMQ callbacks are more reliable than HTTP callbacks. Almost all SMQ callbacks succeed if they are configured properly. |
Security | If you use HTTP callbacks, all users can send callback requests to the specified callback URLs. However, you can use callback authentication to reject invalid requests. This can enhance the security of HTTP callbacks. For more information, see HTTP callback authentication. | SMQ callbacks are more secure because only authorized users can read and write message queues. |
Convenience | HTTP callbacks are more convenient than SMQ callbacks because you need only to deploy a message receiving service to use HTTP callbacks. | To use SMQ callbacks, you must activate and configure Simple Message Queue (formerly MNS), and develop and deploy an application to consume messages. |
Callback protocols
HTTP callbacks
Request: HTTP POST requests are sent and the message body is in the JSON format. For more information about the message body for each event, see the Event types section of this topic.
Response: ApsaraVideo VOD ignores the response body.
Simple Message Queue (formerly MNS) callbacks
Callback messages are in the JSON format. For more information about the message body for each event, see the Event types section of this topic.
Common callback parameters
Parameter | Type | Description |
EventTime | String | The time when the event was generated. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format and is displayed in UTC. |
EventType | String | The event type. |
VideoId | String | The ID of the audio or video file. |
Status | String | The result of the event. Valid values:
|
Extend | String | If the UserData parameter is specified in the upload or submit operations and the Extend field is included, user data is returned in pass-through mode when the callback is returned. The value of this field can be up to 512 bytes in length. |
Callback determination and retries
HTTP callbacks
After an HTTP callback request is sent, ApsaraVideo VOD checks the HTTP status code in the response returned by the HTTP message receiving service. If the HTTP status code 200 is returned, the callback is successful. If an HTTP status code other than 200 is returned or no response is returned within 5 seconds, the callback fails. ApsaraVideo VOD checks only the HTTP status code in responses and ignores the response body.
If the callback request fails to be sent due to incorrect configurations, such as incorrect callback URLs or an abnormal HTTP message receiving service, ApsaraVideo VOD retries to send the callback request two more times. If the callback request fails to be sent after three attempts, ApsaraVideo VOD discards the request.
Simple Message Queue (formerly MNS) callbacks
If you use Simple Message Queue (formerly MNS) callbacks, ApsaraVideo VOD determines that an SMQ callback is successful when the message is pushed to the Simple Message Queue (formerly MNS) queue.
If the message fails to be pushed to the queue due to incorrect configurations, ApsaraVideo VOD retries to push the message two more times. For example, the callback message fails to be sent if ApsaraVideo VOD is not authorized to access SMQ, the Simple Message Queue (formerly MNS) endpoint is not a public endpoint, or the queue name is incorrect. If the message fails to be pushed after three attempts, ApsaraVideo VOD discards the message.
When a callback fails, ApsaraVideo VOD retries the callback at an interval of 1 second. If the callback fails after three attempts, ApsaraVideo VOD discards the request. We recommend that you use Simple Message Queue (formerly MNS) callbacks because they are more reliable than HTTP callbacks. Almost all SMQ callbacks succeed if they are configured properly.
Callback configurations
HTTP callbacks and SMQ callbacks are configured differently. You can use the ApsaraVideo VOD console, API, or SDK to configure HTTP callbacks and SMQ callbacks. For more information, see How to use HTTP callbacks and Usage notes.
Event types
The following table describes the event types for which event notifications are provided in ApsaraVideo VOD.
Event type | References |
FileUploadComplete | |
ImageUploadComplete | |
StreamTranscodeComplete | |
TranscodeComplete | |
SnapshotComplete | |
DynamicImageComplete | |
AddLiveRecordVideoComplete | |
LiveRecordVideoComposeStart | |
UploadByURLComplete | |
UploadByURLComplete | |
CreateAuditComplete | |
AIMediaAuditComplete Note You must select the AI Processing Completed event in the ApsaraVideo VOD console to receive the AIMediaDNAComplete event notification. | |
VideoAnalysisComplete | |
UpdateMediaStorageClassComplete | |
RestoreMediaComplete | |
AIMediaDNAComplete Note You must select the AI Processing Completed event in the ApsaraVideo VOD console to receive the AIMediaDNAComplete event notification. | |
AttachedMediaUploadComplete | |
ProduceMediaComplete | |
DeleteMediaComplete | |
MediaBaseChangeComplete | |
SubmitMediaRefreshComplete |
FAQ
For more information about commonly asked questions, such as how to obtain HTTPS URLs from callback messages and how to specify multiple callback URLs, see FAQ about event notifications.