Asynchronous processing requests return only a task ID. To obtain the result of a task after data processing is complete, you must add message notification parameters to the processing request.
Usage notes
Message notification is supported only for asynchronous processing.
Message notification supports only topics for Simple Message Queue (SMQ). SMQ was formerly known as MNS. For more information about SMQ, see SMQ Quick Start.
Parameter description
When you use the notify parameter, include the following option:
Parameter | Required | Description |
topic | Yes | The name of the SMQ topic.
To learn how to obtain the SMQ topic name, see How do I view the name of my SMQ topic in the console? |
Use REST APIs
If your program requires a high level of customization, you can directly initiate REST API requests. To do this, you must manually write code to calculate signatures.
When you call the PostObject operation to process an object, pass the x-oss-async-process parameter in the request body. Then, add the notify parameter to the request to receive message notifications about the results. Message notification supports only SMQ topics. For more information about using SMQ, see Python SDK version guide.
The following sections provide examples of receiving SMQ message notifications in different scenarios.
Use processing parameters to convert a document and receive SMQ message notifications
Conversion information
Before conversion
File type: DOCX
File name:
example.docx
After conversion
File type: PNG
Storage path:
oss://test-bucket/doc_images/
Message notification
The conversion result notification is sent to the SMQ topic named
test-topic.
Processing example
POST /exmaple.docx?x-oss-async-process HTTP/1.1
Host: doc-demo.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 28 Oct 2022 06:40:10 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
// Convert the DOCX file example.docx to a PNG image, store the converted image in the oss://test-bucket/doc_images/ path, and send the conversion result notification to the SMQ topic named test-topic.
x-oss-async-process=doc/convert,target_png,source_docx|sys/saveas,b_dGVzdC1idWNrZXQ,o_ZG9jX2ltYWdlcy97aW5kZXh9LnBuZw/notify,topic_dGVzdC10b3BpYwUse style parameters to transcode a video and save it to a specified bucket
Transcoding information
Before transcoding
Video format: AVI
Video name:
example.avi
After transcoding
Video format: MP4
Video name:
outobjprefix.mp4Storage path:
oss://outbucket/outobjprefix.mp4
Message notification
The transcoding result notification is sent to the SMQ topic named
test-topic.
POST /exmaple.avi?x-oss-async-process HTTP/1.1
Host: video-demo.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 28 Oct 2022 06:40:10 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
// Use the style named examplestyle to transcode the file example.avi, save the transcoded file as oss://outbucket/outobjprefix.mp4, and send the transcoding result notification to the SMQ topic named test-topic.
x-oss-async-process=style/examplestyle|sys/saveas,b_b3V0YnVja2V0,o_b3V0b2JqcHJlZml4LnthdXRvZXh0fQ/notify,topic_dGVzdC10b3BpYwMessage formats for x-oss-process operations
Feature module | x-oss-process operation | Message format |
Document processing | Sample MNS message for the CreateOfficeConversionTask operation | |
ApsaraVideo Media Processing | ||
File processing | Sample MNS message for the CreateCompressPointCloudTask operation | |
Image processing | Sample MNS message for the CreateDecodeBlindWatermarkTask operation |
FAQ
How do I view the name of my SMQ topic in the console?
To configure a Simple Message Queue (SMQ) topic for OSS event notifications, you must use a topic that is in the same region as your OSS bucket. Follow these steps to find the name of an SMQ topic. SMQ was formerly known as MNS.
Log on to the Simple Message Queue (SMQ), formerly MNS, console.
In the top navigation bar of the console, make sure that you select the same region as your OSS bucket.
In the navigation pane on the left, click Topic-based Model > Topic List to view all created topics in the current region.
Browse the topic list to find the name of the topic that you want to use for your OSS event notification configuration.
By following these steps, you can find the name of the SMQ topic in the same region as your OSS bucket. Using the correct topic name ensures that OSS events are sent to the message queue for processing.