ApsaraVideo VOD:SMQ callbacks

SMQ callback mechanism

1. You must create a queue in Simple Message Queue (formerly MNS) and configure callbacks in ApsaraVideo VOD.

2. When an event occurs, ApsaraVideo VOD pushes the callback message to the queue in Simple Message Queue (formerly MNS).

3. If the message is pushed to the Simple Message Queue (formerly 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 Simple Message Queue (formerly MNS), the SMQ 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 successful callbacks, see Callback determination and retries.

4. After the callback succeeds, you must obtain the callback message from SMQ. 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.

• Simple Message Queue (formerly MNS) is activated. For more information, see Activate SMQ and authorize RAM users to access SMQ.

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 Simple Message Queue (formerly MNS) queues in different regions. However, you can specify only one Simple Message Queue (formerly MNS) queue for Simple Message Queue (formerly MNS) callbacks in each region in ApsaraVideo VOD. We recommend that you specify SMQ queues based on the following rules:

  • If you store videos in the Chinese mainland, we recommend that you push callback messages to an SMQ 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 SMQ 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 SMQ queue in the Singapore region.

• You can specify multiple SMQ 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 Simple Message Queue (formerly MNS).

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

   • Method 1: Authorize ApsaraVideo VOD to access cloud resources in Object Storage Service (OSS), Simple Message Queue (formerly 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 Simple Message Queue (formerly 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 Simple Message Queue (formerly MNS) queue.

   Create an Simple Message Queue (formerly MNS) or use an existing queue. You can create a queue by using the SMQ console, API, or SDK. For information about how to create a queue by using the SMQ console, see Create a queue. For information about how to create a queue by using the SMQ 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 Simple Message Queue (formerly 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 Simple Message Queue (formerly MNS).
         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 Simple Message Queue (formerly MNS) queue is created.
         Queue	Select the queue in the region. Note If no queue exists, create an SMQ 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 Simple Message Queue (formerly 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 Simple Message Queue (formerly 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 SMQ and view the notification content.

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

6. Optional. Delete the callback message in Simple Message Queue (formerly MNS).

   SMQ 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 SMQ console, API, or SDK. For information about how to delete callback messages by using the SMQ console, see Delete a message. For information about how to delete callback messages by using the SMQ API or SDK, see Message-related operations.

SDKs

Simple Message Queue (formerly 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 SMQ SDK for Java, see Manage queues.

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

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

• For information about how to consume messages by using SMQ 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 SMQ callbacks, see Comparison between HTTP callbacks and SMQ callbacks.

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