一、swagger文档
ThingsBoard REST API 交互式文档可通过 Swagger UI 获取。例如,您可以使用
安装 ThingsBoard 服务器后,您可以使用以下 URL 打开swagger文档:
http://YOUR_HOST:PORT/swagger-ui.html
如果您之前已在主登录页面上授权,文档页面将自动使用您的凭据。您可以使用文档页面右上角的“授权”按钮进行手动授权。您还可以使用此按钮授权为其他用户。见下文:
使用knife4j来进行访问
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>3.0.3</version>
</dependency>
1、JWT 令牌
ThingsBoard 使用JWT令牌在 API 客户端(浏览器、脚本等)和平台之间安全地表示声明。当您登录平台时,您的用户名和密码将交换为一对令牌。
主令牌是短期令牌,您应该使用它来执行 API 调用。刷新令牌用于在过期后获取新的主令牌。主令牌和刷新令牌的过期时间可通过 JWT_TOKEN_EXPIRATION_TIME 和 JWT_REFRESH_TOKEN_EXPIRATION_TIME 参数在系统设置中。默认过期时间值分别为 2.5 小时和 1 周。
请参阅下面的示例命令以获取用户“ tenant@thingsboard.org ”、密码“tenant”和服务器“THINGSBOARD_URL”的令牌:
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{"username":"tenant@thingsboard.org", "password":"tenant"}' 'http://THINGSBOARD_URL/api/auth/login'
现在,您应该将“X-Authorization”标头设置为“Bearer $YOUR_JWT_TOKEN”。确保您使用主 JWT 令牌而不是刷新令牌。
二、Rest客户端
ThingsBoard REST API 客户端可帮助您从 Java 应用程序与 ThingsBoard REST API 进行交互。借助 Rest Client,您可以以编程方式在 ThingsBoard 中创建资产、设备、客户、用户和其他实体及其关系。
安装 Rest Client 的推荐方法是使用构建自动化工具,例如 Maven。 REST 客户端的版本取决于您正在使用的平台的版本。
1、社区版 REST 客户端
为了将 REST 客户端添加到您的 Maven项目,您应该使用以下依赖项:
<dependencies>
<dependency>
<groupId>org.thingsboard</groupId>
<artifactId>rest-client</artifactId>
<version>3.6.4</version>
</dependency>
</dependencies>
注意:REST 客户端构建在 Spring RestTemplate 之上,因此依赖于 Spring Web(在撰写本文时为 5.1.5.RELEASE)。
为了下载 REST 客户端依赖项,您应该将以下存储库添加到您的项目中。或者,您可以从源构建 REST 客户端。
<repositories>
<repository>
<id>thingsboard</id>
<url>https://repo.thingsboard.io/artifactory/libs-release-public</url>
</repository>
</repositories>
2、基本用法
下一个示例代码展示了如何实例化 ThingsBoard 客户端、执行登录并获取当前登录用户的用户详细信息。
// ThingsBoard REST API URL
String url = "http://localhost:8080";
// Default Tenant Administrator credentials
String username = "tenant@thingsboard.org";
String password = "tenant";
// Creating new rest client and auth with credentials
RestClient client = new RestClient(url);
client.login(username, password);
// Get information of current logged in user and print it
client.getUser().ifPresent(System.out::println);
// Perform logout of current user and close the client
client.logout();
client.close();
获取租户设备
以下示例代码展示了如何通过页面链接获取租户设备。
// ThingsBoard REST API URL
String url = "http://localhost:8080";
// Default Tenant Administrator credentials
String username = "tenant@thingsboard.org";
String password = "tenant";
// Creating new rest client and auth with credentials
RestClient client = new RestClient(url);
client.login(username, password);
PageData<Device> tenantDevices;
PageLink pageLink = new PageLink(10);
do {
// Fetch all tenant devices using current page link and print each of them
tenantDevices = client.getTenantDevices("", pageLink);
tenantDevices.getData().forEach(System.out::println);
pageLink = pageLink.nextPageLink();
} while (tenantDevices.hasNext());
// Perform logout of current user and close the client
client.logout();
client.close();
获取租户仪表板
以下示例代码展示了如何通过页面链接获取租户仪表板。
// ThingsBoard REST API URL
String url = "http://localhost:8080";
// Default Tenant Administrator credentials
String username = "tenant@thingsboard.org";
String password = "tenant";
// Creating new rest client and auth with credentials
RestClient client = new RestClient(url);
client.login(username, password);
PageData<DashboardInfo> pageData;
PageLink pageLink = new PageLink(10);
do {
// Fetch all tenant dashboards using current page link and print each of them
pageData = client.getTenantDashboards(pageLink);
pageData.getData().forEach(System.out::println);
pageLink = pageLink.nextPageLink();
} while (pageData.hasNext());
// Perform logout of current user and close the client
client.logout();
client.close();
获取客户设备
// ThingsBoard REST API URL
String url = "http://localhost:8080";
// Perform login with default Customer User credentials
String username = "customer@thingsboard.org";
String password = "customer";
RestClient client = new RestClient(url);
client.login(username, password);
PageData<Device> pageData;
PageLink pageLink = new PageLink(10);
do {
// Get current user
User user = client.getUser().orElseThrow(() -> new IllegalStateException("No logged in user has been found"));
// Fetch customer devices using current page link
pageData = client.getCustomerDevices(user.getCustomerId(), "", pageLink);
pageData.getData().forEach(System.out::println);
pageLink = pageLink.nextPageLink();
} while (pageData.hasNext());
// Perform logout of current user and close the client
client.logout();
client.close();
管理设备示例
以下示例代码演示了设备管理 API 的基本概念(添加/获取/删除设备、获取/保存设备属性)。
// ThingsBoard REST API URL
String url = "http://localhost:8080";
// Perform login with default Customer User credentials
String username = "tenantg@thingsboard.org";
String password = "tenant";
RestClient client = new RestClient(url);
client.login(username, password);
// Construct device object
String newDeviceName = "Test Device";
Device newDevice = new Device();
newDevice.setName(newDeviceName);
// Create Json Object Node and set it as additional info
ObjectMapper mapper = new ObjectMapper();
ObjectNode additionalInfoNode = mapper.createObjectNode().put("description", "My brand new device");
newDevice.setAdditionalInfo(additionalInfoNode);
// Save device
Device savedDevice = client.saveDevice(newDevice);
System.out.println("Saved device: " + savedDevice);
// Find device by device id or throw an exception otherwise
Optional<DeviceInfo> optionalDevice = client.getDeviceInfoById(savedDevice.getId());
DeviceInfo foundDevice = optionalDevice
.orElseThrow(() -> new IllegalArgumentException("Device with id " + newDevice.getId().getId() + " hasn't been found"));
// Save device shared attributes
ObjectNode requestNode = mapper.createObjectNode().put("temperature", 22.4).put("humidity", 57.4);
boolean isSuccessful = client.saveEntityAttributesV2(foundDevice.getId(), "SHARED_SCOPE", requestNode);
System.out.println("Attributes have been successfully saved: " + isSuccessful);
// Get device shared attributes
var attributes = client.getAttributesByScope(foundDevice.getId(), "SHARED_SCOPE", List.of("temperature", "humidity"));
System.out.println("Found attributes: ");
attributes.forEach(System.out::println);
// Delete the device
client.deleteDevice(savedDevice.getId());
// Perform logout of current user and close client
client.logout();
client.close();