跳到主要内容

查看 REST API 文档

管理平台提供完整的 API 文档，帮助您快速理解

并调用平台功能。通过使用 API 文档，您可查看详细的 API 说明、在线调试 API、查看 API 认证方式、搜索 API 文档，以及下载API 文档。API 文档页面不受登录权限限制，所有用户均可查看全部 API 说明与详情。但当实际调用 API 时，管理平台会根据操作员的 API 权限（与 Web 界面上对应功能权限一致）和数据权限，控制可访问的功能和可查看的数据，从而保障 API 调用时的安全管控。

限制与指导

REST API 不适用于高版本 CVM 管理低版本 CVK主机的场景。

步骤

在页面右上角单击，然后选择 REST API 文档。

页面布局

REST API 文档页面的布局如下：

REST API documentation layout

功能

• 查看 API 文档摘要

• 查看 API 说明

• 在线调试 API

• 查看 API 认证方式

• 搜索 API 文档

• 下载 API 文档

查看 API 文档摘要​

执行此任务可查看管理平台中 REST API 文档的整体信息，

包括作者、版本号、服务器地址 (Host)、基础路径 (BasePath)、服务条款、分组信息和接口统计。

步骤

  1. 在页面右上角单击，然后选择 REST API 文档。

  2. 在左侧导航页，选择首页。

参数

• Version：API 文档的 API 版本。

• Host：API 服务所在主机的 IP 地址和端口。

• BasePath：所有 API 请求的基础路径，用于构造完整的请求地址。

• TermsOfService：API 使用的协议和限制。

• 分组名称：用于 API 分类的 API 分组名称。

• 分组 URL：API 分组的访问路径，用于获取该分组的OpenAPI 文档。

• 分组位置：API 文档的实际地址。

• 接口统计：各请求方法对应的 API 数量。

查看 API 说明​

您可以获取管理平台中某个 API 的详细文档信息，包括

API 说明、请求参数说明、响应参数说明、示例，以及状态码说明。您还可以查看该 API 的调试页面、OpenAPI 内容和脚本调用模板，以便进行开发和调试。

步骤

  1. 在页面右上角单击，然后选择 REST API 文档。

  2. 在左侧导航页，选择 API 分类 > API。

  3. 单击 Doc 页签可查看 API 的详细信息，包括 API 路径、请求方法、请求与响应数据类型、参数说明和示例值、状态码说明，以及响应结构。您可以执行以下操作：

    ○ 在右上角单击 Copy Url 可将该 API 的请求路径（例如/api/operation-log/list）复制到剪贴板，供后续在脚本或工具中使用。

    ○ 在右上角单击 Copy 可将当前 API 文档页面的所有内容复制到剪贴板。

    ○ 在右上角单击 Copy Address 可将当前 API 文档页面的链接地址复制到剪贴板，用于分享或在其他位置打开。

  4. 单击 Debug 页签。相关操作请参见"在线调试 API"。

  5. 单击 Open 页签。您可以查看该 API 的 OpenAPI 规范内容（JSON 格式）。在此页面，您可以执行以下操作：

    ○ 单击 Copy 可将该 API 的 OpenAPI JSON 内容复制到剪贴板，用于保存或导入到其他工具中进行调试和查看。

在线调试 API​

执行此任务，无需额外的开发或第三方工具即可直接调用并测试

各类 REST API。您可以选择请求方法、输入请求参数、发送请求，并在页面下方实时查看响应内容、原始数据、响应头信息以及对应的 curl 命令。这可帮助您快速验证 API 功能、参数格式和数据返回结果，便于调试和排障。

步骤

  1. 在页面右上角单击，然后选择 REST API 文档。

  2. 在左侧导航页，选择 API 分类 > API。

  3. 单击 Debug 页签。

  4. 在左上角下拉列表中，按需选择请求方法（如 GET 或 POST）。

  5. 在 API 地址栏中，确认要调用的 API 路径。

  6. 单击 Params 页签，输入所需的请求参数内容。若选择x-www-form-urlencoded，修改参数后必须选中该参数以启用。更多信息请参见"参数"。

  7. （可选。）单击 AfterScript 页签。在调用 API 前编写一段 JavaScript 脚本。API 调用成功后，系统会自动运行该脚本。

  8. 单击 Send 向服务器发送请求。

  9. 第一次请求发送后，页面下方会显示响应结果，包括Response、Raw、Headers 和 Curl 页签，以及 Show Description、Code、Duration 和Size 参数。您可以查看不同格式的返回信息。更多信息请参见"参数"。

参数

请求参数支持以下输入格式：

• x-www-form-urlencoded：以键值对格式将请求参数编码到 HTTP 请求体中。选择此格式后，页面显示参数名和参数值列。您可以编辑或删除参数行。

○ 每行左侧的复选框控制该参数是否生效。只有选中的参数才在请求中生效。未选中的参数使用默认值。输入或编辑参数名或参数值后，系统会自动选中该参数。例如，pageSize 参数的默认值为 20。若在值列输入 5 并选中该参数，API 将返回 5 条数据。若不选中该参数，API将返回 20 条数据。

○ 您可以将参数名修改为 Doc 页签中定义的任意 API 请求参数，以便调试不同的参数组合。例如，系统默认有 userName 和 pageSize 参数行。将userName 改为 pageSize，然后在两行 pageSize 中分别输入 5 和 10。通过切换选中项即可快速测试不同的返回结果。

• form-data：以 multipart 表单数据格式传输请求参数。

• raw：直接输入原始请求体数据。选择此格式后，可在右侧选择请求体格式。可选项包括：

○ Auto

○ Text(text/plain)

○ JSON(application/json)

○ Javascript(application/Javascript)

○ XML(application/xml)

○ XML(text/xml)

○ HTML(text/html)

响应结果

• Response：以 JSON 格式显示返回的数据。

• Raw：显示未格式化的原始响应数据。您可以单击 Copy 复制内容。

• Headers：显示服务器返回的 HTTP 响应头信息。

• Curl：显示用于调用请求的 curl 命令（包含方法、URL 和请求头）。您可以单击 Copy 复制内容。

• Show Description：若选中该参数，Response 页签中返回的数据将追加对应的描述信息，便于理解各字段的含义。

• Code：显示 HTTP 状态码。例如 200 表示请求成功。

• Duration：显示完成请求所耗时间（毫秒），可用于API 性能分析。

• Size：显示响应内容的大小（字节），用于评估数据量。

查看 API 认证方式​

搜索 API 文档​

执行此任务可通过关键字在管理平台快速定位所需的 API 文档。

搜索范围包括 API 名称和 API 说明。

步骤

  1. 在页面右上角单击，然后选择 REST API 文档。

  2. 在页面右上角的搜索框中输入关键字。

下载 API 文档​