کلاینت API Dart
نمای کلی
بسته Dart ThingsConnect API Client یک کتابخانه Dart است که اشیاء مدلی و خدماتی را برای ارتباط با پلتفرم ThingsConnect از طریق APIهای RESTful و پروتکل WebSocket ارائه میدهد. با استفاده از این کلاینت Dart، میتوانید به صورت برنامهنویسی به APIهای ThingsConnect دسترسی داشته باشید تا موجودیتها را مدیریت کنید، دادههای تلهمتری را جستجو کنید و بهروزرسانیهای بلادرنگ را از طریق API وبسوکت دریافت کنید. کلاینت Dart ThingsConnect API Client همچنین بخشی از برنامه موبایل ThingsConnect است.
نسخه Dart ThingsConnect API Client به نسخه پلتفرمی که استفاده میکنید، وابسته است.
نصب Dart ThingsConnect API Client (نسخه Community)
برای استفاده از بسته Dart ThingsConnect API Client در پروژه Dart/Flutter خود، این دستور را اجرا کنید:
برای Dart:
dart pub add thingsboard_client
برای Flutter:
flutter pub add thingsboard_client
این دستور یک خط مانند زیر را به فایل pubspec.yaml بسته شما اضافه میکند (و به طور خودکار دستور dart pub get را اجرا میکند):
dependencies:
thingsboard_client: ^1.4.0
بهصورت جایگزین، ممکن است ویرایشگر شما از دستور dart pub get یا flutter pub get پشتیبانی کند. برای اطلاعات بیشتر، مستندات ویرایشگر خود را بررسی کنید.
اکنون میتوانید در کد Dart خود از موارد زیر استفاده کنید:
import 'package:thingsboard_client/thingsboard_client.dart';
استفاده اولیه
نمونه کد زیر نشان میدهد چگونه میتوان کلاینت ThingsConnect را مقداردهی اولیه کرد، وارد سیستم شد و جزئیات کاربر وارد شده فعلی را دریافت کرد:
import 'package:thingsboard_client/thingsboard_client.dart';
// ThingsBoard REST API URL
const thingsBoardApiEndpoint = 'http://localhost:8080';
void main() async {
try {
// Create instance of ThingsBoard API Client
var tbClient = ThingsboardClient(thingsBoardApiEndpoint);
// Perform login with default Tenant Administrator credentials
await tbClient.login(LoginRequest('tenant@thingsboard.org', 'tenant'));
print('isAuthenticated=${tbClient.isAuthenticated()}');
print('authUser: ${tbClient.getAuthUser()}');
// Get user details of current logged in user
var currentUserDetails = await tbClient.getUserService().getUser();
print('currentUserDetails: $currentUserDetails');
// Finally perform logout to clear credentials
await tbClient.logout();
} catch (e, s) {
print('Error: $e');
print('Stack: $s');
}
}
مثالها
دریافت دستگاههای Tenant
نمونه کد زیر نشان میدهد که چگونه میتوان دستگاههای Tenant را با استفاده از پیوند صفحه (Page Link) دریافت کرد:
import 'package:thingsboard_client/thingsboard_client.dart';
// ThingsBoard REST API URL
const thingsBoardApiEndpoint = 'http://localhost:8080';
void main() async {
try {
// Create instance of ThingsBoard API Client
var tbClient = ThingsboardClient(thingsBoardApiEndpoint);
// Perform login with default Tenant Administrator credentials
await tbClient.login(LoginRequest('tenant@thingsboard.org', 'tenant'));
var pageLink = PageLink(10);
PageData devices;
do {
// Fetch tenant devices using current page link
devices = await tbClient.getDeviceService().getTenantDeviceInfos(pageLink);
print('devices: $devices');
pageLink = pageLink.nextPageLink();
} while (devices.hasNext);
// Finally perform logout to clear credentials
await tbClient.logout();
} catch (e, s) {
print('Error: $e');
print('Stack: $s');
}
}
دریافت داشبوردهای Tenant
نمونه کد زیر نشان میدهد که چگونه میتوان داشبوردهای Tenant را با استفاده از پیوند صفحه (Page Link) دریافت کرد:
import 'package:thingsboard_client/thingsboard_client.dart';
// ThingsBoard REST API URL
const thingsBoardApiEndpoint = 'http://localhost:8080';
void main() async {
try {
// Create instance of ThingsBoard API Client
var tbClient = ThingsboardClient(thingsBoardApiEndpoint);
// Perform login with default Tenant Administrator credentials
await tbClient.login(LoginRequest('tenant@thingsboard.org', 'tenant'));
var pageLink = PageLink(10);
PageData dashboards;
do {
// Fetch tenant dashboards using current page link
dashboards = await tbClient.getDashboardService().getTenantDashboards(pageLink);
print('dashboards: $dashboards');
pageLink = pageLink.nextPageLink();
} while (devices.hasNext);
// Finally perform logout to clear credentials
await tbClient.logout();
} catch (e, s) {
print('Error: $e');
print('Stack: $s');
}
}
دریافت دستگاههای مشتری
نمونه کد زیر نشان میدهد که چگونه میتوان دستگاههای مشتری را با استفاده از پیوند صفحه (Page Link) دریافت کرد:
import 'package:thingsboard_client/thingsboard_client.dart';
// ThingsBoard REST API URL
const thingsBoardApiEndpoint = 'http://localhost:8080';
void main() async {
try {
// Create instance of ThingsBoard API Client
var tbClient = ThingsboardClient(thingsBoardApiEndpoint);
// Perform login with default Customer User credentials
await tbClient.login(LoginRequest('customer@thingsboard.org', 'customer'));
var pageLink = PageLink(10);
PageData devices;
do {
// Fetch customer devices using current page link
devices = await tbClient
.getDeviceService()
.getCustomerDeviceInfos(tbClient.getAuthUser()!.customerId, pageLink);
print('devices: $devices');
pageLink = pageLink.nextPageLink();
} while (devices.hasNext);
// Finally perform logout to clear credentials
await tbClient.logout();
} catch (e, s) {
print('Error: $e');
print('Stack: $s');
}
}
شمارش موجودیتها با استفاده از Entity Data Query API
نمونه کد زیر نشان میدهد که چگونه میتوان از Entity Data Query API برای شمارش دستگاهها استفاده کرد: تعداد کل دستگاهها، تعداد دستگاههای فعال و تعداد دستگاههای غیرفعال.
import 'package:thingsboard_client/thingsboard_client.dart';
// ThingsBoard REST API URL
const thingsBoardApiEndpoint = 'http://localhost:8080';
void main() async {
try {
// Create instance of ThingsBoard API Client
var tbClient = ThingsboardClient(thingsBoardApiEndpoint);
// Perform login with default Tenant Administrator credentials
await tbClient.login(LoginRequest('tenant@thingsboard.org', 'tenant'));
// Create entity filter to get all devices
var entityFilter = EntityTypeFilter(entityType: EntityType.DEVICE);
// Create entity count query with provided filter
var devicesQuery = EntityCountQuery(entityFilter: entityFilter);
// Execute entity count query and get total devices count
var totalDevicesCount =
await tbClient.getEntityQueryService().countEntitiesByQuery(devicesQuery);
print('Total devices: $totalDevicesCount');
// Set key filter to existing query to get only active devices
var activeDeviceKeyFilter = KeyFilter(
key: EntityKey(type: EntityKeyType.ATTRIBUTE, key: 'active'),
valueType: EntityKeyValueType.BOOLEAN,
predicate: BooleanFilterPredicate(
operation: BooleanOperation.EQUAL,
value: FilterPredicateValue(true)));
devicesQuery.keyFilters = [activeDeviceKeyFilter];
// Execute entity count query and get total active devices count
var activeDevicesCount =
await tbClient.getEntityQueryService().countEntitiesByQuery(devicesQuery);
print('Active devices: $activeDevicesCount');
// Set key filter to existing query to get only inactive devices
var inactiveDeviceKeyFilter = KeyFilter(
key: EntityKey(type: EntityKeyType.ATTRIBUTE, key: 'active'),
valueType: EntityKeyValueType.BOOLEAN,
predicate: BooleanFilterPredicate(
operation: BooleanOperation.EQUAL,
value: FilterPredicateValue(false)));
devicesQuery.keyFilters = [inactiveDeviceKeyFilter];
// Execute entity count query and get total inactive devices count
var inactiveDevicesCount =
await tbClient.getEntityQueryService().countEntitiesByQuery(devicesQuery);
print('Inactive devices: $inactiveDevicesCount');
// Finally perform logout to clear credentials
await tbClient.logout();
} catch (e, s) {
print('Error: $e');
print('Stack: $s');
}
}
پرسوجو از موجودیتها با استفاده از Entity Data Query API
نمونه کد زیر نشان میدهد که چگونه میتوان از Entity Data Query API برای دریافت تمام دستگاههای فعال استفاده کرد:
import 'package:thingsboard_client/thingsboard_client.dart';
// ThingsBoard REST API URL
const thingsBoardApiEndpoint = 'http://localhost:8080';
void main() async {
try {
// Create instance of ThingsBoard API Client
var tbClient = ThingsboardClient(thingsBoardApiEndpoint);
// Perform login with default Tenant Administrator credentials
await tbClient.login(LoginRequest('tenant@thingsboard.org', 'tenant'));
// Create entity filter to get only devices
var entityFilter = EntityTypeFilter(entityType: EntityType.DEVICE);
// Create key filter to query only active devices
var activeDeviceKeyFilter = KeyFilter(
key: EntityKey(type: EntityKeyType.ATTRIBUTE, key: 'active'),
valueType: EntityKeyValueType.BOOLEAN,
predicate: BooleanFilterPredicate(
operation: BooleanOperation.EQUAL,
value: FilterPredicateValue(true)));
// Prepare list of queried device fields
var deviceFields = [
EntityKey(type: EntityKeyType.ENTITY_FIELD, key: 'name'),
EntityKey(type: EntityKeyType.ENTITY_FIELD, key: 'type'),
EntityKey(type: EntityKeyType.ENTITY_FIELD, key: 'createdTime')
];
// Prepare list of queried device attributes
var deviceAttributes = [
EntityKey(type: EntityKeyType.ATTRIBUTE, key: 'active')
];
// Create entity query with provided entity filter, key filter, queried fields and page link
var devicesQuery = EntityDataQuery(
entityFilter: entityFilter,
keyFilters: [inactiveDeviceKeyFilter],
entityFields: deviceFields,
latestValues: deviceAttributes,
pageLink: EntityDataPageLink(
pageSize: 10,
sortOrder: EntityDataSortOrder(
key: EntityKey(
type: EntityKeyType.ENTITY_FIELD, key: 'createdTime'),
direction: EntityDataSortOrderDirection.DESC)));
PageData devices;
do {
// Fetch active devices using entities query with current page link
devices = await tbClient
.getEntityQueryService()
.findEntityDataByQuery(devicesQuery);
print('Active devices entities data:');
devices.data.forEach((device) {
print(
'id: ${device.entityId.id}, createdTime: ${device.createdTime}, name: ${device.field('name')!}, type: ${device.field('type')!}, active: ${device.attribute('active')}');
});
devicesQuery = devicesQuery.next();
} while (devices.hasNext);
// Finally perform logout to clear credentials
await tbClient.logout();
} catch (e, s) {
print('Error: $e');
print('Stack: $s');
}
}
مثال مدیریت دستگاه
نمونه کد زیر مفاهیم پایهای API مدیریت دستگاه را نشان میدهد (اضافه کردن/دریافت/حذف دستگاه، دریافت/ذخیره ویژگیهای دستگاه):
import 'package:thingsboard_client/thingsboard_client.dart';
// ThingsBoard REST API URL
const thingsBoardApiEndpoint = 'http://localhost:8080';
void main() async {
try {
// Create instance of ThingsBoard API Client
var tbClient = ThingsboardClient(thingsBoardApiEndpoint);
// Perform login with default Tenant Administrator credentials
await tbClient.login(LoginRequest('tenant@thingsboard.org', 'tenant'));
var deviceName = 'My test device';
// Construct device object
var device = Device(deviceName, 'default');
device.additionalInfo = {'description': 'My test device!'};
// Add device
var savedDevice = await tbClient.getDeviceService().saveDevice(device);
print('savedDevice: $savedDevice');
// Find device by device id
var foundDevice =
await tbClient.getDeviceService().getDeviceInfo(savedDevice.id!.id!);
print('foundDevice: $foundDevice');
// Save device shared attributes
var res = await tbClient.getAttributeService().saveEntityAttributesV2(
foundDevice!.id!,
AttributeScope.SHARED_SCOPE.toShortString(),
{'targetTemperature': 22.4, 'targetHumidity': 57.8});
print('Save attributes result: $res');
// Get device shared attributes
var attributes = await tbClient.getAttributeService().getAttributesByScope(
foundDevice.id!,
AttributeScope.SHARED_SCOPE.toShortString(),
['targetTemperature', 'targetHumidity']);
print('Found device attributes: $attributes');
// Delete the device
await tbClient.getDeviceService().deleteDevice(savedDevice.id!.id!);
// Finally perform logout to clear credentials
await tbClient.logout();
} catch (e, s) {
print('Error: $e');
print('Stack: $s');
}
}
مثال WebSocket API
نمونه کد زیر مفاهیم پایهای WebSocket API را نشان میدهد. در این کد، ما قصد داریم یک دستگاه جدید ایجاد کنیم، اشتراکی برای دریافت دادههای دستگاه و بهروزرسانیهای تلهمتری از طریق Entity Data Query API بر روی WebSocket API ایجاد کنیم. در نهایت، تلهمتری نمونه ارسال کرده و بهروزرسانیهای داده را با گوش دادن به جریان دادههای اشتراک دریافت میکنیم.
import 'dart:math';
import 'package:thingsboard_client/thingsboard_client.dart';
// ThingsBoard REST API URL
const thingsBoardApiEndpoint = 'http://localhost:8080';
void main() async {
try {
// Create instance of ThingsBoard API Client
var tbClient = ThingsboardClient(thingsBoardApiEndpoint);
// Perform login with default Tenant Administrator credentials
await tbClient.login(LoginRequest('tenant@thingsboard.org', 'tenant'));
var deviceName = 'My test device';
// Construct device object
var device = Device(deviceName, 'default');
device.additionalInfo = {'description': 'My test device!'};
// Add device
var savedDevice = await tbClient.getDeviceService().saveDevice(device);
print('savedDevice: $savedDevice');
// Create entity filter to get device by its name
var entityFilter = EntityNameFilter(
entityType: EntityType.DEVICE, entityNameFilter: deviceName);
// Prepare list of queried device fields
var deviceFields = [
EntityKey(type: EntityKeyType.ENTITY_FIELD, key: 'name'),
EntityKey(type: EntityKeyType.ENTITY_FIELD, key: 'type'),
EntityKey(type: EntityKeyType.ENTITY_FIELD, key: 'createdTime')
];
// Prepare list of queried device time series
var deviceTelemetry = [
EntityKey(type: EntityKeyType.TIME_SERIES, key: 'temperature'),
EntityKey(type: EntityKeyType.TIME_SERIES, key: 'humidity')
];
// Create entity query with provided entity filter, queried fields and page link
var devicesQuery = EntityDataQuery(
entityFilter: entityFilter,
entityFields: deviceFields,
latestValues: deviceTelemetry,
pageLink: EntityDataPageLink(
pageSize: 10,
sortOrder: EntityDataSortOrder(
key: EntityKey(
type: EntityKeyType.ENTITY_FIELD, key: 'createdTime'),
direction: EntityDataSortOrderDirection.DESC)));
// Create time series subscription command to get data for 'temperature' and 'humidity' keys for last hour with realtime updates
var currentTime = DateTime.now().millisecondsSinceEpoch;
var timeWindow = Duration(hours: 1).inMilliseconds;
var tsCmd = TimeSeriesCmd(
keys: ['temperature', 'humidity'],
startTs: currentTime - timeWindow,
timeWindow: timeWindow);
// Create subscription command with entities query and time series subscription
var cmd = EntityDataCmd(query: devicesQuery, tsCmd: tsCmd);
// Create subscription with provided subscription command
var telemetryService = tbClient.getTelemetryService();
var subscription = TelemetrySubscriber(telemetryService, [cmd]);
// Create listener to get data updates from WebSocket
subscription.entityDataStream.listen((entityDataUpdate) {
print('Received entity data update: $entityDataUpdate');
});
// Perform subscribe (send subscription command via WebSocket API and listen for responses)
subscription.subscribe();
// Post sample telemetry
var rng = Random();
for (var i = 0; i < 5; i++) {
await Future.delayed(Duration(seconds: 1));
var temperature = 10 + 20 * rng.nextDouble();
var humidity = 30 + 40 * rng.nextDouble();
var telemetryRequest = {'temperature': temperature, 'humidity': humidity};
print('Save telemetry request: $telemetryRequest');
var res = await tbClient
.getAttributeService()
.saveEntityTelemetry(savedDevice.id!, 'TELEMETRY', telemetryRequest);
print('Save telemetry result: $res');
}
// Wait few seconds to show data updates are received by subscription listener
await Future.delayed(Duration(seconds: 2));
// Finally unsubscribe to release subscription
subscription.unsubscribe();
// Delete the device
await tbClient.getDeviceService().deleteDevice(savedDevice.id!.id!);
// Finally perform logout to clear credentials
await tbClient.logout();
} catch (e, s) {
print('Error: $e');
print('Stack: $s');
}
}
مثالهای بیشتر
شما میتوانید مثالهای بیشتری را برای یادگیری نحوه استفاده از Dart ThingsConnect API Client در اینجا پیدا کنید.