文档中心
在Gitcode上查看源码

HTTP 工具使用指导 ​

概述 ​

本文档介绍如何使用 HTTP 工具与 openUBMC 进行交互，包括使用 POSTMAN 和 curl 发送 Redfish/Web REST 请求。通过这些工具，用户可以方便地管理和监控 BMC 设备。

认识 RESTful API ​

RESTful API 简介 ​

REST (Representational State Transfer) 是一种软件架构风格，RESTful API 基于 HTTP 协议，使用标准的 HTTP 方法（GET、POST、PUT、PATCH、DELETE）对资源进行操作。

openUBMC 提供了完整的 Redfish API 和 Web REST API，支持以下功能：

  • 系统信息查询
  • 设备配置管理
  • 传感器数据读取
  • 日志查询
  • 用户管理
  • 网络配置

HTTP 方法说明 ​

方法描述用途
GET获取资源查询设备信息、状态、配置
POST创建资源创建新资源、执行 Action
PUT完整更新资源完全替换资源内容
PATCH部分更新资源修改资源的部分属性
DELETE删除资源删除指定资源

认证方式 ​

openUBMC 支持以下认证方式：

  • Basic Auth - 基本认证，使用用户名和密码
  • Session Auth - 会话认证，先登录获取会话令牌

使用 POSTMAN 发送请求 ​

认识 POSTMAN ​

POSTMAN 是一款功能强大的 API 开发和测试工具，提供图形化界面，支持各种 HTTP 方法、认证方式、环境变量等功能，是测试 Redfish/Web REST API 的理想工具。

环境要求 ​

  • 操作系统：Windows
  • 软件：POSTMAN 桌面版或浏览器插件
  • 网络：能够访问 BMC IP 地址

安装 POSTMAN ​

Windows 系统 ​

  1. 访问 POSTMAN 官网：https://www.postman.com/downloads/
  2. 下载 Windows 版本安装包。
  3. 运行安装程序，按提示完成安装。

配置 POSTMAN 环境 ​

创建环境变量 ​

  1. 打开 POSTMAN。
  2. 点击 "Manage Environments" 图标。
  3. 点击 "Add" 创建新环境。
  4. 添加以下变量：
变量名初始值说明
bmc_ip192.168.1.100BMC IP 地址
usernameadmin登录用户名
passwordadmin登录密码

配置认证 ​

  1. 打开任意请求。
  2. 切换到 "Authorization" 标签页。
  3. 选择认证类型：

Basic Auth 配置：

  • Type：Basic Auth
  • Username：{username}
  • Password：{password}

常用 API 请求示例 ​

查询系统信息 ​

GET 请求：

  1. 创建新请求，方法选择 "GET"。
  2. URL 输入：https://{bmc_ip}/redfish/v1/Systems。
  3. 配置认证。
  4. 点击 "Send" 发送请求。

响应示例：

json
{
    "@odata.context": "/redfish/v1/$metadata#ComputerSystemCollection.ComputerSystemCollection",
    "@odata.id": "/redfish/v1/Systems",
    "@odata.type": "#ComputerSystemCollection.ComputerSystemCollection",
    "Name": "Computer System Collection",
    "Members@odata.count": 1,
    "Members": [
        {
            "@odata.id": "/redfish/v1/Systems/1"
        }
    ]
}

创建会话 ​

POST 请求：

URL：https://{bmc_ip}/redfish/v1/SessionService/Sessions

请求体：

json
{
    "UserName": "{username}",
    "Password": "{password}"
}

响应示例：

json
{
    "@odata.context": "/redfish/v1/$metadata#Session.Session",
    "@odata.type": "#Session.v1_7_2.Session",
    "@odata.id": "/redfish/v1/SessionService/Sessions/7a64142bdf0be39d8b5c37dc",
    "Name": "User Session",
    "Id": "7a64142bdf0be39d8b5c37dc",
    "ClientOriginIPAddress": "xx.xx.xx.xx",
    "CreatedTime": "2026-03-14T01:59:47+00:00",
    "Roles": [
        "Administrator"
    ],
    "SessionType": "Redfish",
    "OemSessionType": "Redfish",
    "Oem": {
        "Self": {
            "UserAccount": "admin",
            "LoginTime": "2026-03-14T01:59:47+00:00",
            "UserId": 2,
            "UserValidDays": null,
            "AccountInsecurePromptEnabled": false,
            "UserIP": "xx.xx.xx.xx",
            "UserTag": "Redfish",
            "MySession": true,
            "UserRole": [
                "Administrator"
            ]
        }
    }
}

返回的Header中的 X-Auth-Token 值，后续请求可在请求头中使用 X-Auth-Token 携带对应值来达到session认证的效果。

修改配置 ​

PATCH 请求：

URL：https://{bmc_ip}/redfish/v1/Managers/{ManagerId}/NetworkProtocol

请求头：

bash
# If-Match的值为GET该接口返回的Header中的ETag属性的值
If-Match=W/"xxxxxxxx"

请求体：

json
{
    "SNMP": {
        "ProtocolEnabled": true
    }
}

响应示例：

json
{
    "@odata.context": "/redfish/v1/$metadata#ManagerNetworkProtocol.ManagerNetworkProtocol",
    "@odata.id": "/redfish/v1/Managers/1/NetworkProtocol",
    "@odata.type": "#ManagerNetworkProtocol.v1_9_0.ManagerNetworkProtocol",
    "Name": "Manager Network Protocol",
    "Id": "NetworkProtocol",
    ...
    "SNMP": {
        ...
        "ProtocolEnabled": true
    },
    ...
}

执行 Action ​

POST 请求：

URL：https://{bmc_ip}/redfish/v1/Systems/{SystemId}/Actions/ComputerSystem.Reset

请求体：

json
{
    "ResetType": "ForceRestart"
}

响应示例：

json
{
    "error": {
        "code": "Base.1.0.GeneralError",
        "message": "A general error has occurred. See ExtendedInfo for more information.",
        "@Message.ExtendedInfo": [
            {
                "@odata.type": "#Message.v1_0_0.Message",
                "MessageId": "Base.1.0.Success",
                "RelatedProperties": [],
                "Message": "Successfully Completed Request",
                "MessageArgs": [],
                "Severity": "OK",
                "Resolution": "None"
            }
        ]
    }
}

删除资源 ​

DELETE 请求：

URL：https://{bmc_ip}/redfish/v1/SessionService/Sessions/{SessionId}

响应示例：

json
{
    "error": {
        "code": "Base.1.0.GeneralError",
        "message": "A general error has occurred. See ExtendedInfo for more information.",
        "@Message.ExtendedInfo": [
            {
                "@odata.type": "#Message.v1_0_0.Message",
                "MessageId": "Base.1.0.Success",
                "RelatedProperties": [],
                "Message": "Successfully Completed Request",
                "MessageArgs": [],
                "Severity": "OK",
                "Resolution": "None"
            }
        ]
    }
}

使用 curl 发送请求 ​

认识 curl ​

curl 是一个命令行工具，用于发送 HTTP 请求。它支持多种协议、认证方式，功能强大，适合在脚本中使用。

环境要求 ​

  • 操作系统：Linux、macOS、Windows（需要安装）
  • 网络：能够访问 BMC IP 地址

安装 curl ​

Linux 系统 ​

bash
# Ubuntu/Debian
sudo apt-get install curl

# CentOS/RHEL
sudo yum install curl

常用 curl 参数 ​

参数说明
-X指定 HTTP 方法
-H添加请求头
-d发送 POST 数据
-u指定用户名和密码
-b发送 Cookie
-c保存 Cookie
-k跳过 SSL 证书验证
-i显示响应头
-v显示详细通信过程
-o保存响应到文件

常用 API 请求示例 ​

使用 Basic Auth 认证 ​

GET 请求：

bash
curl -X GET \
    -u admin:admin \
    -k \
    https://{bmc_ip}/redfish/v1/Systems

响应示例：

json
{
    "@odata.context": "/redfish/v1/$metadata#ComputerSystemCollection.ComputerSystemCollection",
    "@odata.id": "/redfish/v1/Systems",
    "@odata.type": "#ComputerSystemCollection.ComputerSystemCollection",
    "Name": "Computer System Collection",
    "Members@odata.count": 1,
    "Members": [
        {
            "@odata.id": "/redfish/v1/Systems/1"
        }
    ]
}

使用 Session 认证 ​

创建会话：

bash
curl -X POST \
    -H "Content-Type: application/json" \
    -d '{"UserName":"admin","Password":"admin"}' \
    -k \
    -i \
    https://{bmc_ip}/redfish/v1/SessionService/Sessions

可以在返回的请求头中获取到 X-Auth-Token 的值，后续可通过请求头携带该 token 来实现通过 session 认证

使用会话发送请求：

bash
curl -X GET \
    -H "X-Auth-Token: xxxxxxxx" \
    -k \
    https://{bmc_ip}/redfish/v1/Systems

删除会话：

bash
curl -X DELETE \
    -H "X-Auth-Token: xxxxxxxx" \
    -k \
    https://{bmc_ip}/redfish/v1/SessionService/Sessions/{SessionId}

修改配置 ​

bash
curl -X PATCH \
    -u admin:admin \
    -H "Content-Type: application/json" \
    -H 'If-Match: W/"xxxxxxxx"' \
    -d '{"SNMP":{"ProtocolEnabled":true}}' \
    -k \
    https://{bmc_ip}/redfish/v1/Managers/{ManagerId}/NetworkProtocol

If-Match的值为GET该接口返回的Header中的ETag属性的值

执行 Action ​

bash
curl -X POST \
    -u admin:admin \
    -H "Content-Type: application/json" \
    -d '{"ResetType":"ForceRestart"}' \
    -k \
    https://{bmc_ip}/redfish/v1/Systems/{SystemId}/Actions/ComputerSystem.Reset

结果验证 ​

执行 curl 命令后，应返回 JSON 格式的响应数据。如果返回错误信息，请检查：

  1. 网络连接是否正常：ping {bmc_ip}
  2. 认证信息是否正确。
  3. URL 路径是否正确。
  4. 请求体格式是否正确。
  5. BMC 服务是否正常运行。

常见问题 ​

SSL 证书验证失败 ​

问题现象：返回 "SSL certificate problem" 错误

解决方法：

  1. 添加 -k 参数跳过证书验证
  2. 或者导入 BMC 的 SSL 证书到系统信任库

认证失败 ​

问题现象：返回 401 Unauthorized 错误

解决方法：

  1. 检查用户名和密码是否正确
  2. 检查 Token 是否过期
  3. 确认认证方式配置正确

请求超时 ​

问题现象：请求长时间无响应

解决方法：

  1. 检查网络连接
  2. 增加 curl 的超时时间：--max-time 60
  3. 检查 BMC 服务状态

JSON 解析错误 ​

问题现象：返回的 JSON 格式不正确

解决方法：

  1. 使用 jq 工具格式化输出
  2. 检查响应头中的 Content-Type
  3. 确认 BMC 返回的是标准 JSON 格式

POSTMAN 环境变量不生效 ​

问题现象：{{variable}} 无法正确替换

解决方法：

  1. 确认环境已选择
  2. 检查变量名拼写是否正确
  3. 重新保存环境变量

附录 ​

HTTP 状态码说明 ​

状态码名称描述
200OK请求成功
201Created资源创建成功
204No Content请求成功，无返回内容
400Bad Request请求格式错误
401Unauthorized未授权
403Forbidden禁止访问
404Not Found资源不存在
405Method Not Allowed方法不支持
500Internal Server Error服务器内部错误
503Service Unavailable服务不可用

Redfish 常用端点 ​

端点描述
/redfish/v1/服务根
/redfish/v1/Systems系统集合
/redfish/v1/Chassis机箱集合
/redfish/v1/Managers管理器集合
/redfish/v1/AccountService账户服务
/redfish/v1/SessionService会话服务
/redfish/v1/EventService事件服务

参考资料 ​

上一篇服务器出厂定制化定位指导
下一篇多层级定制配置指导