human: 如何处理七牛云的对象存储变量

gpt: [对象存储](https://developer.qiniu.com/kodo) > 使用指南 >
[开发指南](https://developer.qiniu.com/kodo/development_guidelines/8596/development-
guidelines) >
[上传资源](https://developer.qiniu.com/kodo/development_guidelines/1234/upload-
types) > 变量

#  变量

最近更新时间: 2023-04-17 19:51:01

变量是七牛云存储同用户交换数据的机制，引入变量的目的在于更灵活的控制上传后续动作中的内容组织和传递。可以认为变量是一种占位符，七牛云存储会将占位符按约定替换为实际内容。

在构造[上传策略 (PutPolicy)](https://developer.qiniu.com/kodo/manual/1206/put-
policy)时，可在上传策略的`ReturnBody`和`callbackBody`字段内容中使用变量。

变量分为两种：魔法变量 和 自定义变量
。魔法变量是系统提供的一系列预定义变量，可直接使用。而自定义变量则由调用方指定，通常应对于上传时的表单参数，服务端会将这些上传参数的具体值返回给调用方。

# 魔法变量

魔法变量是一组预先定义的变量，可以使用
`$(var)`或`${var}`，以及`$(var.field_name)`或`${var.field_name}`
形式求值。在示例中我们使用的是`$(var)`或`$(var.field_name)`的形式，您也可以替换成`${var}`或`${var.field_name}`。

目前可用的魔法变量如下:

变量名 | 包含子项 | 变量说明 | 适用范围  
---|---|---|---  
bucket |  | 获得上传的目标空间名。 |   
key |  | 获得文件保存在空间中的资源名。 |   
etag |  | 文件上传成功后的 HTTP[ETag](https://developer.qiniu.com/kodo/glossary/1649/e#etag)。若上传时未指定资源ID，Etag将作为资源ID使用。 |   
fname |  | 上传的原始文件名。 |   
fsize |  | 资源尺寸，单位为字节。 |   
mimeType |  | 资源类型，例如JPG图片的资源类型为`image/jpg`。 |   
endUser |  | 上传时指定的`endUser`字段，通常用于区分不同终端用户的请求。 |   
persistentId |  | 音视频转码持久化的进度查询ID。 | 不支持用于 persistentOps 中  
exif | 是 | 获取上传图片的[Exif](https://developer.qiniu.com/kodo/glossary/1649/e#exif)信息。该变量包含子字段，例如对`$(exif.ApertureValue.val)`取值将得到该图片拍摄时的光圈值。 | 不支持用于 saveKey，persistentOps 中  
imageInfo | 是 | 获取所上传图片的基本信息。该变量包含子字段，例如对`$(imageInfo.width)`取值将得到该图片的宽度。 | 不支持用于 saveKey，persistentOps 中  
year |  | 上传时的年份。 | 不支持用于 returnBody，persistentOps 和 callbackBody 中  
mon |  | 上传时的月份。 | 不支持用于 returnBody，persistentOps 和 callbackBody 中  
day |  | 上传时的日期。 | 不支持用于 returnBody，persistentOps 和 callbackBody 中  
hour |  | 上传时的小时。 | 不支持用于 returnBody，persistentOps 和 callbackBody 中  
min |  | 上传时的分钟。 | 不支持用于 returnBody，persistentOps 和 callbackBody 中  
sec |  | 上传时的秒钟。 | 不支持用于 returnBody，persistentOps 和 callbackBody 中  
avinfo | 是 | 音视频资源的元信息。 | 暂不支持用于 saveKey，persistentOps 中  
imageAve |  | 图片主色调，算法由[Camera360](http://hr.camera360.com/)友情提供。 | 不支持用于 persistentOps 中  
ext |  | 上传资源的后缀名，通过 $(fname) 的后缀或者自动检测的 mimeType 来获取。优先使用 $(fname) 的后缀 |   
fprefix |  | $(fname) 忽略 $(ext) 的文件名。 |   
uuid |  | 生成`uuid` | 不支持用于 saveKey，persistentOps 中  
bodySha1 |  | callbackBody的sha1（hex编码） | 只支持用于 callbackUrl 中  
  
魔法变量支持`$(<Object>.<Property>)`形式的访问子项，例如：

  * $(<var>)
  * $(<var>.<field_name>)
  * $(<var>.<field_name>.<sub_field_name>)

求值举例：

  * `$(bucket)` \- 获得上传目标bucket名字
  * `$(imageInfo)` \- 获取当前上传图片的基本属性信息
  * `$(imageInfo.height)` \- 获取当前上传图片的原始高度

魔法变量不支持数组形式的访问子项，例如：

  * $(<var>[0])
  * $(<var>.<field_name>[0])

变量`avinfo`在`returnBody`中返回的格式不同于url触发返回的`avinfo`格式，`avinfo`在魔法变量中的类型如下（内容经过格式化以便阅读）：

    
    
    {
    	"audio":{
    		"bit_rate":"64028",
    		"channels":1,
    		"codec_name":"mp3",
    		"codec_type":"audio",
    		"duration":"30.105556",
    		"index":1,
    		"nb_frames":"1153",
    		"r_frame_rate":"0/0",
    		"sample_fmt":"s16p",
    		"sample_rate":"44100",
    		"start_time":"0.000000",
    		"tags":{
    			"creation_time":"2012-10-21 01:13:54"
    		}
    	},
    	"format":{
    		"bit_rate":"918325",
    		"duration":"30.106000",
    		"format_long_name":"QuickTime / MOV",
    		"format_name":"mov,mp4,m4a,3gp,3g2,mj2",
    		"nb_streams":2,
    		"size":"3455888",
    		"start_time":"0.000000",
    		"tags":{
    			"creation_time":"2012-10-21 01:13:54"
    		}
    	},
    	"video":{
    		"bit_rate":"856559",
    		"codec_name":"h264",
    		"codec_type":"video",
    		"display_aspect_ratio":"4:3",
    		"duration":"29.791667",
    		"height":480,
    		"index":0,
    		"nb_frames":"715",
    		"pix_fmt":"yuv420p",
    		"r_frame_rate":"24/1",
    		"sample_aspect_ratio":"1:1",
    		"start_time":"0.000000",
    		"tags":{
    			"creation_time":"2012-10-21 01:13:54"
    		},
    		"width":640
    	}
    }
    

变量`exif`的类型如下（内容经过格式化以便阅读，具体细节请参考[Exif技术白皮书
__](http://www.cipa.jp/std/documents/e/DC-008-2012_E.pdf)）：

    
    
    {
       "DateTime" : {
          "type" : 2,
          "val" : "2011:11:19 17:09:23"
       },
       "ExposureBiasValue" : {
          "type" : 10,
          "val" : "0.33 EV"
       },
       "ExposureTime" : {
          "type" : 5,
          "val" : "1/50 sec."
       },
       "Model" : {
          "type" : 2,
          "val" : "Canon EOS 600D"
       },
       "ISOSpeedRatings" : {
          "type" : 3,
          "val" : "3200"
       },
       "ResolutionUnit" : {
          "type" : 3,
          "val" : " 英寸"
       },
    
       ...后续内容已省略...
    }
    

变量`imageInfo`对应的类型如下（内容经过格式化以便阅读）：

    
    
    {
        "format":       "jpeg",
        "width":        640,
        "height":       427,
        "colorModel":   "ycbcr"
    }
    

如果变量取值失败（例如在[上传策略
(PutPolicy)](https://developer.qiniu.com/kodo/manual/1206/put-
policy)中指定了一个并不存在的魔法变量），响应内容中对应的变量将被赋予空值。

# 自定义变量

应用客户端在上传请求中设定自定义变量的值。七牛云存储收到这些变量信息后，置换掉`ReturnBody`和`callbackBody`中的自定义变量设置，形成最终的反馈结果。

自定义变量的行为同魔法变量基本一致，但变量名必须以`x:`开始。下面是一个自定义变量的示例：

用户设置了如下的`callbackBody`：

    
    
    put_policy = '{
        ...
        "callbackBody" : "name=$(fname)
        		          &hash=$(etag)
        		          &location=$(x:location)
        		          &price=$(x:price)"
        ...
    }'
    

这个例子中的`$(x:location)`和`$(x:price)`就是自定义变量。

之后，用户的客户端构造了如下请求：

    
    
    <form method="post" action="http://upload.qiniup.com/"
    enctype="multipart/form-data">
        <input name="key" type="hidden" value="sunflower.jpg">
        <input name="x:location" type="hidden" value="Shanghai">
        <input name="x:price" type="hidden" value="1500.00">
        <input name="token" type="hidden" value="...">
        <input name="file" type="file" />
    </form>
    

文件上传完成后，服务端会将请求中的`x:location`和`x:price`的值，替换`callbackBody`中的自定义变量：

    
    
    name=sunflower.jpg
    &hash=Fn6qeQi4VDLQ347NiRm- \
    RlQx_4O2
    &location=Shanghai&price=1500.00
    

然后，七牛云存储将此结果进行[URL 安全的 Base64
编码](https://developer.qiniu.com/kodo/manual/1231/appendix#urlsafe-
base64)，作为回调请求的Body调用`callbackUrl`指定的回调服务器。

如果变量取值失败（例如在[上传策略
(PutPolicy)](https://developer.qiniu.com/kodo/manual/1206/put-
policy)中指定了一个并不存在的表单变量），响应内容中对应的变量将被赋予空值。

以上内容是否对您有帮助？