RESTClient

社区版REST客户端
- 基本用法
  - 使用API密钥认证
  - 使用凭据认证（已弃用）
示例

ThingsBoard REST API客户端帮助您从Java应用程序与ThingsBoard REST API进行交互。通过REST客户端，您可以在ThingsBoard中以编程方式创建资产、设备、客户、用户及其他实体和它们之间的关系。

推荐使用构建自动化工具（如Maven）来安装REST客户端。 REST客户端的版本取决于您使用的平台版本。

社区版REST客户端

要将REST客户端添加到您的Maven/Gradle项目中，请使用以下依赖：

<dependencies>
    <dependency>
        <groupId>org.thingsboard</groupId>
        <artifactId>rest-client</artifactId>
        <version>4.3.0.1</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>

基本用法

使用API密钥认证

*4.3及以上版本*

您可以使用API密钥进行认证，无需登录/登出操作：

// ThingsBoard REST API URL
String url = "http://localhost:8080";

// Your API key
String apiKey = "YOUR_API_KEY_VALUE";

// Creating new rest client with API key authentication
RestClient client = RestClient.withApiKey(url, apiKey);

// Get information of current user and print it
client.getUser().ifPresent(System.out::println);

// Close the client when done
client.close();

使用凭据认证（已弃用）

您也可以创建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();

示例

以下示例演示使用API密钥认证。

如果您更倾向于使用用户名/密码进行认证，只需将以下代码：

String apiKey = "YOUR_API_KEY_VALUE";
RestClient client = RestClient.withApiKey(url, apiKey);

替换为：

String username = "tenant@thingsboard.org";
String password = "tenant";
RestClient client = new RestClient(url);
client.login(username, password);

其余逻辑完全相同。

请记得将YOUR_API_KEY_VALUE替换为您实际的API密钥。

获取租户设备

以下示例代码展示如何通过分页链接获取租户设备。

// ThingsBoard REST API URL
String url = "http://localhost:8080";

// Authentication using an API key
String apiKey = "YOUR_API_KEY_VALUE";

// Creating new rest client and auth with API key
RestClient client = RestClient.withApiKey(url, apiKey);

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.close();

获取租户仪表盘

以下示例代码展示如何通过分页链接获取租户仪表盘。

// ThingsBoard REST API URL
String url = "http://localhost:8080";

// Authentication using an API key
String apiKey = "YOUR_API_KEY_VALUE";

// Creating new rest client and auth with API key
RestClient client = RestClient.withApiKey(url, apiKey);

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.close();

获取客户设备

以下示例代码展示如何通过分页链接获取客户设备。

// ThingsBoard REST API URL
String url = "http://localhost:8080";

// Perform login with Customer User API key
String apiKey = "YOUR_API_KEY_VALUE";
RestClient client = RestClient.withApiKey(url, apiKey);

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.close();

使用实体数据查询API统计实体数量

以下示例代码展示如何使用实体数据查询API统计设备总数和活跃设备总数。

// ThingsBoard REST API URL
String url = "http://localhost:8080";

// Perform login with default Customer User API key
String apiKey = "YOUR_API_KEY_VALUE";
RestClient client = RestClient.withApiKey(url, apiKey);

// Create entity filter to get all devices
EntityTypeFilter typeFilter = new EntityTypeFilter();
typeFilter.setEntityType(EntityType.DEVICE);

// Create entity count query with provided filter
EntityCountQuery totalDevicesQuery = new EntityCountQuery(typeFilter);

// Execute entity count query and get total devices count
Long totalDevicesCount = client.countEntitiesByQuery(totalDevicesQuery);
System.out.println("Total devices by the first query: " + totalDevicesCount);

// Set key filter to existing query to get only active devices
KeyFilter keyFilter = new KeyFilter();
keyFilter.setKey(new EntityKey(EntityKeyType.ATTRIBUTE, "active"));
keyFilter.setValueType(EntityKeyValueType.BOOLEAN);

BooleanFilterPredicate filterPredicate = new BooleanFilterPredicate();
filterPredicate.setOperation(BooleanFilterPredicate.BooleanOperation.EQUAL);
filterPredicate.setValue(new FilterPredicateValue<>(true));
        
keyFilter.setPredicate(filterPredicate);

// Create entity count query with provided filter
EntityCountQuery totalActiveDevicesQuery = 
        new EntityCountQuery(typeFilter, List.of(keyFilter));
        
// Execute active devices query and print total devices count
Long totalActiveDevicesCount = client.countEntitiesByQuery(totalActiveDevicesQuery);
System.out.println("Total devices by the second query: " + totalActiveDevicesCount);
        
// Perform logout of current user and close the client
client.close();

使用实体数据查询API查询实体

以下示例代码展示如何使用实体数据查询API获取所有活跃设备。

// ThingsBoard REST API URL
String url = "http://localhost:8080";

// Perform login with default Customer User API key
String apiKey = "YOUR_API_KEY_VALUE";
RestClient client = RestClient.withApiKey(url, apiKey);

// Create entity filter to get only devices
EntityTypeFilter typeFilter = new EntityTypeFilter();
typeFilter.setEntityType(EntityType.DEVICE);

// Create key filter to query only active devices
KeyFilter keyFilter = new KeyFilter();
keyFilter.setKey(new EntityKey(EntityKeyType.ATTRIBUTE, "active"));
keyFilter.setValueType(EntityKeyValueType.BOOLEAN);

BooleanFilterPredicate filterPredicate = new BooleanFilterPredicate();
filterPredicate.setOperation(BooleanFilterPredicate.BooleanOperation.EQUAL);
filterPredicate.setValue(new FilterPredicateValue<>(true));

keyFilter.setPredicate(filterPredicate);

// Prepare list of queried device fields
List<EntityKey> fields = List.of(
        new EntityKey(EntityKeyType.ENTITY_FIELD, "name"),
        new EntityKey(EntityKeyType.ENTITY_FIELD, "type"),
        new EntityKey(EntityKeyType.ENTITY_FIELD, "createdTime")
);

// Prepare list of queried device attributes
List<EntityKey> attributes = List.of(
        new EntityKey(EntityKeyType.ATTRIBUTE, "active")
);

// Prepare page link
EntityDataSortOrder sortOrder = new EntityDataSortOrder();
sortOrder.setKey(new EntityKey(EntityKeyType.ENTITY_FIELD, "createdTime"));
sortOrder.setDirection(EntityDataSortOrder.Direction.DESC);
EntityDataPageLink entityDataPageLink = new EntityDataPageLink(10, 0, "", sortOrder);

// Create entity query with provided entity filter, key filter, queried fields and page link
EntityDataQuery dataQuery = 
        new EntityDataQuery(typeFilter, entityDataPageLink, fields, attributes, List.of(keyFilter));

PageData<EntityData> entityPageData;
do {
    // Fetch active devices using entities query and print them
    entityPageData = client.findEntityDataByQuery(dataQuery);
    entityPageData.getData().forEach(System.out::println);
    dataQuery = dataQuery.next();
} while (entityPageData.hasNext());

// Perform logout of current user and close client
client.close();

设备管理示例

以下示例代码演示设备管理API的基本用法（添加/获取/删除设备，获取/保存设备属性）。

// ThingsBoard REST API URL
String url = "http://localhost:8080";

// Perform login with default Customer User API key
String apiKey = "YOUR_API_KEY_VALUE";
RestClient client = RestClient.withApiKey(url, apiKey);

// 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.close();