ApsaraVideo VOD:Simple Message Queue (formerly MNS) callbacks

Simple Message Queue (formerly MNS) callback mechanism

1. Create a queue in Simple Message Queue (formerly MNS) and configure the corresponding callback in ApsaraVideo VOD.

2. When an event occurs, ApsaraVideo VOD writes the event notification to the Simple Message Queue (formerly MNS) queue.

3. A callback is considered successful if ApsaraVideo VOD successfully writes the message to the Simple Message Queue (formerly MNS) queue. Otherwise, the callback fails. If ApsaraVideo VOD fails to write a message because of configuration errors, such as ApsaraVideo VOD not being authorized to access Simple Message Queue (formerly MNS), the endpoint not being a public endpoint, or an incorrect queue name, ApsaraVideo VOD retries the callback two more times. A callback is attempted a maximum of three times. If all three attempts fail, the message is discarded. For more information about callback validation and retries, see Callback validation and retries.

4. After a successful callback, you can retrieve messages from the Simple Message Queue (formerly MNS) queue to view the event notification content. You can delete a message only after it has been received and consumed. After consumption, the message remains invisible for a period. You must delete it during this time. Otherwise, it becomes visible again and will be consumed again.

How to use

Prerequisites

• An Alibaba Cloud account is created and real-name verification is complete. To create an Alibaba Cloud account, visit the Alibaba Cloud official website. For more information, see Create an Alibaba Cloud account.

• ApsaraVideo VOD is activated. For more information, see Activate ApsaraVideo VOD.

• You have activated Simple Message Queue (formerly MNS). For instructions, see Activate Simple Message Queue (formerly MNS) and grant permissions.

Usage notes

• ApsaraVideo VOD supports multiple service regions. Event notification configurations are specific to each region. You can configure a separate callback method and webhook address for each region.

• In Simple Message Queue (formerly MNS), you can create multiple Simple Message Queue (formerly MNS) queues across different service regions. However, in ApsaraVideo VOD, you can configure only one Simple Message Queue (formerly MNS) queue for MNS callbacks per service region. We recommend that you create and use queues in the following regions:

  • If your videos are stored in the Chinese mainland, such as China (North 2) or China (Shanghai), use a queue in the China (Shanghai) region. Pushing messages to a queue in any region other than China (Shanghai) may cause a short delay.

  • If your videos are stored in other regions, such as Singapore or Japan, create or use a message queue in the corresponding region.

    For example, if your video storage region is Singapore, create or use a message queue in the Singapore region.

• MNS callbacks support multiple webhook addresses to support different development environments. For more information, see Configure multiple webhook addresses.

Procedure

1. Grant ApsaraVideo VOD permission to access Simple Message Queue (formerly MNS).

   You can use one of the following methods to grant permissions:

   • Method 1: Grant ApsaraVideo VOD permission to access your cloud resources, including OSS, Simple Message Queue (formerly MNS), CDN, and KMS.

     Log on to the Alibaba Cloud Management Console. Go to the resource access authorization page and click Confirm Authorization.

   • Method 2: Grant a RAM user, user group, or role permission to access Simple Message Queue (formerly MNS) for the ApsaraVideo VOD service.

     Add the AliyunMNSFullAccess system policy (full access to Simple Message Queue (formerly MNS)) or the AliyunMNSReadOnlyAccess system policy (read-only access to Simple Message Queue (formerly MNS)) to the authorization policy. For more information, see Create a RAM user and grant permissions.

2. Create a queue in Simple Message Queue (formerly MNS).

   You can create a queue in Simple Message Queue (formerly MNS) or use an existing one. You can create a queue in the console or using an API or SDK. To create a queue in the console, see Create a queue. For more information about the API and SDK, see Queue operations.

   Note

   Follow the region recommendations in Usage notes when you create or use a queue.

3. Configure event notifications for Simple Message Queue (formerly MNS) callbacks in ApsaraVideo VOD.

   Note

   Callbacks that are configured in the ApsaraVideo VOD console apply globally to the ApsaraVideo VOD service. Using OpenAPI, you can configure global callbacks or override the callback for a single request.

   Configure Simple Message Queue (formerly MNS) callbacks in the console

   1. Log on to the ApsaraVideo VOD console.

   2. In the left-side navigation pane, choose Configuration Management > Media Processing > Callback.

   3. In the top navigation bar, click the service region next to Workbench and switch to the target service region.

   4. Configure Callback.

      1. To the right of Callback, click Modify.

      2. Configure the callback parameters.

         Parameter name	Description
         Callback Method	Select Simple Message Queue (formerly MNS).
         Region	Select the region where the videos for which you want to configure event notifications are stored. We recommend using the same region as the Simple Message Queue (formerly MNS) queue.
         Queue	Select a queue in the region. Note If no queues are available, create one first. For more information, see Create a queue.
         Callback Event	Select the event types for which you want to receive notifications as needed. For more information about the event types supported by ApsaraVideo VOD and the meaning of each event notification, see Event list. Note If you select Video AI Processing Complete, notifications are triggered after any AI event is complete, including AIMediaAuditComplete, AIMediaDNAComplete, and AIVideoTagComplete.

      3. Click OK to complete the callback configuration for Simple Message Queue (formerly MNS).

   Configure Simple Message Queue (formerly MNS) callbacks using OpenAPI

   You can call different API operations to configure global callbacks or override the callback for a single request.

   • Global configuration: Call the Set event notification configuration operation. Set the CallbackType request parameter to Simple Message Queue (formerly MNS). Configure other parameters, such as EventTypeList (callback event type), MnsEndpoint (public endpoint of the message queue), and MnsQueueName (message queue name).

   • Single-request override: When you call an API operation to upload a media asset or submit a media processing job, you can specify the MessageCallback field in the UserData request parameter to set the callback queue for that specific request. This applies to the following API operations:

     • Obtain an upload URL and credentials for audio and video

     • Obtain an image upload URL and credentials

     • Obtain an upload URL and credentials for an auxiliary media asset

     • Upload media assets by URL in batches

     • Register media asset information

     • Submit a media transcoding job

     • Submit a media snapshot job

     • Submit an automated review job for audio and video

     • Video compositing

   Note

   To set a callback by specifying the MessageCallback field in the UserData parameter, you must first enable global event notifications for ApsaraVideo VOD and configure the corresponding callback event types. Otherwise, the callback configuration for the single request does not take effect.

4. Trigger a callback event.

   After you configure event notifications, you can perform operations in ApsaraVideo VOD, such as uploading media assets (audio, video, or images) or initiating media processing (such as transcoding and snapshots), to trigger the corresponding callback events.

5. View messages in Simple Message Queue (formerly MNS).

   When a callback event is triggered, the ApsaraVideo VOD server-side writes the callback content to the specified queue. You can retrieve messages from Simple Message Queue (formerly MNS) to view the event notification content in the message details.

   You can retrieve messages using the console or an API or SDK. To retrieve messages from the console, see Receive messages. For more information about the API and SDK, see Queue API overview.

6. Optional: Delete messages in Simple Message Queue (formerly MNS).

   A queue supports concurrent access from multiple producers and consumers. After a message is retrieved, it becomes invisible to other consumers for a specific period. You must explicitly delete the message after it is consumed. Otherwise, it becomes visible again after the invisibility period and can be consumed again.

   You can receive messages using the console, an API, or an SDK. For console instructions, see Queue operations. For API and SDK information, see Queue API overview.

SDK examples

Simple Message Queue (formerly MNS) provides SDKs for multiple programming languages. After you configure callbacks, you can use the following SDKs to consume messages:

• For information about how to consume messages using Java code, see Queue Usage Manual.

• For more information about how to consume messages with Python, see Queue User Guide.

• To learn how to consume messages using C# code, see the Queue User Guide.

• For instructions on consuming messages using PHP code, see the Queue User Guide.

• For other languages, you can call API operations to retrieve message content. First, familiarize yourself with the invocation methods. Then, call the ReceiveMessage operation to retrieve the message content and the DeleteMessage operation to delete the message.

References

• For a comparison between HTTP callbacks and MNS callbacks, see Comparison of HTTP and Simple Message Queue (formerly MNS) callbacks.

• If you encounter problems, see FAQ about event notifications.