上传策略_使用指南_对象存储 - 七牛开发者中心
Toggle navigation
开发者中心
产品与服务
对象存储
企业级存储
智能日志管理平台
CDN
智能多媒体服务
直播云
实时音视频
SSL 证书服务
云主机
专有云计算
内容审核
视频监控
云短信
机器数据分析平台
边缘加速
即时通讯
互动白板
全站加速
低代码
容器轻应用平台
SDK & 工具
官方 SDK
社区 SDK
开发者工具
社区插件
解决方案
FAQ
技术支持
官网
管理控制台
更多
官网
管理控制台
SDK & 工具
解决方案
输入搜索的关键字
技术支持
退出当前帐号
登录
注册
对象存储
产品动态
产品更新动态2021 年 08 月 1 日起低频存储数据取回降价通知存储类型转换次数计费项变更
产品简介
产品概述基本概念存储类型存储区域编程模型
购买指南
计量项与计费项账号欠费保护期功能限制
快速入门
快速入门文档控制台用户指南新建存储空间设置镜像回源
使用指南
开发指南安全机制上传策略上传凭证下载凭证管理凭证管理凭证历史文档上传资源表单上传分片上传 v1 版分片上传 v2 版简单反馈回调通知303 重定向异步数据预处理自定义响应内容变量下载资源公开资源下载私有资源下载防盗链下载设置高级下载管理存储空间绑定源站域名访问控制静态页面管理空间备注文件客户端缓存重定向空间标签空间授权跨域资源共享生命周期管理事件通知镜像回源跨区域同步空间访问日志删除空间数据安全Referer 防盗链对象锁定数据处理图片样式转码样式原图保护AWS S3 兼容存储类型服务域名签名认证临时安全凭证兼容公共头兼容 API使用 Bucket Policy 授权兼容工具示例附录控制台指南控制台概览空间管理新建空间空间列表管理空间概览空间设置设置访问控制设置静态页面设置空间备注设置文件客户端缓存设置重定向设置标签管理设置空间授权设置Referer防盗链设置跨域资源共享设置生命周期设置事件通知设置镜像回源设置对象锁定设置空间日志设置空间内容审核删除存储空间域名管理设置自定义CDN加速域名设置自定义源站域名数据处理设置图片样式设置转码样式设置原图保护文件管理上传文件创建目录搜索文件修改文件名修改文件类型查看文件详情设置文件元信息下载文件分享文件刷新 CDN 缓存移动文件删除文件删除目录修改文件存储类型解冻文件任务中心设置跨区域同步统计分析
API 文档
API 概览HTTP Headers错误响应数据格式Service 接口获取 Bucket 列表Bucket 接口创建 Bucket删除 Bucket获取 Bucket 空间域名设置 Bucket 镜像源设置 Bucket 访问权限设置空间标签查询空间标签删除空间标签Object 接口直传文件分片上传 v1 版创建块上传片创建文件分片上传 v2 版初始化任务分块上传数据完成文件上传终止上传列举已上传分片资源列举资源元信息查询资源元信息修改资源移动／重命名资源复制资源删除批量操作修改文件状态修改文件存储类型解冻归档/深度归档存储文件修改文件过期删除时间修改文件生命周期镜像资源更新异步第三方资源抓取数据统计接口
SDK 下载
Rust SDKFlutter SDKC# SDKObjective-C SDKAndroid SDKAndroid SDK历史文档Android SDK V7Java SDKJava SDK 历史文档PHP SDKPHP SDK历史文档Python SDKRuby SDKNode.js SDKNode.js SDK V6C# SDKC# SDK v7.2.15 文档C# SDK v7.0 文档C# SDK v6 文档C/C++ SDKGo SDKGo SDK历史版本JavaScript SDKJavaScript SDK历史文档2.xJavaScript SDK历史文档1.x
实用工具
图形化工具 Kodo Browser命令行工具(qshell)命令行工具(qsuits)（不再维护）文件备份/迁移文件上传和下载文件复制/移动/重命名文件修改/删除等多媒体数据处理内容审核操作CDN 刷新预取操作导出存储私有或公开资源 URL单行式操作交互式操作命令行辅助工具(qrsctl)（不再维护）数据迁移工具(kodoimport)检测工具上传测试页面网络检测工具(qwebtest)Qiniu Jenkins Plugin数据迁移工具(qfetch) （不再维护）
最佳实践
数据安全最佳实践保障安全上传、下载、管理数据降低因账号密码泄露带来的未授权访问风险降低被恶意篡改数据的风险防止恶意文件上传降低被恶意访问、盗量的风险降低或因误操作导致的数据丢失的风险跟踪、追溯对数据的关键操作敏感数据安全防护对象存储开源生态建设使用 Terraform 管理对象存储 Kodo使用 Hadoop S3A 客户端管理对象存储 Kodo使用 Rclone 命令行工具管理对象存储 Kodo使用 Kubernetes CSI 挂载对象存储 Kodo
服务协议
服务等级协议（SLA）
常见问题
术语表
QEHJLU
对象存储 > 使用指南 > 开发指南 > 安全机制 > 上传策略
上传策略
最近更新时间: 2022-03-17 15:42:18
上传策略是资源上传时附带的一组配置设定。通过这组配置信息，七牛云存储可以了解用户上传的需求：它将上传什么资源，上传到哪个空间，上传结果是回调通知还是使用重定向跳转，是否需要设置反馈信息的内容，以及授权上传的截止时间等等。
上传策略同时还参与请求验证，可以验证用户对某个资源的上传请求是否完整。
格式
"scope": "<Bucket string>",
"isPrefixalScope": <IsPrefixalScope int>,
"deadline": <UnixTimestamp uint32>,
"insertOnly": <AllowFileUpdating int>,
"endUser": "<EndUserId string>",
"returnUrl": "<RedirectURL string>",
"returnBody": "<ResponseBodyForAppClient string>",
"callbackUrl": "<RequestUrlForAppServer string>",
"callbackHost": "<RequestHostForAppServer string>",
"callbackBody": "<RequestBodyForAppServer string>",
"callbackBodyType": "<RequestBodyTypeForAppServer string>",
"persistentOps": "<persistentOpsCmds string>",
"persistentNotifyUrl": "<persistentNotifyUrl string>",
"persistentPipeline": "<persistentPipeline string>",
"forcesaveKey": <forcesaveKey bool>,
"saveKey": "<SaveKey string>",
"fsizeMin": <FileSizeMin int64>,
"fsizeLimit": <FileSizeLimit int64>,
"detectMime": <AutoDetectMimeType int>,
"mimeLimit": "<MimeLimit string>",
"fileType": <fileType int>
字段名
必填
说明
scope
指定上传的目标资源空间 Bucket 和资源键 Key（最大为 750 字节）。有三种格式：<bucket>，表示允许用户上传文件到指定的 bucket。在这种格式下文件只能新增（分片上传 v1 版 需要指定 insertOnly 为 1 才是新增，否则也为覆盖上传），若已存在同名资源（且文件内容/etag不一致），上传会失败；若已存在资源的内容/etag一致，则上传会返回成功。 <bucket>:<key>，表示只允许用户上传指定 key 的文件。在这种格式下文件默认允许修改，若已存在同名资源则会被覆盖。如果只希望上传指定 key 的文件，并且不允许修改，那么可以将下面的 insertOnly 属性值设为 1。 <bucket>:<keyPrefix>，表示只允许用户上传指定以 keyPrefix 为前缀的文件，当且仅当 isPrefixalScope 字段为 1 时生效，isPrefixalScope 为 1 时无法覆盖上传。
isPrefixalScope
若为 1，表示允许用户上传以 scope 的 keyPrefix 为前缀的文件。
deadline
上传凭证有效截止时间。Unix时间戳，单位为秒。该截止时间为上传完成后，在七牛空间生成文件的校验时间，而非上传的开始时间，一般建议设置为上传开始时间 + 3600s，用户可根据具体的业务场景对凭证截止时间进行调整。
insertOnly
限定为新增语意。如果设置为非 0 值，则无论 scope 设置为什么形式，仅能以新增模式上传文件。
endUser
唯一属主标识。特殊场景下非常有用，例如根据 App-Client 标识给图片或视频打水印。
returnUrl
Web 端文件上传成功后，浏览器执行 303 跳转的 URL。通常用于表单上传。文件上传成功后会跳转到 <returnUrl>?upload_ret=<queryString>，<queryString>包含 returnBody 内容。如不设置 returnUrl，则直接将 returnBody 的内容返回给客户端。
returnBody
上传成功后，自定义七牛云最终返回給上传端（在指定 returnUrl 时是携带在跳转路径参数中）的数据。支持魔法变量和自定义变量。returnBody 要求是合法的 JSON 文本。例如 {“key”: $(key), “hash”: $(etag), “w”: $(imageInfo.width), “h”: $(imageInfo.height)}。
callbackUrl
上传成功后，七牛云向业务服务器发送 POST 请求的 URL。必须是公网上可以正常进行 POST 请求并能响应 HTTP/1.1 200 OK 的有效 URL。另外，为了给客户端有一致的体验，我们要求 callbackUrl 返回包 Content-Type 为 “application/json”，即返回的内容必须是合法的 JSON 文本。出于高可用的考虑，本字段允许设置多个 callbackUrl（用英文符号 ; 分隔），在前一个 callbackUrl 请求失败的时候会依次重试下一个 callbackUrl。一个典型例子是：http://<ip1>/callback;http://<ip2>/callback，并同时指定下面的 callbackHost 字段。在 callbackUrl 中使用 ip 的好处是减少对 dns 解析的依赖，可改善回调的性能和稳定性。指定 callbackUrl，必须指定 callbackbody，且值不能为空。
callbackHost
上传成功后，七牛云向业务服务器发送回调通知时的 Host 值。与 callbackUrl 配合使用，仅当设置了 callbackUrl 时才有效。
callbackBody
上传成功后，七牛云向业务服务器发送 Content-Type: application/x-www-form-urlencoded 的 POST 请求。业务服务器可以通过直接读取请求的 query 来获得该字段，支持魔法变量和自定义变量。callbackBody 要求是合法的 url query string。例如key=$(key)&hash=$(etag)&w=$(imageInfo.width)&h=$(imageInfo.height)。如果callbackBodyType指定为application/json，则callbackBody应为json格式，例如:{“key”:"$(key)",“hash”:"$(etag)",“w”:"$(imageInfo.width)",“h”:"$(imageInfo.height)"}。
callbackBodyType
上传成功后，七牛云向业务服务器发送回调通知 callbackBody 的 Content-Type。默认为 application/x-www-form-urlencoded，也可设置为 application/json。
persistentOps
资源上传成功后触发执行的预转持久化处理指令列表。fileType=2或3（上传归档存储或深度归档存储文件）时，不支持使用该参数。支持魔法变量和自定义变量。每个指令是一个 API 规格字符串，多个指令用;分隔。请参阅persistenOps详解与示例。同时添加 persistentPipeline 字段，使用专用队列处理，请参阅persistentPipeline。
persistentNotifyUrl
接收持久化处理结果通知的 URL。必须是公网上可以正常进行 POST 请求并能响应 HTTP/1.1 200 OK 的有效 URL。该 URL 获取的内容和持久化处理状态查询的处理结果一致。发送 body 格式是 Content-Type 为 application/json 的 POST 请求，需要按照读取流的形式读取请求的 body 才能获取。
persistentPipeline
转码队列名。资源上传成功后，触发转码时指定独立的队列进行转码。为空则表示使用公用队列，处理速度比较慢。建议使用专用队列。
forceSaveKey
saveKey的优先级设置。为 true 时，saveKey不能为空，会忽略客户端指定的key，强制使用saveKey进行文件命名。参数不设置时，默认值为false
saveKey
自定义资源名。支持魔法变量和自定义变量。forceSaveKey 为false时，这个字段仅当用户上传的时候没有主动指定 key 时起作用；forceSaveKey 为true时，将强制按这个字段的格式命名。
fsizeMin
限定上传文件大小最小值，单位Byte。小于限制上传文件大小的最小值会被判为上传失败，返回 403 状态码
fsizeLimit
限定上传文件大小最大值，单位Byte。超过限制上传文件大小的最大值会被判为上传失败，返回 413 状态码。
detectMime
开启 MimeType 侦测功能，并按照下述规则进行侦测；如不能侦测出正确的值，会默认使用 application/octet-stream 。设为非 0 值，则忽略上传端传递的文件 MimeType 信息，并按如下顺序侦测 MimeType 值：1. 侦测内容；2. 检查文件扩展名；3. 检查 Key 扩展名。 默认设为 0 值，如上传端指定了 MimeType 则直接使用该值，否则按如下顺序侦测 MimeType 值：1. 检查文件扩展名；2. 检查 Key 扩展名；3. 侦测内容。
mimeLimit
限定用户上传的文件类型。指定本字段值，七牛服务器会侦测文件内容以判断 MimeType，再用判断值跟指定值进行匹配，匹配成功则允许上传，匹配失败则返回 403 状态码。示例：image/* 表示只允许上传图片类型 image/jpeg;image/png 表示只允许上传 jpg 和 png 类型的图片 !application/json;text/plain 表示禁止上传 json 文本和纯文本。注意最前面的感叹号！
fileType
文件存储类型。0 为标准存储（默认），1 为低频存储，2 为归档存储，3 为深度归档存储。
使用说明：
Key 必须采用 utf-8 编码，使用非 utf-8 编码的资源名访问时会报错。
callbackUrl 与 callbackBody 配合使用，returnUrl 与 returnBody 配合使用，callbackXXX 与 returnXXX 不可混用。当同时设置 returnUrl 和 callbackUrl 字段时，优先启用 callbackUrl 回调并返回 callbackBody（未设置则返回内容为空），更多详情请见自定义响应。
文件上传后的命名将遵循以下规则：
源 Bucket 和目标 Bucket 必须在同一区域，即处理结果不能跨区域另存。
forceSaveKey=false，以客户端指定的 Key 为高优先级命名
客户端已指定 Key，以 Key 命名
客户端未指定 Key，上传策略中设置了 saveKey，以 saveKey 的格式命名。
客户端未指定 Key，上传策略中未设置 saveKey，以文件 hash(etag) 命名。
forceSaveKey=true，以上传策略中的 saveKey 为高优先级命名；此时上传策略中的 saveKey 不允许为空
客户端已指定 Key，以上传策略中 saveKey 的格式命名
客户端未指定 Key，以上传策略中 saveKey 的格式命名
文件分片上传的创建文件步骤中。若未指定 Key，为达到不覆盖同名资源效果，必须使用 insertOnly 字段。
persistentOps 详解
persistentOps 字段用于指定预转数据处理命令和保存处理结果的存储空间与资源名。在上传归档存储或深度归档存储文件（fileType=2或3）时，不支持使用该字段。
为此字段指定非空值，则在成功上传一个文件后，会启动一个异步数据处理任务。persistentId 字段，唯一标识此任务。
当 returnBody 中指定了 persistentId 魔法变量时，客户端收到的响应内容 returnBody 中会有 persistentId；当没有指定 returnBody 时，默认也会返回 persistentId。
使用默认的存储空间和资源名
当只指定了数据处理命令时，服务端会选择上传文件的 Bucket 作为数据处理结果的存储空间，Key 由七牛服务器自动生成。
使用指定的存储空间和资源名
在数据处理命令后用管道符|拼接saveas/<encodedEntryURI>指令，指示七牛服务器使用EncodedEntryURI格式中指定的 Bucket 与 Key 来保存处理结果（需要注意的是，如果指定的 Bucket 中存在同 Key 的文件将会被处理结果覆盖）。如 avthumb/flv|saveas/cWJ1Y2tldDpxa2V5，是将上传的视频文件转码 flv 格式后存储为qbucket:qkey，其中cWJ1Y2tldDpxa2V5是qbucket:qkey的URL安全的Base64编码结果。以上方式可以同时作用于多个数据处理命令，用;分隔，如 avthumb/mp4|saveas/cWJ1Y2tldDpxa2V5;avthumb/flv|saveas/cWJ1Y2tldDpxa2V5Mg==
示例
persistentOps与persistentNotifyUrl字段
上传一个视频资源，并在成功后触发两个预转处理（转成 mp4 资源和对原资源进行 HLS 切片）：
"scope": "qiniu-ts-demo",
"deadline": 1390528576,
"persistentOps": "avthumb/mp4;avthumb/m3u8/noDomain/1/segtime/15/vb/440k",
"persistentNotifyUrl": "http://fake.com/qiniu/notify"
关于 avthumb 接口的详细信息请参阅音视频转码。
以上内容是否对您有帮助？
文档反馈
(如有产品使用问题，请 提交工单)
提交
服务•咨询
售前 立即咨询
售后 提交工单
回到顶部
×
产品及服务咨询
提交成功！
提交失败，稍后重试！
此表单仅用于产品及服务售前咨询（您也可以拨打400-808-9176转2）
如有售后技术咨询，请提交工单
咨询内容*
请填写咨询内容
最多可输入255字
姓名*
请填写姓名
公司名称
省份*
联系电话*
请以正确的格式填写联系电话
电子邮箱*
请填写电子邮箱
提交
© 2022 七牛云
七牛官网
开发者平台
问答社区
技术支持
服务状态
七牛标识
沪公网安备 31011502000961 号
沪 ICP 备 11037377 号-5