Instructions for use

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.

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 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

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.