文档中心>数据万象>实践教程>文件管理实践>如何在上传文件请求回包中返回文件信息

如何在上传文件请求回包中返回文件信息

最近更新时间:2024-07-22 16:22:11

我的收藏

背景介绍

本文将介绍如何在上传文件到 COS 时同步获取文件信息,如图片的宽高、格式等。
目前,可以通过 COS 上传接口,如 PUT ObjectCompleteMultipartUploads 等将文件存储至 COS 存储桶中,我们针对以下三种场景提供上传时同步获取文件信息的方式:
场景
文件类型
实现方式
上传文件时,同步获取文件元信息
所有文件
ReturnBody
上传文件时,同步获取图片信息
图片文件
方式一:ReturnBody
方式二:Pic-Operations
上传文件时,同步获取媒体文件信息
媒体文件
ReturnBody
ReturnBody 是 COS 对外提供的一种获取文件信息的方式。在上传请求(PUT Object、POST Object、CompleteMultipartUploads)中携带 x-cos-return-body 头部,传入自定义的 ReturnBody 参数,便可在请求响应结果中获取到文件信息,可参考 ReturnBody
Pic-Operations 是上传时的一个请求包头,在上传请求(PUT Object、POST Object、CompleteMultipartUploads)中携带该包头并设置需要返回原图信息的参数,就可在图片上传至 COS 时同步获取原图信息,可参考 图片处理机制介绍
说明:
Pic-Operations 是由数据万象服务提供的获取图片信息的能力,使用时会产生 图片基础处理费用
主要流程如下图所示:




场景一:同步获取文件元信息

如需要在上传文件后,同步获取文件元信息,可以通过 ReturnBody 实现。在上传请求头部中携带由文件元信息组成的 ReturnBody 参数,便可在请求响应结果中获取到文件元信息。
ReturnBody 提供以下文件元信息参数:
变量名
变量说明
bucket
对象上传的目标存储桶
object
对象上传到存储桶内,使用的对象名称
size
对象大小,单位为 Byte
region
对象上传的存储桶所在地域
mimeType
对象元数据 Content-Type
使用时,需要先自定义构造 ReturnBody 参数,这是您希望在返回结果中获取到的文件元信息。
注意:
ReturnBody 参数的 key 可以自定义名称,value 必须跟上述 ReturnBody 提供的变量名保持一致。

请求示例

// ReturnBody 参数的 key 可以自定义名称,value 必须跟 ReturnBody 提供的变量保持一致
{
"bucket": "${bucket}",
"key": "${object}",
"filesize": "${size}",
"mime_type": "${mimeType}"
}
再将 ReturnBody 参数转换为字符串,并进行 URL 安全 的 Base64 编码,可以得到:
eyJidWNrZXQiOiIke2J1Y2tldH0iLCJrZXkiOiIke29iamVjdH0iLCJmaWxlc2l6ZSI6IiR7c2l6ZX0iLCJtaW1lX3R5cGUiOiIke21pbWVUeXBlfSJ9
之后便可在上传文件的请求中,通过设置请求头部 x-cos-return-body 传入上面 Base64 编码后的结果,即可在请求响应中获取到自定义的 bucket、key、filesize、mime_type 文件信息,步骤详情可查看 ReturnBody 使用步骤

响应示例

HTTP/1.1 200 OK
x-cos-request-id: NWU5MDNkZjVfYzVjNzJhMDlfMjVhNzNfMWMy****

{
"bucket":"examplebucket-1250000000000",
"filesize":"30262104",
"key":"test.pptx",
"mime_type":"application/vnd.openxmlformats-officedocument.presentationml.presentation"
}

场景二:同步获取图片信息

如需要在上传图片文件后,同步获取图片信息,有两种实现方式:通过 ReturnBody 同步获取图片信息 和 通过 Pic-Operations 同步获取图片信息。同步获取图片信息后,可以用于后续处理,如给图片分类、打标签等操作。
注意:
两种实现方式都依赖数据万象(Cloud Infinite,CI)服务的能力。使用前需先开通数据万象并绑定存储桶,可参考 存储桶操作
获取图片信息会由 CI 服务收取基础图片处理费用,详情可参考 图片处理费用

方式一:通过 ReturnBody 同步获取图片信息

通过 ReturnBody 同步获取图片信息的方式,需要在上传请求头部中携带由图片信息组成的 ReturnBody 参数,便可在请求响应结果中获取到图片信息。
说明:
当前仅支持在中国大陆公有云地域使用。
ReturnBody 提供的图片信息包括:图片基本信息(imageInfo)图片 exif 信息
其中,图片基本信息(imageInfo)包括:
变量格式
变量说明
imageInfo.format
图片类型。例如 png、gif 等
imageInfo.width
图片的宽度。单位为像素(px)
imageInfo.height
图片的高度。单位为像素(px)
imageInfo.size
图片的大小。单位为 Bytes
imageInfo.md5
图片的 md5 值
imageInfo.frame_count
图片的帧数。静态图为1,动图为对应的帧数
imageInfo.bit_depth
图片的位深
imageInfo.vertical_dpi
图片的垂直分辨率
imageInfo.horizontal_dpi
图片的水平分辨率
图片 exif 信息主要是记录拍摄的硬件或软件信息,包含但不限于以下几项:
变量格式
变量说明
exif.ColorSpace.val
色域、色彩空间
exif.DateTime.val
创建时间
exif.Orientation.val
方向
exif.ResolutionUnit.val
分辨率单位
exif.XResolution.val
X 方向分辨率
exif.YResolution.val
Y 方向分辨率
...
...
使用时,仍需根据 ReturnBody 提供的图片信息先自定义构造 ReturnBody 参数。为了避免 ReturnBody 携带的内容太多,影响接口性能,不支持直接填写${imageInfo}${exif},必须写明具体的子变量,例如${变量名.子变量}${变量名.二级子变量}
注意:
ReturnBody 参数的 key 可以自定义名称,value 必须跟上述 ReturnBody 提供的变量名保持一致。

请求示例

// ReturnBody 参数的 key 可以自定义名称,value 必须跟 ReturnBody 提供的变量保持一致
{
"color_space": "${exif.ColorSpace.val}", "format": "${imageInfo.format}", "width": "${imageInfo.width}", "height": "${imageInfo.height}", "md5": "${imageInfo.md5}", "bit_depth": "${imageInfo.bit_depth}", "vertical_dpi": "${imageInfo.vertical_dpi}", "horizontal_dpi": "${imageInfo.horizontal_dpi}"
}
再将 ReturnBody 参数转换为字符串,并进行 URL 安全 的 Base64 编码,可以得到:
eyJjb2xvcl9zcGFjZSI6IiR7ZXhpZi5Db2xvclNwYWNlLnZhbH0iLCJmb3JtYXQiOiIke2ltYWdlSW5mby5mb3JtYXR9Iiwid2lkdGgiOiIke2ltYWdlSW5mby53aWR0aH0iLCJoZWlnaHQiOiIke2ltYWdlSW5mby5oZWlnaHR9IiwibWQ1IjoiJHtpbWFnZUluZm8ubWQ1fSIsImJpdF9kZXB0aCI6IiR7aW1hZ2VJbmZvLmJpdF9kZXB0aH0iLCJ2ZXJ0aWNhbF9kcGkiOiIke2ltYWdlSW5mby52ZXJ0aWNhbF9kcGl9IiwiaG9yaXpvbnRhbF9kcGkiOiIke2ltYWdlSW5mby5ob3Jpem9udGFsX2RwaX0ifQ
之后便可在上传文件的请求中,通过设置请求头部 x-cos-return-body 传入上面 Base64 编码后的结果,即可在请求响应中获取到自定义的 color_space、format、width、height 等图片信息,步骤详情可查看 ReturnBody 使用步骤

响应示例

HTTP/1.1 200 OK
x-cos-request-id: NWU5MDNkZjVfYzVjNzJhMDlfMjVhNzNfMWMy****

{
"bit_depth":"8",
"color_space":"sRGB",
"format":"png",
"height":"800",
"horizontal_dpi":"0",
"md5":"4f5c260f63af3c56cea542a1c62a0a1b",
"vertical_dpi":"0",
"width":"1200"
}

方式二:通过 Pic-Operations 同步获取图片信息

通过 Pic-Operations 同步获取图片信息的方式,只需要在请求包头部中加入 Pic-Operations 项并设置需要返回原图信息参数,就可在图片上传至 COS 后同步获取原图信息,可参考 图片处理机制介绍
通过 putObject 上传图片,请求头中设置 Pic-Operations,设置 is_pic_info 为 1,代表返回原图信息。在请求结果中可以拿到原图图片信息。

请求示例

PUT /filename.jpg HTTP/1.1
Host: examplebucket-1250000000.cos.ap-chengdu.myqcloud.com
Date: Tue, 04 Apr 2023 09:06:15 GMT
Authorization:XXXXXXXXXXXX
Pic-Operations: {"is_pic_info":1}
Content-Length: 64

[Object]

响应示例

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 645
Date: Tue, 04 Apr 2023 09:06:16 GMT
Status: 200 OK
x-cos-request-id: NWFjMzQ0MDZfOTBmYTUwXzZkZV8z****

<UploadResult>
<OriginalInfo>
<Key>filename.jpg</Key>
<Location>examplebucket-1250000000.cos.ap-chengdu.myqcloud.com/filename.jpg</Location>
<ETag>&quot;580cd6930444576523c25f86ce2af9b1fc2d5484&quot;</ETag>
<ImageInfo>
<Format>JPEG</Format>
<Width>640</Width>
<Height>427</Height>
<Quality>100</Quality>
<Ave>0xa18454</Ave>
<Orientation>1</Orientation>
<FrameCount>1</FrameCount>
</ImageInfo>
</OriginalInfo>
</UploadResult>
说明:
Pic-Operations 支持 COS V5 的分块上传同步获取图片信息,在使用 COS V5 的 Complete Multipart Upload 接口时只需在请求包头部中加入 Pic-Operations 项,在分片上传完成后可以在请求结果中获取到图片信息。
Pic-Operations 只能在数据万象支持的地域使用,详情请参见 地域与域名
仅支持 32M 以内的图片。

场景三:同步获取媒体文件信息

注意:
通过 ReturnBody 同步获取媒体文件信息依赖数据万象(Cloud Infinite,CI)服务的媒体处理功能。使用前需先开通数据万象并绑定存储桶,可参考 存储桶操作,并开启媒体处理功能开关。获取媒体文件信息会由 CI 服务收取视频元信息获取费用,详情可参考 媒体处理费用
如需要在上传媒体文件后,同步获取媒体文件信息,可以通过 ReturnBody 实现。在上传请求头部中携带由媒体文件信息组成的 ReturnBody 参数,便可在请求响应结果中获取到媒体文件信息。
说明:
当前仅支持在中国大陆公有云地域使用。
ReturnBody 提供的媒体文件信息主要内容可参考下表,更多可查看 媒体文件信息
变量格式
变量说明
videoInfo.video.bit_rate
视频比特率,单位为 kbps
videoInfo.video.codec_name
视频编解码格式名字
videoInfo.video.profile
视频编码档位
videoInfo.video.pix_fmt
像素格式
videoInfo.audio.bit_rate
音频比特率,单位 kbps
videoInfo.audio.codec_name
音频编解码格式名字
videoInfo.format.duration
时长,单位为秒
...
...
使用时,仍需根据 ReturnBody 提供的媒体文件信息先自定义构造 ReturnBody 参数。为了避免 ReturnBody 携带的内容太多,影响接口性能,不支持直接填写${videoInfo},必须写明具体的子变量,例如${变量名.子变量}${变量名.二级子变量}
注意:
ReturnBody 参数的 key 可以自定义名称,value 必须跟上述 ReturnBody 提供的变量名保持一致。

请求示例

// ReturnBody 参数的 key 可以自定义名称,value 必须跟 ReturnBody 提供的变量保持一致
{
"video_bit_rate": "${videoInfo.video.bit_rate}", "video_codec_name": "${videoInfo.video.codec_name}", "video_profile": "${videoInfo.video.profile}", "video_pix_fmt": "${videoInfo.video.pix_fmt}", "audio_bit_rate": "${videoInfo.audio.bit_rate}", "audio_codec_name": "${videoInfo.audio.codec_name}", "duration": "${videoInfo.format.duration}",
}
再将 ReturnBody 参数转换为字符串,并进行 URL 安全 的 Base64 编码,可以得到:
eyJ2aWRlb19iaXRfcmF0ZSI6IiR7dmlkZW9JbmZvLnZpZGVvLmJpdF9yYXRlfSIsInZpZGVvX2NvZGVjX25hbWUiOiIke3ZpZGVvSW5mby52aWRlby5jb2RlY19uYW1lfSIsInZpZGVvX3Byb2ZpbGUiOiIke3ZpZGVvSW5mby52aWRlby5wcm9maWxlfSIsInZpZGVvX3BpeF9mbXQiOiIke3ZpZGVvSW5mby52aWRlby5waXhfZm10fSIsImF1ZGlvX2JpdF9yYXRlIjoiJHt2aWRlb0luZm8uYXVkaW8uYml0X3JhdGV9IiwiYXVkaW9fY29kZWNfbmFtZSI6IiR7dmlkZW9JbmZvLmF1ZGlvLmNvZGVjX25hbWV9IiwiZHVyYXRpb24iOiIke3ZpZGVvSW5mby5mb3JtYXQuZHVyYXRpb259In0
之后便可在上传文件的请求中,通过设置请求头部 x-cos-return-body 传入上面 Base64 编码后的结果,即可在请求响应中获取到自定义的 video_bit_rate、video_codec_name、video_profile 等媒体文件信息,步骤详情可查看 ReturnBody 使用步骤

响应示例

HTTP/1.1 200 OK
x-cos-request-id: NWU5MDNkZjVfYzVjNzJhMDlfMjVhNzNfMWMy****

{
"audio_bit_rate":"189.375000",
"audio_codec_name":"aac",
"duration":"123.875000",
"video_bit_rate":"2936.675000",
"video_codec_name":"h264",
"video_pix_fmt":"yuv420p",
"video_profile":"Main"
}