Skip to content
大纲

简介

Flyme云对象存储FOS(Flyme Object Storage),是Flyme云对外提供的稳定、安全、高效以及高扩展存储服务,支持文本、多媒体、二进制等任何类型的数据存储。数据多地域跨集群的存储,以实现资源统一利用,降低使用难度,提高工作效率。用户可以通过本文档提供的简单的RESTful API接口,进行资源管理以及数据上传下载等操作。

服务域名

https://fos.flymeyun.com

规范化字符串(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>

公共请求头

名字类型描述
AuthorizationString用于验证请求合法性的认证信息。更多参见鉴权认证
Content-LengthStringRFC2616中定义的HTTP请求内容的长度。
Content-TypeStringRFC2616中定义的HTTP请求内容的类型。
Content-MD5StringRFC2616定义的HTTP请求内容的MD5摘要,可以通过携带该字段来验证保存在FOS侧的文件和用户预期的文件是否一致。
DateStringHTTP 1.1协议中规定的GMT时间,如Wed, 06 Apr 2016 06:34:40 GMT。
HostString访问Host值,取值为BucketName.fos.flyme.com。
x-ic-dateString当前时间,遵循ISO8601规范,格式如2016-04-06T08:23:49Z。

公共返回头

名字类型描述
Content-LengthStringRFC2616中定义的HTTP请求内容长度。
Content-TypeStringRFC2616中定义的HTTP请求内容的类型。
Content-MD5StringRFC2616定义的HTTP请求内容的MD5摘要,可以通过携带该字段来验证保存在FOS侧的文件和用户预期的文件是否一致。
ConnectionString服务器是否断开连接,取值为close或者keep-alive。
DateStringHTTP 1.1协议中规定的GMT时间,如Wed, 06 Apr 2016 06:34:40 GMT。
eTagStringObject的HTTP协议实体标签。eTag (entity tag) 在每个Object生成的时候被创建,用于标识一个Object的内容,eTag值可以用于检查Object内容是否发生变化。
ServerString服务器的名字,取值为FceFos。
x-ic-request-idString由FCE FOS创建,是请求FceFos的唯一标识。
x-ic-debug-idString由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状态码
successsuccess成功200 OK
successBoth this request and DPF request executed successfully.请求执行成功200 OK
successThis request executed successful, but the DPF request is failed.请求执行成功,但DPF执行失败203 Non-Authoritative Information
successThis request executed successful, but the third-party platform executed failed.请求执行成功,第三方执行失败203 Non-Authoritative Information
successThis request executed successful, but your dpf format is invalid.请求执行成功,DPF格式无效203 Non-Authoritative Information
successCallback failed.回调失败203 Non-Authoritative Information
successEncrypt failed.加密失败203 Non-Authoritative Information
successPayload too large.有效载荷过大203 Non-Authoritative Information
InvalidEncryptionAlgorithmThe specified encryption algorithm is invalid加密算法无效400 Bad Request
InvalidEncryptionCustomerKeyThe specified encryption customer-key is invalid, encrypt object by customer key md5 not match加密密钥无效,密钥md5不匹配。400 Bad Request
InvalidEncryptionKmsMkidThe specified encryption kms mkid is invalid, please check its status指定的加密KMS MKID无效,请检查其状态400 Bad Request
InvalidTargetTypeThe specified object key is symlink, target object of symlink also is symlink.软链接文件不支持再次设置软链接400 Bad Request
InvalidEncryptionSchemeThe specified encryption scheme is invalid, encrypt object by customer key must use https request加密Object必须使用HTTPS请求400 Bad Request
successThis request executed successful, but the dpf executed failed because the assumerole configuration you set is invalid.请求执行成功,但DPF执行失败,因为处理用户权限失败。203 Non-Authoritative Information
AccessDeniedAccess Denied.拒绝访问403 Forbidden
AccountOverdueYour request is denied because there is an overdue bill of your account.用户欠费403 Forbidden
AccessDeniedBySourceUrlAccess Denied By Source Url.源URL拒绝访问403 Forbidden
BadDigestThe 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
BadDigestMD5The Content-MD5 you specified did not match what we received.错误的Content-MD5字段,与实际上传的数据MD5不符400 Bad Request
BadDigestSHA256The x-ic-content-sha256 you specified did not match what we received.错误的x-ic-content-sha256字段,与实际上传的数据sha256不符400 Bad Request
BadDigestCRC32The x-ic-content-crc32 you specified did not match what we received.错误的x-ic-content-crc32字段,与实际上传的数据crc32不符400 Bad Request
BucketAlreadyExistsThe 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
ObjectLockAlreadyInProgressThe bucket lock status is already InProgressBucket已经为锁定状态409 Conflict
BucketNotEmptyThe bucket you tried to delete is not empty.试图删除一个不为空的bucket409 Conflict
ClientSocketErrorclinet socket error, maybe client close connection.客户端连接失败,可能是客户端关闭了连接。200 OK
CORSConfigurationDoesNotMatchThe CORS Options request is not allowed because the request does not match with the CORS Configuration of the resource.请求资源与CORS配置不匹配403 Forbidden
CORSNotEnabledThe CORS is not enabled for this resource.未配置允许跨域访问403 Forbidden
ReplicationNotEnabledThe Bucket Replication is not enabled.跨区域数据同步未开启404 Not Found
UserQuotaNotConfiguredThe user quota does not configured未配置用户配额404 Not Found
ReplicationStatusErrorThe 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
ReplicationStatusNotEmptyThe bucket you tried to delete has an enabled replication conf or is a dest replication bucket of other bucket待删除的Bucket开启了跨区域复制功能。409 Conflict
InventoryStatusErrorThe Bucket Inventory Status is not correct. Please make sure dest bucket is same region!文件清单状态异常。请确保目的bucket在同地域。409 Conflict
ReplicationApiUsedInvalidThe replication api must upgrade,because you have used multi rules跨区域复制API版本需要更新409 Conflict
ReplicationConfDuplicateThe replication has exist with different id跨区域复制配置重复409 Conflict
EmptyHTTPAuthHeaderThe HTTP authorization header is empty. We do not allow using Session Token with empty authorization headersts签名请求中,缺少authorization请求header400 Bad Request
EntityTooSmallYour proposed upload is smaller than the minimum allowed object size.上传的数据小于限制400 Bad Request
EntityTooLargeYour proposed upload exceeds the maximum allowed object size.上传的数据大于限制400 Bad Request
CapacityExceededYour total upload bytes exceeds the maximum allowed in your account.超出账号容量限制403 Forbidden
BucketObjectNumExceededYour total upload object number exceeds the maxinum in your bucket超出Bucket文件数量限制403 Forbidden
BucketCapacityExceededYour total upload bytes exceeds the maximum allowed in your bucket超出Bucket容量限制403 Forbidden
ObjectNumExceededYour total upload object number exceeds the maxinum in your account超出账号文件数量限制403 Forbidden
BucketQuotaNotConfiguredThe bucket quota does not configured未配置Bucket配额404 Not Found
FetchObjectTaskIsRunningThe fetch object task you submit is running.FetchObject进行中200 OK
FetchObjectFailedFetch object failed, please check argument.文件抓取失败400 Bad Request
FileAlreadyExistsThe object you specified already exists and can not be overwritten.指定的文件已存在,无法覆盖409 Conflict
InappropriateJSONThe JSON you provided was well-formed and valid, but not appropriate for this operation.请求中的JSON格式正确,但语义上不符合要求。如缺少某个必需项,或者值类型不匹配等。400 Bad Request
InappropriateXMLThe XML you provided was well-formed and valid, but not appropriate for this operation.请求中的XML格式正确,但语义上不符合要求。适用场景同InappropriateJSON400 Bad Request
InvalidAccessKeyIdThe BCS Access Key Id you provided does not exist in our records.提供的Access Key不存在403 Forbidden
InvalidArgumentInvalid Argument.无效参数400 Bad Request
InvalidBucketNameThe specified bucket is not valid.Bucket名称不正确400 Bad Request
InvalidCopyDestinationThe copy destination is not valid复制的目标对象无效400 Bad Request
InvalidCORSRequestThe CORS request is not valid跨域请求错误400 Bad Request
InvalidDomainThe specified domain is not valid.域名不正确400 Bad Request
InvalidHTTPAuthHeaderThe HTTP authorization header is invalid. Consult the service documentation for details.请求头Authorization无效400 Bad Request
InvalidImageFormatYour image format is invalid.图片格式不正确400 Bad Request
InvalidObjectNameYour object key is too long.文件名长度超过限制400 Bad Request
InvalidTrashDirectoryNameYour trash directory name is not valid.回收站路径不正确400 Bad Request
InvalidDirectoryDirectory file must be empty目录文件必须为空400 Bad Request
ObjectLockNotLockedThe object lock is not locked, can not extend retentionday文件未被锁定,无法延长保留期限400 Bad Request
InvalidPartOne 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
InvalidPartOrderThe list of parts was not in ascending order.Parts list must specified in order by part number.分块列表未按升序排列400 Bad Request
InvalidPolicyDocumentThe content of the form does not meet the conditions specified in the policy document.Policy格式错误400 Bad Request
InvalidRangeThe requested range cannot be satisfied.请求的Range范围无效416 Range Not Satisfiable
InvalidSessionTokenThe 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
InvalidURICould not parse the specified URI.URI形式不正确400 Bad Request
InvalidStaticWebSiteFormatThe format of index file or 404 file are not allowed.不允许的index或者404文件名或格式。 比如:文件格式不允许,或者index与404文件同名。400 Bad Request
InvalidJobStatusThe current job status does not supprot the operation.当前任务状态不支持操作400 Bad Request
InvalidStorageClassThe storage class specified is invalid, please check argument and consult the service documentation.指定的存储类型错误400 Bad Request
NotSupportStorageClassThe storage class specified is not support, please check argument and consult the service documentation.指定的存储类型错误501 Not Implemented
NotAllowShortenRetentiondayCould not shorten retentionday不允许缩短合规保留期限400 Bad Request
InvalidVersionThe API version specified was invalid.API版本错误404 Not Found
RequestRateLimitExceededYour request rate is too high. We have put limits on your bucket.请求速度太快并触发限速429 Too Many Requests
MalformedJSONThe JSON you provided was not well-formed.JSON格式不正确400 Bad Request
MalformedXMLThe XML you provided was not well-formed or did not validate against our published schema.XML格式不正确400 Bad Request
MaxMessageLengthExceededYour request was too big.请求体过大400 Bad Request
MetadataTooLargeYour metadata headers exceed the maximum allowed metadata size.超出metadata大小限制400 Bad Request
MethodNotAllowedThe specified method is not allowed against this resource.请求方法错误405 Method Not Allowed
MirrorFailedMirroring failed, please check your mirror configuration.镜像回源失败424 Failed Dependency
MissingContentLengthYou must provide the Content-Length HTTP header.未提供Content-Length411 Length Required
MissingDateHeaderRequest 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:49Z400 Bad Request
NoSuchBucketThe specified bucket does not exist.Bucket不存在404 Not Found
NoSuchInventoryConfigurationThe specified inventory configuration does not exist.清单配置不存在404 Not Found
NoSuchCORSConfigurationThe CORS configuration does not exist.未配置跨域规则404 Not Found
NoLifecycleConfigurationThe lifecycle configuration does not exist.未配置生命周期规则404 Not Found
NoProcessConfigurationThe process configuration does not exist.数据处理配置不存在404 Not Found
NoNotificationConfigurationThe notification configuration does not exist.未配置事件通知规则404 Not Found
NoReplicationConfigurationThe Replication configuration does not exist.未配置跨区域复制404 Not Found
NoSuchKeyThe specified key does not exist.不存在该Object404 Not Found
NoSuchStyleThe specified style does not exist.图片样式不存在404 Not Found
NoSuchObjectLockThe specified object lock does not exist.合规保留配置不存在404 Not Found
NoSuchJobThe job does not exist.批处理任务不存在404 Not Found
NoSuchUploadThe 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
NoCopyrightProtectionConfigurationThe copyright protection configuration does not exist.未配置版权保护404 Not Found
NoSuchBucketEncryptionThe bucket is not encrypted.该Bucket未加密404 Not Found
NoSuchBucketTrashDirectoryThe bucket does not activate trash, or trash has been turned off未开启回收站404 Not Found
NoSuchBucketAliasThe bucket does not activate alias, or bucket alias has been turned offBucket别名不存在404 Not Found
NoSuchBucketDefaultStyleThe bucket does not activate default style, or bucket default style has been turned offBucket默认样式不存在404 Not Found
NoSuchBucketStaticWebSiteConfigThe static web site configuration does not exist.Bucket 没有开启静态托管404 Not Found
StaticWebSiteIsDisableStatic web site is disabled or not implemented.静态网站托管功能被禁止。 如:即FOS不允许此region的bucket 开启静态网站托管功能,或者静态网站托管功能未上线。501 Not Implemented
NotImplementedA header you provided implies functionality that is not implemented.系统未实现501 Not Implemented
NotSymlinkThe specified object key is not symlink.文件不是软链接类型400 Bad Request
SymlinkTargetNotExistThe specified object key is symlink, target object of symlink does not exist.软链接目标文件不存在404 Not Found
PreconditionFailedThe specified If-Match header doesn't match the header you provided.指定的If-Match请求头与用户提供的不匹配。412 Precondition Failed
OptInRequiredYou must active fos service.FOS服务未开启,请开通FOS服务且确保账户未欠费。403 Forbidden
RequestExpiredRequest has expired. Timestamp date is XXX.请求的时间戳过期。请求超时,XXX要改成x-ic-date的值。如果请求中只有Date,则需要将Date转换为本规范指定的格式。403 Forbidden
RequestTimeoutYour socket connection to the server was not read from or written to within the timeout period.请求超时408 Request Timeout
RequestTimeTooSkewedThe difference between the request time and the server's time is too large.请求时间与服务器时间差异过大403 Forbidden
ObjectTooSmallToProcessObject is too small to process.文件过小,无法进行处理400 Bad Request
ObjectTooLargeToProcessObject is too large to process.文件过大,无法进行处理400 Bad Request
VideoSnapshotFailHandle video snapshot fail视频截帧失败400 Bad Request
VideoRealtimeCodecFailHandle video codec fail视频转码失败400 Bad Request
VideoInfoFailHandle video info fail获取视频信息失败400 Bad Request
SignatureDoesNotMatchThe 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
ServiceUnavailablePlease reduce your request rate.服务不可用503 Service Unavailable
SlowDownPlease reduce your request rate.请求过于频繁503 Service Unavailable
TooManyBucketsYou have attempted to create more buckets than allowed.创建的Bucket数量超过限制400 Bad Request
TooManyConfigurationsYou have attempted to create more configurations than allowed.创建配置超过限制400 Bad Request
TooManyStylesYou have attempted to create more styles than allowed.创建样式数量超过限制400 Bad Request
TooManyJobsYou are attempting to create too many jobs.创建批处理任务数量超过限制400 Bad Request
TooManyMultiUploadsYou have attempted to do more multipart uploads than allowed.上传的分块数量超过限制400 Bad Request
InvalidContentLengthInvalid Content-Length or Transfer-Encoding.Content-Length不正确400 Bad Request
ReadBodyErrorRead http body error, please try again.读取请求内容错误,请重试400 Bad Request
DomainAlreadyExistsThe specified domain is bound to %s already.域名已被绑定到其他bucket409 Conflict
TooManyDomainsYou have attempted to bind to more buckets than allowed.域名数据超过限制400 Bad Request
NoSuchDomainThe specified domain does not exist.域名不存在404 Not Found
NoSuchMirroringThe specified mirroring configuration does not exist.未配置镜像回源规则404 Not Found
OffsetIncorrectOffset not equal to current object length追加Appendable Object时,<OffsetSize>值不等于已上传的Object的大小或者<OffsetSize>值不为0但Object不存在409 Conflict
ObjectUnappendableThe object can not be append不能对非Appendable的Object做AppendObject操作403 Forbidden
NotAllowCopyThis object not allow to copy to another one文件不允许复制400 Bad Request
NotAllowModifyPermission not match, not allow modify object data文件不允许修改403 Forbidden
ObjectIllegalThe Object is illegal文件不合规403 Forbidden
OnlyAllowModifyPermission not match, you only have modify permission, so you can not upload a new object权限不匹配,仅支持修改403 Forbidden
ObjectAclNotPassThe object acl does not pass.文件权限不匹配403 Forbidden
ObjectBannedYour object contains sensitive information. We have restricted your resources.文件已被封禁403 Forbidden
ObjectLockedYour object has been locked.文件已被锁定,无法进行操作423 Locked
ObjectLockConflictYou cannot lock/unlock a banned object.文件已被封禁403 Forbidden
ObjectAclNotExistsThe object acl does not exist.未配置文件权限规则404 Not Found
InternalErrorWe encountered an internal error. Please try again.内部错误500 Internal Server Error
PartialContentErrorErrors occurred at storage system and return partial content.请求时发生错误并返回部分内容510 Not Extended
NoStorageAnalysisConfNo storage analysis conf is set.未设置存储分析配置404 Not Found
StorageAnalysisConfIdConflictThe confId you provide is confict with existing confs.存储分析配置ID与现有配置冲突409 Conflict
ObjectImmutableThe object is immutable已经开启合规保留,文件无法进行删除或修改操作409 Conflict
ObjectRenameConflictObject rename conflict occurred, please retry it later or avoid concurrent update.重命名文件冲突409 Conflict
InvalidStorageAnalysisPrefixThe storage analysis prefix you provide is invalid.存储分析配置中的文件前缀无效400 Bad Request
StorageAnalysisConfigNumExceededStorage analysis confs have exceeded the max allow num.存储分析配置数量超出限制400 Bad Request
SqlSyntaxErrorThe sql expression in SelectRequest is invalid, it contains unsupported syntax or incorrect syntax.SQL语法错误400 Bad Request
InvalidSqlFieldsThe field in sql expression is invalid, it contains operators or other literals in SELECT clause.SQL表达式中字段无效400 Bad Request
InvalidSqlBinaryExprThe binary expression in sql is invalid, left operand is incompatible with right operand.SQL错误400 Bad Request
SqlFieldsNumExceedLimitThe number of fields in sql expression exceed the maximum allowable number limit.SQL中的字段数量超过了允许的最大数量限制400 Bad Request
AggregateInvalidFieldThe field of aggregate function in the sql is invalid, it is not numeric data type.SQL中聚合函数错误,使用字段非数值类型。400 Bad Request
InvalidSqlJsonPathDepthThe depth of json path is invalid, it exceed the maximum limit or less than 1.SQL错误,json路径的深度无效,超过最大限制或者小于1。400 Bad Request
SqlSourceNumExceedLimitOnly one source is supported in sql expression.SQL表达式中仅支持一个数据源400 Bad Request
RecordTooLargeThe length of record in csv file exceeds limit.CSV文件长度超过限制400 Bad Request
FieldNotExistThe field in SQL not exist in fileSQL字段不存在400 Bad Request
InappropriateJsonThe format of json object is inappropriate.JSON格式错误400 Bad Request
HeaderNotExistNo valid header info is found in csv file.CSV文件格式错误400 Bad Request
DecompressErrorError occurred when decompress object.文件解压失败400 Bad Request
InvalidFileTypeThe type of file is invalid, only JSON and CSV are supported.文件类型错误,仅支持JSON及CSV400 Bad Request
DataOverflowsTypeThe aggregate result of data overflows data type limit.数据聚合结果超出了数据类型的限制400 Bad Request
InvalidSqlSourceInvalid data source in sql expression SELECT clause, check the sql source format of csv or json object.请检查CSV或JSON对象的SQL源格式400 Bad Request
InvalidSqlLimitValueThe value of LIMIT clause in sql expression is invalid, it must greater than zero.SQL表达式中LIMIT值无效,必须大于零400 Bad Request
InvalidSqlNotOperatorThe operand of NOT operator is invalid, NOT operator only can be followed by BETWEEN/IN/LIKE.SQL错误,"NOT"操作需要跟随"BETWEEN/IN/LIKE"之后。400 Bad Request
InvalidSqlBetweenOperatorThe operand of BETWEEN operator is invalid, BETWEEN should with AND.SQL中"BETWEEN"使用错误400 Bad Request
InvalidSqlInOperatorThe values of IN operator are invalid, check values in (……).SQL中"IN"操作使用错误400 Bad Request
InvalidSqlIsOperatorThe operand of IS operator is invalid, IS operator can only be followed by NULL or NOT NULL.SQL中"IS"操作使用错误400 Bad Request
InvalidSqlLikeOperatorThe operand of LIKE operator is invalid, LIKE operator can only be followed by string.SQL中"LIKE"操作使用错误400 Bad Request
InvalidSqlFunctionThe function in sql expression is invalid, check the function parameters number and type.SQL表达式中的函数无效,请检查函数参数的数量和类型400 Bad Request
InvalidExpressionParameterThe 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
InvalidExpressionTypeParameterThe value of expressionType parameter in SelectRequest is invalid, only SQL expressions are supported.Select扫描请求expressionType参数错误400 Bad Request
InvalidCompressionTypeParameterThe value of compressionType parameter in SelectRequest is invalid, only GZIP and NONE are supported.Select扫描请求compressionType参数错误400 Bad Request
InvalidJsonTypeParameterThe value of Json type parameter in SelectRequest is invalid, only DOCUMENT/LINES are supported.Select扫描请求json type参数错误400 Bad Request
InvalidQuoteFieldsParameterThe value of quote fields parameter in SelectRequest is invalid, only ALWAYS/ASNEEDED are supported.Select扫描请求quote fields参数错误400 Bad Request
InvalidSelectRequestJsonBodySome parameters in SelectRequest json body is invalid, please check all optional and required parameters.Select扫描请求参数错误400 Bad Request
StorageAnalysisConfigNumExceededStorage analysis confs have exceeded the max allow num.存储分析配置超过最大限制400 Bad Request
NotArchiveObjectObject is not archive storage class.当前object不是归档类型文件400 Bad Request
DuplicationRequestDuplication request.重复请求400 Bad Request
RestoreAlreadyInProgressThe object is restoring.Don't restore the object again.您已经成功调用过RestoreObject接口,FOS服务端正在执行解冻操作。请不要重复执行RestoreObject409 Conflict
RestoreAlreadyThe object is restored.归档文件处于解冻状态,无需重重复调用409 Conflict
ObjectLockAlreadyLockedThe object lock status is locked.合规保留已开启409 Conflict
ObjectLockAlreadyExpiredThe object lock status is expired.合规保留已过期409 Conflict
CasUpdateConflictAn update conflict occurred, please retry it later or avoid concurrent update.并发更新冲突,请稍后重试或者避免并发更新。409 Conflict
InvalidObjectStateThe 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格式的策略描述语言,命名方法为首字母小写的驼峰命名格式,字段区分大小写。 字段总览:

字段数据类型说明是否必须父节点
accessControlListarray标识acl主体的开始,由一或多组acl配置项组成,其中acl配置项由grantee+permission+resource+condition组合而成。
+effectstring指定与该条acl配置项匹配的Request能否执行,取值为Allow或Deny。Allow表示可以执行;Deny表示拒绝执行。accessControlList
+granteearray标识被授权人。accessControlList
+permissionarrayACL配置项所影响的权限,可选值为READ、LIST、WRITE、和GetObject。权限详细解释请参见"Bucket ACL支持的permission权限"。accessControlList
+resourcearrayACL配置项所影响的资源,表示对resource指定范围的资源设置访问权限,支持通配符。如:<BucketName>/<ObjectKey><BucketName>/xxx*。 resource不填或填Bucket名称,等同于resource字段设为[<bucketName>, <bucketName>/*],即对Bucket和所有Object设置访问权限。accessControlList
+notResourcearrayACL配置项所影响的资源,表示对notResource指定范围以外的资源设置访问权限,支持通配符。如:<BucketName>/<ObjectKey><BucketName>/xxx*,表示对BucketName中ObjectKey之外的Object或者以XXX为前缀的Object之外的其他Object设置访问权限。如果notResource字段不填则等同于没有配置notResource,即采用默认配置,对Bucket及所有Object设置访问权限。accessControlList
+conditionarrayACL配置项所包含的限制条件,支持配置IP地址和Referer名单accessControlList
++ipAddressarray标识授予访问权限的ipcondition
++refererstring标识授予访问权限的referercondition
+++stringLikestring标识referer白名单中模糊匹配的地址referer
+++stringEqualsstring标识referer白名单中精确匹配的地址referer
++secureTransportbool标识是否只允许https方式访问。可选值“true”、"false",不设置时视为“false”。当设置为"true"时,表示只允许https方式访问。condition
++currentTimeobjectcondition配置项所包含的时间限制条件,支持配置"dateLessThan","dateLessThanEquals", "dateGreaterThan"和"dateGreaterThanEquals",四个配置项可以任选若干进行设置,匹配有效的条件是所设置配置项均需匹配。condition
+++dateLessThanstring标识授予访问权限的时间小于指定时间。取值为时间字符串,格式符合ISO 8601规范,如“2018-07-01T12:00:00Z”currentTime
+++dateLessThanEqualsstring标识授予访问权限的时间小于或者等于指定时间。取值为时间字符串,格式符合ISO 8601规范,如“2018-07-01T12:00:00Z”currentTime
+++dateGreaterThanstring标识授予访问权限的时间大于指定时间。取值为时间字符串,格式符合ISO 8601规范,如“2018-07-01T12:00:00Z”currentTime
+++dateGreaterThanEqualsstring标识授予访问权限的时间大于或者等于指定时间。取值为时间字符串,格式符合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-aclprivate/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参数响应

响应元素

名称类型描述
ownerObjectBucket owner(拥有者)信息
+idStringBucket owner的用户id
+displayNameStringBucket owner的名称
bucketsArray存放多个bucket信息的容器
+bucketObject存放一个bucket信息的容器
+nameStringBucket名称
+locationStringBucket所在区域
+creationDateDateBucket创建时间
+enableMultiAzBooleanBucket数据是否多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-liststring创建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参数返回

响应元素

注意事项

  1. 只有Bucket的拥有者才能删除对应的Bucket,否则返回403 Forbidden,对应错误信息:AccessDenied。
  2. 为了确保用户数据安全,防止误删除,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-aclStringBucket设置的ACL权限,支持:private、public-read、public-read-write

响应(Response)

响应头域

无特殊Header参数返回

响应元素

注意事项

  1. 只有Bucket的拥有者和被授予FULL_CONTROL权限的用户才能设置 Bucket 的ACL权限。
  2. 在创建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请求为例)
名称类型描述
ownerObjcetBucket拥有者信息
+idStringOwner用户id
accessControlListArray保存acl的容器
+granteeArray一个被授权人
++idString被授权用户id
+permissionArray授权权限支持: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参数

请求元素
名称描述是否必需父节点
corsConfigurationBucket的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参数

请求元素

响应

响应头域

响应元素
名称描述是否必需父节点
corsConfigurationBucket的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>
请求参数
字段类型必要性说明
idString必选规则id
nameString可选规则名称
appIdString必选注册本条规则的产品id
statusString必选可选值:{"disabled", "enabled"}
encryptionObject可选加密方式
+keyString可选加密密钥,如果不为空,则用IAM的算法对通知的请求进行签名,key对应IAM签名中的SecretAccessKey
resources[]Array必选订阅的资源
+resourceString必选订阅的资源,${bucketname}/path1/.jpg或者/path1/_.jpg,最多只能有1个*
events[]Array必选订阅的事件
+eventTypeString必选事件类型,当前支持:
  • 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的地址,用于接收处理结果 |

如果仅用于配置通知或者回调的密钥,可以简化为如下参数:

字段类型必要性说明
idString必选规则id
nameString可选规则名称
appIdString必选注册本条规则的产品id
statusString必选可选值:{"disabled", "enabled"}
encryptionObject可选加密方式
+keyString可选加密密钥,如果不为空,则用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>
请求头域

请求参数

响应

响应头域

响应元素
字段类型必要性说明
idString必选规则id
nameString可选规则名称
appIdString必选注册本条规则的产品id
statusString必选可选值:{"disabled", "enabled"}
encryptionObject可选加密方式
+keyString可选加密密钥,如果不为空,则用IAM的算法对通知的请求进行签名,key对应IAM签名中的SecretAccessKey
resources[]Array必选订阅的资源
+resourceString必选订阅的资源,${bucketname}/path1/.jpg或者/path1/_.jpg,最多只能有1个*
events[]Array必选订阅的事件
+eventTypeString必选事件类型,当前支持:
  • 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-ControlString下载Object的Cache设置,常见的可取值为private、no-cache、max-age、must-revalidate
Content-DispositionString设置浏览器是否下载,可取值为inline、attachment; filename="download.txt"
Content-MD5StringRFC2616定义的HTTP请求内容的MD5摘要,可以通过携带该字段来验证保存在FOS侧的文件和用户预期的文件是否一致。
ExpiresString用于设置下载Object时的缓存失效时间,如果不做时间设置,FOS则会默认设置缓存失效时间为三天。
x-ic-meta-*String用户自定义的meta
x-ic-content-sha256String通过携带该字段来验证保存在FOS侧的文件和用户预期的文件是否一致,sha256的校验准确性更高。所传数据的sha256值必须与此匹配,否则PutObject失败
x-ic-content-crc32String上传object的CRC值(循环冗余校验码)。
x-ic-aclStringCannedACL支持的header,用户设置Object的权限,取值为private和public-read。
x-ic-grant-readStringCannedACL支持的header,用户设置Object的读权限。支持多个id,以逗号分隔
x-ic-grant-full-controlStringCannedACL支持的header,用户设置Object的FULL_CONTROL权限。支持多个id,以逗号分隔

响应头域(Response)

响应头域
名称类型描述
ETagStringObject的HTTP协议实体标签

注意事项

  1. Content-Length是必须参数,如果请求者指定的Content-Length比实际请求体(Object的实际数据)长度小,FOS只保存Content-Length指定长度的数据,多的这部分数据直接废弃;相反,如果Content-Length的长度大,FOS将一直等待请求者上传数据,直到超时。
  2. 上传的Object,如不指定Content-Type,FOS会自动识别设置合适的Content-Type,若无法识别则默认为application/octet-stream
  3. FOS目前不支持Version,如果请求者重复Put一个Object,之前上传的数据将被覆盖。
  4. 由于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>
请求头域
名称类型描述是否必需
RangeString指定Object返回的文件范围。设定 bytes=0-9,表示传送第0到第9这10个字符。默认返回全部数据。
请求参数

响应(Response)

响应头域
名称类型描述
Cache-ControlString下载Object的Cache设置,常见的可取值为private、no-cache、max-age、must-revalidate
Content-LengthLong Int返回Object的数据大小
Content-RangeString有range的情况下返回Object的数据范围
Content-TypeStringObject的类型及编码方式
ExpiresString下载Object时的缓存失效时间
ETagStringObject的HTTP协议实体标签
x-ic-meta-*String如果有自定meta,才返回此项
x-ic-server-side-encryptionStringObject的服务器端加密类型,当前支持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-ControlString下载Object的Cache设置,常见的可取值为private、no-cache、max-age、must-revalidate
Content-DispositionString设置浏览器是否下载,可取值为inline、attachment; filename="download.txt"
Content-LengthLong Int返回Object的数据大小
Content-RangeString有range的情况下返回Object的数据范围
Content-TypeStringObject的类型及编码方式
ExpiresString下载Object时的缓存失效时间
ETagStringObject的HTTP协议实体标签
x-ic-meta-*String如果有自定meta,才返回此项
x-ic-server-side-encryptionStringObject的服务器端加密类型,当前支持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参数

请求参数
字段类型是否必需描述
delimiterString分隔符; 主要用此项实现list文件夹的逻辑。如果在请求的时候指定了delimiter,FOS把匹配到的Object名称按照一定规则(从preifx到第一个delimiter)截取,截取的字符串去重作为CommonPrefixes的数据返回; delimiter长度限制为1
markerStringobject为字母序排列,从marker之后的第一个开始返回
maxKeysInt返回object列表长度最大为1000,默认值是1000,如果指定的值大于1000,按1000操作
prefixStringkey前缀,限定返回的object key必须以此为前缀

响应(Response)

响应头域

无特殊Header参数响应

响应元素
名称类型描述
commonPrefixesArray仅当指定delimiter,才会返回此项
+prefixString匹配以prefix开始到第一次出现Delimiter字符之间的object作为一组元素返回
contentsArray返回的一个object的列表
+keyStringObject名称
+lastModifiedDate此Object最后一次被修改的时间
+eTagStringObject的HTTP协议实体标签
+sizeIntObject的内容的大小(字节数)
+storageClassStringObject的存储类型,低频存储返回STANDARD_IA,冷存储返回COLD,归档存储返回ARCHIVE,标准存储返回STANDARD。
+ownerContainerObject上传者的用户信息
++idStringObject上传者的用户id
++displayNameStringObject上传者的名称
delimiterString查询的结束符
isTruncatedBool指明是否查询完整返回了;false-本次已经返回所有结果,true-本次还没有返回所有结果
maxKeysInt请求返回的最大数目
markerString本次查询的起点
nameStringBucket名称
nextMarkerString当IsTruncated true时,才返回此项,作为下次查询marker的值
prefixString查询的前缀

注意事项 Delimiter可以用来实现文件夹逻辑:

  1. 如果把prefix设为某个文件夹名,就可以罗列以此prefix开头的文件,即该文件夹下递归的所有的文件和子文件夹内的文件。
  2. 如果再把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-sourceString源Object地址
x-ic-copy-source-if-matchString如果源Object的ETag值和用户提供的ETag相等,则执行拷贝操作,否则拷贝失败。
x-ic-metadata-directiveString目的Object的Meta信息是从源Object拷贝,还是用请求传入的meta。有效值为copy和replace,缺省值为copy。如果设置为copy,则直接用源Object的meta;如果设置为replace,则用请求传入的meta。
x-ic-meta-*Stringreplace模式下启动,可修改用户自定义meta,自定义meta是用来保存对象的自定义信息。例如设置文件的标签,参数用“x-ic-meta-gender”,值设置为“Male”。
x-ic-copy-source-if-none-matchString如果源Object的ETag和用户提供的ETag不相等,则执行拷贝操作,否则拷贝失败。
x-ic-copy-source-if-unmodified-sinceString如果源object在x-ic-copy-source-if-unmodified-since之后没被修改,则执行拷贝操作,否则拷贝失败。参数取值为GMT格式,例如:Wed, 06 Apr 2016 06:34:40 GMT。
x-ic-copy-source-if-modified-sinceString如果源object在x-ic-copy-source-if-modified-since之后被修改了,则执行拷贝操作,否则拷贝失败。参数取值为GMT格式,例如:Wed, 06 Apr 2016 06:34:40 GMT。
x-ic-aclStringCannedACL支持的header,用户设置Object的权限,取值为private和public-read。
x-ic-grant-readStringCannedACL支持的header,用户设置Object的读权限。支持多个id,以逗号分隔
x-ic-grant-full-controlStringCannedACL支持的header,用户设置Object的FULL_CONTROL权限。支持多个id,以逗号分隔
x-ic-server-side-encryptionString服务端加密算法,当前支持AES256和SM4加密。

响应(Response)

响应头域

无特殊头域

响应参数
名称类型描述
ETagString目的Object的ETag
lastModifiedDATE目的Object的最后一次修改时间

注意事项

  1. 请求者必须对源Object有读操作权限。
  2. 在计算签名之前,用户需要针对x-ic-copy-source字段中为非标准ASCII字符(例如:中文)的内容做一次url-encode。
  3. 为了保持复制过程中的http连接,CopyObject接口的http结果可能使用Transfer-Encoded: Chunked编码方式。
  4. CopyObject过程中,如果发生服务器端错误,http status code可能返回2XX但是复制失败,复制结果请根据http body中的json判定。
  5. CopyObject如果源object是归档类型,需要先取回归档类型才能调用CopyObject接口。
  6. 归档类型Object不支持通过CopyObject实现Meta更新(使用replace模式且源和目标指向同一个文件)。
  7. 如果复制软链接文件,并不会复制数据,只会复制软链接本身。如果使用软链接访问该接口,且软链接的目标文件删除了,会返回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-ControlString浏览器cache的一种机制设置
Content-DispositionString指示浏览器如何显示附加的文件
Content-MD5StringRFC2616定义的HTTP请求内容的MD5摘要,可以通过携带该字段来验证保存在FOS侧的文件和用户预期的文件是否一致。
ExpiresStringGMT时间,缓存失效时间
x-ic-meta-*String用户自定义的meta
x-ic-content-sha256String指本次所传数据的sha256值,必须与此匹配,否则AppendObject失败
x-ic-content-crc32String本次上传object增量数据的CRC值(循环冗余校验码)。
x-ic-aclStringCannedACL支持的header,用户设置Object的权限,取值为private和public-read。
x-ic-grant-readStringCannedACL支持的header,用户设置Object的读权限。支持多个id,以逗号分隔
x-ic-grant-full-controlStringCannedACL支持的header,用户设置Object的FULL_CONTROL权限。支持多个id,以逗号分隔
x-ic-server-side-encryptionString服务端加密算法,当前支持AES256和SM4加密。
请求参数
名称类型参数位置描述是否必须
append-Query参数代表对Appendable Object进行追加操作
offset-Query参数代表数据断点,即从该点后继续追加,取值为已实际上传的数据大小

响应(Response)

响应头域
名称类型描述是否必须
Content-MD5String当前已成功上传的整个object的MD5值
x-ic-next-append-offsetLong Int指明下次AppendObject请求时传入的OffsetSize的值。如果不使用续传方式,即请求起始行没有offset,则这个值是0
x-ic-content-crc32String整个object数据的CRC值(循环冗余校验码)。
ETagStringAppend后整个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-offsetString当Object是由AppendObject接口创建的,会返回该字段,指明下次AppendObject时请求传入的OffsetSize的值。如果此时Object的大小是5G,offset依然返回5G
x-ic-object-typeString当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参数描述父节点
objectsRequest Body参数保存要删除的Object信息的容器,里面包含一个或多个Object元素。-
+keyRequest 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-aclStringObject设置的ACL权限,支持:private、public-read
x-ic-grant-readString授权读的user id,支持多个id,以逗号分隔
x-ic-grant-full-controlString授权控制权限的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参数返回

响应参数
名称类型描述
accessControlListObjcetACL访问控制列表
+granteeObjcet一个被授权人
++idString被授权用户名id
+permissionString授权权限支持: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-aclStringCannedACL支持的header,用户设置Object的权限,取值为private或public-read。
x-ic-grant-readStringCannedACL支持的header,用户设置Object的读权限。支持多个id,以逗号分隔
x-ic-grant-full-controlStringCannedACL支持的header,用户设置Object的FULL_CONTROL权限。支持多个id,以逗号分隔
x-ic-server-side-encryptionString服务端加密算法,当前支持AES256和SM4加密。
Cache-ControlString下载Object的Cache设置,常见的可取值为private、no-cache、max-age、must-revalidate
ExpiresString设置下载Object时的缓存失效时间

请求参数

名称类型参数位置描述是否必需
uploadsStringQuery参数分块上传的请求

响应(Response)

响应头域

响应元素

名称类型描述
bucketStringBucket名称
keyStringObject名称
uploadIdString全局唯一ID,用于标识此次MultiUpload操作

注意事项

  1. 使用MultipartUpload上传的Object,如不指定Content-Type,FOS会自动识别设置合适的Content-Type,若无法识别则默认为application/octet-stream。
  2. 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-MD5StringRFC2616定义的HTTP请求内容的MD5摘要,可以通过携带该字段来验证保存在FOS侧的文件和用户预期的文件是否一致。
x-ic-content-sha256String通过携带该字段来验证保存在FOS侧的文件和用户预期的文件是否一致,sha256的校验准确性更高。所传数据的sha256值必须与此匹配,否则UploadPart失败。
x-ic-content-crc32String上传object的CRC值(循环冗余校验码)。

请求参数

名称类型参数位置描述是否必需
partNumberIntQuery参数本次上传的part在object的相对位置
uploadIdStringQuery参数InitiateMultipartUpload获取的UploadId

响应(Response)

响应元素

响应头域

名称类型描述
ETagString每个上传分块的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

请求参数

名称类型参数位置描述是否必需
partNumberIntRequest Body参数此part在目的Object中的序号。partNum取值范围 1-10000,一次MultiPart的PartNumber要求必须严格有序,比如有3个Part,PartNumber可以是1,3,5。
eTagStringRequest Body参数Object的HTTP协议实体标签

请求头域

名称类型描述是否必需
Content-LengthLong Int头域,JSON数据的长度
x-ic-meta-*String用户自定义的meta

响应(Response)

响应头域

  • 无特殊头域

响应元素

名称类型描述
bucketString此Object所属的Bucket
eTagStringObject的HTTP协议实体标签
keyStringObject名称
locationString此Object的url

注意事项

  1. CompleteMultipartUpload的请求Body最大为1MB。
  2. 一次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>

请求头域

无特殊要求头域

请求参数

名称类型参数位置描述是否必需
uploadIdStringQuery参数此次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>

请求头域

无特殊头域

请求参数

名称类型参数位置描述是否必需
maxPartsIntQuery参数FOS一次最多返回的part数目,默认1000,最大1000
partNumberMarkerIntQuery参数按照partNumber排序,本次请求的起始part从此partNumber的下一个开始返回
uploadIdStringQuery参数此次MultipartUpload的ID

响应(Response)

响应头域

无特殊头域

响应元素

名称类型描述
bucketString所属Bucket名称
keyStringObject名称
uploadIdString请求指定的UploadId
initiatedStringmultipartUpload的创建时间
ownerContainer此object所属的用户信息
+idString用户ID
+displayNameString用户名
partNumberMarkerInt请求指定的本次part Number起始位置
nextPartNumberMarkerInt本次请求返回的最后一条记录的partNumber,可以作为下一次请求的PartNumberMarker
maxPartsInt请求指定的本次最多返回的part数量
isTruncatedBool标明是否本次返回的List Part结果列表被截断。 true表示本次没有返回全部结果; false表示本次已经返回了全部结果
partsContainer一个part的容器
+partNumberInt该part的标识
+lastModifiedDATE该part的上传时间
+ETagString每个上传分块的ETag
+sizeInt该part大小

注意事项

  1. FOS按照PartNumber升序排序。
  2. 由于网络传输可能出错,所以不推荐用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>

请求头域

无特殊要求头域

请求参数

名称类型参数位置描述是否必需
delimiterStringQuery参数分隔符; 主要应此项实现list文件夹的逻辑
keyMarkerStringQuery参数Object按照字典序排序后,本次从keyMarker的后面的一条开始返回
maxUploadsIntQuery参数本次请求返回Multipart Uploads的最大数目,默认1000,最大1000
prefixStringQuery参数key前缀,限定返回的object key必须以此为前缀
uploadsStringQuery参数标明请求是 ListMultipartUploads

响应(Response)

响应头域

无特殊头域

响应元素

名称类型描述
bucketString所属Bucket名称
commonPrefixes-如果在请求的时候指定了delimiter,将返回此项。FOS把匹配到的Object名称
按照一定规则(从preifx到第一个delimiter)截取,截取的字符串去重作为CommonPrefixes的数据返回
delimiterString返回请求中的delimiter值
prefixStringobject前缀
isTruncatedBool标明是否本次是否没有返回所有的数据。
true表示本次没有返回全部结果; false表示本次已经返回了全部结果
keyMarkerString请求指定的本次返回的MultipartUpload的起始位置
maxUploadsInt请求指定的本次返回的Multipart Uploads的最大数目
nextKeyMarkerString本次返回的最后一条MultipartUpload,可以作为下一次请求的KeyMarker
uploadsContainer保存一个MultipartUpload的容器
+keyStringObject名称
+uploadIdStringMultipartUpload的ID
+ownerContainerObject所属的用户信息
++displayNameString用户名
++idString用户ID
+initiatedDate本次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",
      }
  ]
}