مستندات ویرالینک

RPC – Remote Procedure Call

پلتفرم ویرالینک به شما امکان ارسال دستورات RPC یا همان فراخوانی تابع از راه دور (Remote Procedure Call) از سمت سرور به دستگاه و بلعکس را می‌دهد. این ویژگی به شما امکان می‌دهد تا دستورات خود را به دستگاه ارسال و نتیجه آن را دریافت نمایید. همچنین به طور بلعکس می‌توانید تا با ارسال درخواست از سمت دستگاه به پلتفرم محاسبه‌های خود را در سمت سرور و یا یک منطق خاص در سمت سرور پردازش و نتیجه آن را به دستگاه ارسال نمایید.

انوع فراخوانی های RPC (RPC Call Types) #

RPC ها به دونوع بر اساس مولد تقسیم می‌شوند. RPC‌هایی توسط برنامه‌های سرور تولید شوند RPC‌های سمت سرور (server-side RPC) و RPC‌هایی که توسط دستگاه‌ها تولید شوند RPC‌های سمت کاربر (client-side RPC) می‌نامیم.
RPC‌های سمت سرور به دو نوع یک طرفه و دو طرفه دسته‌بندی می‌شود:

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

API برای RPC‌های سمت کاربر (Client-Side RPC API) #

این API‌ها همان API‌های سمت دستگاه هستند که از سمت دستگاه به سمت سرور درخوست ارسال و پاسخ مناسب دریافت می‌کنند. پلتفرم ویرالینک نسبت به پروتکل های متفاوت API‌های متناسب فراهم کرده تا بتوانید از برنامه‌های دستگاه (Device firmware) به سرور درخواست‌های RPC ارسال کرده و نتیجه آن‌ها دریافت کنید.

  • MQTT RPC API
  • HTTP RPC API
  • CoAP RPC API

API برای RPC‌های سمت سرور (Server-Side RPC API) #

به کمک این API می‌توانید از سمت برنامه‌های سرور به دستگاه‌ها دستورات RPC ارسال کرده و نتیجه آن‌ها را دریافت کنید. برای این کار کافیست به آدرس زیر یک درخواست POST ارسال کنید.

https://console.viralink.io/api/plugins/rpc/{callType}/{deviceId}

پارامتر های درخواست بالا عبارت است از:

  • callType – برای درخواست‌های یک طرفه oneway و برای درخواست های دو طرفه twoway
  • deviceId – شناسه دستگاه مد نظر که می‌خواهید دستور RPC به آن ارسال شود.

محتوای بدنه درخواست (body) باید به فرمت json بوده و دارای پارامتر های زیر باشد:

  • method – نام تابع, JSON String
  • params – پارامتر های تابع, JSON Strin

برای مثال:

{
  "method": "setGpio",
  "params": {
    "pin": "23",
    "value": 1
  }
}

curl -v -X POST -d @set-gpio-request.json https://console.viralink.io/api/plugins/rpc/twoway/$DEVICE_ID \
--header "Content-Type:application/json" \
--header "X-Authorization: $JWT_TOKEN"

توجه: برای اجرای صحیح دستور بالا متن $JWT_TOKEN را با توکن معتبر جایگزین کنید. برای اطلاعات بیشتر درباره دریافت توکن می‌توانید به راهنمای REST API مراجعه نمایید. کاربران مجاز برای ارسال درخواست:

  • مدیر پلتفرم (TENANT_ADMIN)
  • مشتریانی (CUSTOMER_USER) که صاحب دستگاه هستند.

موتور قواعد RPC #

در موتور قواعد دو گره RPC Reply و RPC Request برای کار کردن با RPC‌ها وجود دارد.