文档首页/ 对象存储服务 OBS/ API参考/ 如何调用API/ 构造请求
更新时间：2025-08-29 GMT+08:00
分享

构造请求

本节介绍REST API请求的组成。

您还可以通过这个视频教程了解如何构造请求调用API：https://bbs.huaweicloud.com/videos/101580

请求URI

OBS根据桶和对象及携带的资源参数来确定具体的URI，当需要进行资源操作时，可以使用这个URI地址。

URI的一般格式为（方括号内为可选项）：

protocol://[bucket.]domain[:port][/object][?param]

表1 URI中的参数

参数名称

参数类型

是否必选

描述

protocol

String

必选

参数解释：

请求使用的协议类型。

约束限制：

不涉及

取值范围：

  • HTTP：超文本传输协议，使用明文传输数据，容易被窃听和篡改。通常用于传输不包含敏感信息的网站，如新闻网站等。
  • HTTPS：安全超文本传输协议，使用SSL/TLS协议对数据进行加密，提供安全可靠的通信，用于传输需要保护的敏感信息。

默认取值：

无

bucket

String

可选

参数解释：

桶名。

约束限制：

  • 桶的名字需全局唯一，不能与已有的任何桶名称重复，包括其他用户创建的桶。
  • 桶命名规则如下：
    • 3～63个字符，数字或字母开头，支持小写字母、数字、“-”、“.”。
    • 禁止使用IP地址。
    • 禁止以“-”或“.”开头及结尾。
    • 禁止两个“.”相邻（如：“my..bucket”）。
    • 禁止“.”和“-”相邻（如：“my-.bucket”和“my.-bucket”）。
  • 同一用户在同一个区域多次创建同名桶不会报错，创建的桶属性以第一次请求为准。

默认取值：

无

domain

String

必选

参数解释：

各区域的终端节点（Endpoint）

约束限制：

不涉及

取值范围：

各区域的终端节点详情请参见地区和终端节点。

默认取值：

不涉及

port

String

可选

参数解释：

请求使用的端口号。根据软件服务器的部署不同而不同。

约束限制：

不涉及

取值范围：

OBS对象存储服务的HTTP方式访问端口为80，HTTPS方式访问端口为443。

默认取值：

缺省时使用默认端口，各种传输协议都有默认的端口号，如HTTP的默认端口为80，HTTPS的默认端口为443。

object

String

可选

参数解释：

对象名。对象名是对象在存储桶中的唯一标识。对象名是对象在桶中的完整路径，路径中不包含桶名。

例如，您对象的访问地址为examplebucket.obs.cn-north-4.myhuaweicloud.com/folder/test.txt 中，对象名为folder/test.txt。

取值范围：

长度大于0且不超过1024的字符串。

默认取值：

无

param

String

可选

参数解释：

请求使用的桶和对象的具体资源。

约束限制：

不涉及

取值范围：

不涉及

默认取值：

不设置默认为请求桶或对象自身资源。

除获取桶列表之外的所有接口，都应当包含桶名。OBS基于DNS解析性能和可靠性的考虑，要求凡是携带桶名的请求，在构造URL的时候都必须将桶名放在domain前面，形成三级域名形式，又称为虚拟主机访问域名。

例如，如果您有一个位于cn-north-4区域的名为test-bucket的桶，期望访问桶中一个名为test-object对象的acl，正确的访问URL为https://test-bucket.obs.cn-north-4.myhuaweicloud.com/test-object?acl

请求方法

HTTP方法（也称为操作或动词），它告诉服务您正在请求什么类型的操作。

表2 对象存储支持的REST请求方法

方法

说明

GET

请求服务器返回指定资源，如获取桶列表、下载对象等。

PUT

请求服务器更新指定资源，如创建桶、上传对象等。

POST

请求服务器新增资源或执行特殊操作，如初始化上传段任务、合并段等。

DELETE

请求服务器删除指定资源，如删除对象等。

HEAD

请求服务器返回指定资源的概要，如获取对象元数据等。

OPTIONS

请求服务器检查是否具有某个资源的操作权限，需要桶配置CORS。

请求消息头

可选的附加请求头字段，如指定的URI和HTTP方法所要求的字段。详细的公共请求消息头字段请参见表3。

表3 公共请求消息头

消息头名称

参数类型

是否必选

描述

Authorization

String

有条件必选

参数解释：

请求消息中可带的签名信息。

约束限制：

匿名请求不需要带，其他请求必选。

取值范围：

不涉及

默认取值：

不涉及

Content-Length

String

有条件必选

参数解释：

消息（不包含消息头）长度。

约束限制：

PUT操作可选，加载XML的操作必须带。

取值范围：

不涉及

默认取值：

不涉及

Content-Type

String

否

参数解释：

资源内容的类型，例如： text/plain。

约束限制：

不涉及

取值范围：

常见的Content-Type类型参见常见的Content-Type类型。

默认取值：

如果上传对象时未携带该字段，下载对象时默认返回的Content-Type为binary/octet-stream。

Date

String

有条件必选

参数解释：

请求发起端的日期和时间，例如：Wed, 27 Jun 2018 13:39:15 +0000。

约束限制：

如果是匿名请求或者消息头中带了x-obs-date字段，则可以不带该字段，其他情况下必选。

取值范围：

不涉及

默认取值：

不涉及

Host

String

是

参数解释：

桶的访问域名，格式为桶名.终端节点，即BucketName.Endpoint

如examplebucketname.obs.cn-north-4.myhuaweicloud.com。

约束限制：

桶名的约束限制如下：

  • 桶的名字需全局唯一，不能与已有的任何桶名称重复，包括其他用户创建的桶。
  • 桶命名规则如下：
    • 3～63个字符，数字或字母开头，支持小写字母、数字、“-”、“.”。
    • 禁止使用IP地址。
    • 禁止以“-”或“.”开头及结尾。
    • 禁止两个“.”相邻（如：“my..bucket”）。
    • 禁止“.”和“-”相邻（如：“my-.bucket”和“my.-bucket”）。
  • 同一用户在同一个区域多次创建同名桶不会报错，创建的桶属性以第一次请求为准。

取值范围：

各区域的终端节点详情请参见地区和终端节点。

默认取值：

不涉及

请求消息体（可选）

请求消息体通常以结构化格式（如JSON或XML）发出，与请求消息头中Content-type对应，传递除请求消息头之外的内容。如果请求消息体中参数支持中文，则中文字符必须为UTF-8编码。

每个接口的请求消息体内容不同，也并不是每个接口都需要有请求消息体（或者说消息体为空），GET、DELETE操作类型的接口就不需要消息体，消息体具体内容需要根据具体接口而定。

发起请求

共有两种方式可以基于已构建好的请求消息发起请求，分别为：

  • cURL

    cURL是一个命令行工具，用来执行各种URL操作和信息传输。cURL充当的是HTTP客户端，可以发送HTTP请求给服务端，并接收响应消息。cURL适用于接口调试。关于cURL详细信息请参见https://curl.haxx.se/。由于cURL无法计算签名，使用cURL时仅支持访问匿名的公共OBS资源。

  • 编码

    通过编码调用接口，组装请求消息，并发送处理请求消息。可以使用SDK或自行编码实现。

父主题： 如何调用API

相关文档