ApsaraVideo VOD:MNS callbacks

MNS callback mechanism

1. You must create a queue in MNS and configure callbacks in ApsaraVideo VOD.

2. When an event occurs, ApsaraVideo VOD pushes the callback message to the queue in MNS.

3. If the message is pushed to the MNS queue, the callback is successful. Otherwise, the callback fails. If the callback message fails to be pushed to the queue due to incorrect configurations, ApsaraVideo VOD retries to push the message two times. For example, the callback message fails to be pushed if ApsaraVideo VOD is not authorized to access MNS, the MNS endpoint is not a public endpoint, or the queue name is incorrect. If the callback message fails to be pushed after three attempts, ApsaraVideo VOD discards the message. For more information about the retry logic and how to determine a successful callback, see Callback determination and retries.

4. After the callback succeeds, you must obtain the callback message from MNS. You can delete a message only after it is received and consumed. A message is invisible for a period of time after it is consumed. If you do not manually delete the message, it can be consumed again.

Usage notes

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.

• MNS is activated. For more information, see Activate MNS and authorize RAM users to access MNS.

Usage notes

• ApsaraVideo VOD supports multiple service regions. The event notification configurations among regions are independent of each other. You can use different callback methods and callback URLs for different regions.

• You can create multiple MNS queues in different regions. However, you can specify only one MNS queue for MNS callbacks in each region in ApsaraVideo VOD. We recommend that you specify MNS queues based on the following rules:

  • If you store videos in the Chinese mainland, we recommend that you push callback messages to an MNS queue in the China (Shanghai) region. If you push callback messages to a queue in a region other than China (Shanghai), you may experience a short delay.

  • If you store videos outside the Chinese mainland, such as the Singapore or Japan (Tokyo) region, we recommend that you push callback messages to an MNS queue in the region where your videos are stored.

    For example, if you store videos in the Singapore region, we recommend that you create or use an MNS queue in the Singapore region.

• You can specify multiple MNS callback URLs to meet your development requirements in different environments. For more information, see Specify multiple callback URLs.

Procedure

1. Authorize ApsaraVideo VOD to access MNS.

   You can use one of the following methods to authorize ApsaraVideo VOD to access MNS:

   • Method 1: Authorize ApsaraVideo VOD to access cloud resources in Object Storage Service (OSS), MNS, Alibaba Cloud CDN, and Key Management Service (KMS).

     Log on to the Alibaba Cloud Management Console. On the Cloud Resource Access Authorization page, click Confirm Authorization Policy.

   • Method 2: Grant permissions to users, user groups, or roles of ApsaraVideo VOD to access MNS.

     Attach the AliyunMNSFullAccess or AliyunMNSReadOnlyAccess policy to users, users groups, or roles of ApsaraVideo VOD. For more information, see Create and grant permissions to a RAM user.

2. Create an MNS queue.

   Create an MNS queue or use an existing queue. You can create a queue by using the MNS console, API, or SDK. For information about how to create a queue by using the MNS console, see Create a queue. For information about how to create a queue by using the MNS API or SDK, see Queue-related operations.

   Note

   We recommend that you follow the rules described in Usage notes to create or use queues.

3. Configure MNS callbacks to receive event notifications.

   Note

   If you configure event callbacks by using the ApsaraVideo VOD console, the settings take effect globally. You can also call different API operations to configure global callback settings or configure a specific callback in ApsaraVideo VOD.

   By using the ApsaraVideo VOD 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, select the desired region from the drop-down list next to the Workbench button.

   4. In the left-side navigation pane, choose Configuration Management > Media Processing > Callback. On the Callback page, configure the callback settings.

      1. Click Modify in the Callback section.

      2. Configure callback parameters. The following table describes the parameters.

         Parameter	Description
         Callback Method	Select MNS Queue.
         Region	Select the region where the video for which you want to configure event notifications is stored. We recommend that you select the region where the MNS queue is created.
         Queue	Select the queue in the region. Note If no queue exists, create an MNS queue. For more information, see Create a queue.
         Events	Select the events for which you want to configure callbacks based on your business requirements. For more information about the events supported in ApsaraVideo VOD and event notification content, see Events. Note If you select AI Processing Completed, notifications are sent for all AI events such as AIMediaAuditComplete, AIMediaDNAComplete, and AIVideoTagComplete.

      3. Click OK.

   By using the ApsaraVideo VOD API or SDK

   You can call different API operations to configure global callback settings or configure a specific callback in ApsaraVideo VOD.

   • Configure global callback settings: Call the SetMessageCallback operation. Set CallbackType to MNS and specify other request parameters such as EventTypeList, MnsEndpoint, and MnsQueueName.

   • Configure a specific callback: Specify the MessageCallback field in UserData when you call the following API operations to upload media files or submit media processing jobs:

     • CreateUploadVideo

     • CreateUploadImage

     • CreateUploadAttachedMedia

     • UploadMediaByURL

     • RegisterMedia

     • SubmitTranscodeJobs

     • SubmitSnapshotJob

     • SubmitAIMediaAuditJob

     • ProduceEditingProjectVideo

   Note

   You can specify the MessageCallback field in UserData to configure callbacks. You must enable global event notifications and configure related events for the HTTP callback settings to take effect.

4. Trigger the event.

   After you configure event notifications, you can perform operations, such as uploading audio, video, or image files, to trigger the event. You can also submit media processing jobs, such as transcoding jobs and snapshot jobs, to trigger the event.

5. View the callback message in MNS.

   When a callback is triggered, ApsaraVideo VOD pushes the callback message to the MNS queue that you specified. You must receive the message in MNS and view the notification content.

   You can receive callback messages by using the MNS console, API, or SDK. For information about how to receive callback messages by using the MNS console, see Receive a message. For information about how to receive callback messages by using the MNS API or SDK, see Message-related operations.

6. Optional. Delete the callback message in MNS.

   MNS queues support a large number of concurrent requests from multiple producers and consumers. After a message is pulled from a queue, the message cannot be pulled again within a specified period of time. A message is invisible for a period of time after it is consumed. If you do not manually delete the message, it can be consumed again.

   You can delete callback messages by using the MNS console, API, or SDK. For information about how to delete callback messages by using the MNS console, see Delete a message. For information about how to delete callback messages by using the MNS API or SDK, see Message-related operations.

SDKs

MNS provides SDKs for multiple languages. After you configure callbacks, you can use code to consume callback messages. The following items provide references on how to consume callback messages:

• For information about how to consume messages by using MNS SDK for Java, see Manage queues.

• For information about how to consume messages by using MNS SDK for Python, see Manage queues.

• For information about how to consume messages by using MNS SDK for C#, see Manage queues.

• For information about how to consume messages by using MNS SDK for PHP, see Manage queues.

• For the programming language that is not mentioned, you can call the ReceiveMessage operation to receive messages and the DeleteMessage operation to delete messages. For more information, see Call MNS APIs.

References

• For more information about the comparison between HTTP callbacks and MNS callbacks, see Comparison between HTTP callbacks and MNS callbacks.

• If issues occur when you configure callbacks, see FAQ about event notifications.