API 调用说明 | OceanBase 文档中心

API 调用说明

更新时间：2026-04-14 16:45:43

本文介绍使用 HTTP 的方式，调用 OCP 的开放 API。并以"查询集群列表"的接口调用作为示例。

请求结构

完整的 HTTP 请求包括 请求 URI 、 请求方法 、 请求消息头 、 请求消息体 。

请求 URI

请求 URI 由如下部分组成：

{scheme}://{endpoint}/{resource-path}?{query-string}

字段	说明
scheme	指定传输协议，一般为 `http` 或 `https` 。
endpoint	即 OCP 的服务地址。如 `192.168.0.1:8080` ，由具体的部署决定。
resource-path	接口的资源路径。各接口的资源路径请参考对应接口文档的"请求路径"的章节部分。例如，"查询集群列表"的资源路径为 `/api/v2/ob/clusters` 。
query-string	查询参数。可选部分，形如 `a=10&b=hello` ，包括若干个键值对。query-string 与 resource-path 以 `?` 分隔。

完整的" 查询集群列表 "的 URI 示例如下：

http://192.168.0.1:8080/api/v2/ob/clusters

请求方法

即 HTTP 协议的方法。包括：GET、PUT、POST、DELETE。各接口文档中详细说明了接口的请求方法。

例如："查询集群列表" 的请求路径为 GET /api/v2/ob/clusters 。即该接口的的请求方法为"GET"。

请求消息头

包含请求的附加信息，如：语言、鉴权信息等。

名称	必选	说明	示例
Content-Type	是	消息体的类型。OCP 统一使用 application/json 类型的消息体。	application/json
Accept-Language	否	客户端的可支持的语言。OCP 开放 API 具备国际化的支持，会根据客户端的语言设置，返回指定语言选项的内容。	en-US, en, q=0.9 zh-CN
Authorization	是	鉴权信息。OCP 开放 API 使用 HTTP 规范的 Basic 认证的鉴权。用户名与密码以 Base64 的规范编码。	Basic Zm9vOmJhcg==

请求消息体

请求消息体是可选部分。包含发送到服务器的业务数据。OCP 开放 API 统一使用 JSON 格式的请求消息体。

鉴权说明

OCP 开放 API 的客户端鉴权，使用 HTTP Basic 认证的模式。

调用时需要通过"请求消息头"的 Authorization 属性，传递用户/密码的 Base64 编码。

例如，用户 foo 的密码为 bar。使用用户 foo 来调用 OCP 开放 API 时，需要传递请求消息头：

Authorization: Basic Zm9vOmJhcg==

其中， Zm9vOmJhcg== 为 foo:bar 的 Base64 编码。

返回结构

开放 API 返回数据使用统一的数据结构（个别特殊接口除外）。基础返回结果的数据结构如下：

参数	类型	说明
data	Object	"单值型数据"或"列表型数据"或"分页型数据"
├─ contents	Array	├─ 表示与上一行参数的从属关系
successful	Boolean	请求是否成功
timestamp	Datetime	服务端完成请求的时间戳
duration	Integer	服务端处理请求的时间（毫秒）
status	Integer	符合 HTTP Status 规范的编码
traceId	String	请求的 Trace Id，用于排查问题。
server	String	响应请求的服务端的地址

调用示例

curl

可以使用 curl 工具调用开放 API 的接口。下面的例子中，使用用户 admin:hello，访问 OCP 应用的地址为 192.168.100.1 ，端口为 8080，访问的接口为查询租户列表。其中， YWRtaW46aGVsbG8= 为 admin:hello 的 Base64 编码。

curl "http://192.168.0.1:8080/api/v2/ob/clusters/1/tenants"  \
  -H "Authorization: Basic YWRtaW46aGVsbG8="

curl 也提供明文密码的调用方式。

curl "http://192.168.0.1:8080/api/v2/ob/clusters/1/tenants"  \
  --user admin:hello

说明

使用明文密码的方式会降低安全性，请谨慎使用。

国际化说明

OCP 开放 API 具备国际化的支持。接口会根据客户端的语言配置，返回对应语言的内容。详细请参考各 API 接口的文档，说明了其中的属性是否具备国际化的支持。

OCP 开放 API 使用"请求消息头"的 Accept-Language 属性，来指示客户端的语言选项。

流控说明

OCP 提供流量控制功能，可防止用户访问 OCP 过于频繁。在创建用户时，系统管理员可以为 OCP 用户设置流控策略。流控资源包括全局的路径，其包含除静态资源外的 HTTP 请求；细粒度访问控制则能够为 OCP 中不同的资源类型设置访问次数限制。流控时间窗口支持 10 秒、1 分钟、1 小时、一天。

通过系统参数 ocp.iam.rate-limit.enabled 来打开或关闭流控功能。默认为 true ，即打开流控功能。

流控放行时，返回 Header 包括：

RateLimit-Limit : 当前时间窗口内访问次数上限，如 "10"。
RateLimit-Remaining ：当前时间窗口内剩余访问次数，如"7"。
RateLimit-Reset ：当前时间窗口重置剩余重制时间，如"53"。

用户在某一时间窗口内访问相应的资源接口频率超过设定值导致流控拒绝请求时，HTTP 返回码 429 。此时返回结果如下：

{
    "duration":0,
    "error":{
        "code":0,
        "message":"请求次数过多，你已经超过当前流控窗口内的请求上限"
    },
    "server":"192.168.0.1",
    "status":429,
    "successful":false,
    "timestamp":"2020-12-03T09:38:24.194+08:00",
    "traceId":""
}