All Products
Search

This Product

    Object Storage Service:variable

    Document Center

    Object Storage Service:variable

    Last Updated:Jun 20, 2026

    When you use the data processing feature, each object triggers a task. For each task, you must specify a save path for the processed object. To prevent objects from being overwritten, you must use a dynamic output path. You can use variables to reference information from the source object, such as its bucket, object key, or upload time. For example, in a video frame extraction task, you can set the output path to oss://test-bucket/{dirname}/{barename}_output.{autoext}. This saves the processed object to the same directory as the source object, names it source-object-name_output, and automatically adds the correct extension.

    Use cases

    Console use cases

    • Tasks: You can reference source object information in the output path of a processing task. For example, to convert a document to JPG images, set the output path to oss://test-bucket/output/{dirname}/{barename}/{index}.{autoext}. During processing, {autoext} is replaced with jpg. The resulting images are saved to oss://test-bucket/output/source-directory/source-filename/image-sequence-number.jpg.

      In the Create Task dialog box, select doc_to_jpg for Style. A prompt below Output Path states that you must enter a complete object key, the object key can include variables, and the input and output paths must be different. In the Notification Configuration section, you can select Message Queue. After you complete the configurations, click OK.

    • Batch processing: When you create a batch processing job, the system generates a task for each existing object. To avoid data overwrites, we recommend that you use variables in the output path. For example, to extract frames from a video and save them as PNG images, set the output path to oss://test-bucket/output/{dirname}/{barename}/{index}.{autoext}. During processing, {autoext} is replaced with png. The generated PNG images are saved to oss://test-bucket/output/source-directory/source-filename/frame-number.png.

      After you configure the output path in the Output Configuration section, make sure that the output path is different from the input path if you use the key, barename, or basename variables. This prevents the source object from being overwritten and avoids creating infinite loops. In the Permission Configuration section, select AliyunIMMBatchTriggerRole (Default Role) for Service Role, and then click OK.

    • Triggers: Creating a trigger generates a task for each new object. To avoid object overwrites, we recommend that you use variables in the output path. For example, if a document conversion trigger is created to convert documents to JPG images, set the output path to oss://test-bucket/output/{dirname}/{barename}/{index}.{autoext}. During processing, {autoext} is replaced with jpg. The generated JPG images are saved to oss://test-bucket/output/source-directory/source-filename/image-sequence-number.jpg.

      If you use the object key, barename, or basename variables, ensure the output path is different from the input path to prevent object overwrites. In the Permission Configuration section, select AliyunIMMBatchTriggerRole (Default Role) for Service Role, and then click OK.

    API use cases

    • Save as (sys/saveas): The b (bucket) and o (object) parameters for the save as (sys/saveas) operation support variables. For example, to convert pages 1 to 10 of a document named example.docx to PNG images, you can set the sys/saveas parameter to b_e2J1Y2tldH0,o_ZG9jX2ltYWdlcy97aW5kZXh9LnBuZw. In this parameter, e2J1Y2tldH0 is the Base64-encoded value of {bucket}, and ZG9jX2ltYWdlcy97aW5kZXh9LnBuZw is the Base64-encoded value of doc_images/{index}.png. The converted images are then saved to the same bucket as the source object at the path doc_images/index.png.

    • Tasks: The output path for tasks supports 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, including the extension. The TargetURI can contain variables, such as oss://test-bucket/output/{dirname}/{barename}/{index}.jpg.

    Notes

    • For batch processing and triggers, if the output path does not end with a forward slash (/), the object key must include at least one variable. This prevents multiple output objects from overwriting each other.

    • The output path for a task cannot end with a forward slash (/) but can contain variables.

    Task-related variables

    You can also use the timestamp of a synchronous or asynchronous processing request as a variable. For example, if you submit a processing request at 2022-09-01T02:06:57.798Z, you can use the variables in the following table.

    Parameter

    Description

    Example value

    t_year

    The four-digit year (yyyy) when the request was submitted.

    2022

    t_mon

    The two-digit month (mm) when the request was submitted.

    09

    t_day

    The two-digit day (dd) when the request was submitted.

    01

    t_hour

    The hour (HH, 24-hour format) when the request was submitted.

    02

    t_min

    The minute (MM) when the request was submitted.

    06

    t_sec

    The second (SS) when the request was submitted.

    57

    Image processing variables

    For a source object named oss://test-bucket/path1/path2/name.png that was uploaded at 2022-04-22 14:38:25, you can use the variables in the following table.

    Parameter

    Description

    Example value

    bucket

    The name of the bucket where the source object is stored.

    test-bucket

    key

    The object key of the source object in the bucket.

    Important

    Do not set the output and source paths to be identical when using this variable. Otherwise, you may overwrite the source object or cause an infinite loop in a batch processing job.

    path1/path2/name.png

    dirname

    The directory path of the source object.

    Important

    Do not set the output and source paths to be identical when using this variable. Otherwise, you may overwrite the source object or cause an infinite loop in a batch processing job.

    path1/path2

    barename

    The name of the source object without its extension.

    Important

    Do not set the output and source paths to be identical when using this variable. Otherwise, you may overwrite the source object or cause an infinite loop in a batch processing job.

    name

    basename

    The name of the source object with its extension.

    Important

    Do not set the output and source paths to be identical when using this variable. Otherwise, you may overwrite the source object or cause an infinite loop in a batch processing job.

    name.png

    ext

    The extension of the source object. The extension is obtained from the auto-detected mimeType or from the suffix of the object key.

    png

    year

    The four-digit year (yyyy) when the source object was uploaded.

    2022

    mon

    The two-digit month (mm) when the source object was uploaded.

    04

    day

    The two-digit day (dd) when the source object was uploaded.

    22

    hour

    The hour (HH, 24-hour format) when the source object was uploaded.

    14

    min

    The minute (MM) when the source object was uploaded.

    38

    sec

    The second (SS) when the source object was uploaded.

    25

    Document conversion variables

    For document conversion, you can use variables such as page numbers and sheet names. For example, to convert an Excel document containing a sheet named sheet1 to JPG images, you can use the variables in the following table.

    Parameter

    Description

    Example value

    autoext

    The extension of the output object in a document conversion task.

    png

    index

    The output index, which increments from 1. For Word, PDF, and PPT documents, this variable represents the page number. For Excel documents, it is in the format of sheetindex_sheetsubindex.

    For Word, PDF, and PPT: 1

    For Excel: 1_1

    sheetname

    The name of the sheet in an Excel document.

    sheet1

    sheetindex

    The index of the sheet in an Excel document, starting from 1.

    1

    sheetsubindex

    The sub-index of a sheet in an Excel document, starting from 1.

    1

    Media processing variables

    For media processing, you can use variables such as the container extension and resolution. For example, to transcode a video named video.mp4 into ts segments with a resolution of 1920x1080, you can use the variables in the following table.

    Parameter

    Description

    Example value

    autoext

    The extension of the output object in a media processing task.

    ts

    index

    The output index, which increments from 1. This is used in multi-output scenarios such as segmented transcoding or frame extraction.

    1

    streamindex

    The ID of the audio or video stream. The IDs for audio and video streams increment independently from 0.

    0

    resolution

    The resolution set for transcoding. This is available only for video transcoding.

    1920x1080

    Using the REST API

    If your application requires a high degree of customization, you can call the RESTful API directly, which requires you to write code to calculate signatures manually.

    You can process objects by adding processing or style parameters to a PostObject request. For more information, see Save as.

    Example 1: Document format conversion

    The following RESTful API example shows how to add processing parameters to a PostObject request to convert the format of example.docx. The b (bucket) and o (object) parameters of the save as (sys/saveas) operation use variables.

    • pages_MS0xMA: Converts pages 1 to 10 of the document. MS0xMA is the Base64-encoded value of "1-10".

    • target_png: Converts the document to the PNG image format.

    • source_docx: Specifies that the source object type is DOCX.

    • sys/saveas: Save as.

      • b_e2J1Y2tldH0: After transcoding is complete, the {bucket} variable saves the resulting images to the source bucket. e2J1Y2tldH0 is the Base64-encoded value of {bucket}.

      • o_ZG9jX2ltYWdlcy97aW5kZXh9LnBuZw: This saves the object to the doc_images directory. The object key uses the {index} variable, which corresponds to the page number of example.docx. 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: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
 // Converts pages 1 to 10 of the example.docx object to PNG images. The processed objects are saved to 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

    This example demonstrates how to transcode the example.avi object by configuring multiple processing parameters.

    • f_mp4: Sets the container of the transcoded media file to MP4.

    • vcodec_h265: Sets the video stream format to H.265.

    • s_1920x1080: Sets the resolution to 1920x1080.

    • vb_2000000: Sets the video bitrate to 2 Mbps.

    • 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 Kbps.

    • sn_1: Disables the subtitle stream.

    • sys/saveas: Save as.

      • b_e2J1Y2tldH0: After transcoding is complete, the resulting object is saved to the source bucket by using the {bucket} variable. e2J1Y2tldH0 is the Base64-encoded value of {bucket}.

      • o_b3V0cHV0LnthdXRvZXh0fQ: The {autoext} variable automatically adds an extension to the object, resulting in a saved 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: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
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