منو
منو

مروری بر موتور قوانین

موتور قوانین Thingsconnect یک سیستم قابل تنظیم و پیکربندی بالا برای پردازش رویدادهای پیچیده است. با استفاده از موتور قوانین، شما قادر خواهید بود پیام‌های ورودی ارسال شده توسط دستگاه‌های اینترنت اشیاء (IoT) و دارایی‌های مرتبط را فیلتر، توسعه داده و تبدیل کنید. همچنین قادر خواهید بود عملیات‌های مختلفی مانند ارسال اعلان‌ها یا ارتباط با سیستم‌های خارجی را فعال کنید.

مفاهیم کلیدی

پیام موتور قوانین

پیام موتور قوانین، یک ساختار داده قابل سریالیزه و غیرقابل تغییر است که نماینده‌ی پیام‌های مختلف در سیستم می‌باشد. به عنوان مثال:

  • تلمتری دریافتی، بروزرسانی ویژگی یا فراخوانی RPC از دستگاه
  • رویداد چرخه عمر موجودیت: ایجاد شده، بروزرسانی شده، حذف شده، اختصاص داده شده، عدم اختصاص داده شده، ویژگی‌ها بروزرسانی شده؛
  • رویداد وضعیت دستگاه: متصل، قطع، فعال، غیرفعال و غیره؛
  • سایر رویدادهای سیستم.

پیام موتور قوانین شامل اطلاعات زیر است:

  • شناسه پیام: بر اساس زمان و یکتا در سراسر دنیا؛
  • منبع پیام: شناسه دستگاه، دارایی یا موجودیت دیگر؛
  • نوع پیام: "ارسال تلمتری" یا "رویداد عدم فعالیت" و غیره؛
  • بار پیام: بدنه JSON با بار واقعی پیام؛
  • متادیتا: لیستی از جفت‌های کلید-مقدار با اطلاعات اضافی در مورد پیام.

گره قوانین

گره قوانین یکی از اجزای اصلی موتور قوانین است که هر بار یک پیام ورودی را پردازش کرده و یک یا چند پیام خروجی تولید می‌کند. این گره به‌عنوان واحد اصلی منطقی موتور قوانین عمل می‌کند و قادر است پیام‌های ورودی را فیلتر، غنی‌سازی، تبدیل کند، اقدامات مختلفی را اجرا کند یا با سیستم‌های خارجی ارتباط برقرار کند.

اتصال گره قوانین

گره‌های قوانین می‌توانند به گره‌های دیگر متصل شوند. هر اتصال دارای یک نوع مشخص است که به‌عنوان برچسبی برای بیان معنای منطقی آن استفاده می‌شود. وقتی گره قوانین پیام خروجی تولید می‌کند، همیشه نوع اتصال را مشخص می‌کند تا پیام به گره بعدی هدایت شود.

ارتباطات رایج بین گره‌ها شامل "موفقیت" و "شکست" هستند. گره‌های مربوط به عملیات منطقی ممکن است از "صحیح" یا "غلط" استفاده کنند. برخی از گره‌های خاص نیز ممکن است از انواع دیگری از ارتباطات مانند "ارسال تله‌متری"، "به‌روزرسانی ویژگی‌ها"، "ایجاد موجودیت" و غیره بهره ببرند.

برخی گره‌های قوانین از نام‌های اتصال سفارشی نیز پشتیبانی می‌کنند. کافی است نام دلخواه خود را وارد کرده و روی لینک «ایجاد نام جدید» کلیک کنید.

image

تمامی نام‌های اتصال به حروف بزرگ و کوچک حساس هستند.

زنجیره قوانین

زنجیره قوانین یک گروه منطقی از گره‌های قوانین و روابط آن‌ها است. به عنوان مثال، زنجیره قوانین زیر قادر خواهد بود:

  • ذخیره تمامی پیام‌های تله‌متری در پایگاه داده؛

  • صدور "هشدار دمای بالا" در صورتی که مقدار فیلد دما در پیام بیشتر از ۵۰ درجه باشد؛

  • صدور "هشدار دمای پایین" در صورتی که مقدار فیلد دما در پیام کمتر از ۴۰- درجه باشد؛

  • ثبت خطا در اجرای اسکریپت‌های بررسی دما در کنسول در صورت بروز خطاهای منطقی یا نحوی در اسکریپت.

image

مدیر Tenant می‌تواند یک زنجیره قوانین ریشه (Root Rule Chain) و در صورت نیاز چندین زنجیره قوانین دیگر را تعریف کند. زنجیره قوانین ریشه تمامی پیام‌های ورودی را مدیریت کرده و می‌تواند آن‌ها را برای پردازش بیشتر به زنجیره‌های قوانین دیگر ارسال کند. سایر زنجیره‌های قوانین نیز می‌توانند پیام‌ها را به زنجیره‌های قوانین مختلف ارسال کنند.

به عنوان مثال، زنجیره قوانین زیر قادر خواهد بود:

  • ذخیره تمامی پیام‌های تله‌متری در پایگاه داده؛

  • صدور "هشدار دمای بالا" در صورتی که مقدار فیلد دما در پیام بیشتر از ۵۰ درجه باشد؛

  • صدور "هشدار دمای پایین" در صورتی که مقدار فیلد دما در پیام کمتر از ۴۰- درجه باشد؛

  • ثبت خطا در اجرای اسکریپت‌های بررسی دما در کنسول در صورت بروز خطاهای منطقی یا نحوی در اسکریپت.

image

نتیجه پردازش پیام

سه نتیجه ممکن برای پردازش پیام وجود دارد: موفقیت، شکست و اتمام زمان. تلاش برای پردازش پیام زمانی به عنوان «موفقیت» علامت‌گذاری می‌شود که آخرین گره قانون در زنجیره پردازش پیام را با موفقیت پردازش کند. تلاش برای پردازش پیام زمانی به عنوان «شکست» علامت‌گذاری می‌شود که یکی از گره‌های قانون، «شکست» در پردازش پیام تولید کند و هیچ گره قانونی برای مدیریت آن شکست وجود نداشته باشد. تلاش برای پردازش پیام زمانی به عنوان «اتمام زمان» علامت‌گذاری می‌شود که کل زمان پردازش از حد قابل تنظیم فراتر رود.

به نمودار زیر نگاه کنید و بیایید سناریوهای ممکن را مرور کنیم:

image

اگر اسکریپت "تبدیل" (Transformation) شکست بخورد، پیام به عنوان "شکست" علامت‌گذاری نمی‌شود، زیرا یک گره "ذخیره در پایگاه داده" (Save to DB) وجود دارد که با رابطه "شکست" (Failure) متصل است. اگر اسکریپت "تبدیل" موفق باشد، پیام از طریق یک فراخوان REST API به سیستم خارجی منتقل می‌شود. اگر سیستم خارجی بارگذاری بالایی داشته باشد، فراخوان REST API ممکن است برای مدتی متوقف شود. فرض کنیم زمان نهایی برای پردازش بسته پیام ۲۰ ثانیه باشد. زمان اجرای اسکریپت "تبدیل" را نادیده می‌گیریم چون کمتر از ۱ میلی‌ثانیه است. بنابراین، اگر سیستم خارجی در عرض ۲۰ ثانیه پاسخ دهد، پیام با موفقیت پردازش خواهد شد. به طور مشابه، اگر فراخوان "ذخیره در پایگاه داده" موفق باشد، پیام با موفقیت پردازش می‌شود. با این حال، اگر سیستم خارجی در عرض ۲۰ ثانیه پاسخ ندهد، تلاش برای پردازش پیام به عنوان "اتمام زمان" علامت‌گذاری می‌شود. همچنین، اگر فراخوان "ذخیره در پایگاه داده" شکست بخورد، پیام به عنوان شکست خورده علامت‌گذاری خواهد شد.

صف موتور قوانین

به اسناد جدید مراجعه کنید.

استراتژی ارسال صف

به اسناد جدید مراجعه کنید.

استراتژی پردازش صف

به اسناد جدید مراجعه کنید.

صف‌های پیش‌فرض

به اسناد جدید مراجعه کنید.

انواع پیام از پیش تعریف‌شده

فهرست انواع پیام‌های از پیش تعریف‌شده در جدول زیر ارائه شده است:

نوع پیام

نام نمایشی

توضیحات

متادیتای پیام

بار محتوایی پیام

POST_ATTRIBUTES_REQUEST

Post attributes

Request from device to publish client side attributes (see attributes api for reference)

deviceName - originator device name,
deviceType - originator device type

key/value json:
{
"currentState": "IDLE"
}

POST_TELEMETRY_REQUEST

Post telemetry

Request from device to publish telemetry (see telemetry upload api for reference)

deviceName - originator device name,
deviceType - originator device type,
ts - timestamp (milliseconds)

key/value json:
{
"temperature": 22.7
}

TO_SERVER_RPC_REQUEST

RPC Request from Device

RPC request from device (see client side rpc for reference)

deviceName - originator device name,
deviceType - originator device type,
requestId - RPC request Id provided by client

json containing method and params:
{
"method": "getTime",
"params": { "param1": "val1" }
}

RPC_CALL_FROM_SERVER_TO_DEVICE

RPC Request to Device

RPC request from server to device (see server side rpc api for reference)

requestUUID - internal request id used by sustem to identify reply target,
expirationTime - time when request will be expired,
oneway - specifies request type: true - without response, false - with response

json containing method and params:
{
"method": "getGpioStatus",
"params": { "param1": "val1" }
}

ACTIVITY_EVENT

Activity Event

Event indicating that device becomes active

deviceName - originator device name,
deviceType - originator device type

json containing device activity information:
{
"active": true,
"lastConnectTime": 1526979083267,
"lastActivityTime": 1526979083270,
"lastDisconnectTime": 1526978493963,
"lastInactivityAlarmTime": 1526978512339,
"inactivityTimeout": 10000
}

INACTIVITY_EVENT

Inactivity Event

Event indicating that device becomes inactive

deviceName - originator device name,
deviceType - originator device type

json containing device activity information, see Activity Event payload

CONNECT_EVENT

Connect Event

Event produced when device is connected

deviceName - originator device name,
deviceType - originator device type

json containing device activity information, see Activity Event payload

DISCONNECT_EVENT

Disconnect Event

Event produced when device is disconnected

deviceName - originator device name,
deviceType - originator device type

json containing device activity information, see Activity Event payload

ENTITY_CREATED

Entity Created

Event produced when new entity was created in system

userName - name of the user who created the entity,
userId - the user Id

json containing created entity details:
{
"id": {
"entityType": "DEVICE",
"id": "efc4b9e0-5d0f-11e8-8559-37a7f8cdca74"
},
"createdTime": 1526918366334,
...
"name": "my-device",
"type": "temp-sensor"
}

ENTITY_UPDATED

Entity Updated

Event produced when existing entity was updated

userName - name of the user who updated the entity,
userId - the user Id

json containing updated entity details, see Entity Created payload

ENTITY_DELETED

Entity Deleted

Event produced when existing entity was deleted

userName - name of the user who deleted the entity,
userId - the user Id

json containing deleted entity details, see Entity Created payload

ENTITY_ASSIGNED

Entity Assigned

Event produced when existing entity was assigned to customer

userName - name of the user who performed assignment operation,
userId - the user Id,
assignedCustomerName - assigned customer name,
assignedCustomerId - Id of assigned customer

json containing assigned entity details, see Entity Created payload

ENTITY_UNASSIGNED

Entity Unassigned

Event produced when existing entity was unassigned from customer

userName - name of the user who performed unassignment operation,
userId - the user Id,
unassignedCustomerName - unassigned customer name,
unassignedCustomerId - Id of unassigned customer

json containing unassigned entity details, see Entity Created payload

ADDED_TO_ENTITY_GROUP

Added to Group

Event produced when entity was added to Entity Group. This Message Type is specific to ThingsConnect PE.

userName - name of the user who performed assignment operation,
userId - the user Id,
addedToEntityGroupName - entity group name,
addedToEntityGroupId - Id of entity group

empty json payload

REMOVED_FROM_ENTITY_GROUP

Removed from Group

Event produced when entity was removed from Entity Group. This Message Type is specific to ThingsConnect PE.

userName - name of the user who performed unassignment operation,
userId - the user Id,
removedFromEntityGroupName - entity group name,
removedFromEntityGroupId - Id of entity group

empty json payload

ATTRIBUTES_UPDATED

Attributes Updated

Event produced when entity attributes update was performed

userName - name of the user who performed attributes update,
userId - the user Id,
scope - updated attributes scope (can be either SERVER_SCOPE or SHARED_SCOPE)

key/value json with updated attributes:
{
"softwareVersion": "1.2.3"
}

ATTRIBUTES_DELETED

Attributes Deleted

Event produced when some of entity attributes were deleted

userName - name of the user who deleted attributes,
userId - the user Id,
scope - deleted attributes scope (can be either SERVER_SCOPE or SHARED_SCOPE)

json with attributes field containing list of deleted attributes keys:
{
"attributes": ["modelNumber", "serial"]
}

ALARM

Alarm event

Event produced when an alarm was created, updated or deleted

All fields from original Message Metadata
isNewAlarm - true if a new alram was just created
isExistingAlarm - true if an alarm is existing already
isClearedAlarm - true if an alarm was cleared

json containing created alarm details:
{
"tenantId": {
...
},
"type": "High Temperature Alarm",
"originator": {
...
},
"severity": "CRITICAL",
"status": "CLEARED_UNACK",
"startTs": 1526985698000,
"endTs": 1526985698000,
"ackTs": 0,
"clearTs": 1526985712000,
"details": {
"temperature": 70,
"ts": 1526985696000
},
"propagate": true,
"id": "33cd8999-5dac-11e8-bbab-ad47060c9431",
"createdTime": 1526985698000,
"name": "High Temperature Alarm"
}

ALARM_ASSIGNED

Alarm Assigned

Event produced when an alarm was assigned to some user

All fields from original Message Metadata
entityName - name of alarm
entityType - ALARM
userEmail - user email
userFirstName - user first name
userId - user id
userLastName - user last name
userName - user name

json containing alarm details, see Alarm event

COMMENT_CREATED

Comment Created

Event produced when an alarm comment was created

All fields from original Message Metadata
userId - user id
userName - user name
userFirstName - first name of user
userLastName - last name of user
userEmail - email of user
comment - json object containing comment details and text of comment

json containing alarm details, see Alarm event

COMMENT_UPDATED

Comment Updated

Event produced when an alarm comment was updated

All fields from original Message Metadata
userId - user id
userName - user name
userFirstName - first name of user
userLastName - last name of user
userEmail - email of user
comment - json object containing comment details and text of comment

json containing alarm details, see Alarm event

REST_API_REQUEST

REST API Request to Rule Engine

Event produced when user executes REST API call

requestUUID - the unique request id,
expirationTime - the expiration time of the request

json with request payload

به اسناد جدید مراجعه کنید.

انواع گره‌های قانون

تمام گره‌های قانون موجود بر اساس ماهیت آن‌ها گروه‌بندی شده‌اند:

  • گره‌های فیلتر برای فیلتر کردن و مسیریابی پیام استفاده می‌شوند؛

  • گره‌های غنی‌سازی برای به‌روزرسانی اطلاعات فراداده پیام‌های ورودی به کار می‌روند؛

  • گره‌های تغییر برای تغییر فیلدهای پیام‌های ورودی مانند مبدأ، نوع، بار پیام (Payload) و فراداده استفاده می‌شوند؛

  • گره‌های عملیاتی بر اساس پیام ورودی، اقدامات مختلفی را اجرا می‌کنند؛

  • گره‌های خارجی برای تعامل با سیستم‌های خارجی استفاده می‌شوند.

پیکربندی

هر گره قانون ممکن است دارای پارامترهای پیکربندی خاصی باشد که به پیاده‌سازی گره قانون بستگی دارد. به‌عنوان مثال، گره قانون «فیلتر - اسکریپت» از طریق تابع سفارشی جاوااسکریپت که داده‌های ورودی را پردازش می‌کند، قابل پیکربندی است. پیکربندی گره «خارجی - ارسال ایمیل» به شما این امکان را می‌دهد که پارامترهای اتصال به سرور ایمیل را مشخص کنید.

پنجره پیکربندی گره قانون را می‌توان با دوبار کلیک بر روی گره در ویرایشگر زنجیره قوانین باز کرد:

image

تست توابع اسکریپت

برخی از گره‌های قانون دارای ویژگی‌های خاص رابط کاربری هستند که به کاربران امکان می‌دهد توابع TBEL/JS را تست کنند. با کلیک بر روی گزینه "تست تابع فیلتر"، ویرایشگر جاوااسکریپت (JS Editor) نمایش داده می‌شود که به شما اجازه می‌دهد پارامترهای ورودی را جایگزین کرده و خروجی تابع را بررسی کنید.

image

می‌توانید موارد زیر را تعریف کنید:

  • نوع پیام در قسمت بالای سمت چپ.

  • بار پیام (Payload) در بخش پیام در سمت چپ.

  • فراداده در بخش فراداده در سمت راست.

  • اسکریپت TBEL/JS واقعی در بخش فیلتر.

با فشردن دکمه تست، خروجی در بخش سمت راست خروجی نمایش داده می‌شود.

آمار موتور قوانین

تیم ThingsConnect یک داشبورد "پیش‌فرض" برای آمار موتور قوانین تهیه کرده است. این داشبورد به‌طور خودکار برای هر مستاجر بارگذاری می‌شود. شما می‌توانید با مراجعه به بخش "استفاده از API" -> "مشاهده آمار" به آن دسترسی پیدا کنید (به تصویر زیر مراجعه کنید).

image

جمع‌آوری آمار به‌طور پیش‌فرض فعال است و از طریق خصوصیات پیکربندی کنترل می‌شود.

ممکن است در داشبورد زیر بینش‌هایی درباره خطاهای پردازش و علل آن‌ها مشاهده کنید:

image

اشکال‌زدایی

ThingsConnect این قابلیت را فراهم می‌کند که پیام‌های ورودی و خروجی را برای هر گره قانون مرور کنید. برای فعال‌سازی حالت اشکال‌زدایی، باید مطمئن شوید که کادر "حالت اشکال‌زدایی" در پنجره اصلی پیکربندی انتخاب شده است (به تصویر اول در بخش پیکربندی مراجعه کنید).

پس از فعال‌سازی اشکال‌زدایی، کاربر می‌تواند اطلاعات پیام‌های ورودی و خروجی و همچنین انواع روابط مربوطه را مشاهده کند. برای نمونه‌ای از نمایش پیام‌های اشکال‌زدایی، به تصویر زیر مراجعه کنید:

image

وارد کردن/صادر کردن

شما می‌توانید زنجیره قوانین خود را به فرمت JSON صادر کرده و آن را به نمونه‌های دیگر یا همان نمونه ThingsConnect وارد کنید.

برای صادر کردن زنجیره قوانین، باید به صفحه زنجیره‌های قوانین بروید و بر روی دکمه صادر کردن که در کارت مربوط به زنجیره قوانین خاص قرار دارد، کلیک کنید.

image

به‌طور مشابه، برای وارد کردن زنجیره قوانین، باید به صفحه زنجیره‌های قوانین بروید و بر روی دکمه بزرگ “+” در قسمت پایین سمت راست صفحه کلیک کرده و سپس بر روی دکمه وارد کردن کلیک کنید.

معماری

برای آشنایی بیشتر با ساختار داخلی موتور قوانین، به صفحه معماری مراجعه کنید.

تماس‌های REST API سفارشی با موتور قوانین

ویژگی نسخه حرفه‌ای ThingsConnect

فقط نسخه حرفه‌ای (Professional Edition) از ویژگی تماس‌های REST API سفارشی موتور قوانین پشتیبانی می‌کند. از ThingsConnect Cloud استفاده کنید یا نسخه خود را نصب کنید.

ThingsConnect API این امکان را فراهم می‌کند که تماس‌های REST API سفارشی به موتور قوانین ارسال کنید، بار درخواست را پردازش کرده و نتیجه پردازش را در بدنه پاسخ برگردانید. این ویژگی برای موارد مختلف کاربردی است. به‌عنوان مثال:

  • افزودن تماس‌های API سفارشی به REST API موجود پلتفرم؛

  • غنی‌سازی تماس‌های REST API با ویژگی‌های دستگاه/دارایی/مشتری و ارسال به سیستم‌های خارجی برای پردازش پیچیده؛

  • ارائه API سفارشی برای ویجت‌های سفارشی خود.

برای اجرای تماس‌های REST API، می‌توانید از API های REST مربوط به کنترل‌کننده موتور قوانین استفاده کنید:

image

توجه: شناسه موجودیتی که در تماس مشخص کرده‌اید، به‌عنوان مبدأ پیام موتور قوانین در نظر گرفته خواهد شد. اگر پارامترهای شناسه موجودیت را مشخص نکنید، موجودیت کاربر شما به‌عنوان مبدأ پیام در نظر گرفته خواهد شد.

عیب یابی

اگر از صف کافکا برای پردازش پیام‌ها استفاده می‌کنید، ThingsConnect این قابلیت را فراهم می‌کند که نرخ ارسال پیام‌ها به کافکا را در مقایسه با نرخ مصرف و پردازش آنها نظارت کنید (در این صورت ممکن است تأخیر پردازش پیام‌ها افزایش یابد). برای فعال‌سازی این قابلیت، باید مطمئن شوید که آمار مصرف‌کننده کافکا (Kafka consumer-stats) فعال است (به بخش "queue.kafka.consumer-stats" در خصوصیات پیکربندی مراجعه کنید).

پس از فعال‌سازی آمار مصرف‌کننده کافکا، لاگ‌هایی درباره تأخیر در جابجایی آفست برای گروه‌های مصرف‌کننده مشاهده خواهید کرد (لاگ‌های مربوط به گروه مصرف‌کننده برای tb-core، tb-rule-engine و تمام سرویس‌های حمل و نقل وجود دارد).

در اینجا یک نمونه از پیام لاگ آورده شده است:

				
					2021-03-19 15:01:59,794 [kafka-consumer-stats-11-thread-1] INFO  o.t.s.q.k.TbKafkaConsumerStatsService - [re-Main-consumer] Topic partitions with lag: [[topic=[tb_rule_engine.main.0], partition=[0], committedOffset=[5413], endOffset=[5418], lag=[5]]].

با فشردن دکمه تست، خروجی در بخش سمت راست خروجی نمایش داده می‌شود.

				
					TIME [STATS_PRINTING_THREAD_NAME] INFO  o.t.s.q.k.TbKafkaConsumerStatsService - [CONSUMER_GROUP_NAME] Topic partitions with lag: [[topic=[KAFKA_TOPIC], partition=[KAFKA_TOPIC_PARTITION], committedOffset=[LAST_PROCESSED_MESSAGE_OFFSET], endOffset=[LAST_QUEUED_MESSAGE_OFFSET], lag=[LAG]],[topic=[ANOTHER_TOPIC], partition=[], committedOffset=[], endOffset=[], lag=[]],...].

تعاریف:

  • CONSUMER_GROUP_NAME: نام گروه مصرف‌کننده که پیام‌ها را پردازش می‌کند (می‌تواند یکی از صف‌های موتور قوانین، صف مرکزی و غیره باشد).

  • KAFKA_TOPIC: نام دقیق موضوع (Topic) در کافکا.

  • KAFKA_TOPIC_PARTITION: شماره پارتیشن موضوع.

  • LAST_PROCESSED_MESSAGE_OFFSET: شماره ترتیب آخرین پیامی که توسط مصرف‌کننده پردازش شده است (آخرین پیام تأیید شده در موتور قوانین و غیره).

  • LAST_QUEUED_MESSAGE_OFFSET: شماره ترتیب آخرین پیامی که با موفقیت به موضوع کافکا ارسال شده است.

  • LAG: تعداد پیام‌های پردازش‌نشده.

توجه: لاگ‌های مربوط به تأخیر مصرف‌کننده فقط در صورتی چاپ می‌شوند که تأخیری برای این گروه مصرف‌کننده وجود داشته باشد.

شرایط استفاده از خدمات

aparat-icon-svg Telegram

عناوین هر بخش

شرایط استفاده از خدمات

aparat-icon-svg Telegram
بستن