---
title: "API 调用说明 - 云平台 OCP V4.3.5 | OceanBase 文档中心"
description: "API 调用说明 本文介绍使用 HTTP 的方式，调用 OCP 的开放 API。并以 “查询集群列表” 的接口调用作为示例。 请求结构 完整的 HTTP 请求包括 请求 URI 、 请求方法 、 请求消息头 、 请求消息体 。 请求 URI 请求 URI 由如下部分组成： {scheme}://{endpoint}/…"
---
切换语言

- 中文站 - 简体中文
- International - English
- 日本站 - 日本語

文档反馈![](https://mdn.alipayobjects.com/huamei_22khvb/afts/img/A*lJTmRZ61jSUAAAAAAAAAAAAADiGDAQ/original) 云平台 OCPV 4.3.5

# API 调用说明

更新时间：2026-04-14 15:11:03

[编辑](https://github.com/oceanbase/ocp-doc/edit/V4.3.5/zh-CN/1900.reference-guide/200.api-reference/200.api-call-description.md)  

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

## 请求结构

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

## 请求 URI

请求 URI 由如下部分组成：

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

```

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

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

```java
http://xxx.xxx.xxx.xxx: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 的客户端鉴权，支持使用 AK/SK 和 HTTP Basic 两种认证模式。

- HTTP Basic 认证模式

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

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

  ```java
  Authorization: Basic Zm9vOmJhcg==

  ```

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

  #### 说明

  HTTP Basic 认证模式可能存在密码泄漏风险，推荐您使用 AK/SK 认证模式。
 - AK/SK 认证模式

  AK/SK 认证模式可以避免在 HTTP 中明文传输密码，也可以让您在不共享密码的情况下授权他人登录。

  详情可参考 [AK/SK 签名生成规则](https://www.oceanbase.com/docs/common-ocp-1000000002381202)。

## 返回结构

开放 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 应用的地址为 `xxx.xxx.xxx.xxx` ，端口信息为 `8080`，访问的接口为查询租户列表。其中， `YWRtaW46aGVsbG8=` 为 `admin:hello` 的 Base64 编码。

```java
curl "http://xxx.xxx.xxx.xxx:8080/api/v2/ob/clusters/1/tenants"  \
  -H "Authorization: Basic YWRtaW46aGVsbG8="

```

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

```java
curl "http://xxx.xxx.xxx.xxx: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 小时、一天。

![1](https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/9246790261/p273248.png)

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

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

1. `RateLimit-Limit` : 当前时间窗口内访问次数上限，如 “10”。
 2. `RateLimit-Remaining` ：当前时间窗口内剩余访问次数，如 “7”。
 3. `RateLimit-Reset` ：当前时间窗口重置剩余重制时间，如 “53”。

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

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

```

 上一篇 下一篇 ![有帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*y6ocSqN8cqsAAAAAAAAAAAAAARQnAQ)![无帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*BG9IQJyLHF8AAAAAAAAAAAAAARQnAQ)![反馈](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*eTWdQKCRKHwAAAAAAAAAAAAAARQnAQ)[AI](https://www.oceanbase.com/obi) 咨询热线