AI 助理
备案控制台
文档
输入文档关键字查找
首页 对象存储 操作指南 数据处理 基本概念 变量

变量

更新时间：
产品详情
我的收藏

在使用数据处理功能的批处理或触发器功能时，每个Object都会触发一个任务，任务中需要指定处理后的文件保存的输出路径，如果多个任务输出路径是同一个路径，则会产生文件覆盖，因此需要保证输出路径为动态路径，所以引入变量。此外，您可以在输出路径中引用源文件的已有信息，如源文件所在的Bucket、文件名、文件上传时间等信息。例如：将视频截帧任务的输出路径指定为oss://test-bucket/{dirname}/{barename}_output.{autoext}，将目标文件保存到源文件所在目录下，目标文件名为源文件名_output，并且根据目标文件类型自动添加后缀。

使用场景

控制台使用场景

  • 任务：处理任务可以在输出路径中引用源文件的已有信息。例如：文档转jpg图片任务，输出路径设置为oss://test-bucket/output/{dirname}/{barename}/{index}.{autoext}，处理时{autoext}将被替换为jpg，转换生成的图片保存路径为oss://test-bucket/output/源文件目录/源文件名/图片序号.jpg。

    image

  • 批处理：批处理创建成功后会对每个存量文件生成对应的任务进行数据处理，为避免批处理任务导致的数据覆盖，建议您在批处理的输出路径中设置变量。例如：视频截帧批处理将视频截帧为png格式，输出路径设置为oss://test-bucket/output/{dirname}/{barename}/{index}.{autoext}，处理时{autoext}将被替换为png，处理后生成的png图片保存路径为oss://test-bucket/output/源文件目录/源文件名/图片序号.png。

    image

  • 触发器：触发器创建成功后会对每个新增文件生成对应的任务进行数据处理，如果有多个文件触发任务可能会产生文件覆盖，此时您需要在触发器的输出路径中设置变量。例如：文档转换触发器将文档转换为jpg图片格式，将输出路径设置为oss://test-bucket/output/{dirname}/{barename}/{index}.{autoext}，处理时{autoext}将被替换为jpg，处理后生成的jpg图片文件保存路径为oss://test-bucket/output/源文件目录/源文件名/图片序号.jpg。

    image

API使用场景

  • 另存为 (sys/saveas)：另存为 (sys/saveas) 中的b（Bucket）和o（Object）参数支持变量。例如：您在对example.docx文档进行文档转换处理时，需要将1~10页分别转换为png格式，可以将sys/saveas设置为b_e2J1Y2tldH0,o_ZG9jX2ltYWdlcy97aW5kZXh9LnBuZw（e2J1Y2tldH0是{bucket}进行Base64编码之后的值，ZG9jX2ltYWdlcy97aW5kZXh9LnBuZw是doc_images/{index}.png编码之后的值），则转换后生成的图片保存到源文件相同的Bucket下，路径为doc_images/下标.png。

  • 任务：任务的输出路径支持变量。例如：您在调用CreateOfficeConversionTask - 创建文档转换任务接口创建文档转换任务时，TargetURI参数必须填写包含扩展名的完整输出文件路径，TargetURI使用变量（例如：oss://test-bucket/output/{dirname}/{barename}/{index}.jpg）。

注意事项

  • 批处理和触发器的输出路径以非/结尾时，文件名需要至少包含一个变量，否则多个输出文件将会互相覆盖。

  • 任务的输出路径不支持以/结尾的路径，支持使用变量。

文件元数据相关变量

以源文件oss://test-bucket/path1/path2/name.png为例，该文件上传时间为2022-04-22 14:38:25，可以使用下表中的变量。

变量

说明

示例值

bucket

原始文件存储空间（Bucket）名称。

test-bucket

key

原始文件保存在存储空间中的资源名。

重要

使用该变量时请避免将输出文件和输入文件设置为相同文件，否则会覆盖源文件或在批处理时循环触发。

path1/path2/name.png

dirname

原始文件路径目录。

重要

使用该变量时请避免将输出文件和输入文件设置为相同文件，否则会覆盖源文件或在批处理时循环触发。

path1/path2

barename

原始文件名（不包含扩展名）。

重要

使用该变量时请避免将输出文件和输入文件设置为相同文件，否则会覆盖源文件或在批处理时循环触发。

name

basename

原始文件名（包含扩展名）。

重要

使用该变量时请避免将输出文件和输入文件设置为相同文件，否则会覆盖源文件或在批处理时循环触发。

name.png

ext

原始文件资源的扩展名，通过自动检测的mimeType或者key的后缀来获取。

png

year

原始文件上传时的年份，格式为yyyy。

2022

mon

原始文件上传时的月份，格式为mm。

04

day

原始文件上传时的日期，格式为dd。

22

hour

原始文件上传时的小时，格式为HH。

14

min

原始文件上传时的分钟，格式为MM。

38

sec

原始文件上传时的秒钟，格式为SS。

25

任务相关变量

同步处理和异步处理请求的时间点也可以作为变量，例如您在2022-09-01T02:06:57.798Z时刻提交的处理请求，可以使用下表中的变量。

变量

说明

示例值

t_year

处理请求提交时的年份，格式为yyyy。

2022

t_mon

处理请求提交时的月份，格式为mm。

09

t_day

处理请求提交时的日期，格式为dd。

01

t_hour

处理请求提交时的小时，格式为HH。

02

t_min

处理请求提交时的分钟，格式为MM。

06

t_sec

处理请求提交时的秒钟，格式为SS。

57

文档转换相关变量

文档转换处理可以使用页码、Sheet名称等作为变量，例如将含有一个Sheet，Sheet名称为sheet1的Excel文档转换为JPG图片，可以使用下表中的变量。

变量

说明

示例值

autoext

文档转换中输出文件的后缀。

png

index

输出下标，从1开始，Word、PDF、PPT为页码，Excel中为sheetindex_sheetsubindex。

1_1

sheetname

Excel的Sheet名称。

sheet1

sheetindex

Excel的Sheet下标，从1开始。

1

sheetsubindex

Excel的Sheet其中部分下标，从1开始。

1

媒体处理相关变量

媒体处理可以使用容器扩展名、分辨率等作为变量。例如，对video.mp4进行分片转码，媒体容器为ts，目标分辨率为1920x1080，可以使用下表中的变量。

变量

说明

示例值

autoext

媒体处理中输出文件的后缀。

ts

index

输出文件下标，从0开始递增，用于分片转码、截图等多输出场景。

1

streamindex

音视频流ID，音视频流分别从0递增。

0

resolution

设置的转码分辨率，仅视频转码可用。

1920x1080

使用REST API

如果您的程序自定义要求较高，您可以直接发起REST API请求。直接发起REST API请求需要手动编写代码计算签名。

您可以在PostObject接口中以添加处理参数或样式参数的方式来处理文件。更多信息，请参见另存为。

示例一：文档格式转换

如下REST API示例在PostObject接口中以添加处理参数的方式对example.docx进行文档格式转换处理，在另存为 (sys/saveas) 中的b（Bucket）和o（Object）参数使用变量。

  • pages_MS0xMA：转换文档1-10页（MS0xMA是1-10进行Base64编码之后的值）。

  • target_png：将文档转换成png图片格式。

  • source_docx：指定源文件类型为docx。

  • sys/saveas：另存为。

    • b_e2J1Y2tldH0：转码完成后将得到的图片使用{bucket}变量保存到源Bucket（e2J1Y2tldH0是{bucket}进行Base64编码后的值）。

    • o_ZG9jX2ltYWdlcy97aW5kZXh9LnBuZw：object使用{index}变量以example.docx页码作为图片文件名保存到doc_images目录下（ZG9jX2ltYWdlcy97aW5kZXh9LnBuZw是doc_images/{index}.png进行Base64编码之后的值）。

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****************
 
 // 将文件example.docx的1-10页转换为PNG格式的图片文件，转换后的存储路径为：oss://源Bucket/doc_images/页码.png。
x-oss-async-process=doc/convert,pages_MS0xMA,target_png,source_docx|sys/saveas,b_e2J1Y2tldH0,o_ZG9jX2ltYWdlcy97aW5kZXh9LnBuZw

示例二：视频转码

如下以视频转码处理场景为，对example.avi文件进行视频转码处理，配置了多个处理参数。

  • f_mp4：转码输出媒体文件容器为MP4。

  • vcodec_h265：视频流格式为H.265。

  • s_1920x1080：分辨率为1920x1080。

  • vb_2000000：视频码率为2 Mbps。

  • fps_30：视频帧率为30 fps。

  • acodec_aac：音频编码格式为AAC。

  • ab_100000：音频码率为100 Kbps。

  • sn_1：禁用字幕流。

  • sys/saveas 另存为。

    • b_e2J1Y2tldH0：转码完成后将得到的文件使用{bucket}变量保存到源Bucket（e2J1Y2tldH0是{bucket}进行Base64编码后的值）。

    • o_b3V0cHV0LnthdXRvZXh0fQ：object使用{autoext}变量自动添加后缀，保存后的object为output.mp4（b3V0cHV0LnthdXRvZXh0fQ是output.{autoext}进行Base64编码后的值）。

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

上一篇：另存为下一篇：消息通知
文档推荐