Appearance
简介
Flyme云对象存储FOS(Flyme Object Storage),是Flyme云对外提供的稳定、安全、高效以及高扩展存储服务,支持文本、多媒体、二进制等任何类型的数据存储。数据多地域跨集群的存储,以实现资源统一利用,降低使用难度,提高工作效率。用户可以通过本文档提供的简单的RESTful API接口,进行资源管理以及数据上传下载等操作。
服务域名
规范化字符串(UrlEncode)
通常一个字符串中可以包含任何Unicode字符。在编程中这种灵活性会带来不少困扰。因此引入“规范字符串”的概念。一个规范字符串只包含百分号编码字符以及URI(Uniform Resource Identifier)非保留字符(Unreserved Characters)。 RFC 3986规定URI非保留字符包括以下字符:字母(A-Z,a-z)、数字(0-9)、连字号(-)、点号(.)、下划线(_)、波浪线(~)。 将任意一个字符串转换为规范字符串的方式是:
- 将字符串转换成UTF-8编码的字节流。
- 保留所有URI非保留字符原样不变。
- 对其余字节做一次RFC 3986中规定的百分号编码(Percent-Encoding),即一个%后面跟着两个表示该字节值的十六进制字母。字母一律采用大写形式。示例: 原字符串:this is an example for 测试, 对应的规范字符串:this%20is%20an%20example%20for%20%E6%B5%8B%E8%AF%95。
说明: 下面这段sample代码以java为例演示如何进行UrlEncode。其中input为输入字符串,encodeSlash用来控制是否对"/"进行编码。在有些情况下,做UrlEncode时需要忽略"/",具体情况可以参见“编码规范”。
java
public static String uri_encode(CharSequence input, boolean encodeSlash) {
StringBuilder result = new StringBuilder();
for (int i = 0; i < input.length(); i++) {
char ch = input.charAt(i);
if ((ch >= 'A' && ch <= 'Z') || (ch >= 'a' && ch <= 'z') || (ch >= '0' && ch <= '9') || ch == '_' || ch == '-' || ch == '~' || ch == '.') {
result.append(ch);
} else if (ch == '/') {
result.append(encodeSlash ? "%2F" : ch);
} else {
result.append(toHexUTF8(ch));
}
}
return result.toString();
}
编码规范
- 可解析内容,所有request/response body内容目前均使用UTF-8编码。
- 在请求时,需要对以下做UrlEncode:
- Objectname,其中,Resource做UrlEncode的时候需要忽略“/”。
- Querystring的Value。
- x-ic-copy-source(忽略“/”)。
- 自定义Meta:Meta Value只支持可见的ASCII字符,如果需要其它的字符,推荐使用UrlEncode处理。
资源数目及大小规范
- 租户可有的Bucket数目500。如果需要更多bucket,可以通过工单系统申请。
- Bucket中的Object数不限。
- 支持单个Object最大为48.8TB。
- 用户请求Header大小不得超过8KB。其中用户自定义Meta(x-ic-meta-)不得超过2KB;Meta值不能为空,且只支持ASCII格式。
命名规范
- Bucket格式要求:
- 只能包括小写字母,数字和连字符“-”。
- Bucket名开头和结尾必须是小写字母或数字。
- 长度为3~63位。
- Object格式要求:
- 长度不能超过1024个字节的UTF-8字符。
日期与时间
日期与时间的表示有多种方式。为统一起见,除非是约定俗成或者有相应规范的,凡是HTTP标准中规定的表示日期和时间字段用GMT,其他日期时间表示的地方一律采用UTC时间,遵循ISO 8601,并做以下约束:
- 表示日期一律采用YYYY-MM-DD方式,例如2014-06-01表示2014年6月1日。
- 表示时间一律采用hh:mm:ss方式,并在最后加一个大写字母Z表示UTC时间。例如23:00:10Z表示UTC时间23点0分10秒。
- 凡涉及日期和时间合并表示时,在两者中间加大写字母T,例如2014-06-01T23:00:10Z表示UTC时间2014年6月1日23点0分10秒。
接口规范
请求响应格式标准
- HTTP请求,Querystring中参数的Key,为首字母小写的驼峰方式。如 upLoadId,partNumber等。
- 所有用户自定义Meta,以x-ic-meta-*的形式放Header中,自定义Meta总大小不得超过2K。x-ic-meta-*的Key会被Server端统一按照小写进行处理。
例如:用户使用PutObject接口上传了x-ic-meta-DeMo:value,Server端会统一按照小写x-ic-meta-demo:value进行处理,用户在使用GetObject接口时,Sever端的返回值为x-ic-meta-demo:value。
- 除RFC2616规定的标准Header外,其他Header以x-ic-*的形式定义。
- FOS的RESTful API支持仅支持JSON形式。
- 所有JSON中,Key均为首字母小写的驼峰方式。
- 每个请求响应中均带有x-ic-request-id和x-ic-debug-id这两个Header。
- Header中Date、Content-MD5、Content-Type、Content-Length等相关字段遵守RFC 2616约束。
- 依据HTTP协议的规定,Content-MD5既要做MD5也要进行Base64编码,其计算方法如下:Content-MD5 = "Content-MD5" ":" md5-digest md5-digest = <base64 of 128 bit MD5 digest as per RFC 1864>
公共请求头
名字 | 类型 | 描述 |
---|---|---|
Authorization | String | 用于验证请求合法性的认证信息。更多参见鉴权认证 |
Content-Length | String | RFC2616中定义的HTTP请求内容的长度。 |
Content-Type | String | RFC2616中定义的HTTP请求内容的类型。 |
Content-MD5 | String | RFC2616定义的HTTP请求内容的MD5摘要,可以通过携带该字段来验证保存在FOS侧的文件和用户预期的文件是否一致。 |
Date | String | HTTP 1.1协议中规定的GMT时间,如Wed, 06 Apr 2016 06:34:40 GMT。 |
Host | String | 访问Host值,取值为BucketName.fos.flyme.com。 |
x-ic-date | String | 当前时间,遵循ISO8601规范,格式如2016-04-06T08:23:49Z。 |
公共返回头
名字 | 类型 | 描述 |
---|---|---|
Content-Length | String | RFC2616中定义的HTTP请求内容长度。 |
Content-Type | String | RFC2616中定义的HTTP请求内容的类型。 |
Content-MD5 | String | RFC2616定义的HTTP请求内容的MD5摘要,可以通过携带该字段来验证保存在FOS侧的文件和用户预期的文件是否一致。 |
Connection | String | 服务器是否断开连接,取值为close或者keep-alive。 |
Date | String | HTTP 1.1协议中规定的GMT时间,如Wed, 06 Apr 2016 06:34:40 GMT。 |
eTag | String | Object的HTTP协议实体标签。eTag (entity tag) 在每个Object生成的时候被创建,用于标识一个Object的内容,eTag值可以用于检查Object内容是否发生变化。 |
Server | String | 服务器的名字,取值为FceFos。 |
x-ic-request-id | String | 由FCE FOS创建,是请求FceFos的唯一标识。 |
x-ic-debug-id | String | 由FCE FOS创建,用于帮助排除故障的标识ID,如果在使用FOS过程中遇到问题,可以在工单中提供该字段便于快速定位问题。 |
错误码
错误信息格式
当用户访问FOS出现错误时,FOS会返回给用户相应的错误码和错误信息,便于用户定位问题,并做出适当的处理。 系统返回错误信息格式如下:
json
{
"code": "NoSuchKey",
"message": "The resource you requested does not exist",
"requestId": " 4db2b34d-654d-4d8a-b49b-3049ca786409"
}
FOS错误码
其中code、message字段定义如下:
错误码(code) | 消息(message) | 描述 | HTTP状态码 |
---|---|---|---|
success | success | 成功 | 200 OK |
success | Both this request and DPF request executed successfully. | 请求执行成功 | 200 OK |
success | This request executed successful, but the DPF request is failed. | 请求执行成功,但DPF执行失败 | 203 Non-Authoritative Information |
success | This request executed successful, but the third-party platform executed failed. | 请求执行成功,第三方执行失败 | 203 Non-Authoritative Information |
success | This request executed successful, but your dpf format is invalid. | 请求执行成功,DPF格式无效 | 203 Non-Authoritative Information |
success | Callback failed. | 回调失败 | 203 Non-Authoritative Information |
success | Encrypt failed. | 加密失败 | 203 Non-Authoritative Information |
success | Payload too large. | 有效载荷过大 | 203 Non-Authoritative Information |
InvalidEncryptionAlgorithm | The specified encryption algorithm is invalid | 加密算法无效 | 400 Bad Request |
InvalidEncryptionCustomerKey | The specified encryption customer-key is invalid, encrypt object by customer key md5 not match | 加密密钥无效,密钥md5不匹配。 | 400 Bad Request |
InvalidEncryptionKmsMkid | The specified encryption kms mkid is invalid, please check its status | 指定的加密KMS MKID无效,请检查其状态 | 400 Bad Request |
InvalidTargetType | The specified object key is symlink, target object of symlink also is symlink. | 软链接文件不支持再次设置软链接 | 400 Bad Request |
InvalidEncryptionScheme | The specified encryption scheme is invalid, encrypt object by customer key must use https request | 加密Object必须使用HTTPS请求 | 400 Bad Request |
success | This request executed successful, but the dpf executed failed because the assumerole configuration you set is invalid. | 请求执行成功,但DPF执行失败,因为处理用户权限失败。 | 203 Non-Authoritative Information |
AccessDenied | Access Denied. | 拒绝访问 | 403 Forbidden |
AccountOverdue | Your request is denied because there is an overdue bill of your account. | 用户欠费 | 403 Forbidden |
AccessDeniedBySourceUrl | Access Denied By Source Url. | 源URL拒绝访问 | 403 Forbidden |
BadDigest | The Content-MD5 or x-ic-content-sha256 or x-ic-content-crc32 you specified did not match what we received. | 摘要错误,用户指定的md5或者sha256或者crc32与服务端计算不一致。 | 400 Bad Request |
BadDigestMD5 | The Content-MD5 you specified did not match what we received. | 错误的Content-MD5字段,与实际上传的数据MD5不符 | 400 Bad Request |
BadDigestSHA256 | The x-ic-content-sha256 you specified did not match what we received. | 错误的x-ic-content-sha256字段,与实际上传的数据sha256不符 | 400 Bad Request |
BadDigestCRC32 | The x-ic-content-crc32 you specified did not match what we received. | 错误的x-ic-content-crc32字段,与实际上传的数据crc32不符 | 400 Bad Request |
BucketAlreadyExists | The requested bucket name is not available. The bucket namespace is shared by all users of the system. Please select a different name and try again. | Bucket已经存在 | 409 Conflict |
ObjectLockAlreadyInProgress | The bucket lock status is already InProgress | Bucket已经为锁定状态 | 409 Conflict |
BucketNotEmpty | The bucket you tried to delete is not empty. | 试图删除一个不为空的bucket | 409 Conflict |
ClientSocketError | clinet socket error, maybe client close connection. | 客户端连接失败,可能是客户端关闭了连接。 | 200 OK |
CORSConfigurationDoesNotMatch | The CORS Options request is not allowed because the request does not match with the CORS Configuration of the resource. | 请求资源与CORS配置不匹配 | 403 Forbidden |
CORSNotEnabled | The CORS is not enabled for this resource. | 未配置允许跨域访问 | 403 Forbidden |
ReplicationNotEnabled | The Bucket Replication is not enabled. | 跨区域数据同步未开启 | 404 Not Found |
UserQuotaNotConfigured | The user quota does not configured | 未配置用户配额 | 404 Not Found |
ReplicationStatusError | The Bucket Replication Status is not correct. Please make sure both the source and dest bucket have no enabled replication conf and both are not the dest replication bucket of other bucket | 跨区域复制源Bucket或目标Bucket已经在另一条跨区域复制规则中被指定 | 409 Conflict |
ReplicationStatusNotEmpty | The bucket you tried to delete has an enabled replication conf or is a dest replication bucket of other bucket | 待删除的Bucket开启了跨区域复制功能。 | 409 Conflict |
InventoryStatusError | The Bucket Inventory Status is not correct. Please make sure dest bucket is same region! | 文件清单状态异常。请确保目的bucket在同地域。 | 409 Conflict |
ReplicationApiUsedInvalid | The replication api must upgrade,because you have used multi rules | 跨区域复制API版本需要更新 | 409 Conflict |
ReplicationConfDuplicate | The replication has exist with different id | 跨区域复制配置重复 | 409 Conflict |
EmptyHTTPAuthHeader | The HTTP authorization header is empty. We do not allow using Session Token with empty authorization header | sts签名请求中,缺少authorization请求header | 400 Bad Request |
EntityTooSmall | Your proposed upload is smaller than the minimum allowed object size. | 上传的数据小于限制 | 400 Bad Request |
EntityTooLarge | Your proposed upload exceeds the maximum allowed object size. | 上传的数据大于限制 | 400 Bad Request |
CapacityExceeded | Your total upload bytes exceeds the maximum allowed in your account. | 超出账号容量限制 | 403 Forbidden |
BucketObjectNumExceeded | Your total upload object number exceeds the maxinum in your bucket | 超出Bucket文件数量限制 | 403 Forbidden |
BucketCapacityExceeded | Your total upload bytes exceeds the maximum allowed in your bucket | 超出Bucket容量限制 | 403 Forbidden |
ObjectNumExceeded | Your total upload object number exceeds the maxinum in your account | 超出账号文件数量限制 | 403 Forbidden |
BucketQuotaNotConfigured | The bucket quota does not configured | 未配置Bucket配额 | 404 Not Found |
FetchObjectTaskIsRunning | The fetch object task you submit is running. | FetchObject进行中 | 200 OK |
FetchObjectFailed | Fetch object failed, please check argument. | 文件抓取失败 | 400 Bad Request |
FileAlreadyExists | The object you specified already exists and can not be overwritten. | 指定的文件已存在,无法覆盖 | 409 Conflict |
InappropriateJSON | The JSON you provided was well-formed and valid, but not appropriate for this operation. | 请求中的JSON格式正确,但语义上不符合要求。如缺少某个必需项,或者值类型不匹配等。 | 400 Bad Request |
InappropriateXML | The XML you provided was well-formed and valid, but not appropriate for this operation. | 请求中的XML格式正确,但语义上不符合要求。适用场景同InappropriateJSON | 400 Bad Request |
InvalidAccessKeyId | The BCS Access Key Id you provided does not exist in our records. | 提供的Access Key不存在 | 403 Forbidden |
InvalidArgument | Invalid Argument. | 无效参数 | 400 Bad Request |
InvalidBucketName | The specified bucket is not valid. | Bucket名称不正确 | 400 Bad Request |
InvalidCopyDestination | The copy destination is not valid | 复制的目标对象无效 | 400 Bad Request |
InvalidCORSRequest | The CORS request is not valid | 跨域请求错误 | 400 Bad Request |
InvalidDomain | The specified domain is not valid. | 域名不正确 | 400 Bad Request |
InvalidHTTPAuthHeader | The HTTP authorization header is invalid. Consult the service documentation for details. | 请求头Authorization无效 | 400 Bad Request |
InvalidImageFormat | Your image format is invalid. | 图片格式不正确 | 400 Bad Request |
InvalidObjectName | Your object key is too long. | 文件名长度超过限制 | 400 Bad Request |
InvalidTrashDirectoryName | Your trash directory name is not valid. | 回收站路径不正确 | 400 Bad Request |
InvalidDirectory | Directory file must be empty | 目录文件必须为空 | 400 Bad Request |
ObjectLockNotLocked | The object lock is not locked, can not extend retentionday | 文件未被锁定,无法延长保留期限 | 400 Bad Request |
InvalidPart | One or more of the specified parts could not be found. The part might not have been uploaded, or the specified entity tag might not have matched the part's entity tag. | 找不到指定的分块。该分块可能未上传或指定的etag与分块不匹配。 | 400 Bad Request |
InvalidPartOrder | The list of parts was not in ascending order.Parts list must specified in order by part number. | 分块列表未按升序排列 | 400 Bad Request |
InvalidPolicyDocument | The content of the form does not meet the conditions specified in the policy document. | Policy格式错误 | 400 Bad Request |
InvalidRange | The requested range cannot be satisfied. | 请求的Range范围无效 | 416 Range Not Satisfiable |
InvalidSessionToken | The Session Token you provided is not valid. Please double check that you are using the correct Session Token obtained from STS (Security Token Service) | STS Token无效 | 400 Bad Request |
InvalidURI | Could not parse the specified URI. | URI形式不正确 | 400 Bad Request |
InvalidStaticWebSiteFormat | The format of index file or 404 file are not allowed. | 不允许的index或者404文件名或格式。 比如:文件格式不允许,或者index与404文件同名。 | 400 Bad Request |
InvalidJobStatus | The current job status does not supprot the operation. | 当前任务状态不支持操作 | 400 Bad Request |
InvalidStorageClass | The storage class specified is invalid, please check argument and consult the service documentation. | 指定的存储类型错误 | 400 Bad Request |
NotSupportStorageClass | The storage class specified is not support, please check argument and consult the service documentation. | 指定的存储类型错误 | 501 Not Implemented |
NotAllowShortenRetentionday | Could not shorten retentionday | 不允许缩短合规保留期限 | 400 Bad Request |
InvalidVersion | The API version specified was invalid. | API版本错误 | 404 Not Found |
RequestRateLimitExceeded | Your request rate is too high. We have put limits on your bucket. | 请求速度太快并触发限速 | 429 Too Many Requests |
MalformedJSON | The JSON you provided was not well-formed. | JSON格式不正确 | 400 Bad Request |
MalformedXML | The XML you provided was not well-formed or did not validate against our published schema. | XML格式不正确 | 400 Bad Request |
MaxMessageLengthExceeded | Your request was too big. | 请求体过大 | 400 Bad Request |
MetadataTooLarge | Your metadata headers exceed the maximum allowed metadata size. | 超出metadata大小限制 | 400 Bad Request |
MethodNotAllowed | The specified method is not allowed against this resource. | 请求方法错误 | 405 Method Not Allowed |
MirrorFailed | Mirroring failed, please check your mirror configuration. | 镜像回源失败 | 424 Failed Dependency |
MissingContentLength | You must provide the Content-Length HTTP header. | 未提供Content-Length | 411 Length Required |
MissingDateHeader | Request must have a "date" or "x-ic-date" header. | 请求中找不到date和x-ic-date两者之一;如果同时添加了date和x-ic-date,则x-ic-date的优先级高于date,二者的格式请参考:\ndate: Wed, 06 Apr 2016 06:34:40 GMT\nx-ic-date: 2016-04-06T08:23:49Z | 400 Bad Request |
NoSuchBucket | The specified bucket does not exist. | Bucket不存在 | 404 Not Found |
NoSuchInventoryConfiguration | The specified inventory configuration does not exist. | 清单配置不存在 | 404 Not Found |
NoSuchCORSConfiguration | The CORS configuration does not exist. | 未配置跨域规则 | 404 Not Found |
NoLifecycleConfiguration | The lifecycle configuration does not exist. | 未配置生命周期规则 | 404 Not Found |
NoProcessConfiguration | The process configuration does not exist. | 数据处理配置不存在 | 404 Not Found |
NoNotificationConfiguration | The notification configuration does not exist. | 未配置事件通知规则 | 404 Not Found |
NoReplicationConfiguration | The Replication configuration does not exist. | 未配置跨区域复制 | 404 Not Found |
NoSuchKey | The specified key does not exist. | 不存在该Object | 404 Not Found |
NoSuchStyle | The specified style does not exist. | 图片样式不存在 | 404 Not Found |
NoSuchObjectLock | The specified object lock does not exist. | 合规保留配置不存在 | 404 Not Found |
NoSuchJob | The job does not exist. | 批处理任务不存在 | 404 Not Found |
NoSuchUpload | The specified multipart upload does not exist. The upload ID might be invalid, or the multipart upload might have been aborted or completed. | 该uploadId所对应的三步上传不存在。uploadId错误或者三步上传已中止或者已完成。 | 404 Not Found |
NoCopyrightProtectionConfiguration | The copyright protection configuration does not exist. | 未配置版权保护 | 404 Not Found |
NoSuchBucketEncryption | The bucket is not encrypted. | 该Bucket未加密 | 404 Not Found |
NoSuchBucketTrashDirectory | The bucket does not activate trash, or trash has been turned off | 未开启回收站 | 404 Not Found |
NoSuchBucketAlias | The bucket does not activate alias, or bucket alias has been turned off | Bucket别名不存在 | 404 Not Found |
NoSuchBucketDefaultStyle | The bucket does not activate default style, or bucket default style has been turned off | Bucket默认样式不存在 | 404 Not Found |
NoSuchBucketStaticWebSiteConfig | The static web site configuration does not exist. | Bucket 没有开启静态托管 | 404 Not Found |
StaticWebSiteIsDisable | Static web site is disabled or not implemented. | 静态网站托管功能被禁止。 如:即FOS不允许此region的bucket 开启静态网站托管功能,或者静态网站托管功能未上线。 | 501 Not Implemented |
NotImplemented | A header you provided implies functionality that is not implemented. | 系统未实现 | 501 Not Implemented |
NotSymlink | The specified object key is not symlink. | 文件不是软链接类型 | 400 Bad Request |
SymlinkTargetNotExist | The specified object key is symlink, target object of symlink does not exist. | 软链接目标文件不存在 | 404 Not Found |
PreconditionFailed | The specified If-Match header doesn't match the header you provided. | 指定的If-Match请求头与用户提供的不匹配。 | 412 Precondition Failed |
OptInRequired | You must active fos service. | FOS服务未开启,请开通FOS服务且确保账户未欠费。 | 403 Forbidden |
RequestExpired | Request has expired. Timestamp date is XXX. | 请求的时间戳过期。请求超时,XXX要改成x-ic-date的值。如果请求中只有Date,则需要将Date转换为本规范指定的格式。 | 403 Forbidden |
RequestTimeout | Your socket connection to the server was not read from or written to within the timeout period. | 请求超时 | 408 Request Timeout |
RequestTimeTooSkewed | The difference between the request time and the server's time is too large. | 请求时间与服务器时间差异过大 | 403 Forbidden |
ObjectTooSmallToProcess | Object is too small to process. | 文件过小,无法进行处理 | 400 Bad Request |
ObjectTooLargeToProcess | Object is too large to process. | 文件过大,无法进行处理 | 400 Bad Request |
VideoSnapshotFail | Handle video snapshot fail | 视频截帧失败 | 400 Bad Request |
VideoRealtimeCodecFail | Handle video codec fail | 视频转码失败 | 400 Bad Request |
VideoInfoFail | Handle video info fail | 获取视频信息失败 | 400 Bad Request |
SignatureDoesNotMatch | The request signature we calculated does not match the signature you provided. Check your Secret Access Key and signing method. Consult the service documentation for details. | Authorization头域中附带的签名和服务端验证不一致 | 403 Forbidden |
ServiceUnavailable | Please reduce your request rate. | 服务不可用 | 503 Service Unavailable |
SlowDown | Please reduce your request rate. | 请求过于频繁 | 503 Service Unavailable |
TooManyBuckets | You have attempted to create more buckets than allowed. | 创建的Bucket数量超过限制 | 400 Bad Request |
TooManyConfigurations | You have attempted to create more configurations than allowed. | 创建配置超过限制 | 400 Bad Request |
TooManyStyles | You have attempted to create more styles than allowed. | 创建样式数量超过限制 | 400 Bad Request |
TooManyJobs | You are attempting to create too many jobs. | 创建批处理任务数量超过限制 | 400 Bad Request |
TooManyMultiUploads | You have attempted to do more multipart uploads than allowed. | 上传的分块数量超过限制 | 400 Bad Request |
InvalidContentLength | Invalid Content-Length or Transfer-Encoding. | Content-Length不正确 | 400 Bad Request |
ReadBodyError | Read http body error, please try again. | 读取请求内容错误,请重试 | 400 Bad Request |
DomainAlreadyExists | The specified domain is bound to %s already. | 域名已被绑定到其他bucket | 409 Conflict |
TooManyDomains | You have attempted to bind to more buckets than allowed. | 域名数据超过限制 | 400 Bad Request |
NoSuchDomain | The specified domain does not exist. | 域名不存在 | 404 Not Found |
NoSuchMirroring | The specified mirroring configuration does not exist. | 未配置镜像回源规则 | 404 Not Found |
OffsetIncorrect | Offset not equal to current object length | 追加Appendable Object时,<OffsetSize>值不等于已上传的Object的大小或者<OffsetSize>值不为0但Object不存在 | 409 Conflict |
ObjectUnappendable | The object can not be append | 不能对非Appendable的Object做AppendObject操作 | 403 Forbidden |
NotAllowCopy | This object not allow to copy to another one | 文件不允许复制 | 400 Bad Request |
NotAllowModify | Permission not match, not allow modify object data | 文件不允许修改 | 403 Forbidden |
ObjectIllegal | The Object is illegal | 文件不合规 | 403 Forbidden |
OnlyAllowModify | Permission not match, you only have modify permission, so you can not upload a new object | 权限不匹配,仅支持修改 | 403 Forbidden |
ObjectAclNotPass | The object acl does not pass. | 文件权限不匹配 | 403 Forbidden |
ObjectBanned | Your object contains sensitive information. We have restricted your resources. | 文件已被封禁 | 403 Forbidden |
ObjectLocked | Your object has been locked. | 文件已被锁定,无法进行操作 | 423 Locked |
ObjectLockConflict | You cannot lock/unlock a banned object. | 文件已被封禁 | 403 Forbidden |
ObjectAclNotExists | The object acl does not exist. | 未配置文件权限规则 | 404 Not Found |
InternalError | We encountered an internal error. Please try again. | 内部错误 | 500 Internal Server Error |
PartialContentError | Errors occurred at storage system and return partial content. | 请求时发生错误并返回部分内容 | 510 Not Extended |
NoStorageAnalysisConf | No storage analysis conf is set. | 未设置存储分析配置 | 404 Not Found |
StorageAnalysisConfIdConflict | The confId you provide is confict with existing confs. | 存储分析配置ID与现有配置冲突 | 409 Conflict |
ObjectImmutable | The object is immutable | 已经开启合规保留,文件无法进行删除或修改操作 | 409 Conflict |
ObjectRenameConflict | Object rename conflict occurred, please retry it later or avoid concurrent update. | 重命名文件冲突 | 409 Conflict |
InvalidStorageAnalysisPrefix | The storage analysis prefix you provide is invalid. | 存储分析配置中的文件前缀无效 | 400 Bad Request |
StorageAnalysisConfigNumExceeded | Storage analysis confs have exceeded the max allow num. | 存储分析配置数量超出限制 | 400 Bad Request |
SqlSyntaxError | The sql expression in SelectRequest is invalid, it contains unsupported syntax or incorrect syntax. | SQL语法错误 | 400 Bad Request |
InvalidSqlFields | The field in sql expression is invalid, it contains operators or other literals in SELECT clause. | SQL表达式中字段无效 | 400 Bad Request |
InvalidSqlBinaryExpr | The binary expression in sql is invalid, left operand is incompatible with right operand. | SQL错误 | 400 Bad Request |
SqlFieldsNumExceedLimit | The number of fields in sql expression exceed the maximum allowable number limit. | SQL中的字段数量超过了允许的最大数量限制 | 400 Bad Request |
AggregateInvalidField | The field of aggregate function in the sql is invalid, it is not numeric data type. | SQL中聚合函数错误,使用字段非数值类型。 | 400 Bad Request |
InvalidSqlJsonPathDepth | The depth of json path is invalid, it exceed the maximum limit or less than 1. | SQL错误,json路径的深度无效,超过最大限制或者小于1。 | 400 Bad Request |
SqlSourceNumExceedLimit | Only one source is supported in sql expression. | SQL表达式中仅支持一个数据源 | 400 Bad Request |
RecordTooLarge | The length of record in csv file exceeds limit. | CSV文件长度超过限制 | 400 Bad Request |
FieldNotExist | The field in SQL not exist in file | SQL字段不存在 | 400 Bad Request |
InappropriateJson | The format of json object is inappropriate. | JSON格式错误 | 400 Bad Request |
HeaderNotExist | No valid header info is found in csv file. | CSV文件格式错误 | 400 Bad Request |
DecompressError | Error occurred when decompress object. | 文件解压失败 | 400 Bad Request |
InvalidFileType | The type of file is invalid, only JSON and CSV are supported. | 文件类型错误,仅支持JSON及CSV | 400 Bad Request |
DataOverflowsType | The aggregate result of data overflows data type limit. | 数据聚合结果超出了数据类型的限制 | 400 Bad Request |
InvalidSqlSource | Invalid data source in sql expression SELECT clause, check the sql source format of csv or json object. | 请检查CSV或JSON对象的SQL源格式 | 400 Bad Request |
InvalidSqlLimitValue | The value of LIMIT clause in sql expression is invalid, it must greater than zero. | SQL表达式中LIMIT值无效,必须大于零 | 400 Bad Request |
InvalidSqlNotOperator | The operand of NOT operator is invalid, NOT operator only can be followed by BETWEEN/IN/LIKE. | SQL错误,"NOT"操作需要跟随"BETWEEN/IN/LIKE"之后。 | 400 Bad Request |
InvalidSqlBetweenOperator | The operand of BETWEEN operator is invalid, BETWEEN should with AND. | SQL中"BETWEEN"使用错误 | 400 Bad Request |
InvalidSqlInOperator | The values of IN operator are invalid, check values in (……). | SQL中"IN"操作使用错误 | 400 Bad Request |
InvalidSqlIsOperator | The operand of IS operator is invalid, IS operator can only be followed by NULL or NOT NULL. | SQL中"IS"操作使用错误 | 400 Bad Request |
InvalidSqlLikeOperator | The operand of LIKE operator is invalid, LIKE operator can only be followed by string. | SQL中"LIKE"操作使用错误 | 400 Bad Request |
InvalidSqlFunction | The function in sql expression is invalid, check the function parameters number and type. | SQL表达式中的函数无效,请检查函数参数的数量和类型 | 400 Bad Request |
InvalidExpressionParameter | The value of expression parameter in SelectRequest is invalid, please base64 decode it and do not exceed max length limit. | Select扫描请求expression参数错误,请进行base64编码并不超过长度限制。 | 400 Bad Request |
InvalidExpressionTypeParameter | The value of expressionType parameter in SelectRequest is invalid, only SQL expressions are supported. | Select扫描请求expressionType参数错误 | 400 Bad Request |
InvalidCompressionTypeParameter | The value of compressionType parameter in SelectRequest is invalid, only GZIP and NONE are supported. | Select扫描请求compressionType参数错误 | 400 Bad Request |
InvalidJsonTypeParameter | The value of Json type parameter in SelectRequest is invalid, only DOCUMENT/LINES are supported. | Select扫描请求json type参数错误 | 400 Bad Request |
InvalidQuoteFieldsParameter | The value of quote fields parameter in SelectRequest is invalid, only ALWAYS/ASNEEDED are supported. | Select扫描请求quote fields参数错误 | 400 Bad Request |
InvalidSelectRequestJsonBody | Some parameters in SelectRequest json body is invalid, please check all optional and required parameters. | Select扫描请求参数错误 | 400 Bad Request |
StorageAnalysisConfigNumExceeded | Storage analysis confs have exceeded the max allow num. | 存储分析配置超过最大限制 | 400 Bad Request |
NotArchiveObject | Object is not archive storage class. | 当前object不是归档类型文件 | 400 Bad Request |
DuplicationRequest | Duplication request. | 重复请求 | 400 Bad Request |
RestoreAlreadyInProgress | The object is restoring.Don't restore the object again. | 您已经成功调用过RestoreObject接口,FOS服务端正在执行解冻操作。请不要重复执行RestoreObject | 409 Conflict |
RestoreAlready | The object is restored. | 归档文件处于解冻状态,无需重重复调用 | 409 Conflict |
ObjectLockAlreadyLocked | The object lock status is locked. | 合规保留已开启 | 409 Conflict |
ObjectLockAlreadyExpired | The object lock status is expired. | 合规保留已过期 | 409 Conflict |
CasUpdateConflict | An update conflict occurred, please retry it later or avoid concurrent update. | 并发更新冲突,请稍后重试或者避免并发更新。 | 409 Conflict |
InvalidObjectState | The object is freezed or restoring. | 归档类型文件状态不合法,归档文件冰冻中或取回中。 | 403 Forbidden |
访问控制
签名认证访问
Flyme云采用统一的API鉴权认证机制,详情请见鉴权认证机制。
AK/SK鉴权
AK/SK是指您在注册FOS时,系统自动分配给您的AK(Access Key ID)/SK(Secret Access Key),主要用于对用户的调用行为进行鉴权和认证,相当于Flyme云API专用的用户名及密码。您向FOS发送的每个请求,都需要通过鉴权认证通过后,FOS才会处理您的请求。 当您在授权的时候,建议严格遵循最小权限原则,限定用户执行受限的操作(如仅授权读操作)并设置访问指定前缀的资源,避免授予过大的权限,导致预期外的越权操作,造成数据安全风险。
Bucket权限控制
关于权限控制中出现的 grantee 均代表租户ID,非用户ID。目前权限控制暂时只支持到租户级别。
权限控制概述
FOS支持使用ACL对Bucket权限进行管理。Bucket ACL是附属于资源即某个Bucket的权限,其本质上是授权谁(grantee)可以执行哪些操作(permission)。为了方便用户更精细地控制Bucket里的资源,Bucket ACL支持resource和notResource字段。Resource字段用于实现对指定范围的prefix和object粒度的权限控制,notResource字段用户实现对指定范围外的prefix和object粒度的权限控制。 此外,Bucket ACL还支持condition字段,Condition字段可以用来设置访问者的IP、Referer等信息。 为了保障您存储在FOS中数据的高安全性,我们为您提供了丰富的多级权限管理能力。 FOS的权限体系分为如下三级: Bucket标准权限(即CannedACL) 粗粒度自定义权限 FOS目前可以通过上传ACL文件和使用CannedAcl两种方式来设置ACL,两种方式都通过PutBucketAcl接口实现。上传ACL文件是通过一个JSON文件来描述谁(grantee)在什么条件下(condition)可以对什么资源(resource或notResource)执行哪些操作(permission)。直接编辑ACL文件门槛较高,因此FOS还支持CannedAcl方式。CannedAcl本质上就是对几种常见的权限控制场景进行了封装,直接在PutBucketAcl的头域中的“x-ic-acl”字段对资源进行设置。
使用CannedAcl方式的权限控制
CannedAcl是一种方便用户使用的方式,对常见的几种权限情况进行了封装。通过在PutBucketAcl的头域中的“x-ic-acl”字段对该资源进行设0置的。例:x-ic-acl:public-read。字段区分大小写。 当前支持的CannedAcl包括:
ACL | 添加的权限 |
---|---|
private(私有) | Bucket Owner获得FULL_CONTROL,其他人没有任何权限 |
public-read(公共读) | Bucket Owner获得FULL_CONTROL,其他人获得READ权限 |
public-read-write(公共读写) | Bucket Owner获得FULL_CONTROL,其他人获得READ和WRITE权限。注意:该权限安全风险极高。 |
**说明:**通过PutBucket创建的新Bucket权限默认是private。
上传ACL文件方式的权限控制
ACL文件格式
PutBucketAcl可以通过上传一个ACL文件的方式对访问权限进行设置。FOS ACL使用Json格式的策略描述语言,命名方法为首字母小写的驼峰命名格式,字段区分大小写。 字段总览:
字段 | 数据类型 | 说明 | 是否必须 | 父节点 |
---|---|---|---|---|
accessControlList | array | 标识acl主体的开始,由一或多组acl配置项组成,其中acl配置项由grantee+permission+resource+condition组合而成。 | 是 | 无 |
+effect | string | 指定与该条acl配置项匹配的Request能否执行,取值为Allow或Deny。Allow表示可以执行;Deny表示拒绝执行。 | 否 | accessControlList |
+grantee | array | 标识被授权人。 | 是 | accessControlList |
+permission | array | ACL配置项所影响的权限,可选值为READ、LIST、WRITE、和GetObject。权限详细解释请参见"Bucket ACL支持的permission权限"。 | 是 | accessControlList |
+resource | array | ACL配置项所影响的资源,表示对resource指定范围的资源设置访问权限,支持通配符。如:<BucketName> /<ObjectKey> 或<BucketName> /xxx*。 resource不填或填Bucket名称,等同于resource字段设为[<bucketName> , <bucketName> /*],即对Bucket和所有Object设置访问权限。 | 否 | accessControlList |
+notResource | array | ACL配置项所影响的资源,表示对notResource指定范围以外的资源设置访问权限,支持通配符。如:<BucketName> /<ObjectKey> 或<BucketName> /xxx*,表示对BucketName中ObjectKey之外的Object或者以XXX为前缀的Object之外的其他Object设置访问权限。如果notResource字段不填则等同于没有配置notResource,即采用默认配置,对Bucket及所有Object设置访问权限。 | 否 | accessControlList |
+condition | array | ACL配置项所包含的限制条件,支持配置IP地址和Referer名单 | 否 | accessControlList |
++ipAddress | array | 标识授予访问权限的ip | 否 | condition |
++referer | string | 标识授予访问权限的referer | 否 | condition |
+++stringLike | string | 标识referer白名单中模糊匹配的地址 | 否 | referer |
+++stringEquals | string | 标识referer白名单中精确匹配的地址 | 否 | referer |
++secureTransport | bool | 标识是否只允许https方式访问。可选值“true”、"false",不设置时视为“false”。当设置为"true"时,表示只允许https方式访问。 | 否 | condition |
++currentTime | object | condition配置项所包含的时间限制条件,支持配置"dateLessThan","dateLessThanEquals", "dateGreaterThan"和"dateGreaterThanEquals",四个配置项可以任选若干进行设置,匹配有效的条件是所设置配置项均需匹配。 | 否 | condition |
+++dateLessThan | string | 标识授予访问权限的时间小于指定时间。取值为时间字符串,格式符合ISO 8601规范,如“2018-07-01T12:00:00Z” | 否 | currentTime |
+++dateLessThanEquals | string | 标识授予访问权限的时间小于或者等于指定时间。取值为时间字符串,格式符合ISO 8601规范,如“2018-07-01T12:00:00Z” | 否 | currentTime |
+++dateGreaterThan | string | 标识授予访问权限的时间大于指定时间。取值为时间字符串,格式符合ISO 8601规范,如“2018-07-01T12:00:00Z” | 否 | currentTime |
+++dateGreaterThanEquals | string | 标识授予访问权限的时间大于或者等于指定时间。取值为时间字符串,格式符合ISO 8601规范,如“2018-07-01T12:00:00Z” | 否 | currentTime |
说明:
- 所使用的ACL格式如上所述;在上传ACL文件时,可不带Owner属性(json字段标识Bucket的Owner);如果带有Owner属性,则其id值必须为Bucket的Owner id
- 上传的ACL文件不大于20KB。
- 若用户使用PutBucketAcl接口的时候,在Http报文的Header(Canned ACL)和Body中同时设置了ACL,则返回错误码400,错误说明为“参数不正确”。
- 设置currentTime子字段值时,设置的是GMT时间,注意与本地时间的差别。
- 在一条ACL规则中,同时只能存在一个resource或一个notResource的设置。
Bucket ACL支持粗粒度自定义权限 permission本质上对应一组FOS API操作。FOS API分为bucket级别API和object级别的API,如ListObjects用来查看一个bucket中的所有Object列表,是一个bucket级别API,PutObject用来上传一个文件,是一个object级别API。 所以在ACL文件里,当设置好permission后,需要设定相应的resource或notResource。缺省情况下resource字段不填或填bucket名称,就可以同时匹配bucket级别和object级别的所有操作。 Bucket ACL支持如下粗粒度自定义权限:
权限名称 | 权限支持的操作 |
---|---|
READ | 允许读取Bucket内的Object及其相关信息,但没有列表权限,具体操作权限包含GetBucketLocation,HeadBucket,GetObject,GetObjectMeta,ListParts,RestoreObject。READ权限对应的API既有bucket级别的API如GetBucketLocation,也有object级别的API如GetObject和ListParts。 |
LIST | 列表权限,可以查看指定Bucket下的Object列表以及获取所有未执行完的MultipartUpload,具体操作权限包含ListObjects和ListMultipartUploads。LIST权限对应的API只有bucket级别的API。 |
WRITE | 允许创建,覆盖和删除Bucket内的Object,具体操作权限包含PutObject,PostObject,InitiateMultipartUpload,UploadPart,CompleteMultipartUpload,AbortMultipartUpload,AppendObject,DeleteObject,DeleteMultipleObjects |
和FetchObject。WRITE权限对应的API只有object级别。 | |
MODIFY | 用户仅可做PutObject、AppendObject等相关写入操作,不可做数据新增、删除操作。该权限主要功能是与Deny合用防止Bucket数据被篡改 |
FULL_CONTROL | 包含以上所有权限。FULL_CONTROL除了具有READ、LIST和WRITE的所有操作权限以外,还包括以下操作权限PutBucketAcl,GetBucketACL,PutBucketCors,GetBucketCors和DeleteBucketCors。FULL_CONTROL权限对应的API既有bucket级别的API也有Object级别的API。 |
Bucket ACL支持细粒度自定义权限 为了保障您存储在FOS中数据的高安全性和满足您对FOS资源更加细粒度的进行权限访问控制,FOS在支持READ、LIST、WRITE、MODIFY、FULL_CONTROL这几种粗细粒度的基础上,现在扩展支持了各类细粒度权限。 Bucket相关权限说明如下:
Bucket 相关权限 | 支持的操作 |
---|---|
GetBucket | 该权限表示允许用户获取Bucket内容及其相关信息,例如,列出Bucket下面的Objects、在三步上传时列出Bucket下面的所有未执行完成的Multipart Upload |
GetBucketAcl | 该权限表示允许用户获取Bucket Acl的信息 |
PutBucketAcl | 该权限表示允许用户新增Bucket Acl |
GetBucketCors | 该权限表示允许用户获取Bucket上的跨域资源共享(CORS)的规则 |
PutBucketCors | 该权限表示允许用户在指定的Bucket上设定或者删除一个跨域资源共享(CORS)的规则 |
GetBucketStyle | 该权限表示允许用户获取或者列出Bucket Style的规则 |
PutBucketStyle | 该权限表示允许用户新增或者删除Bucket Style的规则 |
GetBucketMirroring | 该权限表示允许用户获取Bucket镜像回源的相关信息 |
PutBucketMirroring | 该权限表示允许用户新增或者删除Bucket镜像回源的相关信息 |
GetCopyRightProtection | 该权限表示允许用户获取Bucket的原图保护配置的信息 |
PutCopyRightProtection | 该权限表示允许用户开启或者关闭Bucket的原图保护功能 |
Object相关权限说明如下:
Object 相关权限 | 支持的操作 |
---|---|
PutObject | 该权限表示允许用户进行上传Object的相关操作,例如PutObject、PostObject、AppendObject、FetchObject、CopyObject、三步上传、三步Copy |
GetObject | 仅支持GetObject和GetObjectMeta操作。GetObject权限对应的API只有object级别。 |
RestoreObject | 该权限表示允许用户取回归档类型文件 |
DeleteObject | 该权限表示允许用户进行删除单个Object或者批量删除Object的相关操作 |
RenameObject | 该权限表示允许用户对Object进行重命名(Rename) |
ListParts | 该权限表示允许用户列出三步上传过程中指定的UploadId所有已经上传成功的Part,用户可以查看三步上传的当前进度 |
GetObjectAcl | 该权限表示允许用户获取Object Acl |
PutObjectAcl | 该权限表示允许用户新增Object Acl和删除Object Acl |
说明:
- 新增的粗细粒度和以前的READ、LIST、WRITE、FULL_CONTROL、MODIFY、GetObject、RestoreObject这几种粗细粒度互不影响,其中READ,WRITE,LIST,FULL_CONTROL, MODIFY属于粗粒度权限。
- 粗粒度权限高于细粒度权限,如果既配了粗粒度权限又配了细粒度权限,粗粒度权限会覆盖细粒度权限,以粗粒度为主。
- Bucket级别的细粒度是指对Bucket进行的相关操作。
- Object级别的细粒度是指对Object进行的相关操作。
Bucket ACL支持Deny和数据防篡改 Bucket Acl同时支持effect字段,用于设置该条权限的效果,effect支持Allow和Deny这两种配置方式。 说明:
- 在不配置effect的情况下,默认情况下是隐式Allow。在配置effect的情况下,当值为Allow时是显式Allow;在不配置effect和配置effect并且其值为Allow的况下,这两种情况是等价的。
- Deny的语义高于Allow,当用户既配了Allow也配了Deny的情况下,以Deny为准,拒绝通过;Deny了粗粒度权限,不管细粒度权限是否允许,都不允许通过。
- Allow了粗粒度权限,但是Deny了细粒度权限,那么就取粗粒度与细粒度的差集,差集部分的操作是允许通过的。
- 目前READ、LIST、WRITE、FULL_CONTROL、MODIFY权限为粗粒度权限,其余的权限可以归结为细粒度权限。
为了解决由于密钥泄露、权限控制不严格、操作失误等带来的数据删除、篡改风险,FOS推出Bucket数据防篡改的功能,通过在Bucket Acl设置MODIFY粗粒度权限和Deny关键字组合就可以起到Bucket数据防篡改的效果。 目前涉及到写的粗粒度有WRITE、FULL_CONTROL、MODIFY,细粒度有PutObject、RenameObject、DeleteObject。 MODIFY的使用方式主要有两大类,Allow和Deny这两种。 说明:
- 写操作,包括新增操作、覆盖操作和删除操作,新增操作是指:新上传一个Object,这个Object以前是不存在的,覆盖操作是指:上传一个Object,这个Object以前是存在的。
- MODIFY粗粒度写权限包含RenameObject细粒度写权限和PutObject细粒度写权限下面的部分操作,如PutObject、PostObject、AppendObject、CopyObject、FetchObject、MultiUploadInitObject等
- 如果配置允许了PutObject、RenameObject、DeleteObject、WRITE、FULL_CONTROL几种写粒度之中的任意一种,并且没有配置Deny MODIFY,那么允许用户进行正常的写操作。
Allow的示例如下表所示:
MODIFY配置为Allow的示例 | 配置示例描述 | 备注 |
---|---|---|
Allow MODIFY | 只配置了Allow MODIFY,没有配置其它写粒度权限 | 这种场景下,只允许覆盖,不允许新增或删除 |
Allow MODIFY + Allow 细粒度写权限 | 配置了Allow MODIFY和细粒度写权限 | 这种场景下,在配置细粒度写权限下的操作允许新增,并且允许任何覆盖操作 |
Allow MODIFY + Allow 粗粒度写权限 | 配置了Allow MODIFY和粗粒度写权限 | 这种场景下,允许任何写操作 |
Allow MODIFY + Allow 粗粒度写权限 + Allow 细粒度写权限 | 配置了Allow MODIFY和粗细粒度写权限 | 这种场景下,允许任何写操作,粗细粒度同时配置时以粗粒度为准 |
Allow MODIFY + Deny 细粒度写权限 | 配置了Allow MODIFY和Deny细粒度写权限 | 这种场景下,不允许新增、删除,在配置细粒度写权限之外的操作允许覆盖 |
Allow MODIFY + Deny 粗粒度写权限 | 配置了Allow MODIFY和Deny粗粒度写权限 | 这种场景下,不允许新增、删除,也不允许覆盖 |
Allow MODIFY + Deny 细粒度写权限 + Allow 粗粒度写权限 | 配置了Allow MODIFY、Deny细粒度写权限和Allow粗粒度写权限 | 这种场景下,在配置细粒度写权限下面对应的操作不可以新增、删除,也不可以覆盖;在配置了细粒度写权限之外的操作允许新增并且允许覆盖 |
Deny的示例如下表所示
MODIFY配置为Deny的示例 | 配置示例描述 | 备注 |
---|---|---|
Deny MODIFY | 只配置了Deny MODIFY,没有配置其它写粒度权限 | 这种场景下,不允许覆盖,允许新增或删除 |
Deny MODIFY + Deny 细粒度写权限 | 配置了Deny MODIFY和细粒度写权限 | 这种场景下,不允许覆盖,在配置细粒度写权限之外的操作允许增加、删除操作 |
Deny MODIFY + Deny 粗粒度写权限 | 配置了Deny MODIFY和粗粒度写权限 | 这种场景下,不允许任何写操作 |
Deny MODIFY + Deny 粗细粒度写权限 | 配置了Deny MODIFY和粗细粒度写权限 | 这种场景下,不允许任何写操作,粗细粒度同时配置时以粗粒度为准 |
Deny MODIFY + Allow 细粒度写权限 | 配置了Deny MODIFY和Allow细粒度写权限 | 这种场景下,在配置了细粒度写权限下面的操作可以新增、删除,不允许覆盖操作 |
Deny MODIFY + Allow 粗粒度写权限 | 配置了Deny MODIFY和Allow粗粒度写权限 | 这种场景下,允许任何新增、删除操作,不允许覆盖操作 |
Deny MODIFY + Deny 细粒度写权限 + Allow 粗粒度写权限 | 配置了Deny MODIFY、Deny细粒度写权限和Allow粗粒度写权限 | 这种场景下,在配置了细粒度写权限下的操作不允许新增、删除,也不允许覆盖;其余的细粒度写权限下面的操作允许新增、删除,但是不允许覆盖 |
数据安全提示: 在您为用户授权时,建议严格遵循最小权限原则,限定用户执行受限的操作并设置访问指定前缀的资源,避免授予过大的权限,导致预期外的越权操作,造成数据安全风险。包括但不限于以下典型场景:
- 粗粒度自定义权限LIST、WRITE操作的安全风险较高,不建议向所有用户授权该操作。
- 授权WRITE操作时,建议避免授权Bucket级别的写权限,建议配置resource字段值精确到BucketName/ObjectName/*。
- 自定义粗粒度权限中,READ权限允许读取Bucket内的Object及其相关信息,但没有列表权限,LIST权限为列表权限,可以查看指定Bucket下的Object列表以及获取所有未执行完的MultipartUpload。建议区分READ权限和LIST权限支持的操作范围,在最小范围内为用户分配权限。
- 多用户共同使用同一个Bucket时,建议通过划分Bucket区域的方式明确用户可访问的资源,授权时精确到BucketName/Userid/*。
请求授权过程
使用ACL对Bucket进行权限管理时,每个Bucket只能有一个ACL文件,但每个ACL里可以有一组或多组ACL配置项用来定义不同用户对不同资源拥有不同操作权限,accessControlList字段用来标识acl主体的开始。ACL文件中的每组ACL配置项由grantee+permission+resource(或notResource)+condition组合而成,如果某个请求能成功授权则需要匹配一组ACL配置项中的所有条件。当一条请求过来时会逐个匹配ACL中的配置项,只要某组ACL配置项中有一个条件没有匹配上则不能通过授权,除非一组ACL配置项中的所有条件匹配上才能完成授权。ACL授权过程如下图: 假定此时ACL文件定义的grantee是*即所有用户,permission是READ,resource是bucket1。
- 如果请求为PutObject即上传文件cat.jpg到bucket1中,该请求会被拒绝,因为PutObject不属于READ permission所包含的API,所以请求不能通过。
- 如果请求为GetObject即从bucket1中下载文件cat.jpg,该请求可以通过授权,因为GetObject对应的permission是READ,匹配ACL中的所有条件,所以通过授权。
说明: CopyObject操作,需要对源Object有READ、GetObject或FULL_CONTROL权限,对目标Object有WRITE或FULL_CONTROL权限。 示例
- 该示例主要讲解grantee和permission的基础用法。假设bucket1的owner希望让另一个Flyme云用户(userId=16147f559dd14bb294175a8bab74ff1f)帮助自己管理bucket1,即设置该用户对bucket1拥有FULL_CONTROL权限,对应的acl文件格式如下:
{
"accessControlList": [
{
"grantee": [
{
"id": "*"
}
],
"permission": [
"FULL_CONTROL"
]
}
]
}
- 该示例主要讲解多个ACL配置项的使用方法。bucket1的owner希望所有人都可以读取bucket的内容,但只有一个Flyme云用户(userid=b124deeaf6f641c9ac27700b41a350a8)能够管理bucket,则设置所有用户为READ权限,而userid=b124deeaf6f641c9ac27700b41a350a8的用户为FULL_CONTROL权限。对应的ACL文件格式如下:
{
"accessControlList": [
{
"grantee": [
{
"id": "b124deeaf6f641c9ac27700b41a350a8"
}
],
"permission": [
"FULL_CONTROL"
]
},
{
"grantee": [
{
"id": "*"
}
],
"permission": [
"READ"
]
}
]
}
- 该示例主要讲解condition字段的使用方法。bucket1的owner允许通过特定IP段的userid=10eb6f5ff6ff4605bf044313e8f3ffa5的用户来管理Bucket,则通过condition定义IP地址段,并授权这些用户FULL_CONTROL权限。对应的ACL文件格式如下:
{
"accessControlList": [
{
"grantee": [
{
"id":"10eb6f5ff6ff4605bf044313e8f3ffa5"
}
],
"permission": [
"FULL_CONTROL"
],
"condition" : {
"ipAddress": [
"192.168.0.0/16",
"192.169.0.*",
"192.170.0.5"
]
}
}
]
}
- 该示例主要讲解condition的secureTransport和currentTime字段的使用方法。bucket1的owner只允许通过https方式在指定时间访问的userid=10eb6f5ff6ff4605bf044313e8f3ffa5的用户来管理Bucket,则通过condition定义secureTransport、currentTime地址段,并授权这些用户FULL_CONTROL权限。对应的ACL文件格式如下:
{
"accessControlList": [
{
"grantee": [
{
"id": "10eb6f5ff6ff4605bf044313e8f3ffa5"
}
],
"permission": [
"FULL_CONTROL"
],
"resource": [
"bucket1/*"
],
"condition": {
"currentTime": {
"dateLessThan": "2020-07-01T12:00:00Z" ,
"dateGreaterThan": "2018-03-01T15:00:00Z"
},
"secureTransport": true
}
}
]
}
- 该示例主要讲解referer字段的使用方法。bucket1的owner允许通过特定IP且referer与配置的白名单匹配的userid=c558855ea8514c299508699b115473ef的用户查看Bucket和Object信息。其中referer字段用来定义允许访问的白名单,stringEquals用于精确匹配,stringLike用于模糊匹配。stringLike中代表0到任意多的字符,最多可以有一个,*可以在字符串的任意位置。对应的ACL文件格式如下:
{
"accessControlList": [
{
"condition": {
"referer": {
"stringLike": [
"http://www.abc.com/*"
],
"stringEquals": [
"http://www.abc.com"
]
},
"ipAddress": [
"192.168.1.1"
]
},
"grantee": [
{
"id": "c558855ea8514c299508699b115473ef"
}
],
"permission": [
"LIST"
],
"resource": [
"bucket1",
"bucket1/*"
]
}
]
}
- 该示例主要讲解resource字段的使用方法。resource字段可以用来对Bucket内的文件和目录(prefix)设置访问权限。 bucket1的owner只允许另一个Flyme云用户(userid=10eb6f5ff6ff4605bf044313e8f3ffa5)对“cook” 为前缀的Object、“edu/” 为前缀的Object和“travel/中国国家地理杂志”这个Object有FULL_CONTROL权限。resource字段的末尾有且只能有一个*。由于resource字段所指定资源是Object,所以只有FULL_CONTROL permission所包含的Object级别的API操作(如PutObject、GetObject、DeleteObject)会被执行。对应的ACL文件格式如下:
{
"accessControlList": [
{
"grantee": [
{
"id":"10eb6f5ff6ff4605bf044313e8f3ffa5"
}
],
"permission": [
"FULL_CONTROL"
],
"resource": [
"bucket1/cook*",
"bucket1/edu/*",
"bucket1/travel/中国国家地理杂志"
]
}
]
}
- 该示例主要讲解notResource字段的使用方法。notResource字段可以用来对Bucket内某些指定文件和目录(prefix)之外的Object设置访问权限。bucket1的owner只允许另一个Flyme云用户(userid=10eb6f5ff6ff4605bf044313e8f3ffa5)对除“cook”为前缀的Object、“edu/”为前缀的Object和“travel/中国国家地理杂志”这个Object之外的其它Object有FULL_CONTROL权限。notResource字段的末尾有且只能有一个*。由于notResource所指定资源是Object,所以只有FULL_CONTROL permission所包含的Object级别的API操作(如PutObject、GetObject、DeleteObject)会被执行。对应的ACL文件格式如下:
{
"accessControlList": [
{
"grantee": [
{
"id":"10eb6f5ff6ff4605bf044313e8f3ffa5"
}
],
"permission": [
"FULL_CONTROL"
],
"notResource": [
"bucket1/cook*",
"bucket1/edu/*",
"bucket1/travel/中国国家地理杂志"
]
}
]
}
- 该示例主要讲解Bucket级别的权限示例的基础用法。 bucket1的owner希望只有一个Flyme云用户(userid=b124deeaf6f641c9ac27700b41a350a8)能够查看bucket的信息或者列出Bucket下面的Object,则设置这个用户为GetBucket权限。对应的ACL文件格式如下:
{
"accessControlList": [
{
"grantee": [
{
"id": "b124deeaf6f641c9ac27700b41a350a8"
}
],
"permission": [
"GetBucket"
]
}
]
}
- 该示例主要讲解Object级别的权限示例的基础用法。bucket1的owner希望所有人都只可以对Bucket里面的Object进行读和写,但只有一个Flyme云用户(userid=b124deeaf6f641c9ac27700b41a350a8)能够管理bucket,则设置所有用户为GetObject,PutObject权限,而userid=b124deeaf6f641c9ac27700b41a350a8的用户为FULL_CONTROL权限。对应的ACL文件格式如下:
{
"accessControlList": [
{
"grantee": [
{
"id": "b124deeaf6f641c9ac27700b41a350a8"
}
],
"permission": [
"FULL_CONTROL"
]
},
{
"grantee": [
{
"id": "*"
}
],
"permission": [
"GetObject","PutObject"
]
}
]
}
- 该示例主要讲解Bucket防数据篡改示例的基础用法。bucket1的owner不希望一个Flyme云用户(userid=b124deeaf6f641c9ac27700b41a350a8)篡改Bucket的数据,但是允许其新增数据和读取数据,则设置userid=b124deeaf6f641c9ac27700b41a350a8的用户权限为Deny MODIFY、Allow PutObject、Allow READ,对应的ACL文件格式如下:
{
"accessControlList": [
{
"effect" : "Deny",
"grantee": [
{
"id": "b124deeaf6f641c9ac27700b41a350a8"
}
],
"permission": [
"MODIFY"
]
},{
"effect" : "Allow",
"grantee": [
{
"id": "b124deeaf6f641c9ac27700b41a350a8"
}
],
"permission": [
"PutObject","READ"
]
}
]
}
查看访问权限
- 查看某Bucekt的访问权限,详见GetBucketAcl接口。
- 返回的ACL会自动加上Owner属性。
Object权限控制
FOS支持使用ACL对Object权限进行管理。Object ACL是附属于资源即某个Object的权限,其本质上是授权谁(grantee)可以执行哪些操作(permission)。 FOS目前可以通过上传ACL文件和使用CannedAcl两种方式来设置ACL,两种方式都可以通过PutObjectAcl接口实现。
- 上传ACL文件是通过一个JSON文件来描述Object ACL信息。直接编辑ACL文件门槛较高,因此FOS还支持CannedAcl方式。
- CannedAcl本质上就是对几种常见的权限控制场景进行了封装,直接在PutObjectAcl的头域中的“x-ic-acl”字段或者x-ic-grant-read/x-ic-grant-full-control字段对资源进行设置。
Object ACL支持的permission权限
Object Acl支持的权限值 | 支持的操作 |
---|---|
READ | 该属性表示允许用户读取Object内容及其相关信息 |
FULL_CONTROL | 该属性表示用户拥有Object的控制权限,等价于READ和put/get/delete object acl的权限 |
CannedACL支持类型
Acl | 添加的权限 |
---|---|
private(私有) | Bucket Owner获得FULL_CONTROL,其他人没有任何权限 |
public-read(公共读) | Bucket Owner获得FULL_CONTROL,其他人获得READ权限 |
CannedACL支持的三种header 为了方便权限设置,在创建Object、复制Object及设置Object ACL时可以添加CannedACL,通过头域的"x-ic-acl"或者"x-ic-grant-permission'来设置Object访问权限,目前不支持在同一请求中同时设置CannedACL和上传ACL文件。主要有以下header设置方式, 两种类型的header不可以同时在一个请求中出现。
CannedACL Header | 有效值 | 是否必须 |
---|---|---|
x-ic-acl | private/public-read | 否 |
x-ic-grant-read | 支持多个id,以逗号分隔 | 否 |
x-ic-grant-full-control | 支持多个id,以逗号分隔 | 否 |
说明:
- 如果object是归档类型的文件,那么该文件在归档文件刚上传和取回过程完成前,不能设置和删除object acl配置。
可通过Header修改Canned ACL的接口
- PutObject接口
- PostObject接口
- AppendObject接口
- CopyObject接口
- InitMultiUpload接口
- PutObjectAcl接口
Service相关接口
ListBuckets
接口描述
本接口列举了请求者拥有的所有bucket。
请求(Request)
请求语法
GET / HTTP/1.1
Host: fos.flymeyun.com
Date: <Date>
请求头域
无特殊参数
请求参数
无特殊参数
响应(Response)
响应头域
无特殊Header参数响应
响应元素
名称 | 类型 | 描述 |
---|---|---|
owner | Object | Bucket owner(拥有者)信息 |
+id | String | Bucket owner的用户id |
+displayName | String | Bucket owner的名称 |
buckets | Array | 存放多个bucket信息的容器 |
+bucket | Object | 存放一个bucket信息的容器 |
+name | String | Bucket名称 |
+location | String | Bucket所在区域 |
+creationDate | Date | Bucket创建时间 |
+enableMultiAz | Boolean | Bucket数据是否多AZ分布,非多AZ bucket不返回该属性 |
注意: 如果请求中没有用户验证信息(即匿名访问),返回403 Forbidden,错误信息:AccessDenied。
示例
JSON请求示例
说明:一次请求最多返回100个bucket的信息。
json
GET / HTTP/1.1
Host: fos.flymeyun.com
Date: Wed, 06 Apr 2016 06:34:40 GMT
JSON请求响应示例
json
{
"owner": {
"id": "10eb6f5ff6ff4605bf044313e8f3ffa5",
"displayName": "FosUser"
},
"buckets": [
{
"name": "bucket1",
"location": "bj",
"creationDate": "2016-04-05T10:20:35Z",
"enableMultiAz": true
},
{
"name": "bucket2",
"location": "bj",
"creationDate": "2016-04-05T16:41:58Z"
}
]
}
说明: JSON请求响应项的命名规则是首字母小写的驼峰格式。
Bucket相关接口
基础操作
PutBucket
接口描述
本接口用于创建Bucket。每一个租户只允许创建100个Bucket。创建的Bucket其权限默认为private,即Bucket Owner获得FULL_CONTROL,其他租户没有任何权限。
请求(Request)
请求语法
PUT /<BucketName> HTTP/1.1
Host: fos.flymeyun.com
Date: <Date>
Content-Length: <ContentLength>
Content-Type: text/plain
请求参数
无
请求头域
名称 | 类型 | 描述 | 是否必须 |
---|---|---|---|
x-ic-tag-list | string | 创建bucket时为bucket绑定tag,格式为tag1=value1&tag2=value2 | 否 |
响应
响应头域
无特殊Header参数返回
响应参数
无 注意事项
- 若一个用户创建的Bucket超过100个,服务将返回400 Bad Request,错误码TooManyBuckets。
- 若请求的Bucket已存在,无论该Bucket是否是请求者创建,都会返回409 Conflict,错误信息:BucketAlreadyExists。
示例
请求示例
PUT /<BucketName> HTTP/1.1
Host: fos.flymeyun.com
Date: <Date>
Content-Length: <ContentLength>
Content-Type: text/plain
响应示例
HTTP/1.1 200 OK
x-ic-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
Date: Wed, 06 Apr 2016 06:34:40 GMT
Content-Length: 0
DeleteBucket
接口描述
本接口用于删除一个Bucket。在删除前需要保证此Bucket下的所有Object和未完成的三步上传Part已经已被删除,否则会删除失败。 **说明:**删除Bucket之前确认该Bucket没有开通跨区域复制,不是跨区域复制规则中的源Bucket,否则不能删除。
请求(Request)
请求语法
DELETE /<BucketName> HTTP/1.1
Host: fos.flymeyun.com
Date: <Date>
请求头域
无特殊Header参数
请求参数
无特殊参数
响应(Response)
响应头域
无特殊Header参数返回
响应元素
无 注意事项
- 只有Bucket的拥有者才能删除对应的Bucket,否则返回403 Forbidden,对应错误信息:AccessDenied。
- 为了确保用户数据安全,防止误删除,FOS不允许用户删除一个非空的Bucket。如果用户试图删除一个存在Object的Bucket,返回409 Conflict错误,错误码:BucketNotEmpty。
示例
请求示例
DELETE /<BucketName> HTTP/1.1
Host: fos.flymeyun.com
Date: Wed, 06 Apr 2016 06:34:40 GMT
响应示例
HTTP/1.1 204 No Content
x-ic-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
Date: Wed, 06 Apr 2016 06:34:40 GMT
HeadBucket
接口描述
本接口用于查看Bucket是否存在和请求者是否有权限访问这个Bucket。当请求返还200 OK时,说明Bucket存在且请求者有权限访问。
请求(Request)
请求语法
HEAD /<BucketName> HTTP/1.1
Host: fos.flymeyun.com
Date: <Date>
请求头域
无特殊Header参数
请求参数
无特殊参数
响应(Response)
响应头域
无特殊Header参数返回
响应元素
无
示例
请求示例
HEAD /<BucketName> HTTP/1.1
Host: fos.flymeyun.com
Date: Wed, 06 Apr 2016 06:34:40 GMT
响应示例
HTTP/1.1 200 OK
x-ic-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
Date: Wed, 06 Apr 2016 06:34:40 GMT
权限控制
PutBucketAcl
接口描述
本接口用于设置Bucket的访问权限。目前FOS支持两种方式设置ACL。第一种是使用CannedAcl,在PutBucketAcl的时候,通过头域的“x-ic-acl"来设置,当前可设置的权限包括:private, public-read, public-read-write(大小写敏感)。第二种方式是上传一个ACL文件,文件格式参见ACL文件格式。 注意 FOS系统不支持在同一请求中,同时设置“x-ic-acl”和上传ACL文件。
请求(Request)
请求语法
PUT <BucketName>/?acl HTTP/1.1
Host: fos.flymeyun.com
x-ic-date: <Date>
Content-Length: <ContentLength>
Content-Type:application/json; charset=utf-8
x-ic-acl: <ACLString>
请求参数
无特殊参数
请求头域
名称 | 类型 | 描述 | 是否必需 |
---|---|---|---|
x-ic-acl | String | Bucket设置的ACL权限,支持:private、public-read、public-read-write | 否 |
响应(Response)
响应头域
无特殊Header参数返回
响应元素
无
注意事项
- 只有Bucket的拥有者和被授予FULL_CONTROL权限的用户才能设置 Bucket 的ACL权限。
- 在创建Bucket时,Bucket权限会默认设置为private。
示例
使用CannedAcl的请求示例
PUT /<BucketName>?acl HTTP/1.1
Host: fos.flymeyun.com
x-ic-date: 2016-04-06T08:23:49Z
Authorization: AuthorizationString
x-ic-acl: public-read
Content-Type: application/json; charset=utf-8
Content-length: 0
上传ACL文件的示例
PUT /<BucketName>?acl HTTP/1.1
Host: fos.flymeyun.com
x-ic-date: 2016-04-06T08:23:49Z
Content-Length :1324
Content-Type: application/json; charset=utf-8
{
"accessControlList":[
{
"grantee":[{
# 租户ID
"id":"168bf6fd8fa74d9789f35a283a1f15e2"
}],
"permission":["READ"]
}
]
}
响应示例
HTTPS/1.1 200 OK
x-ic-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
Content-Length: 0
Date: Wed, 06 Apr 2016 06:34:40 GMT
GetBucketAcl
接口描述
本接口用来获取某个Bucket的访问权限。
请求(Request)
请求语法
GET /<BucketName>?acl HTTP/1.1
Host: fos.flymeyun.com
x-ic-date: <Date>
请求头域
无特殊参数
请求参数
无特殊参数
响应(Response)
响应元素(以JSON请求为例)
名称 | 类型 | 描述 |
---|---|---|
owner | Objcet | Bucket拥有者信息 |
+id | String | Owner用户id |
accessControlList | Array | 保存acl的容器 |
+grantee | Array | 一个被授权人 |
++id | String | 被授权用户id |
+permission | Array | 授权权限支持:FULL_CONTROL,READ,WRITE、LIST、MODIFY、GetObject、PutObject、DeleteObject、RestoreObject等 |
响应头域
无
示例
请求示例
GET /<BucketName>?acl HTTP/1.1
Host: fos.flymeyun.com
x-ic-date: 2016-04-06T08:23:49Z
响应示例
HTTP/1.1 200 OK
x-ic-acl: public-read
x-ic-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
Date: Wed, 06 Apr 2016 06:34:40 GMT
{
"owner":{
"id":"16df583fe6824d73a5f858f06de0af03"
}
"accessControlList":[
{
"grantee":[{
"id":"168bf6fd8fa74d9789f35a283a1f15e2"
}],
"permission":["FULL_CONTROL"]
},
{
"grantee":[{
"id":"10eb6f5ff6ff4605bf044313e8f3ffa5"
}],
"permission":["READ"]
}
],
}
生命周期管理
PutBucketLifecycle
接口描述
本接口用来创建生命周期管理规则。 注意:
- 只有bucket的owner且拥有FULL_CONTROL权限才能够进行此请求。
- PutBucketLifecycle会覆盖原有的生命周期规则, 如果需要在原有规则基础上新增, 需要在请求中携带所有新旧规则。
请求(Request)
请求语法
PUT /<BucketName>?lifecycle HTTP/1.1
Host: fos.flymeyun.com
x-ic-date: date
Content-Length: request-body length
Content-Type: application/json; charset=utf-8
{
"rule": [{
"id": "rule-id",
"status": "enabled",
"resource": [
"bucket/prefix/*"
],
"condition": {
"time": {
"dateGreaterThan": "2016-09-07T00:00:00Z"
}
},
"action": {
"name": "DeleteObject"
}
}]
}
请求头域
无特殊参数
请求参数
规则项 | 描述 | 是否必须 | 备注 |
---|---|---|---|
rule | 规则的列表 | 是 | 所有规则的列表 |
+id | 规则的标识符。 | 是 | 同一个bucket内规则id必须唯一,不能重复。如果用户不填系统会自动帮用户生成一个。 |
+status | 规则的状态。 | 是 | 取值为enabled或disabled,当规则处于disabled时规则不生效。 |
+resource | 规则对哪些资源生效。 | 是 | 举例:对samplebucket里以prefix/为前缀的Object生效:samplebucket/prefix/;对samplebucket里所有Object生效:samplebucket/。 |
+condition | 规则依赖的条件。 | 是 | 目前只支持time形式,智能分层规则返回值为null |
+time | 时间限制条件。 | 否 | 通过定义的dateGreaterThan实现。 |
++dateGreaterThan | 描述时间关系。 | 否 | 支持绝对时间date和相对时间days。绝对时间date格式为yyyy-mm-ddThh:mm:ssZ,eg. 2016-09-07T00:00:00Z。绝对时间为UTC时间, 必须以00:00:00(UTC 0点)结尾;相对时间days的描述遵循ISO8601, 支持的最小时间粒度为天,如: $(lastModified)+P7D表示的时间为object的last-modified之后7天。 |
action | 对resource执行的操作动作。 | 是 | - |
+name | 执行的操作名称。 | 是 | 取值为Transition、DeleteObject、AbortMultipartUpload、IntelligentTiering。 |
响应(Response)
响应元素
- 无特殊元素
响应头域
- 无特殊头域
基础生命周期管理请求示例
请求示例
PUT /bucket?lifecycle HTTP/1.1
Host: fos.flymeyun.com
x-ic-date: 2016-08-16T08:23:49Z
Content-Length :1324
Content-Type: application/json; charset=utf-8
{
"rule": [
{
"id": "sample-rule-delete-prefix",
"status": "enabled",
"resource": [
"bucket/prefix/*"
],
"condition": {
"time": {
"dateGreaterThan": "2016-09-07T00:00:00Z"
}
},
"action": {
"name": "DeleteObject"
}
},
{
"id": "sample-rule-transition-prefix",
"status": "enabled",
"resource": [
"bucket/prefix/*"
],
"condition": {
"time": {
"dateGreaterThan": "$(lastModified)+P7D"
}
},
"action": {
"name": "Transition",
"storageClass": "STANDARD_IA"
}
},
{
"id": "sample-rule-abort-multiupload-prefix",
"status": "enabled",
"resource": [
"bucket/prefix/*"
],
"condition": {
"time": {
"dateGreaterThan": "$(lastModified)+P7D"
}
},
"action": {
"name": "AbortMultipartUpload"
}
}
]
}
响应示例
HTTP/1.1 200 OK
x-ic-request-id: 0A49CE4060975EAC
Date: Wed, 12 Oct 2016 17:50:00 GMT
Content-Length: 0
Connection: keep-alive
智能分层管理请求示例
请求示例
PUT /<BucketName>?lifecycle HTTP/1.1
Host: fos.flymeyun.com
x-ic-date: 2022-07-26T17:18:55Z
Content-Length: 576
Content-Type: application/json; charset=utf-8
{
"rule": [
{
"action": {
"name": "IntelligentTiering"
},
"id": "sample-rule-intelligent-tiering-prefix",
"resource": [
"bucket/*"
],
"status": "enabled"
},
{
"id": "sample-rule-delete-prefix",
"status": "enabled",
"resource": [
"bucket/prefix/*"
],
"condition": {
"time": {
"dateGreaterThan": "2022-07-27T00:00:00Z"
}
},
"action": {
"name": "DeleteObject"
}
},
{
"id": "sample-rule-abort-multiupload-prefix",
"status": "enabled",
"resource": [
"bucket/prefix/*"
],
"condition": {
"time": {
"dateGreaterThan": "$(lastModified)+P7D"
}
},
"action": {
"name": "AbortMultipartUpload"
}
}
]
}
响应示例
HTTP/1.1 200 OK
x-ic-request-id: FSZ89ESW7DS6FA9
Date: Wed, Tue, 26 Jul 2022 05:01:28 GMT
Content-Length: 0
Connection: keep-alive
GetBucketLifecycle
接口描述
此接口用于获取定义的生命周期管理规则详细信息。
请求(Request)
请求语法
GET /<BucketName>?lifecycle HTTP/1.1
Host: fos.flymeyun.com
Date: date
请求头域
无特殊参数
请求参数
无特殊参数
响应(Response)
请求参数
规则项 | 描述 | 是否必填 | 备注 |
---|---|---|---|
rule | 规则的列表 | 必填 | 所有规则的列表 |
+id | 规则的标识符。 | 必填 | 同一个bucket内规则id必须唯一,不能重复。如果用户不填系统会自动帮用户生成一个。 |
+status | 规则的状态。 | 必填 | 取值为enabled或disabled,当规则处于disabled时规则不生效。 |
+resource | 规则对哪些资源生效。 | 必填 | 举例:对samplebucket里以prefix/为前缀的Object生效:samplebucket/prefix/;对samplebucket里所有Object生效:samplebucket/。 |
+condition | 规则依赖的条件。 | 选填 | 目前只支持time形式,基础生命周期规则下为必填项。 |
+time | 时间限制条件。 | 选填 | 通过定义的dateGreaterThan实现,智能分层配置下无填充参数 |
++dateGreaterThan | 描述时间关系。 | 必填 | 支持绝对时间date和相对时间days。绝对时间date格式为yyyy-mm-ddThh:mm:ssZ,eg. 2016-09-07T00:00:00Z。绝对时间为UTC时间, 必须以00:00:00(UTC 0点)结尾;相对时间days的描述遵循ISO8601, 支持的最小时间粒度为天,如: $(lastModified)+P7D表示的时间为object的last-modified之后7天。 |
action | 对resource执行的操作动作。 | 选填 | 基础生命周期规则下为必填项。 |
+name | 执行的操作名称。 | 必填 | 取值为Transition、DeleteObject、AbortMultipartUpload。 |
响应元素
无特殊元素
响应头域
无特殊头域 注意事项
- 如果请求的源Bucket不存在,返回404错误,错误码为NoSuchBucket。
- 如果请求的源Bucket没有配置lifecycle,返回404错误,错误码为NoLifecycleConfiguration。
基础生命周期请求示例
请求示例
GET /<BucketName>?lifecycle HTTP/1.1
Host: fos.flymeyun.com
Date: Thu, 15 Sep 2016 00:16:26 GMT
响应示例
HTTP/1.1 200 OK
Date: Thu, 15 Sep 2016 00:17:23 GMT
x-ic-request-id: 1a5fd81e-626b-45b3-a885-15fff9cd106c
Connection: keep-alive
Content-Length: 358
{
"rule": [
{
"id": "sample-rule-delete-prefix",
"status": "enabled",
"resource": [
"bucket/prefix/*"
],
"condition": {
"time": {
"dateGreaterThan": "2016-09-07T00:00:00Z"
}
},
"action": {
"name": "DeleteObject"
}
},
{
"id": "sample-rule-transition-prefix",
"status": "enabled",
"resource": [
"bucket/prefix/*"
],
"condition": {
"time": {
"dateGreaterThan": "$(lastModified)+P7D"
}
},
"action": {
"name": "Transition",
"storageClass": "STANDARD_IA"
}
},
{
"id": "sample-rule-abort-multiupload-prefix",
"status": "enabled",
"resource": [
"bucket/prefix/*"
],
"condition": {
"time": {
"dateGreaterThan": "$(lastModified)+P7D"
}
},
"action": {
"name": "AbortMultipartUpload"
}
}
]
}
DeleteBucketLifecycle
接口描述
本接口用来删除定义的生命周期管理规则。
请求(Request)
请求语法
DELETE /<BucketName>?lifecycle HTTP/1.1
Host: fos.flymeyun.com
Date: GMT Date
请求头域
无特殊参数
请求参数
无特殊参数
响应(Response)
响应元素
无特殊元素
响应头域
无特殊头域
示例
请求示例
DELETE /<BcuketName>?lifecycle HTTP/1.1
Host: fos.flymeyun.com
Date: Tue, 17 Sep 2016 08:36:52 GMT
响应示例
HTTP/1.1 204 No Content
Date: Wed, 14 Sep 2016 05:37:16 GMT
x-ic-request-id: 1a5fd81e-626b-45b3-a885-15fff9cd106c
Connection: keep-alive
跨越访问
PutBucketCors
接口描述
本接口用来在指定的Bucket上设定一个跨域资源共享(CORS)的规则,如果原规则存在则覆盖原规则。
权限说明
只有Bucket的所有者和被授予FULL_CONTROL权限的用户才能设置Bucket的CORS。没有权限时,返回403 Forbidden错误,错误码:AccessDenied。
请求
请求语法
PUT /<BucketName>?cors HTTP/1.1
Host: fos.flymeyun.com
x-ic-date: date
Content-Length: content_length
Content-Type: application/json; charset=utf-8
{
Cors json file …
}
请求参数
无
请求头域
无特殊Header参数
请求元素
名称 | 描述 | 是否必需 | 父节点 |
---|---|---|---|
corsConfiguration | Bucket的CORS规则容器。每个Bucket |
最多允许有100条规则。 如果有多条配置,执行顺序为从上到下。 | 是 | 无 | | allowedOrigins | 存储允许的跨域请求的来源的容器。 | 是 | corsConfiguration | | allowedOrigin | 指定允许的跨域请求的来源,允许使用 最多一个通配符。 如果指定为则表示允许所有的来源的 跨域请求。特别的还支持作为后缀来 表示某一类网站比如abc,则表示支持 abc开头的网站。 注意:allowedOrigin匹配时大小写敏感。 类型:字符串 | 是 | allowedOrigins | | allowedMethods | 存储允许的跨域请求方法的容器。 | 是 | corsConfiguration | | allowedMethod | 指定允许的跨域请求的方法,不支持通配 符*,大小写敏感。 类型:枚举,取值有“GET,PUT,DELETE, POST,HEAD”。 | 是 | allowedMethods | | allowedHeaders | 存储允许的allowedHeaders容器。控制 在OPTIONS预取指令中Access-Control- Request-Headers头中指定的header是 否允许。 | 否 | corsConfiguration | | allowedHeader | 控制在OPTIONS预取指令中Access-Control -Request-Headers头中指定的header是否允许。 在Access-Control-Request-Headers中指定的每 个header都必须在allowedHeader中有一条对应 的项。每一个header允许使用最多一个*通配符, 不区分大小写。 类型:字符串。 | 否 | allowedHeaders | | allowedExposeHeaders | 存储允许用户从应用程序中访问的响应头的容器。 | 否 | corsConfiguration | | allowedExposeHeader | 指定允许用户从应用程序中访问的响应头(例如一个 Javascript的XMLHttpRequest对象)。不允许使用 *通配符。 OPTIONS请求中将根据此定义设置Access-Control -Expose-Headers。 类型:字符串。 | 否 | allowedExposeHeaders | | maxAgeSeconds | 指定浏览器对特定资源的预取(OPTIONS)请求返 回结果的缓存时间,在缓存时间内请求方不必发送重 复的preflight 请求,单位为秒。 类型:Int64。 | 否 | corsConfiguration |
响应
响应头域
无
响应元素
无 注意事项
- 通过此接口设置CORS规则之前,Bucket的CORS权限设置为不允许跨域。
- 每个Bucket最多只允许有一个规则文件,因此新上传的规则文件会覆盖原有的。
- CORS规则文件大小限制为20KB,因此请求时大于20KB会返回超出大小错误(400 Bad Request: EntityTooLarge)。
示例
请求示例
PUT /BucketName?cors HTTP/1.1
Host: fos.flymeyun.com
x-ic-date: 2016-04-06T08:23:49Z
Content-Length: 1024
Content-Type: application/json; charset=utf-8
{
"corsConfiguration": [
{
"allowedOrigins": [
"http://www.example.com",
"www.example2.com"
],
"allowedMethods": [
"GET",
"HEAD",
"DELETE"
],
"allowedHeaders": [
"Authorization",
"x-ic-test",
"x-ic-test2"
],
"allowedExposeHeaders": [
"user-custom-expose-header"
],
"maxAgeSeconds": 3600
},
{
"allowedOrigins": [
"http://www.flymeyun.com"
],
"allowedMethods": [
"GET",
"HEAD",
"DELETE"
],
"allowedHeaders": [
"*",
],
"allowedExposeHeaders": [
"user-custom-expose-header"
],
"maxAgeSeconds": 1800
}
]
}
响应示例
HTTP/1.1 200 OK
x-ic-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
Content-Length: 0
Date: Wed, 06 Apr 2016 06:34:40 GMT
GetBucketCors
接口描述
本接口用于获取指定的Bucket当前的CORS规则。
权限说明
只有Bucket的所有者和被授予FULL_CONTROL权限的用户才能设置Bucket的CORS。没有权限时,返回403 Forbidden错误,错误码: AccessDenied。
请求
请求语法
GET /<BucketName>?cors HTTP/1.1
Host: fos.flymeyun.com
Date: date
请求参数
无
请求头域
无特殊Header参数
请求元素
无
响应
响应头域
无
响应元素
名称 | 描述 | 是否必需 | 父节点 |
---|---|---|---|
corsConfiguration | Bucket的CORS规则容器。每个Bucket最多允许有100条规则。如果有多条配置,执行顺序为从上到下。 | 是 | 无 |
allowedOrigins | 存储允许的跨域请求的来源的容器。 | 是 | corsConfiguration |
allowedOrigin | 指定允许的跨域请求的来源,允许使用最多一个通配符。 如果指定为则表示允许所有的来源的跨域请求。特别的还支持作为后缀来表示某一类网站比如abc,则表示支持abc开头的网站。注意:allowedOrigin匹配时大小写敏感。类型:字符串 | 是 | allowedOrigins |
allowedMethods | 存储允许的跨域请求方法的容器。 | 是 | corsConfiguration |
allowedMethod | 指定允许的跨域请求的方法,不支持通配符*,大小写敏感。类型:枚举,取值有“GET,PUT,DELETE,POST,HEAD”。 | 是 | allowedMethods |
allowedHeaders | 存储允许的allowedHeaders容器。控制在OPTIONS预取指令中Access-Control-Request-Headers头中指定的header是否允许。 | 否 | corsConfiguration |
allowedHeader | 控制在OPTIONS预取指令中Access-Control-Request-Headers头中指定的header是否允许。在Access-Control-Request-Headers中指定的每个header都必须在allowedHeader中有一条对应的项。每一个header允许使用最多一个*通配符,不区分大小写。类型:字符串。 | 否 | allowedHeaders |
allowedExposeHeaders | 存储允许用户从应用程序中访问的响应头的容器。 | 否 | corsConfiguration |
allowedExposeHeader | 指定允许用户从应用程序中访问的响应头(例如一个Javascript的XMLHttpRequest对象)。不允许使用*通配符。OPTIONS请求中将根据此定义设置Access-Control-Expose-Headers。类型:字符串。 | 否 | allowedExposeHeaders |
maxAgeSeconds | 指定浏览器对特定资源的预取(OPTIONS)请求返回结果的缓存时间,在缓存时间内请求方不必发送重复的preflight请求,单位为秒。类型:Int64。 | 否 | corsConfiguration |
注意事项
- 当Bucket不存在时,会返回404 Not Found错误,错误码:NoSuchBucket。
- 如果CORS规则并不存在,会返回404 Not Found错误,错误码:NoSuchCORSConfiguration。
示例
请求示例
GET /<BucketName>?cors HTTP/1.1
Host: fos.flymeyun.com
Date: Wed, 06 Apr 2016 06:34:40 GMT
响应示例
HTTP/1.1 200 OK
x-ic-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
Date: Wed, 06 Apr 2016 06:34:40 GMT
Content-Length: 1324
Content-Type: application/json; charset=utf-8
{
"corsConfiguration": [
{
"allowedOrigins": [
"http://www.example.com",
"www.example2.com"
],
"allowedMethods": [
"GET",
"HEAD",
"DELETE"
],
"allowedHeaders": [
"Authorization",
"x-ic-test",
"x-ic-test2"
],
"allowedExposeHeaders": [
"user-custom-expose-header"
],
"maxAgeSeconds": 3600
},
{
"allowedOrigins": [
"http://www.meizu.com"
],
"allowedMethods": [
"GET",
"HEAD",
"DELETE"
],
"allowedHeaders": [
"*"
],
"allowedExposeHeaders": [
"user-custom-expose-header"
],
"maxAgeSeconds": 1800
}
]
}
DeleteBucketCors
接口描述
DeleteBucketCors用于关闭指定Bucket的CORS功能并清空所有规则。
权限说明
只有Bucket的所有者和被授予FULL_CONTROL权限的用户才有权限删除CORS规则。
请求
请求语法
DELETE /<BucketName>?cors HTTP/1.1
Host:fos.flymeyun.com
Date: Wed, 06 Apr 2016 06:34:40 GMT
请求参数
无
请求头域
无特殊Header参数
请求元素
无
响应
响应头域
无
响应元素
无 注意事项
- 当所对应的Bucket不存在时,会返回错误404 Not Found错误,错误码:NoSuchBucket。
- 当没有权限Delete Cors时,会返回错误403 Forbidden,错误码:AccessDenied。
- 当所对应的Bucket原本并不存在CORS规则时,会返回204 No Content。
示例
请求示例
DELETE /BucketName?cors HTTP/1.1
Host: fos.flymeyun.com
Date: Wed, 06 Apr 2016 06:34:40 GMT
响应示例
HTTP/1.1 204 OK
x-ic-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
Date: Wed, 06 Apr 2016 06:34:40 GMT
Connection: close
事件通知
PutNotification
接口描述
本接口用于指定bucket上增加通知规则。 注意:
- 只有bucket owner或者full control权限才能获取这个bucket的配置。
- 如果不是bucket owner则返回403,如果对应的文件不存在则返回404。
请求
请求语法
PUT /<BucketName>?notification HTTP/1.1
Host: fos.flymeyun.com
Date: <Date>
Content-Type: application/json; charset=utf-8
Content-Length: <ContentLength>
请求参数
字段 | 类型 | 必要性 | 说明 |
---|---|---|---|
id | String | 必选 | 规则id |
name | String | 可选 | 规则名称 |
appId | String | 必选 | 注册本条规则的产品id |
status | String | 必选 | 可选值:{"disabled", "enabled"} |
encryption | Object | 可选 | 加密方式 |
+key | String | 可选 | 加密密钥,如果不为空,则用IAM的算法对通知的请求进行签名,key对应IAM签名中的SecretAccessKey |
resources[] | Array | 必选 | 订阅的资源 |
+resource | String | 必选 | 订阅的资源,${bucketname}/path1/.jpg或者/path1/_.jpg,最多只能有1个* |
events[] | Array | 必选 | 订阅的事件 |
+eventType | String | 必选 | 事件类型,当前支持: |
- PutObject:普通上传Object
- PostObject:表单上传Object
- AppendObject:追加上传Object
- CopyObject:拷贝Object
- CompleteMultipartUpload:完成Object分片上传
- FetchObject:抓取Object,包含镜像回源等产生的抓取
- DeleteObject:删除Object
- DeleteMultipleObjects:删除多个Object | | apps[] | Array | 必选 | 订阅消息的产品 | | +id | String | 必选 | 被通知的产品id | | +eventUrl | String | 必选 | 处理事件通知的url,可选值:{"http", "https", "brn", "app"},http/https为自定义应用,brn为cfc的通知,app为官方应用 | | +xVars | String | 可选 | 透传的自定义参数,对框架透明,用于业务自我回传的值,如果是官方AI应用,则是一个字符串化的json,并包含一个saveUrl的地址,用于接收处理结果 |
如果仅用于配置通知或者回调的密钥,可以简化为如下参数:
字段 | 类型 | 必要性 | 说明 |
---|---|---|---|
id | String | 必选 | 规则id |
name | String | 可选 | 规则名称 |
appId | String | 必选 | 注册本条规则的产品id |
status | String | 必选 | 可选值:{"disabled", "enabled"} |
encryption | Object | 可选 | 加密方式 |
+key | String | 可选 | 加密密钥,如果不为空,则用IAM的算法对通知的请求进行签名,key对应IAM签名中的SecretAccessKey |
请求头域
无
响应
响应头域
无
响应元素
无
示例
请求示例
PUT /<BucketName>?notification HTTP/1.1
Host: fos.flymeyun.com
Date: Wed, 12 Sep 2018 06:34:40 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 0
{
"notifications": [
{
"id": "notify-id-1",
"name": "rule-name",
"appId": "app-id-1",
"status": "enabled",
"encryption": {
"key": "06a62b70f47dc4a0a7da349609f1a1ac",
},
"resources": [
"bucket-a/path1", "/path2", "/path3/*.jpg", "/path4/*"
],
"events": [
"PutObject"
],
"apps": [
{
"id": "app-id-1",
"eventUrl": "http://xxx.com/event",
"xVars": ""
},
{
"id": "app-id-2",
"eventUrl": "brn:ic:cfc:bj:1f1c3e38xxxxxxxx4c44523f0d5b22:function:hello_fos:$LATEST"
},
{
"id": "app-id-3",
"eventUrl": "app:ImageOcr",
"xVars": "{\"saveUrl\": \"http://xxx.com/ocr\"}"
}
]
}
]
}
响应示例
HTTP/1.1 200 OK
x-ic-request-id: 4db2b34d-654d-4d8a-b49b-xxxxxx786409
Date: Wed, 12 Sep 2018 06:34:40 GMT
Content-Length: 0
Connection: close
GetNotification
接口描述
本接口用于获取指定bucket上的通知规则。
请求
请求语法
GET /<BucketName>?notification HTTP/1.1
Host: fos.flymeyun.com
Date: <Date>
请求头域
无
请求参数
无
响应
响应头域
无
响应元素
字段 | 类型 | 必要性 | 说明 |
---|---|---|---|
id | String | 必选 | 规则id |
name | String | 可选 | 规则名称 |
appId | String | 必选 | 注册本条规则的产品id |
status | String | 必选 | 可选值:{"disabled", "enabled"} |
encryption | Object | 可选 | 加密方式 |
+key | String | 可选 | 加密密钥,如果不为空,则用IAM的算法对通知的请求进行签名,key对应IAM签名中的SecretAccessKey |
resources[] | Array | 必选 | 订阅的资源 |
+resource | String | 必选 | 订阅的资源,${bucketname}/path1/.jpg或者/path1/_.jpg,最多只能有1个* |
events[] | Array | 必选 | 订阅的事件 |
+eventType | String | 必选 | 事件类型,当前支持: |
- PutObject:普通上传Object
- PostObject:表单上传Object
- AppendObject:追加上传Object
- CopyObject:拷贝Object
- CompleteMultipartUpload:完成Object分片上传
- FetchObject:抓取Object,包含镜像回源等产生的抓取
- DeleteObject:删除Object
- DeleteMultipleObjects:删除多个Object | | apps[] | Array | 必选 | 订阅消息的产品 | | +id | String | 必选 | 被通知的产品id | | +eventUrl | String | 必选 | 处理事件通知的url,可选值:{"http", "https", "brn", "app"},http/https为自定义应用,brn为cfc的通知,app为官方应用 | | +xVars | String | 可选 | 透传的自定义参数,对框架透明,用于业务自我回传的值,如果是官方AI应用,则是一个字符串化的json,并包含一个saveUrl的地址,用于接收处理结果 |
示例
请求示例
GET /<BucketName>?notification HTTP/1.1
Host: fos.flymeyun.com
Date: Wed, 12 Sep 2018 06:34:40 GMT
响应示例
HTTP/1.1 200 OK
x-ic-request-id: 4db2b34d-654d-4d8a-b49b-xxxxxx786409
Date: Wed, 12 Sep 2018 06:34:40 GMT
Content-Length: 0
Connection: close
{
"notifications": [
{
"id": "notify-id-1",
"name": "rule-name",
"appId": "app-id-1",
"status": "enabled",
"resources": [
"bucket-a/path1", "/path2", "/path3/*.jpg", "/path4/*"
],
"events": [
"PutObject"
],
"apps": [
{
"id": "app-id-1",
"eventUrl": "http://xxx.com/event",
"xVars": ""
},
{
"id": "app-id-2",
"eventUrl": "brn:ic:cfc:bj:1f1c3e383c31e6467c4c44523f0d5b22:function:hello_fos:$LATEST"
},
{
"id": "app-id-3",
"eventUrl": "app:ImageOcr",
"xVars": "{\"saveUrl\": \"http://xxx.com/ocr\"}"
}
]
}
]
}
DeleteNotification
接口描述
本接口用于删除指定bucket上的通知规则。
请求
请求语法
DELETE /<BucketName>?notification HTTP/1.1
Host: fos.flymeyun.com
Date: <Date>
请求头域
无
请求参数
无
响应
响应头域
无
响应元素
无
示例
请求示例
DELETE /<BucketName>?notification HTTP/1.1
Host: fos.flymeyun.com
Date: Wed, 12 Sep 2018 06:34:40 GMT
响应示例
HTTP/1.1 200 OK
x-ic-request-id: 4db2b34d-654d-4d8a-b49b-xxxxxx786409
Date: Wed, 06 Apr 2016 06:34:40 GMT
Content-Length: 0
Connection: close
Object相关接口
基础操作
PutObject
接口描述
此接口用于向指定的Bucket上传一个文件,请求者必须具有Write权限。在PutObject前需要确保对应的Bucket已经存在,FOS支持Object文件的长度范围是0Byte-100M。如果需要上传大于100M的文件,请参考分块上传。
请求(Request)
请求语法
PUT /<BucketName>/<ObjectName> HTTP/1.1
Host: fos.flymeyun.com
Date: <Date>
Content-Type: text/plain
Content-Length: <Content_Length>
请求参数
无特殊参数
请求头域
名称 | 类型 | 描述 | 是否必需 |
---|---|---|---|
Cache-Control | String | 下载Object的Cache设置,常见的可取值为private、no-cache、max-age、must-revalidate | 否 |
Content-Disposition | String | 设置浏览器是否下载,可取值为inline、attachment; filename="download.txt" | 否 |
Content-MD5 | String | RFC2616定义的HTTP请求内容的MD5摘要,可以通过携带该字段来验证保存在FOS侧的文件和用户预期的文件是否一致。 | 否 |
Expires | String | 用于设置下载Object时的缓存失效时间,如果不做时间设置,FOS则会默认设置缓存失效时间为三天。 | 否 |
x-ic-meta-* | String | 用户自定义的meta | 否 |
x-ic-content-sha256 | String | 通过携带该字段来验证保存在FOS侧的文件和用户预期的文件是否一致,sha256的校验准确性更高。所传数据的sha256值必须与此匹配,否则PutObject失败 | 否 |
x-ic-content-crc32 | String | 上传object的CRC值(循环冗余校验码)。 | 否 |
x-ic-acl | String | CannedACL支持的header,用户设置Object的权限,取值为private和public-read。 | 否 |
x-ic-grant-read | String | CannedACL支持的header,用户设置Object的读权限。支持多个id,以逗号分隔 | 否 |
x-ic-grant-full-control | String | CannedACL支持的header,用户设置Object的FULL_CONTROL权限。支持多个id,以逗号分隔 | 否 |
响应头域(Response)
响应头域
名称 | 类型 | 描述 |
---|---|---|
ETag | String | Object的HTTP协议实体标签 |
注意事项
- Content-Length是必须参数,如果请求者指定的Content-Length比实际请求体(Object的实际数据)长度小,FOS只保存Content-Length指定长度的数据,多的这部分数据直接废弃;相反,如果Content-Length的长度大,FOS将一直等待请求者上传数据,直到超时。
- 上传的Object,如不指定Content-Type,FOS会自动识别设置合适的Content-Type,若无法识别则默认为application/octet-stream
- FOS目前不支持Version,如果请求者重复Put一个Object,之前上传的数据将被覆盖。
- 由于FOS本身是一个(<\Key>,<Value>)的存储系统,所以原则上并不会存在“文件夹”的概念。若需要按照文件夹来划分,可以把 “/” 符号作为分隔符模拟文件夹。例如上传object为 “work/test/123.txt”,控制台显示时会根据“/”自动切分,创建work文件夹下面的test文件夹和test文件夹下的123.txt文件。
响应参数
无
示例
请求示例
PUT /BucketName/ObjectName HTTP/1.1
Host: fos.flymeyun.com
Date: Wed, 06 Apr 2016 06:34:40 GMT
Content-Type: text/plain
Content-Length: 11434
[11434 bytes of object data]
响应示例
HTTP/1.1 200 OK
x-ic-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
Date: Wed, 06 Apr 2016 06:34:40 GMT
ETag: "1b2cf535f27731c974343645a3985328"
Content-Length: 0
Connection: close
GetObject
接口描述
此命令用于从FOS获取某个Object。此操作需要请求者对该Object有读权限。请求者可以在Header中设置Range来指定需要获取的Object数据的范围。
请求(Request)
请求语法
GET /<BucketName>/<ObjectKey> HTTP/1.1
Host: fos.flymeyun.com
Date: <Date>
Range: <Range_String>
请求头域
名称 | 类型 | 描述 | 是否必需 |
---|---|---|---|
Range | String | 指定Object返回的文件范围。设定 bytes=0-9,表示传送第0到第9这10个字符。默认返回全部数据。 | 否 |
请求参数
无
响应(Response)
响应头域
名称 | 类型 | 描述 |
---|---|---|
Cache-Control | String | 下载Object的Cache设置,常见的可取值为private、no-cache、max-age、must-revalidate |
Content-Length | Long Int | 返回Object的数据大小 |
Content-Range | String | 有range的情况下返回Object的数据范围 |
Content-Type | String | Object的类型及编码方式 |
Expires | String | 下载Object时的缓存失效时间 |
ETag | String | Object的HTTP协议实体标签 |
x-ic-meta-* | String | 如果有自定meta,才返回此项 |
x-ic-server-side-encryption | String | Object的服务器端加密类型,当前支持AES256和SM4加密。 |
注意事项
- GetObject通过Range参数可以支持断点续传,对于比较大的Object建议使用该功能。
- 如果在请求头中使用Range参数;则返回消息中会包含整个文件的长度和此次返回的范围,例如:Content-Range: bytes 0-9/44,表示整个文件长度为 44,此次返回的范围为0-9。
- 对于Range读大小为0字节的对象, 会返回400错误, Range是前闭后闭区间。
- 归档存储类型对象需要先取回才能调用GetObject接口。
如您想在response请求里面获得某些特定的header信息,可通过如下两种方式:
- 在PutObject时增加header信息,则GetObject时会直接返回在response里面,请参考PutObject接口。
- GetObject时,在queryString里面直接增加“responseXXX=YYY”,返回的header里面会包含“XXX: YYY”。例如:GET /testBucket/testObject?responseContentType= image/jpg,在这个http请求的response里面就会有“Content-Type: image/jpg”。具体的形式为response$header=urlencode(value),需要注意,当前$header只支持“ContentDisposition、ContentType、ContentLanguage、Expires、CacheControl、ContentEncoding”。
响应元素
无
示例
请求示例
GET /BucketName/ObjectName
Host: fos.flymeyun.com
Date: Wed, 06 Apr 2016 06:34:40 GMT
Range: bytes=0-9
响应示例
HTTP/1.1 206 Partial Content
x-ic-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
Date: Wed, 06 Apr 2016 06:34:40 GMT
Last-Modified: Fri, 28 Jan 2011 20:10:32 GMT
ETag: "b2419b1e3fd45d596ee22bdf62aaaa2f"
Accept-Ranges: bytes
Content-Range: bytes 0-9/443
Content-Type: text/plain
Content-Length: 10
[10 bytes of object data]
GetObjectMeta
接口描述
此命令用于获取某个Object的Meta信息,但此时并不返回数据。 注意:
- 如果使用软链接访问GetObjectMeta, 返回响应头中Content-Length、ETag、Content-Md5 均为目标文件的元信息;Last-Modified是目标文件和软链接的最大值;其他均为软链接元信息。
- 如果使用软链接访问该接口且目标文件删除了,会返回Http 404,SymlinkTargetNotExist,调用GetSymlink不会报错。
请求(Request)
请求语法
HEAD /<BucketName>/<ObjectName> HTTP/1.1
Host: fos.flymeyun.com
Date: <Date>
请求头域
无特殊header参数
请求参数
无特殊参数
响应(Response)
响应头域
名称 | 类型 | 描述 |
---|---|---|
Cache-Control | String | 下载Object的Cache设置,常见的可取值为private、no-cache、max-age、must-revalidate |
Content-Disposition | String | 设置浏览器是否下载,可取值为inline、attachment; filename="download.txt" |
Content-Length | Long Int | 返回Object的数据大小 |
Content-Range | String | 有range的情况下返回Object的数据范围 |
Content-Type | String | Object的类型及编码方式 |
Expires | String | 下载Object时的缓存失效时间 |
ETag | String | Object的HTTP协议实体标签 |
x-ic-meta-* | String | 如果有自定meta,才返回此项 |
x-ic-server-side-encryption | String | Object的服务器端加密类型,当前支持AES256和SM4加密。 |
响应参数
无
注意事项
无
示例
请求示例
HEAD /BucketName/ObjectName HTTP/1.1
Host: fos.flymeyun.com
Date: Wed, 06 Apr 2016 06:34:40 GMT
响应示例
HTTP/1.1 200 OK
x-ic-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
Date: Wed, 06 Apr 2016 06:34:40 GMT
Last-Modified: Sun, 1 Jan 2006 12:00:00 GMT
ETag: "fba9dede5f27731c9771645a39863328"
Content-Length: 0
Content-Type: text/plain
Connection: close
ListObjects
接口描述
本接口用于获得指定Bucket的Object信息列表。
请求(Request)
请求语法
GET /<BucketName> HTTP/1.1
Host: fos.flymeyun.com
Date: <Date>
请求头域
无特殊Header参数
请求参数
字段 | 类型 | 是否必需 | 描述 |
---|---|---|---|
delimiter | String | 否 | 分隔符; 主要用此项实现list文件夹的逻辑。如果在请求的时候指定了delimiter,FOS把匹配到的Object名称按照一定规则(从preifx到第一个delimiter)截取,截取的字符串去重作为CommonPrefixes的数据返回; delimiter长度限制为1 |
marker | String | 否 | object为字母序排列,从marker之后的第一个开始返回 |
maxKeys | Int | 否 | 返回object列表长度最大为1000,默认值是1000,如果指定的值大于1000,按1000操作 |
prefix | String | 否 | key前缀,限定返回的object key必须以此为前缀 |
响应(Response)
响应头域
无特殊Header参数响应
响应元素
名称 | 类型 | 描述 |
---|---|---|
commonPrefixes | Array | 仅当指定delimiter,才会返回此项 |
+prefix | String | 匹配以prefix开始到第一次出现Delimiter字符之间的object作为一组元素返回 |
contents | Array | 返回的一个object的列表 |
+key | String | Object名称 |
+lastModified | Date | 此Object最后一次被修改的时间 |
+eTag | String | Object的HTTP协议实体标签 |
+size | Int | Object的内容的大小(字节数) |
+storageClass | String | Object的存储类型,低频存储返回STANDARD_IA,冷存储返回COLD,归档存储返回ARCHIVE,标准存储返回STANDARD。 |
+owner | Container | Object上传者的用户信息 |
++id | String | Object上传者的用户id |
++displayName | String | Object上传者的名称 |
delimiter | String | 查询的结束符 |
isTruncated | Bool | 指明是否查询完整返回了;false-本次已经返回所有结果,true-本次还没有返回所有结果 |
maxKeys | Int | 请求返回的最大数目 |
marker | String | 本次查询的起点 |
name | String | Bucket名称 |
nextMarker | String | 当IsTruncated true时,才返回此项,作为下次查询marker的值 |
prefix | String | 查询的前缀 |
注意事项 Delimiter可以用来实现文件夹逻辑:
- 如果把prefix设为某个文件夹名,就可以罗列以此prefix开头的文件,即该文件夹下递归的所有的文件和子文件夹内的文件。
- 如果再把delimiter设置为 / 时,返回值就只罗列该文件夹下的文件,该文件夹下的子文件夹名返回在CommonPrefixes部分,子文件夹下递归的文件不被显示。 如一个bucket下存在三个object:fun/test.jpg,fun/movie/001.avi,fun/movie/007.avi。 若设定prefix为“fun/”,则返回三个object;如果增加设定delimiter为“/”,则返回文件“fun/test.jpg”和前缀“fun/movie/”。
示例
请求示例(JSON)1
json
GET /<BucketName> HTTP/1.1
Host: fos.flymeyun.com
Date: Wed, 06 Apr 2016 06:34:40 GMT
响应示例(JSON)1,递归列举所有object
json
HTTP/1.1 200 OK
x-ic-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
Date: Wed, 06 Apr 2016 06:34:40 GMT
{
"name":"bucket",
"prefix":"",
"delimiter":"/",
"marker":"",
"maxKeys":1000,
"isTruncated":false,
"contents":[
{
"key":"my-image.jpg",
"lastModified":"2009-10-12T17:50:30Z",
"eTag":"fba9dede5f27731c9771645a39863328",
"size":434234,
"storageClass":"STANDARD",
"owner":{
"id":"168bf6fd8fa74d9789f35a283a1f15e2",
"displayName":"mtd"
}
},
{
"key":"my-image1.jpg",
"lastModified":"2009-10-12T17:51:30Z",
"eTag":"0cce7caecc8309864f663d78d1293f98",
"size":124231,
"storageClass":"COLD",
"owner":{
"id":"168bf6fd8fa74d9789f35a283a1f15e2",
"displayName":"mtd"
}
]
}
请求示例(JSON)2,列举根目录下的部分文件和子目录,受maxKeys限制(不包括子目录下的文件)
json
GET /<BucketName>?delimiter=/ HTTP/1.1
Host: fos.flymeyun.com
Date: Wed, 06 Apr 2016 06:34:40 GMT
响应示例(JSON)2
json
HTTP/1.1 200 OK
x-ic-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
Date: Wed, 06 Apr 2016 06:34:40 GMT
{
"name":"bucket",
"prefix":"" ,
"delimiter":"/",
"marker":"",
"maxKeys":1000,
"isTruncated":false,
"contents":{
"key":"my-image.jpg",
"lastModified":"2009-10-12T17:50:30Z",
"eTag":"fba9dede5f27731c9771645a39863328",
"size":434234,
"storageClass":"STANDARD",
"owner":{
"id":"168bf6fd8fa74d9789f35a283a1f15e2",
"displayName":"mtd"
}
},
"commonPrefixes":[
{"prefix":"photos/"},
{"prefix":"mtd/"}
]
}
CopyObject
接口描述
此接口用于把一个已经存在的Object拷贝为另外一个Object,支持Object文件的长度范围是0Byte-5GB。该接口也可以用来实现Meta更新(使用replace模式且源和目标指向同一个文件)。此接口需要请求者在header中指定拷贝源。
请求(Request)
请求语法
PUT /<BucketName>/<ObjectKey> HTTP/1.1
Host: fos.flymeyun.com
Date: <Date>
Content-Length: <ContentLength>
Content-Type:text/plain
x-ic-copy-source: /SourceBucket/SourceObject
x-ic-copy-source-if-match: 3858f62230ac3c915f300c664312c11f
x-ic-metadata-directive: <DirectiveString>
请求参数
无
请求头域
x-ic-copy-source | String | 源Object地址 | 是 |
---|---|---|---|
x-ic-copy-source-if-match | String | 如果源Object的ETag值和用户提供的ETag相等,则执行拷贝操作,否则拷贝失败。 | 否 |
x-ic-metadata-directive | String | 目的Object的Meta信息是从源Object拷贝,还是用请求传入的meta。有效值为copy和replace,缺省值为copy。如果设置为copy,则直接用源Object的meta;如果设置为replace,则用请求传入的meta。 | 否 |
x-ic-meta-* | String | replace模式下启动,可修改用户自定义meta,自定义meta是用来保存对象的自定义信息。例如设置文件的标签,参数用“x-ic-meta-gender”,值设置为“Male”。 | 否 |
x-ic-copy-source-if-none-match | String | 如果源Object的ETag和用户提供的ETag不相等,则执行拷贝操作,否则拷贝失败。 | 否 |
x-ic-copy-source-if-unmodified-since | String | 如果源object在x-ic-copy-source-if-unmodified-since之后没被修改,则执行拷贝操作,否则拷贝失败。参数取值为GMT格式,例如:Wed, 06 Apr 2016 06:34:40 GMT。 | 否 |
x-ic-copy-source-if-modified-since | String | 如果源object在x-ic-copy-source-if-modified-since之后被修改了,则执行拷贝操作,否则拷贝失败。参数取值为GMT格式,例如:Wed, 06 Apr 2016 06:34:40 GMT。 | 否 |
x-ic-acl | String | CannedACL支持的header,用户设置Object的权限,取值为private和public-read。 | 否 |
x-ic-grant-read | String | CannedACL支持的header,用户设置Object的读权限。支持多个id,以逗号分隔 | 否 |
x-ic-grant-full-control | String | CannedACL支持的header,用户设置Object的FULL_CONTROL权限。支持多个id,以逗号分隔 | 否 |
x-ic-server-side-encryption | String | 服务端加密算法,当前支持AES256和SM4加密。 | 否 |
响应(Response)
响应头域
无特殊头域
响应参数
名称 | 类型 | 描述 |
---|---|---|
ETag | String | 目的Object的ETag |
lastModified | DATE | 目的Object的最后一次修改时间 |
注意事项
- 请求者必须对源Object有读操作权限。
- 在计算签名之前,用户需要针对x-ic-copy-source字段中为非标准ASCII字符(例如:中文)的内容做一次url-encode。
- 为了保持复制过程中的http连接,CopyObject接口的http结果可能使用Transfer-Encoded: Chunked编码方式。
- CopyObject过程中,如果发生服务器端错误,http status code可能返回2XX但是复制失败,复制结果请根据http body中的json判定。
- CopyObject如果源object是归档类型,需要先取回归档类型才能调用CopyObject接口。
- 归档类型Object不支持通过CopyObject实现Meta更新(使用replace模式且源和目标指向同一个文件)。
- 如果复制软链接文件,并不会复制数据,只会复制软链接本身。如果使用软链接访问该接口,且软链接的目标文件删除了,会返回Http 404,SymlinkTargetNotExist。
示例
请求示例
PUT /BucketName/ObjectName HTTP/1.1
Host: fos.flymeyun.com
Date: Wed, 06 Apr 2016 06:34:40 GMT
Content-Length: 0
Content-Type:text/plain
x-ic-copy-source: /SourceBucket/SourceObject
x-ic-copy-source-if-match: 3858f62230ac3c915f300c664312c11f
x-ic-metadata-directive: replace
x-ic-meta-mykey: myvalue
响应示例
Copy成功
HTTP/1.1 200 OK
x-ic-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
Date: Wed, 06 Apr 2016 06:34:40 GMT
Connection: close
{
"lastModified":"2009-10-28T22:32:00Z",
"ETag":"9b2cf535f27731c974343645a3985328"
}
服务端异常, 需要根据返回json判断
HTTP/1.1 200 OK
Date: Thu, 12 May 2016 09:14:32 GMT
Content-Type: application/json; charset=utf-8
Connection: keep-alive
x-ic-request-id: bb90cc9c-2b80-462c-87a4-095e610c9a2f
Transfer-Encoding: chunked
{
"code":"InternalError",
"message":"We encountered an internal error. Please try again.",
"requestId":"52454655-5345-4420-4259-204e47494e58"
}
AppendObject
接口描述
AppendObject以追加写的方式上传文件。通过AppendObject操作创建的Object类型为Appendable Object,可以对该Object追加数据;而通过PutObject上传的Object是Normal Object,不可进行数据追加写。 说明:
- Appendable Object大小限制为0~100M
- AppendObject接口在进行追加写时要求对该Object有写权限
- 归档类型对象暂时不支持AppendObject。
- 软链接不是可追加类型,会返回HTTP 403,ObjectUnappendable错误。
请求(Request)
请求语法
首次上传AppendObject 时,使用如下方法:
POST /<BucketName>/<ObjectName>?append HTTP/1.1
Host: fos.flymeyun.com
Date: <GMT Date>
Content-Type: text/plain
Content-Length: <ContentLength>
说明:
- 如该Object不存在,则创建一个Appendable的Object。
- 如已存在同名的Object,则上传的数据会覆盖原有的Object,无论原有Object是否为Appendable,均创建新的Appendable Object。
- 允许创建或者覆盖一个长度为0的Object。
如已上传了部分AppendObject,需要进行断点续传时,使用如下方法:
POST /<BucketName>/<ObjectName>?append&offset=<OffsetSize> HTTP/1.1
Host: fos.flymeyun.com
Date: <GMT Date>
Content-Type: text/plain
Content-Length: <ContentLength>
说明:
- 如要续传的Object不存在时,会返回错误码404 NoSuchKey。
- 如要续传的Object并不是Appendable的,则会返回403 ObjectUnappendable。
- 如值错误,则返回409 OffsetIncorrect。
- 如果不指定offset会直接覆盖而不是默认追加在末尾
请求头域
名称 | 类型 | 描述 | 是否必须 |
---|---|---|---|
Cache-Control | String | 浏览器cache的一种机制设置 | 否 |
Content-Disposition | String | 指示浏览器如何显示附加的文件 | 否 |
Content-MD5 | String | RFC2616定义的HTTP请求内容的MD5摘要,可以通过携带该字段来验证保存在FOS侧的文件和用户预期的文件是否一致。 | 否 |
Expires | String | GMT时间,缓存失效时间 | 否 |
x-ic-meta-* | String | 用户自定义的meta | 否 |
x-ic-content-sha256 | String | 指本次所传数据的sha256值,必须与此匹配,否则AppendObject失败 | 否 |
x-ic-content-crc32 | String | 本次上传object增量数据的CRC值(循环冗余校验码)。 | 否 |
x-ic-acl | String | CannedACL支持的header,用户设置Object的权限,取值为private和public-read。 | 否 |
x-ic-grant-read | String | CannedACL支持的header,用户设置Object的读权限。支持多个id,以逗号分隔 | 否 |
x-ic-grant-full-control | String | CannedACL支持的header,用户设置Object的FULL_CONTROL权限。支持多个id,以逗号分隔 | 否 |
x-ic-server-side-encryption | String | 服务端加密算法,当前支持AES256和SM4加密。 | 否 |
请求参数
名称 | 类型 | 参数位置 | 描述 | 是否必须 |
---|---|---|---|---|
append | - | Query参数 | 代表对Appendable Object进行追加操作 | 是 |
offset | - | Query参数 | 代表数据断点,即从该点后继续追加,取值为已实际上传的数据大小 | 否 |
响应(Response)
响应头域
名称 | 类型 | 描述 | 是否必须 |
---|---|---|---|
Content-MD5 | String | 当前已成功上传的整个object的MD5值 | 是 |
x-ic-next-append-offset | Long Int | 指明下次AppendObject请求时传入的OffsetSize的值。如果不使用续传方式,即请求起始行没有offset,则这个值是0 | 是 |
x-ic-content-crc32 | String | 整个object数据的CRC值(循环冗余校验码)。 | 否 |
ETag | String | Append后整个Object的ETag值 | 是 |
响应参数
无 使用细节说明 对于Appendable的Object:
- 支持AppendObject。
- 支持RenameObject。
- 对一个已存在的Appendable的Object执行PutObject,则Appendable的Object会被覆盖变成普通Object。
- 对一个已存在的Appendable的Object,在
<OffsetSize>
值正确的情况下,追加一个长度为0的内容,不会改变Object的任何状态。 - 不建议并发操作同一个Object,如一个线程执行AppendObject,另一线程执行PutObject/CopyObjcect/DeleteObject等操作,可能会导致操作结果错误或操作失败。
- 如果对同一个Object做多线程或者多进程的并发追加,有可能因为并发过程的不确定性,返回409 OffsetIncorrect失败。
对其他接口的影响
对于GetObjectMeta接口,当一个Object是Appendable时,返回的结果中会多如下两个字段:
名称 | 类型 | 描述 | 是否必须 |
---|---|---|---|
x-ic-next-append-offset | String | 当Object是由AppendObject接口创建的,会返回该字段,指明下次AppendObject时请求传入的OffsetSize的值。如果此时Object的大小是5G,offset依然返回5G | 是 |
x-ic-object-type | String | 当Object的类型值。当object是由AppendObject创建的,返回的值为Appendable,其他情况暂不返回 | 是 |
关于用户自定义的x-ic-meta-*
- 在首次创建AppendableObject(即Http请求起始行不带offset参数)时,携带的x-ic-meta-* Header会被存储,后续追加AppendObject(即Http请求起始行携带offset参数)时的x-ic-meta- *Header则默认被忽略。
- 由于Appendable Object支持CopyObject,因此可以使用CopyObject自我拷贝以覆盖的形式来修改x-ic-meta-* Header的值。
数据校验
- 每次调用AppendObject的时候,如您上传MD5或者Sha256值,FOS会对该次调用上传的数据进行校验。
- 每次数据追加结束,会返回已上传的整个Object的MD5值。
示例
请求示例一
POST /BucketName/ObjectName?append HTTP/1.1
Host: fos.flymeyun.com
Date: Wed, 06 Apr 2016 06:34:40 GMT
Content-Type: text/plain
Content-Length: 1134
[1134 bytes of object data]
响应示例一
HTTP/1.1 200 OK
x-ic-request-id: c31b374e-048a-41f0-9a9a-31bc4bc57509
Date: Wed, 06 Apr 2016 06:34:40 GMT
ETag: "7c935a3947e3a684333480bd6b58b7c2"
Content-Length: 0
Content-MD5: RJBidEhsrgCKeDjvQjrF8A==
x-ic-next-append-offset: 1134
Connection: close
请求示例二
POST /BucketName/ObjectName?append&offset=1134 HTTP/1.1
Host: fos.flymeyun.com
Date: Wed, 06 Apr 2016 06:34:40 GMT
Content-Type: text/plain
Content-Length: 1900
[1900 bytes of object data]
响应示例二
HTTP/1.1 200 OK
x-ic-request-id: 28a99102-d0a5-4252-a4ed-fa6dc801806b
Date: Wed, 06 Apr 2016 06:34:40 GMT
ETag: "11257f81dce31a95f67f6e75018b77e3"
Content-Length: 0
Content-MD5: fJNaOUfjpoQzNIC9a1i3wg==
x-ic-next-append-offset: 3034
DeleteObject
接口描述
此命令用于删除指定Bucket的一个Object,要求请求者对此Object有写权限。
请求(Request)
请求语法
DELETE /<BucketName>/<ObjectName> HTTP/1.1
Host: fos.flymeyun.com
Date: <Date>
请求头域
无特殊Header参数
请求参数
无特殊参数
响应(Response)
响应头域
无特殊Header参数返回
响应参数
无
注意事项
无
示例
请求示例
DELETE /BucketName/ObjectName HTTP/1.1
Host: fos.flymeyun.com
Date: Wed, 06 Apr 2016 06:34:40 GMT
响应示例
HTTP/1.1 204 No Content
x-ic-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
Date: Wed, 06 Apr 2016 06:34:40 GMT
Content-Length: 0
Connection: close
DeleteMultipleObjects
接口描述
该命令可以实现通过一个HTTP请求删除同一个Bucket下的多个Object。
- 支持一次请求内最多删除1000个Object。
- 消息体(body)不超过2M。
- 返回的消息体中只包含删除过程中出错的Object结果;如果所有Object都删除都成功的话,则没有消息体。
请求(Request)
请求语法
POST /<BucketName>?delete HTTP/1.1
Host: fos.flymeyun.com
Date: <Date>
Content-Length: <ContentLength>
Content-Type: text/plain
{
"objects": [
{
"key": "my-object1"
},
{
"key": "my-object2"
}
]
}
请求头域
无特殊Header参数
请求参数
参数名称 | Query参数 | 描述 | 父节点 |
---|---|---|---|
objects | Request Body参数 | 保存要删除的Object信息的容器,里面包含一个或多个Object元素。 | - |
+key | Request Body参数 | 要删除的Object名称。 | objects |
响应(Response)
响应头域
无特殊Header参数返回
响应参数
参数名称 | 描述 | 父节点 |
---|---|---|
errors | 删除过程中出错的Object信息的容器,里面包含一个或多个Object元素。 | - |
+key | 删除出错的Object名称。 | errors |
+code | 错误代码。 | errors |
+message | 错误信息。 | errors |
示例
请求示例
POST /<BucketName>/?delete HTTP/1.1
Host: fos.flymeyun.com
Date: Wed, 06 Apr 2016 06:34:40 GMT
Content-Length: 11434
Content-Type: text/plain
{
"objects": [
{
"key": "my-object1"
},
{
"key": "my-object2"
}
]
}
响应示例
HTTP/1.1 200 OK
x-ic-request-id : 4db2b34d-654d-4d8a-b49b-3049ca786409
Date: Wed, 06 Apr 2016 06:34:40 GMT
Connection: close
Content-Length: 1324
{
"errors": [
{
"key": "my-object1",
"code": "NoSuchKey",
"message": "The specified key does not exist."
},
{
"key": "my-object2",
"code": "InvalidArgument",
"message": "Invalid Argument."
}
]
}
权限控制
PutObjectAcl
接口描述
此命令用于设置Object的访问权限。目前FOS支持两种方式设置ACL。第一种是使用Canned Acl,在PutObjectAcl的时候,通过头域的"x-ic-acl"或者"x-ic-grant-permission'来设置object访问权限,当前可设置的权限包括private和public-read,两种类型的header不可以同时在一个请求中出现。第二种方式是上传一个ACL文件,文件格式参见ACL文件格式,目前ACL文件只支持accessControlList,grantee,id,permission字段。 目前不支持在同一请求中同时设置canned acl和上传ACL文件。
请求(Request)
ACL文件请求语法
PUT /<BucketName>/<ObjectKey>?acl HTTP/1.1
Host: fos.flymeyun.com
x-ic-date: <Date>
Content-Type: application/json; charset=utf-8
Content-Length: <ContentLength>
Canned ACL文件请求语法(设置x-ic-acl)
PUT /<BucketName>/<ObjectKey>?acl HTTP/1.1
Host: fos.flymeyun.com
x-ic-date: <Date>
x-ic-acl: <ObjectAcl>
Content-Length: <ContentLength>
Content-Type: application/json; charset=utf-8
Canned ACL文件请求语法(设置x-ic-grant-permission)
PUT /<BucketName>/<ObjectKey>?acl HTTP/1.1
Host: fos.flymeyun.com
x-ic-date: <Date>
x-ic-grant-read: <ObjectGrantRead>
Content-Length: <ContentLength>
Content-Type: application/json; charset=utf-8
请求头域
名称 | 类型 | 描述 | 是否必需 |
---|---|---|---|
x-ic-acl | String | Object设置的ACL权限,支持:private、public-read | 否 |
x-ic-grant-read | String | 授权读的user id,支持多个id,以逗号分隔 | 否 |
x-ic-grant-full-control | String | 授权控制权限的user id,支持多个id,以逗号分隔 | 否 |
注意事项
- 只有Bucket的拥有者和被授予FULL_CONTROL权限的用户才能设置Object的ACL权限。
- 在上传Object时,Object权限会默认为空,如果没有设置Object的权限,即当Object权限为空时,默认以Bucket权限为准。
- 当Object权限和Bucket权限不一致时,以Object权限为准。
请求参数
无特殊参数
响应(Response)
响应头域
无特殊参数返回
响应参数
无
示例
ACL文件请求示例
PUT /BucketName/ObjectName?acl HTTP/1.1
Host: fos.flymeyun.com
x-ic-date: 2017-05-01T12:23:49Z
Content-Type: application/json; charset=utf-8
Content-Length: 315
{
"accessControlList":[
{
"grantee":[{
"id":"e13b12d0131b4c8bae959df4969387b8"
}],
"permission":["READ"]
}
]
}
Canned ACL 请求示例(设置x-ic-acl)
PUT /BucketName/ObjectName?acl HTTP/1.1
Host: fos.flymeyun.com
x-ic-date: 2017-05-01T12:23:49Z
x-ic-acl: public-read
Content-Length: 0
Content-Type: application/json; charset=utf-8
Canned ACL请求示例(设置x-ic-grant-permission)
PUT /BucketName/ObjectName?acl HTTP/1.1
Host: fos.flymeyun.com
x-ic-date: 2017-05-01T12:23:49Z
x-ic-grant-read:id="e13b12d0131b4c8bae959df4969387b8",id="8c47a952db4444c5a097b41be3f24c94"
Content-Length: 0
Content-Type: application/json; charset=utf-8
响应示例
HTTP/1.1 200 OK
Date: Wed, 01 Mar 2017 12:25:00 GMT
Content-Length: 0
x-ic-request-id:413e34fd-118d-4049-b992-1b1f3a68b1f5
GetObjectAcl
接口描述
此命令用来获取某个Object的访问权限。
请求(Request)
请求语法
GET /<BucketName>/<ObjectName>?acl HTTP/1.1
Host: fos.flymeyun.com
x-ic-date: <Date>
请求头域
无特殊参数
请求参数
无特殊参数
响应(Response)
响应头域
无特殊Header参数返回
响应参数
名称 | 类型 | 描述 |
---|---|---|
accessControlList | Objcet | ACL访问控制列表 |
+grantee | Objcet | 一个被授权人 |
++id | String | 被授权用户名id |
+permission | String | 授权权限支持:FULL_CONTROL,READ |
示例
请求示例
GET /BucketName/ObjectKey?acl HTTP/1.1
Host: fos.flymeyun.com
x-ic-date: 2017-05-01T12:23:49Z
响应示例
HTTP/1.1 200 OK
Date: Wed, 01 Mar 2017 12:25:00 GMT
x-ic-request-id: 236A23124128905248E5A01
{
"accessControlList":[
{
"grantee":[{
"id":"e13b12d0131b4c8bae959df4969387b8"
}],
"permission":["FULL_CONTROL"]
},
{
"grantee":[{
"id":"8c47a952db4444c5a097b41be3f24c94"
}],
"permission":["READ"]
}
]
}
DeleteObjectAcl
接口描述
此命令用来删除某个Object的访问权限。
请求(Request)
请求语法
DELETE /<BucketName>/<ObjectName>?acl HTTP/1.1
Host: fos.flymeyun.com
x-ic-date: <Date>
请求头域
无特殊Header参数
请求参数
无特殊参数
响应(Response)
响应头域
无特殊参数返回
响应参数
无特殊参数返回
示例
请求示例
DELETE /BucketName/ObjectName?acl HTTP/1.1
Host: fos.flymeyun.com
x-ic-date: 2017-05-01T12:23:49Z
响应示例
HTTP/1.1 200 OK
Date: Wed, 01 Mar 2017 12:25:00 GMT
Content-Length: 0
x-ic-request-id:413e34fd-118d-4049-b992-1b1f3a68b1f5
分片上传相关接口
使用指南
概述
MultipartUpload相关接口用于实现FOS的“三步上传”和“三步Copy”功能。
- 三步上传:请求者将一个Object拆分成多个分块(又称Part),然后分别上传这些分块。当所有分块全部上传完成后,FOS将请求者上传的所有分块组合成完整Object。MultipartUpload常使用于流式上传,大文件上传和断点上传。MultipartUpload上传有InitiateMultipartUpload,UploadPart和CompleteMultipartUpload三个步骤,俗称“三步上传”。 三步上传相关的接口包括:
- InitMultiUpload
- UploadPart
- CompleteMultiUpload
- ListParts
- AbortMultiUpload
- ListMultipartUploads
- 三步Copy:三步Copy和三步上传实现原理类似,将一个Object分块复制,最后再合并为一个完整的Object。三步Copy通过将大任务切分为小任务,可以并发复制,提高了文件的复制效率和成功率。三步Copy有InitiateMultipartUpload,UploadPartCopy和CompleteMultipartUpload三个步骤,相关接口包括:
- InitMultiUpload
- UploadPartCopy
- CompleteMultiUpload
- ListParts
- AbortMultiUpload
- ListMultipartUploads
InitiateMultipartUpload
接口描述
InitiateMultipartUpload是MultipartUpload的第一步,此命令向FOS请求一个全局唯一的UploadId,用于表示此次MultipartUpload,在MultipartUpload后续两个步骤都需要此UploadId,请求者也可以通过UploadId来查询上传的进度或者中断这次上传操作。
请求(Request)
请求语法
POST /<BucketName>/<ObjectName>?uploads HTTP/1.1
Host: fos.flymeyun.com
Date: <Date>
Content-Type: text/plain
Content-Length: <ContentLength>
请求头域
名称 | 类型 | 描述 | 是否必需 |
---|---|---|---|
x-ic-acl | String | CannedACL支持的header,用户设置Object的权限,取值为private或public-read。 | 否 |
x-ic-grant-read | String | CannedACL支持的header,用户设置Object的读权限。支持多个id,以逗号分隔 | 否 |
x-ic-grant-full-control | String | CannedACL支持的header,用户设置Object的FULL_CONTROL权限。支持多个id,以逗号分隔 | 否 |
x-ic-server-side-encryption | String | 服务端加密算法,当前支持AES256和SM4加密。 | 否 |
Cache-Control | String | 下载Object的Cache设置,常见的可取值为private、no-cache、max-age、must-revalidate | 否 |
Expires | String | 设置下载Object时的缓存失效时间 | 否 |
请求参数
名称 | 类型 | 参数位置 | 描述 | 是否必需 |
---|---|---|---|---|
uploads | String | Query参数 | 分块上传的请求 | 是 |
响应(Response)
响应头域
无
响应元素
名称 | 类型 | 描述 |
---|---|---|
bucket | String | Bucket名称 |
key | String | Object名称 |
uploadId | String | 全局唯一ID,用于标识此次MultiUpload操作 |
注意事项
- 使用MultipartUpload上传的Object,如不指定Content-Type,FOS会自动识别设置合适的Content-Type,若无法识别则默认为application/octet-stream。
- InitiateMultipartUpload获取的UploadId将用于MultiUpload的后续2步操作,也可以用此UploadId来查询整个MultiUpload的进度和中断此次MultiUpload操作。
示例
请求示例
POST /BucketName/ObjectName?uploads
Host: fos.flymeyun.com
Date: Wed, 06 Apr 2016 06:34:40 GMT
Content-Length: 0
响应示例
HTTP/1.1 200 OK
x-ic-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
Date: Wed, 06 Apr 2016 06:34:40 GMT
Content-Length: 197
Connection: keep-alive
{
"bucket": "BucketName",
"key":"ObjectName",
"uploadId": "a44cc9bab11cbd156984767aad637851"
}
UploadPart
接口描述
在调用 InitiateMultipartUpload 获取 UploadId 后,我们需要用 UploadPart 命令来上传 Object 拆分后的数据(Part)。为了标识各个 Part 在 Object 的相对位置,在 UploadPart 需要指定一个 partNumber 参数,partNumber 的取值范围是 1 - 10000。 FOS Part 的大小有一定限制,除最后一个分片外,单个分片最小支持 100 KB,最大支持 100M,且整个 Object 大小不超过 976.5G。
请求(Request)
请求语法
PUT /<BucketName>/<ObjectName>?partNumber=PartNumber&uploadId=UploadId HTTP/1.1
Host: fos.flymeyun.com
Date: <Date>
Content-Length: <ContentLength>
请求头域
名字 | 类型 | 描述 |
---|---|---|
Content-MD5 | String | RFC2616定义的HTTP请求内容的MD5摘要,可以通过携带该字段来验证保存在FOS侧的文件和用户预期的文件是否一致。 |
x-ic-content-sha256 | String | 通过携带该字段来验证保存在FOS侧的文件和用户预期的文件是否一致,sha256的校验准确性更高。所传数据的sha256值必须与此匹配,否则UploadPart失败。 |
x-ic-content-crc32 | String | 上传object的CRC值(循环冗余校验码)。 |
请求参数
名称 | 类型 | 参数位置 | 描述 | 是否必需 |
---|---|---|---|---|
partNumber | Int | Query参数 | 本次上传的part在object的相对位置 | 是 |
uploadId | String | Query参数 | InitiateMultipartUpload获取的UploadId | 是 |
响应(Response)
响应元素
无
响应头域
名称 | 类型 | 描述 |
---|---|---|
ETag | String | 每个上传分块的ETag |
其他 | - | 其他RFC2616相关的Header字段 |
注意事项 UploadPart会返回本次Part的eTag,在MultipartUpload的第三步中需要此eTag,也建议用户用eTag验证上传数据的正确性。
示例
请求示例
PUT /BucketName/ObjectName?partNumber=PartNumber&uploadId=UploadId HTTP/1.1
Host: fos.flymeyun.com
Date: Wed, 06 Apr 2016 06:34:40 GMT
Content-length:2794
Content-Type:text/plain
[2794 bytes of object data]
响应示例
HTTP/1.1 200 OK
x-ic-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
Date: Wed, 06 Apr 2016 06:34:40 GMT
ETag: "b54357faf0632cce46e942fa68356b38"
Content-Length: 0
Connection: keep-alive
CompleteMultipartUpload
接口描述
当请求者用UploadPart将所有的Part都上传完成后,需要用此CompleteMultipartUpload命令完成整个MultipartUpload操作。此命令需要请求提供有效的Part列表,包含part的PartNumber和eTag。FOS收到此命令后会检查数据,然后把所有的Part组合成一个Object。
请求(Request)
请求语法
POST /<BucketName>/<ObjectName>?uploadId=UploadId HTTP/1.1
Host: fos.flymeyun.com
Date: <Date>
Content-Length: <ContentLength>
Content-Type: text/plain
请求参数
名称 | 类型 | 参数位置 | 描述 | 是否必需 |
---|---|---|---|---|
partNumber | Int | Request Body参数 | 此part在目的Object中的序号。partNum取值范围 1-10000,一次MultiPart的PartNumber要求必须严格有序,比如有3个Part,PartNumber可以是1,3,5。 | 是 |
eTag | String | Request Body参数 | Object的HTTP协议实体标签 | 是 |
请求头域
名称 | 类型 | 描述 | 是否必需 |
---|---|---|---|
Content-Length | Long Int | 头域,JSON数据的长度 | 是 |
x-ic-meta-* | String | 用户自定义的meta | 否 |
响应(Response)
响应头域
- 无特殊头域
响应元素
名称 | 类型 | 描述 |
---|---|---|
bucket | String | 此Object所属的Bucket |
eTag | String | Object的HTTP协议实体标签 |
key | String | Object名称 |
location | String | 此Object的url |
注意事项
- CompleteMultipartUpload的请求Body最大为1MB。
- 一次MultiPart的PartNumber可以是不连续的,比如1, 3, 5。
示例
请求示例
POST /BucketName/ObjectName?uploadId=UploadId HTTP/1.1
Host: fos.flymeyun.com
Date: Wed, 06 Apr 2016 06:34:40 GMT
Content-Length: 11434
Content-Type: text/plain
{
"parts":[
{
"partNumber":1,
"eTag":"a54357aff0632cce46d942af68356b38"
},
{
"partNumber":2,
"eTag":"0c78aef83f66abc1fa1e8477f296d394"
},
{
"partNumber":3,
"eTag":"acbd18db4cc2f85cedef654fccc4a4d8"
}
]
}
响应示例
HTTP/1.1 200 OK
x-ic-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
Date: Wed, 06 Apr 2016 06:34:40 GMT
Connection: close
{
"location":"http://fos.flymeyun.com/BucketName/ObjectName",
"bucket":"BucketName",
"key":"object",
"eTag":"3858f62230ac3c915f300c664312c11f"
}
AbortMultipartUpload
接口描述
用户可以使用此接口来中断某个MultipartUpload请求,FOS收到此命令后,将会清除已上传的数据。
请求(Request)
- 请求语法:
DELETE /<BucketName>/<ObjectKey>?uploadId=UploadId HTTP/1.1
Host: fos.flymeyun.com
Date: <Date>
Content-Length: <ContentLength>
请求头域
无特殊要求头域
请求参数
名称 | 类型 | 参数位置 | 描述 | 是否必需 |
---|---|---|---|---|
uploadId | String | Query参数 | 此次MultipartUpload的ID | 是 |
响应(Response)
响应头域
无特殊头域
响应元素
无
注意事项
中止一个Multipart Upload事件时,如果其所属的某些Part仍然在上传,那么这次中止操作将无法删除这些Part。所以如果存在并发访问的情况,为了彻底释放FOS上的空间,需要调用几次Abort Multipart Upload接口。
示例
请求示例
DELETE /BucketName/ObjectName?uploadId=a44cc9bab11cbd156984767aad637851 HTTP/1.1
Host: fos.flymeyun.com
Date: Wed, 06 Apr 2016 06:34:40 GMT
响应示例
HTTP/1.1 204 No Content
x-ic-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
Date: Wed, 06 Apr 2016 06:34:40 GMT
Content-Length: 0
Connection: keep-alive
ListParts
接口描述
此命令用于列出用户指定UploadId所属的所有已经上传成功的Part,用户可以通过此命令查看当前的进度。
请求(Request)
请求语法
GET /<BucketName>/<ObjectName>?uploadId=UploadId&maxParts=MaxParts&partNumberMarker=PartNumberMarker HTTP/1.1
Host: fos.flymeyun.com
Date: <Date>
请求头域
无特殊头域
请求参数
名称 | 类型 | 参数位置 | 描述 | 是否必需 |
---|---|---|---|---|
maxParts | Int | Query参数 | FOS一次最多返回的part数目,默认1000,最大1000 | 否 |
partNumberMarker | Int | Query参数 | 按照partNumber排序,本次请求的起始part从此partNumber的下一个开始返回 | 否 |
uploadId | String | Query参数 | 此次MultipartUpload的ID | 是 |
响应(Response)
响应头域
无特殊头域
响应元素
名称 | 类型 | 描述 |
---|---|---|
bucket | String | 所属Bucket名称 |
key | String | Object名称 |
uploadId | String | 请求指定的UploadId |
initiated | String | multipartUpload的创建时间 |
owner | Container | 此object所属的用户信息 |
+id | String | 用户ID |
+displayName | String | 用户名 |
partNumberMarker | Int | 请求指定的本次part Number起始位置 |
nextPartNumberMarker | Int | 本次请求返回的最后一条记录的partNumber,可以作为下一次请求的PartNumberMarker |
maxParts | Int | 请求指定的本次最多返回的part数量 |
isTruncated | Bool | 标明是否本次返回的List Part结果列表被截断。 true表示本次没有返回全部结果; false表示本次已经返回了全部结果 |
parts | Container | 一个part的容器 |
+partNumber | Int | 该part的标识 |
+lastModified | DATE | 该part的上传时间 |
+ETag | String | 每个上传分块的ETag |
+size | Int | 该part大小 |
注意事项
- FOS按照PartNumber升序排序。
- 由于网络传输可能出错,所以不推荐用ListParts出来的结果生成最后CompleteMultipartUpload的Part列表。
示例
请求示例
GET /BucketName/ObjectName?uploadId=a44cc9bab11cbd156984767aad637851&maxParts=2&partNumberMarker=1
Host: fos.flymeyun.com
Date: Wed, 06 Apr 2016 06:34:40 GMT
响应示例
HTTP/1.1 200 OK
x-ic-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
Date: Wed, 06 Apr 2016 06:34:40 GMT
Content-Length: 985
Connection: keep-alive
{
"bucket":"BucketName",
"key":"object",
"uploadId":"a44cc9bab11cbd156984767aad637851",
"initiated":"2010-11-10T20:48:33Z",
"owner":{
"id":"75aa570f8e7faeebf76c078efc7c6caea54ba06a",
"displayName":"someName"
},
"storageClass":"STANDARD",
"partNumberMarker":1,
"nextPartNumberMarker":3,
"maxParts":2,
"isTruncated":true,
"parts":[
{
"partNumber":2,
"lastModified":"2010-11-10T20:48:34Z",
"ETag":"7778aef83f66abc1fa1e8477f296d394",
"size":10485760
},
{
"partNumber":3,
"lastModified":"2010-11-10T20:48:33Z",
"ETag":"aaaa18db4cc2f85cedef654fccc4a4x8",
"size":10485760
}
]
}
ListMultipartUploads
接口描述
此命令用于列出指定Bucket下面的所有未执行完成的Multipart Upload。“未执行完”是指完成了InitMultipartUpload,但是还没有调用CompleteMultipartUpload或AbortMultipartUpload的Multipart Upload。每次FOS最多返回1000个Multipart Upload,FOS支持prefix和delimiter过滤。
请求(Request)
请求语法
GET /<BucketName>?uploads HTTP/1.1
Host: fos.flymeyun.com
Date: <Date>
请求头域
无特殊要求头域
请求参数
名称 | 类型 | 参数位置 | 描述 | 是否必需 |
---|---|---|---|---|
delimiter | String | Query参数 | 分隔符; 主要应此项实现list文件夹的逻辑 | 否 |
keyMarker | String | Query参数 | Object按照字典序排序后,本次从keyMarker的后面的一条开始返回 | 否 |
maxUploads | Int | Query参数 | 本次请求返回Multipart Uploads的最大数目,默认1000,最大1000 | 否 |
prefix | String | Query参数 | key前缀,限定返回的object key必须以此为前缀 | 否 |
uploads | String | Query参数 | 标明请求是 ListMultipartUploads | 是 |
响应(Response)
响应头域
无特殊头域
响应元素
名称 | 类型 | 描述 |
---|---|---|
bucket | String | 所属Bucket名称 |
commonPrefixes | - | 如果在请求的时候指定了delimiter,将返回此项。FOS把匹配到的Object名称 |
按照一定规则(从preifx到第一个delimiter)截取,截取的字符串去重作为CommonPrefixes的数据返回 | ||
delimiter | String | 返回请求中的delimiter值 |
prefix | String | object前缀 |
isTruncated | Bool | 标明是否本次是否没有返回所有的数据。 |
true表示本次没有返回全部结果; false表示本次已经返回了全部结果 | ||
keyMarker | String | 请求指定的本次返回的MultipartUpload的起始位置 |
maxUploads | Int | 请求指定的本次返回的Multipart Uploads的最大数目 |
nextKeyMarker | String | 本次返回的最后一条MultipartUpload,可以作为下一次请求的KeyMarker |
uploads | Container | 保存一个MultipartUpload的容器 |
+key | String | Object名称 |
+uploadId | String | MultipartUpload的ID |
+owner | Container | Object所属的用户信息 |
++displayName | String | 用户名 |
++id | String | 用户ID |
+initiated | Date | 本次MultipartUpload开始时间 |
注意事项:此处的Delimiter跟ListObjects的类似,可以参考ListObjects的接口说明。
示例
请求示例
GET /BucketName?uploads HTTP/1.1
Host: fos.flymeyun.com
Date: Wed, 06 Apr 2016 06:34:40 GMT
响应示例(JSON)
HTTP/1.1 200 OK
x-ic-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
Date: Wed, 06 Apr 2016 06:34:40 GMT
Content-Length: 1330
Connection: keep-alive
{
"bucket":"bucket",
"keyMarker":"",
"nextKeyMarker":"my-movie.m2ts",
"maxUploads":3,
"isTruncated":true,
"uploads": [
{
"key":"my-divisor",
"uploadId":"a44cc9bab11bdc157676984aad851637",
"owner":{
"id":"75aa57f09aa0c8caeab4aeebf76c078efc7c6caea54ba06a",
"displayName":"OwnerDisplayName"
},
"initiated":"2010-11-10T20:48:33Z"
"storageClass" : "STANDARD_IA",
},
{
"key":"my-movie",
"uploadId":"b44cc9bab11cbd156984767aad637851",
"owner":{
"id":"b1d16700c70b0b05597d7acd6a3f92be",
"displayName":"OwnerDisplayName"
},
"initiated":"2010-11-10T20:48:33Z"
"storageClass" : "STANDARD",
},
{
"key":"my-movie.m2ts",
"uploadId":"c41cc9aad11cbd637851767bab156984",
"owner":{
"id":"b1d16700c70b0b05597d7acd6a3f92be",
"displayName":"OwnerDisplayName"
},
"initiated":"2010-11-10T20:49:33Z"
"storageClass" : "STANDARD_IA",
}
]
}