主题切换
REST API
以下几部分详细介绍osca Open API的定义。
通用请求头
请求URI
osca根据桶和对象及带的资源参数来确定具体的URI，当需要进行资源操作时，可以使用这个URI地址。
URI的一般格式为（方括号内为可选项）：
protocol://domain[:port]/[bucket][/object][?param]URI中的参数
| 参数 | 描述 | 是否必选 |
|---|---|---|
| protocol | 请求使用的协议类型，如HTTP、HTTPS。 | 必选 |
| bucket | 请求使用的桶资源路径，在整个系统中唯一标识一个桶。 | 可选 |
| domain | 存放资源的服务器的域名或IP地址。 | 必选 |
| port | 请求使用的端口号。根据软件服务器的部署不同而不同。缺省时使用默认端口，各种传输协议都有默认的端口号，如HTTP的默认端口为80，HTTPS的默认端口为443。osca对象存储服务的HTTP方式访问端口为80，HTTPS方式访问端口为443。 | 可选 |
| object | 请求使用的对象资源路径。 | 可选 |
| param | 请求使用的桶和对象的具体资源，缺省默认为请求桶或对象自身资源。 | 可选 |
请求方法
HTTP方法（也称为操作或动词），它告诉服务你正在请求什么类型的操作。
对象存储支持的REST请求方法
| 方法 | 说明 |
|---|---|
| GET | 请求服务器返回指定资源，如获取桶列表、下载对象等。 |
| PUT | 请求服务器更新指定资源，如创建桶、上传对象等。 |
| POST | 请求服务器新增资源或执行特殊操作，如初始化上传段任务、合并段等。 |
| DELETE | 请求服务器删除指定资源，如删除对象等。 |
| HEAD | 请求服务器返回指定资源的概要，如获取对象元数据等。 |
| OPTIONS | 请求服务器检查是否具有某个资源的操作权限，需要桶配置CORS。 |
请求消息头
可选的附加请求头字段，如指定的URI和HTTP方法所要求的字段。
公共请求消息头
| 消息头名称 | 描述 | 是否必选 |
|---|---|---|
| Authorization | 请求消息中可带的签名信息。类型：String 条件：匿名请求不需要带，其他请求必选。 默认值：无。 | 有条件必选 |
| Content-Length | RFC 2616中定义的消息（不包含消息头）长度。类型：String。 默认值：无。条件：PUT操作可选，加载XML的操作必须带。 | 有条件必选 |
| Content-Type | 资源内容的类型，例如：text/plain。类型：String。默认值：无。 | 否 |
| X-Amz-Date | 请求发起端的日期和时间。例如：Wed, 27 Jun 2018 13:39:15 +0000。类型：String 默认值：无。条件：如果是匿名请求或者消息头中带了x-osca-date字段，则可以不带该字段，其他情况下必选。 | 有条件必选 |
| X-Amz-Content-Sha256 | 请求正文的 SHA-256 散列值。这个散列值用于验证请求的内容完整性。类型：String。默认值：无。 | 有条件必选 |
| Host | 表明主机地址。如fgws3-ocloud.ihep.ac.cn。类型：String。默认值：无。 | 是 |
请求消息体（可选） 请求消息体通常以结构化格式（如JSON或XML）发出，与请求消息头中Content-type对应，传递除请求消息头之外的内容。若请求消息体中参数支持中文，则中文字符必须为UTF-8编码。
每个接口的请求消息体内容不同，也并不是每个接口都需要有请求消息体（或者说消息体为空），GET、DELETE操作类型的接口就不需要消息体，消息体具体内容需要根据具体接口而定。
请求消息体（可选）
请求消息体通常以结构化格式（如JSON或XML）发出，与请求消息头中Content-type对应，传递除请求消息头之外的内容。若请求消息体中参数支持中文，则中文字符必须为UTF-8编码。
每个接口的请求消息体内容不同，也并不是每个接口都需要有请求消息体（或者说消息体为空），GET、DELETE操作类型的接口就不需要消息体，消息体具体内容需要根据具体接口而定。
发起请求
共有两种方式可以基于已构建好的请求消息发起请求，分别为：
cURL cURL是一个命令行工具，用来执行各种URL操作和信息传输。cURL充当的是HTTP客户端，可以发送HTTP请求给服务端，并接收响应消息。cURL适用于接口调试。关于cURL详细信息请参见https://curl.haxx.se/。由于cURL无法计算签名，使用cURL时仅支持访问匿名的公共osca资源。
编码 通过编码调用接口，组装请求消息，并发送处理请求消息。可以使用SDK或自行编码实现。
通用响应头
请求发送以后，您会收到响应，包含状态码、响应消息头和消息体。
状态码
状态码是一组从2xx（成功）到4xx或5xx（错误）的数字代码，状态码表示了请求响应的状态，完整的状态码列表请参见状态码。
响应消息头
对应请求消息头，响应同样也有消息头，如“Content-type”。
公共响应消息头
| 消息头名称 | 描述 |
|---|---|
| Content-Length | 响应消息体的字节长度。类型：整数。默认值：无。 |
| Content-Type | 响应消息体的内容类型。例如，application/json 或 text/html。默认值：无。 |
| Server | 服务器软件的名称和版本信息。例如 JWanFS FGW Server 服务 |
| Date | 响应生成的日期和时间。例如 Fri, 24 Nov 2023 08:09:04 GMT |
| X-Amz-Request-Id | Amazon S3 生成的唯一请求标识符。类型：字符串。默认值：无。 例如 1700813344215040281 |
| Accept-Ranges | 表示服务器是否支持范围请求的响应头。类型：字符串。默认值：无。 例如 bytes |
响应消息体（可选）
响应消息体通常以结构化格式（如JSON或XML）返回，与响应消息头中Content-type对应，传递除响应消息头之外的内容。
错误码定义
调用接口出错后，将不会返回结果数据。调用方可根据每个接口对应的错误码来定位错误原因。 当调用出错时，HTTP请求返回一个3xx，4xx或5xx的HTTP状态码。返回的消息体中是具体的错误代码及错误信息。在调用方找不到错误原因时，可以联系华为云客服，并提供错误码，以便我们尽快帮您解决问题。
错误响应消息格式
当错误发生时，响应消息头中都会包含：
- Content-Type: application/xml
- 错误对应的3xx，4xx或5xx的HTTP状态码。 响应消息体中同样会包含对错误的描述信息。下面的错误响应消息体示例展示了所有REST错误响应中公共的元素。
text
<?xml version="1.0" encoding="UTF-8"?>
<Error>
<Code>AccessDenied</Code>
<Message>访问被拒绝</Message>
<Resource>/20001-cbq</Resource>
<RequestId>1700819696586081391</RequestId>
</Error>错误响应消息元素
| 消息头名称 | 描述 |
|---|---|
| Error | 错误响应消息体XML结构中描述错误信息的根节点元素 。 |
| Code | 错误响应消息体XML中错误响应对应的HTTP消息返回码。 |
| Message | 错误响应消息体XML中具体错误更全面的解释。 |
| RequestId | 本次错误请求的请求ID，用于错误定位。 |
| Resource | 该错误相关的桶或对象资源。 |
错误码说明
在向OSCA-OSS系统发出请求后，如果遇到错误，会在响应中包含响应的错误码描述错误信息。对象存储访问服务的错误码如下所示。
错误码
| 状态码 | 错误码 | 错误信息 |
|---|---|---|
| 400 | InvalidBucketName | 指定的存储桶无效。 |
| 400 | InvalidDigest | 您指定的Content-Md5无效。 |
| 400 | InvalidArgument | 参数max-uploads必须是介于0和2147483647之间的整数 |
| 400 | InvalidArgument | 参数maxKeys必须是介于0和2147483647之间的整数 |
| 400 | InvalidArgument | 参数max-parts必须是介于0和2147483647之间的整数 |
| 400 | InvalidArgument | 参数对象可以包含最多1000个键的列表 |
| 400 | InvalidArgument | 参数partNumberMarker必须是整数。 |
| 400 | InvalidPart | 找不到一个或多个指定部件。部件可能尚未上载，或者指定的实体标记可能与部件的实体标记不匹配。 |
| 400 | InvalidRequest | 此复制请求是非法的，因为它试图在不更改对象的元数据、存储类、网站重定向位置或加密属性的情况下将对象复制到自身。 |
| 400 | InvalidArgument | 复制源必须提到源桶和密钥：sourcebucket/sourcekey。 |
| 400 | InvalidTag | 您提供的标记值无效 |
| 400 | MalformedXML | 您提供的XML格式不正确，或者没有根据我们发布的架构进行验证。 |
| 400 | InvalidArgument | 授权标头无效--只需要一个' '（空格）。 |
| 400 | InvalidRequest | 不支持您提供的授权机制。请使用AWS4-HMAC-SHA256。 |
| 400 | MalformedPOSTRequest | POST请求的主体不是格式正确的多部分/表单数据。 |
| 400 | InvalidArgument | POST要求每个请求只上传一个文件。 |
| 400 | EntityTooSmall | 您建议的上载小于允许的最小对象大小。 |
| 400 | EntityTooLarge | 您建议的上载超出了允许的最大对象大小。 |
| 400 | MissingFields | 请求中缺少字段。 |
| 400 | InvalidRequest | 此请求缺少凭据字段。 |
| 400 | AuthorizationQueryParametersError | 分析X-Amz-Credential参数时出错 凭证格式错误 应为<YOUR-AKID>/YYYMMDD/REGION/SERVICE/aws4_request |
| 400 | MalformedDate | 日期格式标头无效，应为ISO8601、RFC1123或RFC1123Z时间格式 |
| 400 | AuthorizationQueryParametersError | X-Amz-Date必须采用ISO8601长格式 "yyyyMMdd'T'HHmmss'Z'" |
| 400 | InvalidArgument | 签名标头缺少SignedHeaders字段 |
| 400 | AccessDenied | 签名标头缺少签名字段 |
| 400 | AccessDenied | 请求中存在未签名的标头 |
| 400 | AuthorizationQueryParametersError | 查询字符串身份验证版本4需要X-Amz-Algorithm、X-Amz-Credential、X-Amz Signature、X-Amz-Date、X-Amz-SignedHeaders和X-Amz-Expires参数 |
| 400 | AuthorizationQueryParametersError | X-Amz-Algorithm 仅支持 "AWS4-HMAC-SHA256". |
| 400 | AuthorizationQueryParametersError | X-Amz-Expires 应为数字 |
| 400 | AuthorizationQueryParametersError | X-Amz-Expires 必须为非负数 |
| 400 | AuthorizationQueryParametersError | X-Amz-Expires必须少于一星期 (单位:秒)也就是说 给定X-Amz-Expires必须小于604800秒 |
| 400 | XAmzContentSHA256Mismatch | 提供的 x-amz-content-sha256 标头与计算的内容不匹配 |
| 400 | AccessDenied | AWS认证需要有效的日期或x-amz-date头 |
| 400 | InvalidRequest | 无效的请求 |
| 400 | InvalidRequest | 签名请求需要设置JWanFS FGW Server身份验证 |
| 403 | AccessDenied | 请求已过期 |
| 403 | AccessDenied | 访问被拒绝 |
| 403 | PostPolicyInvalidKeyName | 根据策略无效：策略条件失败 |
| 403 | InvalidAccessKeyId | 您提供的访问密钥ID在我们的记录中不存在 |
| 403 | AccessDenied | 请求尚未有效 |
| 403 | SignatureDoesNotMatch | 我们计算的请求签名与您提供的签名不匹配。检查您的密钥和签名方法 |
| 404 | NoSuchBucket | 指定的存储桶不存在 |
| 404 | NoSuchBucketPolicy | 存储桶策略不存在 |
| 404 | NoSuchCORSConfiguration | CORS配置不存在 |
| 404 | NoSuchLifecycleConfiguration | 生命周期配置不存在 |
| 404 | NoSuchKey | 指定的密钥不存在。 |
| 404 | NoSuchUpload | 指定的多部分上载不存在。上载ID可能无效，或者上载可能已中止或完成。 |
| 404 | OwnershipControlsNotFoundError | 未找到存储桶所有权控件 |
| 404 | ErrNotFound | 未找到指定资源 |
| 405 | MethodNotAllowed | 此资源不允许使用指定的方法 |
| 409 | BucketNotEmpty | 您尝试删除的bucket不为空 |
| 409 | BucketAlreadyExists | 请求的存储桶名称不可用。bucket名称不能是现有集合，并且bucket命名空间由系统的所有用户共享。请选择其他名称并重试 |
| 409 | BucketAlreadyOwnedByYou | 您之前创建命名桶的请求成功了，并且您已经拥有了它。 |
| 409 | ExistingObjectIsDirectory | 现有对象是一个目录 |
| 409 | ExistingObjectIsFile | 现有对象是一个文件 |
| 412 | PreconditionFailed | 至少有一个您指定的前提条件不成立 |
| 416 | InvalidRange | 请求的范围不满足要求 |
| 429 | ErrTooManyRequest | 同时请求计数过多 |
| 429 | ErrRequestBytesExceed | 同时请求字节数超过限制 |
| 500 | ErrOutOfBucketSize | 桶空间不足，无法写入 |
| 500 | InternalError | 我们遇到内部错误，请重试。 |
| 501 | NotImplemented | 您提供的标头表示未实现的功能 |