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 系统

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

配置 POSTMAN 环境

创建环境变量

打开 POSTMAN。
点击 "Manage Environments" 图标。
点击 "Add" 创建新环境。
添加以下变量：

变量名	初始值	说明
bmc_ip	192.168.1.100	BMC IP 地址
username	admin	登录用户名
password	admin	登录密码

配置认证

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

Basic Auth 配置：

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

常用 API 请求示例

查询系统信息

GET 请求：

创建新请求，方法选择 "GET"。
URL 输入：https://{bmc_ip}/redfish/v1/Systems。
配置认证。
点击 "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 格式的响应数据。如果返回错误信息，请检查：

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

常见问题

SSL 证书验证失败

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

解决方法：

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

认证失败

问题现象：返回 401 Unauthorized 错误

解决方法：

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

请求超时

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

解决方法：

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

JSON 解析错误

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

解决方法：

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

POSTMAN 环境变量不生效

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

解决方法：

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

附录

HTTP 状态码说明

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

Redfish 常用端点

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

参考资料

Redfish 规范：https://www.dmtf.org/standards/redfish
POSTMAN 文档：https://learning.postman.com/
curl 文档：https://curl.se/docs/
openUBMC 官网：https://www.openubmc.cn/

HTTP 工具使用指导 ​

概述 ​

认识 RESTful API ​

RESTful API 简介 ​

HTTP 方法说明 ​

认证方式 ​

使用 POSTMAN 发送请求 ​

认识 POSTMAN ​

环境要求 ​

安装 POSTMAN ​

Windows 系统 ​

配置 POSTMAN 环境 ​

创建环境变量 ​

配置认证 ​

常用 API 请求示例 ​

查询系统信息 ​

创建会话 ​

修改配置 ​

执行 Action ​

删除资源 ​

使用 curl 发送请求 ​

认识 curl ​

环境要求 ​

安装 curl ​

Linux 系统 ​

常用 curl 参数 ​

常用 API 请求示例 ​

使用 Basic Auth 认证 ​

使用 Session 认证 ​

修改配置 ​

执行 Action ​

结果验证 ​

常见问题 ​

SSL 证书验证失败 ​

认证失败 ​

请求超时 ​

JSON 解析错误 ​

POSTMAN 环境变量不生效 ​

附录 ​

HTTP 状态码说明 ​

Redfish 常用端点 ​

参考资料 ​

HTTP 工具使用指导

概述

认识 RESTful API

RESTful API 简介

HTTP 方法说明

认证方式

使用 POSTMAN 发送请求

认识 POSTMAN

环境要求

安装 POSTMAN

Windows 系统

配置 POSTMAN 环境

创建环境变量

配置认证

常用 API 请求示例

查询系统信息

创建会话

修改配置

执行 Action

删除资源

使用 curl 发送请求

认识 curl

环境要求

安装 curl

Linux 系统

常用 curl 参数

常用 API 请求示例

使用 Basic Auth 认证

使用 Session 认证

修改配置

执行 Action

结果验证

常见问题

SSL 证书验证失败

认证失败

请求超时

JSON 解析错误

POSTMAN 环境变量不生效

附录

HTTP 状态码说明

Redfish 常用端点

参考资料