使用 Mender API：管理 API 的基础知识

使用 Mender API：管理 API 的基础知识

Mender API 是一组开放的 REST 接口，旨在简化与 CI/CD 管道和车队管理工作流的集成。通过这些接口，用户可以轻松实现自动化操作和设备管理。本文将为您介绍 Mender API 的基础知识，特别是管理 API 的使用方法，并通过实际示例帮助您快速上手。

Mender API 概述

Mender API 分为以下两类：

• 设备 API：由安装了 Mender 客户端的 IoT 设备使用，用于轮询和接收更新。
• 管理 API：主要供用户界面使用，同时也可用于在 OTA 软件部署工作流中实现自动化。

本文将重点介绍管理 API 的使用方法。

版本控制

在阅读管理 API 文档时，您可能会注意到部分内容前面标注了版本号。这些版本号表示 API 的不同版本。根据 Mender 文档的描述：

• 高版本的 API 包含新旧端点的混合。
• 对于未在新版本中更改的端点，默认使用旧版本端点。
• 总是优先使用最高版本的 API。如果某个端点在当前版本中不存在，则会回退到前一个版本。

身份验证

在使用 API 之前，您需要进行身份验证，以获取服务器认可的 JWT（JSON Web Token）令牌。只有在 API 调用中包含有效的 JWT，服务器才会授予访问权限。

获取 JWT 的两种方法：

1. 直接生成个人访问令牌（PAT）：
   使用 Hosted Mender 的用户名和密码调用 /api/management/v1/useradm/auth/login 端点，服务器将返回一个令牌。

2. 使用 PAT：
   推荐使用 PAT，因为它允许设置到期时间，提供更高的灵活性。

在本教程中，我们将通过用户名和密码生成 PAT，并在后续示例中使用该令牌。

实践示例 – 使用 Bash 命令行工具

以下工具将用于实践示例：

• curl：发送 HTTP 请求。
• jq：解析 JSON 文件。

示例 1：获取 PAT（个人访问令牌）

通过以下步骤生成 PAT：

USER=
PASS=
BASE_URL="https://hosted.mender.io/api/management/v1/useradm"
API_ENDPOINT="/auth/login"

JWT_TEMP=$(curl -X POST -H "Content-Type: application/json" -u "$USER:$PASS" "$BASE_URL$API_ENDPOINT")
echo $JWT_TEMP

生成的 PAT 将作为 JWT 令牌，用于后续的 API 调用。

示例 2：按身份列出所有设备

设备在 Mender 中有两种标识符：

• 设备标识：如 MAC 地址。
• 设备 ID：系统分配的唯一标识符。

以下命令用于获取所有设备的设备标识：

BASE_URL="https://hosted.mender.io/api/management/v1/inventory"
API_ENDPOINT="/devices"

curl -X GET "$BASE_URL$API_ENDPOINT" 
-H "Accept: application/json" 
-H "Authorization: Bearer $JWT" > devices.jsonjq '.[].identity_data' devices.json

示例 3：获取设备的库存数据

要获取特定设备的库存数据，需要先获取设备 ID。以下命令用于根据设备标识（如 MAC 地址）获取设备 ID：

SERIAL_NUMBER="dc:a6:32:7d:9f:f2"

DEVICE_ID=$(jq -r '.[] | select(.identity_data.mac=="'"$SERIAL_NUMBER"'") | .id' devices.json)echo $DEVICE_ID

然后，通过设备 ID 获取设备的库存数据：

BASE_URL="https://hosted.mender.io/api/management/v1/inventory"
API_ENDPOINT="/devices/$DEVICE_ID"

curl -X GET "$BASE_URL$API_ENDPOINT" 
-H "Accept: application/json" 
-H "Authorization: Bearer $JWT" > inventory-$DEVICE_ID.json

示例 4：创建新用户并分配角色

以下命令用于创建新用户：

BASE_URL="https://hosted.mender.io/api/management/v1/useradm"
API_ENDPOINT="/users"

curl -X POST "$BASE_URL$API_ENDPOINT" 
-H "Content-Type: application/json" 
-H "Authorization: Bearer $JWT" 
-d '{"email": "newuser@example.com", "password": "password123"}'

创建用户后，可以为其分配角色。例如，将角色 RBAC_ROLE_OBSERVER 分配给新用户：

BASE_URL="https://hosted.mender.io/api/management/v1/useradm"
API_ENDPOINT="/roles"

curl -X GET "$BASE_URL$API_ENDPOINT" 
-H "Accept: application/json" 
-H "Authorization: Bearer $JWT" | jq '.[].name'# 分配角色
ROLE_ID="RBAC_ROLE_OBSERVER"
USER_ID="newuser@example.com"curl -X PUT "$BASE_URL/users/$USER_ID/roles" 
-H "Content-Type: application/json" 
-H "Authorization: Bearer $JWT" 
-d '{"roles": ["'"$ROLE_ID"'"]}'

总结

通过以上示例，您已经了解了如何使用 Mender API 进行身份验证、设备管理和用户角色分配。这些示例仅仅是 Mender API 功能的冰山一角。您可以基于这些基础知识，进一步探索其他 API 端点，满足更多业务需求。

有关更详细的 API 文档和功能说明，请参考 Mender 官方文档。

原文链接: https://mender.io/blog/using-the-mender-api-the-basics-of-the-management-api