When an asynchronous processing request returns, it only provides a task ID. To receive the results of a data processing task upon completion, you need to add notification parameters to the processing request.
Notes
Only asynchronous processing supports notifications.
Notifications only support Simple Message Queue (SMQ, formerly MNS) topics. For more information about SMQ, see SMQ quick start.
Parameter description
When using the notify parameter, you need to include the following options:
Parameter | Required | Description |
topic | Yes | SMQ topic name.
For information about how to obtain the SMQ topic name, see How to view your SMQ topic name in the console? |
Using REST API
If your business requires a high level of customization, you can directly call REST API operations. To directly call an API operation, you must include the signature calculation in your code.
When you call the PostObject operation to process services, you can pass x-oss-async-process in the body. Then, add the notify parameter to the processing request to receive processing result notifications. Notifications only support SMQ topics. For more information about how to use SMQ, see Python SDK version guide.
The following examples show how to receive SMQ notifications in various scenarios.
Use processing parameters to convert documents and receive SMQ notifications
Conversion information
Source object
Object format: DOCX
File name:
example.docx
Destination object
Object format: PNG
File storage path:
oss://test-bucket/doc_images/
Notification
Send conversion result notifications 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 PNG format images, store the converted images 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 videos and save to a specified bucket
Transcoding information
Source object
Video format: AVI
Video name:
example.avi
Destination object
Video format: MP4
Video name:
outobjprefix.mp4Video storage path:
oss://outbucket/outobjprefix.mp4
Notification
Send transcoding result notifications 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 conversion 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 | ||
Media processing | ||
File processing |
FAQ
How to view your SMQ topic name in the console?
To help you configure Simple Message Queue (SMQ, formerly MNS) topics related to OSS event notifications, you can follow these steps to find and confirm SMQ topic names in the same region as your OSS.
Log on to the Simple Message Queue (SMQ, formerly MNS) console.
In the top menu bar of the console, make sure you select the same region as your OSS bucket.
In the left navigation bar, click Topic Model > Topic List to display all topics created in the current region.
Browse the topic list to find the topic name that matches your OSS event notification configuration.
By following these steps, you can effectively locate and configure SMQ topic names in the same region as your OSS, ensuring that OSS events are correctly sent to the message queue for processing.