Object Storage Service:Variables

Scenarios

Usage scenarios in the OSS console

• Tasks: The data processing task can use information about the source object in the output path. For example, if you want to convert a document to jpg images, you can set the output path to oss://test-bucket/output/{dirname}/{barename}/{index}.{autoext}, in which {autoext} is replaced by jpg during the document conversion task. The processed objects are saved to oss://test-bucket/output/source object directory/source object name/image serial number.jpg.

• Batch processing: After a batch processing job is created, a data processing task is generated. To prevent overwriting, we recommend that you specify variables in the output path of the processed objects. For example, if you want to capture png frames from multiple videos at a time, set the output paths of the png frames to oss://test-bucket/output/{dirname}/{barename}/{index}.{autoext}, in which {autoext} is replaced by png. The png frames are saved to oss://test-bucket/output/source video directory/source video name/frame sequence number.png.

• Trigger: After you create a trigger, a task is created for each new object. To prevent overwriting, we recommend that you specify variables in the output paths of the processed objects when you create the trigger. For example, if you create a trigger to convert documents to jpg images, set the output paths of the jpg images to oss://test-bucket/output/{dirname}/{barename}/{index}.{autoext}, in which {autoext} is replaced by jpg during the document conversion task. The jpg images are saved to oss://test-bucket/output/source object directory/source object name/image sequence number.jpg.

API usage scenarios

• sys/saveas parameter: The b and o options in the sys/saveas parameter support variables. For example, if you want to convert page 1 to page 10 of a document named example.docx to png images, set the sys/saveas parameter to b_e2J1Y2tldH0,o_ZG9jX2ltYWdlcy97aW5kZXh9LnBuZw, in which e2J1Y2tldH0 is the Base64-encoded value of {bucket} and ZG9jX2ltYWdlcy97aW5kZXh9LnBuZw is the Base64-encoded value of doc_images/{index}.png. In this case, the png images are stored in the same bucket as the source object and the output paths of the png images are doc_images/index.png.

• Tasks: The output paths of the processed objects for data processing tasks can contain variables. For example, when you call the CreateOfficeConversionTask operation to create a document conversion task, you must set the TargetURI parameter to the full output path of the processed object that contains the file extension. Variables can be used in the TargetURI parameter. Example: oss://test-bucket/output/{dirname}/{barename}/{index}.jpg.

Usage notes

• If the output paths of the processed objects for a batch processing job or a trigger task do not end with a forward slash (/), you must include at least one variable in the names of the processed objects. Otherwise, multiple processed objects may overwrite each other.

• The output paths of the processed objects for a data processing task cannot end with a forward slash (/), but can end with a variable.

Variables related to data processing tasks

The point in time when a request is synchronously or asynchronously processed can be used as variables. For example, you can use the variables in the following table in the request that was submitted on 2022-09-01T02:06:57.798Z.

Variables related to IMG

In this example, a data processing task is run on a source object named oss://test-bucket/path1/path2/name.png, which was uploaded on 2022-04-22 14:38:25. The output path of the processed object for the data processing task can contain the variables in the following table.

Variables related to document conversion

You can use the page number and the sheet name as variables in a document conversion task. For example, to convert an Excel object that contains one sheet named sheet1 to a JPG image, you can use the variables in the following table in the output path of the JPG image.

Variables related to media processing

Items such as the container extension and resolution, can be used as variables for media processing. For example, to perform multipart transcoding on a video named video.mp4 to obtain a processed ts video whose resolution is 1920 x 1080, you can use the variables in the following table in the output path of the processed video.

Example 1: Document conversion

In the following example, processing parameters are specified in a PostObject request to convert the format of the example.docx object. The b and o options of the sys/saveas parameter are used as variables in the output paths of the processed objects.

• pages_MS0xMA: converts page 1 to page 10 of the example.docx object. MS0xMA is the Base64-encoding value of 1 to 10.

• target_png: converts the format of the example.docx object to png.

• source_docx: specifies that the type of the source object is docx.

• sys/saveas: saves the processed objects to a specific bucket.

  • b_e2J1Y2tldH0: After the document conversion task is complete, the processed objects are saved to the source bucket by specifying the {bucket} variable. e2J1Y2tldH0 is the Base64-encoded value of {bucket}.

  • o_ZG9jX2ltYWdlcy97aW5kZXh9LnBuZw: Store the output object in the doc_images directory with the corresponding page number as the name specified by the index variable (ZG9jX2ltYWdlcy97aW5kZXh9LnBuZw is the Base64-encoded value of doc_images/{index}.png).

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: OSS qn6q**************:77Dv****************
 
 // Convert page 1 to page 10 of the example.docx object to png objects and store the png objects in oss://source bucket/doc_images/page number.png. 
x-oss-async-process=doc/convert,pages_MS0xMA,target_png,source_docx|sys/saveas,b_e2J1Y2tldH0,o_ZG9jX2ltYWdlcy97aW5kZXh9LnBuZw

Example 2: Video transcoding

In the following example, multiple processing parameters are configured to transcode the example.avi object.

• f_mp4: sets the transcoded output file format to MP4.

• vcodec_h265: sets the format of the video streams to H.265.

• s_1920x1080: sets the resolution to 1920 x 1080.

• vb_2000000: sets the video bitrate to 2 Mbit/s.

• fps_30: sets the video frame rate to 30 fps.

• acodec_aac: sets the audio encoding format to AAC.

• ab_100000: sets the audio bitrate to 100 Kbit/s.

• sn_1: disables the subtitle stream.

• sys/saveas: saves the processed objects to a specific bucket.

  • b_e2J1Y2tldH0: After the video transcoding task is complete, the processed objects are saved to the source bucket by specifying the {bucket} variable. e2J1Y2tldH0 is the Base64-encoded value of {bucket}.

  • o_b3V0cHV0LnthdXRvZXh0fQ: The {autoext} variable is specified to automatically add the extension to the processed object named output.mp4. b3V0cHV0LnthdXRvZXh0fQ is the Base64-encoded value of output.{autoext}.

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: OSS qn6q**************:77Dv****************
 
x-oss-async-process=video/convert,f_mp4,vcodec_h265,s_1920x1080,vb_2000000,fps_30,acodec_aac,ab_100000,sn_1|sys/saveas,b_e2J1Y2tldH0,o_b3V0cHV0LnthdXRvZXh0fQ