All Products
Search
Document Center

Instructions for use

Last Updated: Jul 11, 2019

Overview

ApsaraVideo for VOD supports multiple storage regions (such as Mainland China, Singapore, and Frankfurt). You can configure the event notification callback method and URL for each region separately. Users can upload videos to different storage regions. After videos are processed (for example, uploaded or transcoded), ApsaraVideo for VOD notifies users of the processing result in a timely manner based on the callback configurations for the storage regions.

Event types

The following table lists the event types currently supported by ApsaraVideo for VOD.

Event type Description
FileUploadComplete The event indicating that a video is uploaded.
ImageUploadComplete The event indicating that an image is uploaded.
StreamTranscodeComplete The event indicating that a video is transcoded in a single definition.
TranscodeComplete The event indicating that a video is transcoded in all definitions.
SnapshotComplete The event indicating that video snapshots are taken.
AddLiveRecordVideoComplete The event indicating that an on-demand video is recorded for a live stream.
LiveRecordVideoComposeStart The event indicating that ApsaraVideo for VOD starts video production based on on-demand videos.
UploadByURLComplete The event indicating that videos are uploaded based on URLs.
CreateAuditComplete The event indicating that manual review is completed.
AIMediaAuditComplete The event indicating that automated review is completed.
VideoAnalysisComplete The event indicating that audio or video analysis is completed.
AIMediaDNAComplete The event indicating that a media fingerprint job is completed.
ProduceMediaComplete The event indicating that media production is completed.
DeleteMediaComplete The event indicating that a media file is deleted.

Callback methods

Currently, ApsaraVideo for VOD supports HTTP callbacks (compatible with HTTPS) and MNS callbacks for receiving event notifications. You can use these callback methods as follows:

  • HTTP (HTTPS) callbacks: Deploy an HTTP message receiving service and configure the callback URL in the ApsaraVideo for VOD console. When an event is generated, ApsaraVideo for VOD sends an HTTP POST request to this URL, with the specific content sent in the HTTP body.

  • MNS callbacks: Authorize ApsaraVideo for VOD to access MNS. Log on to the MNS console and create a queue or select an existing queue. Then, submit a ticket to specify the region for which the callback service is configured, callback events, queue name, and Internet endpoint. When an event is generated, ApsaraVideo for VOD pushes the callback message to the queue. For more information about how to receive messages, see the MNS product documentation.

Comparison of the two methods

  • Reliability: Compared with HTTP, MNS is more reliable. Almost all MNS callback events can be delivered when the configuration is correct. However, the successful delivery of HTTP callback events depends on the HTTP message receiving service. If the service is abnormal (for example, breaks down or restarts), messages may be lost.

  • Security: In MNS, only authorized users can read and write the message queue. Therefore, MNS is more secure. In HTTP, all users can send requests to the callback URL. To enhance security of HTTP callbacks, you can configure callback authentication to reject invalid requests.

  • Convenience: HTTP is more convenient. To use HTTP callbacks, you only need to deploy a message receiving service. To use MNS callbacks, you need to activate and configure MNS and develop and deploy the application that consumes messages. For more information, see Reliable MNS event notifications.

Select the appropriate callback method based on your scenario.

Callback configuration

Log on to the ApsaraVideo for VOD console and choose Global Settings > Callback. Configure the callback URL, queue, and events.

Callback configuration

Callback protocols

HTTP callback

  • Request: The HTTP POST request is used, with the body in JSON format. For more information about the specific body content for each event, see the event description.
  • Response: ApsaraVideo for VOD ignores the body content of responses.

MNS callback

  • The content of the received message is in JSON format. For more information about the specific body content for each event, see the event description.

Common parameters of callback content

Parameter Type Description
EventTime String The time when the event occurs. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time is displayed in UTC.
EventType String The type of the event.
VideoId String The video ID.
Status String The processing result. Valid values: success and fail.

Callback judgment and retry

HTTP callback

  • After sending an HTTP callback request, ApsaraVideo for VOD checks the HTTP status code in the response returned by the HTTP message receiving service. If the HTTP status code is 200, ApsaraVideo for VOD considers that the callback is successful. If the HTTP status code is not 200 or the callback times out when no response is received within 5 seconds, ApsaraVideo for VOD considers that the callback fails. ApsaraVideo for VOD checks only the HTTP status code in responses, and ignores the body content of responses.
  • If the configuration is incorrect, for example, the callback URL is incorrect or the HTTP message receiving service is abnormal, the callback request fails to be sent. ApsaraVideo for VOD retries to send the callback request twice. That is, ApsaraVideo for VOD attempts to send a callback request for a total of three times. If the callback request still fails to be sent, ApsaraVideo for VOD discards the request.

MNS callback

  • ApsaraVideo for VOD considers that an MNS callback is successful when the message is pushed to the MNS queue.
  • If ApsaraVideo for VOD is unauthorized to access MNS, the MNS endpoint is not an Internet endpoint, or the queue name is incorrect, the message fails to be pushed to the queue. In this case, ApsaraVideo for VOD retries the push twice. That is, ApsaraVideo for VOD attempts to push a message to the queue for a total of three times. If the message still fails to be pushed, ApsaraVideo for VOD discards the message.

Note: ApsaraVideo for VOD retries at an interval of 1 second upon a callback failure. After three consecutive failures, ApsaraVideo for VOD stops retrying and discards the callback request or message. We recommend that you use MNS callbacks that are more reliable. Almost all MNS callbacks can be successful when the configuration is correct.

FAQ

For more information, see Event notification FAQ.