منو
منو

مرجع API دستگاه HTTP

شروع به کار

اصول اولیه HTTP

HTTP یک پروتکل شبکه همه‌منظوره است که می‌تواند در برنامه‌های IoT مورد استفاده قرار گیرد. اطلاعات بیشتر درباره HTTP را می‌توانید اینجا پیدا کنید. پروتکل HTTP مبتنی بر TCP بوده و از مدل درخواست-پاسخ استفاده می‌کند.

گره‌های سرور ThingsConnect به‌عنوان یک HTTP Server عمل می‌کنند و از پروتکل‌های HTTP و HTTPS پشتیبانی می‌کنند.

تنظیم کتابخانه‌های کلاینت

کتابخانه‌های کلاینت HTTP برای زبان‌های برنامه‌نویسی مختلف در اینترنت موجود است. مثال‌های این مقاله بر اساس ابزار curl ارائه می‌شوند. برای راه‌اندازی این ابزار، می‌توانید از دستورالعمل‌های موجود در راهنمای Hello World ما استفاده کنید.

احراز هویت HTTP و کدهای خطا

در این مقاله از اعتبارسنجی دستگاه مبتنی بر Access Token استفاده می‌شود که در ادامه با عنوان $ACCESS_TOKEN به آن اشاره خواهد شد. برنامه باید در هر درخواست HTTP، $ACCESS_TOKEN را به‌عنوان یک پارامتر مسیر (Path Parameter) درج کند.

کدهای خطای احتمالی و دلایل آن‌ها:

  • 400 Bad Request - آدرس URL نامعتبر، پارامترها یا بدنه درخواست اشتباه.
  • 401 Unauthorized - $ACCESS_TOKEN نامعتبر.
  • 404 Not Found - منبع یافت نشد.

قالب کلید-مقدار

به‌طور پیش‌فرض، ThingsConnect از محتوای کلید-مقدار (Key-Value) در قالب JSON پشتیبانی می‌کند. کلید همیشه یک رشته (String) است، در حالی که مقدار می‌تواند یکی از انواع زیر باشد:رشته (String)، بولین (Boolean)، عدد اعشاری (Double)، عدد صحیح بلند (Long)،JSON برای مثال:

				
					{
 "stringKey":"value1", 
 "booleanKey":true, 
 "doubleKey":42.0, 
 "longKey":73, 
 "jsonKey": {
    "someNumber": 42,
    "someArray": [1,2,3],
    "someNestedObject": {"key": "value"}
 }
}

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

API بارگذاری داده‌های تله‌متری

برای ارسال داده‌های تله‌متری به گره سرور ThingsConnect، درخواست POST را به آدرس زیر ارسال کنید:

				
					http(s)://$THINGSBOARD_HOST_NAME/api/v1/$ACCESS_TOKEN/telemetry

از

  • $THINGSBOARD_HOST_NAME - نام میزبان یا آدرس IP که پلتفرم شما روی آن اجرا می‌شود.
  • $ACCESS_TOKEN - توکن دسترسی دستگاه.

اگر از سرور نسخه نمایشی زنده استفاده می‌کنید، دستور به شکل زیر خواهد بود:

				
					https://demo.thingsboard.io/api/v1/$ACCESS_TOKEN/telemetry

ساده‌ترین قالب‌های داده پشتیبانی‌شده عبارتند از:

				
					{"key1":"value1", "key2":"value2"}

یا

				
					[{"key1":"value1"}, {"key2":"value2"}]

در این حالت، زمان سرور به داده‌های بارگذاری‌شده اختصاص داده خواهد شد!

اگر دستگاه شما قادر به دریافت زمان از سمت کلاینت باشد، می‌توانید از قالب زیر استفاده کنید:

				
					{"ts":1451649600512, "values":{"key1":"value1", "key2":"value2"}}

جایی که 1451649600512 یک زمان‌بندی یونیکس با دقت میلی‌ثانیه است. برای مثال، مقدار 1451649600512 متناظر با تاریخ جمعه، 1 ژانویه 2016 ساعت 12:00:00.512 به وقت گرینویچ است.

در زیر مثال‌هایی از دستورات برای انتشار انواع مختلف داده‌های تله‌متری آورده شده است.

فراموش نکنید که demo.thingsboard.io را با نام میزبان خود و $ACCESS_TOKEN را با توکن دسترسی دستگاه خود جایگزین کنید. در این مثال، نام میزبان به سرور نمایشی زنده اشاره دارد.
مثال 1. انتشار داده به‌عنوان یک شیء بدون زمان‌بندی (از زمان سرور استفاده خواهد شد)

دستور زیر را اجرا کنید:

				
					curl -v -X POST --data "{"temperature":42,"humidity":73}" https://demo.thingsboard.io/api/v1/$ACCESS_TOKEN/telemetry --header "Content-Type:application/json"

داده‌های تله‌متری:

				
					{"temperature":42,"humidity":73}

مثال 2. انتشار داده به‌عنوان یک شیء بدون زمان‌بندی (از زمان سرور استفاده خواهد شد) با استفاده از داده‌های فایل telemetry-data-as-object.json

دستور زیر را اجرا کنید:

				
					curl -v -X POST -d @telemetry-data-as-object.json https://demo.thingsboard.io/api/v1/$ACCESS_TOKEN/telemetry --header "Content-Type:application/json"

محتوای فایل JSON:

				
					{
  "stringKey": "value1",
  "booleanKey": true,
  "doubleKey": 42.0,
  "longKey": 73,
  "jsonKey": {
    "someNumber": 42,
    "someArray": [1,2,3],
    "someNestedObject": {"key": "value"}
  }
}

مثال 3. انتشار داده به‌عنوان یک آرایه از اشیاء بدون زمان‌بندی (از زمان سرور استفاده خواهد شد) با استفاده از داده‌های فایل telemetry-data-as-array.json

دستور زیر را اجرا کنید:

				
					curl -v -X POST -d @telemetry-data-as-array.json https://demo.thingsboard.io/api/v1/$ACCESS_TOKEN/telemetry --header "Content-Type:application/json"

محتوای فایل JSON:

				
					[{"key1":"value1"}, {"key2":true}]

مثال 4. انتشار داده به‌عنوان یک شیء با زمان‌بندی (از زمان‌بندی تله‌متری استفاده خواهد شد) با استفاده از داده‌های فایل telemetry-data-with-ts.json

دستور زیر را اجرا کنید:

				
					curl -v -X POST -d @telemetry-data-with-ts.json https://demo.thingsboard.io/api/v1/$ACCESS_TOKEN/telemetry --header "Content-Type:application/json"

محتوای فایل JSON:

				
					{
  "ts": 1451649600512,
  "values": {
    "stringKey": "value1",
    "booleanKey": true,
    "doubleKey": 42.0,
    "longKey": 73,
    "jsonKey": {
      "someNumber": 42,
      "someArray": [1, 2, 3],
      "someNestedObject": {
        "key": "value"
      }
    }
  }
}

API ویژگی‌ها

API ویژگی‌های ThingsConnect به دستگاه‌ها این امکان را می‌دهد که:

  • ویژگی‌های دستگاه از سمت کلاینت را به سرور بارگذاری کنند.
  • ویژگی‌های دستگاه از سمت کلاینت و ویژگی‌های مشترک دستگاه را از سرور درخواست کنند.
  • به ویژگی‌های مشترک دستگاه از سرور مشترک شوند.
  • به‌روزرسانی ویژگی‌ها را به سرور ارسال کنند.

برای ارسال ویژگی‌های دستگاه از سمت کلاینت به گره سرور ThingsConnect، درخواست POST را به آدرس زیر ارسال کنید:

				
					http(s)://$THINGSBOARD_HOST_NAME/api/v1/$ACCESS_TOKEN/attributes
  • $THINGSBOARD_HOST_NAME - نام میزبان یا آدرس IP که پلتفرم شما روی آن اجرا می‌شود.
  • $ACCESS_TOKEN - توکن دسترسی دستگاه.

اگر از سرور نسخه نمایشی زنده استفاده می‌کنید، دستور به شکل زیر خواهد بود:

				
					https://demo.thingsboard.io/api/v1/$ACCESS_TOKEN/attributes

در زیر مثال‌هایی از دستورات برای انتشار انواع مختلف داده‌های تله‌متری آورده شده است.

فراموش نکنید که demo.thingsboard.io را با نام میزبان خود و $ACCESS_TOKEN را با توکن دسترسی دستگاه خود جایگزین کنید. در این مثال، نام میزبان به سرور نسخه نمایشی زنده اشاره دارد.
مثال 1. انتشار به‌روزرسانی ویژگی‌های دستگاه از سمت کلاینت

				
					curl -v -X POST --data "{"attribute1": "value1", "attribute2":true, "attribute3": 43.0}" https://demo.thingsboard.io/api/v1/$ACCESS_TOKEN/attributes --header "Content-Type:application/json"

مثال 2. انتشار به‌روزرسانی ویژگی‌های دستگاه از سمت کلاینت از فایل new-attributes-values.json

				
					curl -v -X POST -d @new-attributes-values.json https://demo.thingsboard.io/api/v1/$ACCESS_TOKEN/attributes --header "Content-Type:application/json"

محتوای فایل JSON:

				
					{
  "attribute1": "value1",
  "attribute2": true,
  "attribute3": 42.0,
  "attribute4": 73,
  "attribute5": {
    "someNumber": 42,
    "someArray": [1,2,3],
    "someNestedObject": {"key": "value"}
  }
}

برای درخواست ویژگی‌های دستگاه از سمت کلاینت یا ویژگی‌های مشترک دستگاه از گره سرور ThingsConnect، درخواست GET را به آدرس زیر ارسال کنید:

				
					http(s)://$THINGSBOARD_HOST_NAME/api/v1/$ACCESS_TOKEN/attributes?clientKeys=attribute1,attribute2&sharedKeys=shared1,shared2
  • $THINGSCONNECT_HOST_NAME - نام میزبان یا آدرس IP که پلتفرم شما روی آن اجرا می‌شود.
  • $ACCESS_TOKEN - توکن دسترسی دستگاه.

اگر از سرور نسخه نمایشی زنده استفاده می‌کنید، دستور به شکل زیر خواهد بود:

				
					https://demo.thingsboard.io/api/v1/$ACCESS_TOKEN/attributes?clientKeys=attribute1,attribute2&sharedKeys=shared1,shared2

دستور را اجرا کنید. فراموش نکنید که demo.thingsconnect.io را با نام میزبان خود و $ACCESS_TOKEN را با توکن دسترسی دستگاه خود جایگزین کنید. در این مثال، نام میزبان به سرور نسخه نمایشی زنده اشاره دارد.

				
					curl -v -X GET "https://demo.thingsboard.io/api/v1/$ACCESS_TOKEN/attributes?clientKeys=attribute1,attribute2&sharedKeys=shared1,shared2"

نتیجه:

				
					{"client":{"attribute1":"value1","attribute2":true}}

لطفاً توجه داشته باشید

تداخل کلیدهای ویژگی‌های دستگاه از سمت کلاینت و ویژگی‌های مشترک دستگاه یک عمل ناپسند است! با این حال، هنوز ممکن است کلیدهای یکسانی برای ویژگی‌های دستگاه از سمت کلاینت، مشترک یا حتی ویژگی‌های سمت سرور وجود داشته باشد.

مشترک شدن به به‌روزرسانی ویژگی‌ها از سرور

برای مشترک شدن به تغییرات ویژگی‌های دستگاه مشترک، درخواست GET را با پارامتر اختیاری "timeout" به آدرس زیر ارسال کنید:

				
					http(s)://$THINGSBOARD_HOST_NAME/api/v1/$ACCESS_TOKEN/attributes/updates
  • $THINGSCONNECT_HOST_NAME - نام میزبان یا آدرس IP که پلتفرم شما روی آن اجرا می‌شود.
  • $ACCESS_TOKEN - توکن دسترسی دستگاه.

اگر از سرور نسخه نمایشی زنده استفاده می‌کنید، دستور به شکل زیر خواهد بود:

				
					https://demo.thingsboard.io/api/v1/$ACCESS_TOKEN/attributes/updates

به‌محض اینکه یکی از اجزای سمت سرور (مانند REST API یا زنجیره قوانین) ویژگی مشترک را تغییر دهد، کلاینت به‌روزرسانی زیر را دریافت خواهد کرد:

دستور را اجرا کنید. فراموش نکنید که demo.thingsconnect.io را با نام میزبان خود و $ACCESS_TOKEN را با توکن دسترسی دستگاه خود جایگزین کنید. در این مثال، نام میزبان به سرور نسخه نمایشی زنده اشاره دارد.

				
					curl -v -X GET https://demo.thingsboard.io/api/v1/$ACCESS_TOKEN/attributes/updates?timeout=20000

نتیجه:

				
					{"client":{"attribute1":"value1","attribute2":true}}

پشتیبانی از مقدار JSON

ما پشتیبانی از ساختارهای داده‌ای JSON را به API‌های تله‌متری و ویژگی‌ها اضافه کرده‌ایم تا کار با تنظیمات دستگاه ساده‌تر شود. پشتیبانی از JSON به شما این امکان را می‌دهد که داده‌ها را هم از دستگاه بارگذاری کنید و هم اشیای تو در تو را به دستگاه ارسال کنید. می‌توانید یک JSON تنظیمات را به‌عنوان ویژگی مشترک ذخیره کرده و به دستگاه ارسال کنید. همچنین می‌توانید داده‌های JSON را در موتور قوانین پردازش کنید، هشدار ایجاد کنید و غیره.

این بهبود، تعداد عملیات پایگاه داده را هنگام ذخیره داده‌ها در ThingsConnect به حداقل می‌رساند. برای مثال، داده‌های "دمای هوا" و "رطوبت" معمولاً به‌صورت ردیف‌های جداگانه در پایگاه داده‌های SQL یا NoSQL ذخیره می‌شوند تا این داده‌ها به‌طور کارآمد برای نمایش تجمیع شوند. ازآنجایی‌که نیازی به تجمیع داده‌های JSON نیست، می‌توانیم همه محتوا را به‌صورت یک ردیف ذخیره کنیم، به‌جای ذخیره جداگانه برای هر آیتم تنظیمات. در برخی از محیط‌های ما، امکان کاهش تعداد عملیات پایگاه داده بیش از 10 برابر از طریق تجمیع چندین پارامتر در یک JSON وجود دارد.

با تماشای ویدیو، اطلاعات بیشتری درباره پشتیبانی از مقدار JSON کسب کنید.

API فراخوانی روش از راه دور (RPC)

RPC سمت سرور

برای مشترک شدن در دستورات RPC از سرور، درخواست GET را با پارامتر اختیاری "timeout" به آدرس زیر ارسال کنید:

				
					http(s)://$THINGSBOARD_HOST_NAME/api/v1/$ACCESS_TOKEN/rpc

اگر از سرور نسخه نمایشی زنده استفاده می‌کنید، دستور به شکل زیر خواهد بود:

  • $THINGSCONNECT_HOST_NAME - نام میزبان یا آدرس IP که پلتفرم شما روی آن اجرا می‌شود.
  • $ACCESS_TOKEN - توکن دسترسی دستگاه.
				
					https://demo.thingsboard.io/api/v1/$ACCESS_TOKEN/rpc

پس از اشتراک، کلاینت ممکن است یک درخواست RPC دریافت کند یا در صورت نبود درخواست برای دستگاه مشخص، پیامی با محتوای پایان زمان دریافت کند. نمونه‌ای از بدنه درخواست RPC در زیر نشان داده شده است:

				
					{
  "id": "1",
  "method": "setGpio",
  "params": {
    "pin": "23",
    "value": 1
  }
}
  • id - شناسه درخواست، یک عدد صحیح برای شناسایی درخواست.
  • method - نام متد RPC، یک رشته.
  • params - پارامترهای متد RPC، یک شیء JSON سفارشی.

می‌توانید با استفاده از درخواست POST به آدرس زیر به این درخواست‌ها پاسخ دهید:

				
					http(s)://$THINGSBOARD_HOST_NAME/api/v1/$ACCESS_TOKEN/rpc/{$id}

اگر از سرور نسخه نمایشی زنده استفاده می‌کنید، دستور به شکل زیر خواهد بود:

				
					http(s)://$THINGSBOARD_HOST_NAME/api/v1/$ACCESS_TOKEN/rpc/{$id}
  • $id - شناسه درخواست، یک عدد صحیح برای شناسایی درخواست.

بیایید یک مثال را بررسی کنیم:

  • از ابزارک RPC debug terminal در نمونه ThingsConnect خود استفاده کنید.
  • برای مشترک شدن در دستورات RPC از سرور، از دستور زیر استفاده کنید. برای انجام این کار، در پنجره اول ترمینال، درخواست GET را با پرچم observe ارسال کنید. فراموش نکنید که $THINGSCONNECT_HOST_NAME را با نام میزبان خود و $ACCESS_TOKEN را با توکن دسترسی دستگاه خود جایگزین کنید:
				
					curl -v -X GET http://$THINGSBOARD_HOST_NAME/api/v1/$ACCESS_TOKEN/rpc?timeout=20000
  • یک درخواست RPC با عنوان "connect" را با استفاده از ابزارک RPC debug terminal به دستگاه ارسال کنید.
  • فایل rpc-response.json را در رایانه خود ذخیره کنید.
  • در پنجره دوم ترمینال، ارسال یک پاسخ از دستگاه به سرور را شبیه‌سازی کنید:
				
					curl -v -X POST -d @rpc-response.json http://$THINGSBOARD_HOST_NAME/api/v1/$ACCESS_TOKEN/rpc/1 --header "Content-Type:application/json"

شما باید یک پاسخ از دستگاه دریافت کنید:

				
					{"result":"ok"}

RPC سمت کلاینت

برای ارسال دستورات RPC به سرور، درخواست POST را به آدرس زیر ارسال کنید:

				
					http(s)://$THINGSBOARD_HOST_NAME/api/v1/$ACCESS_TOKEN/rpc
  • $THINGSCONNECT_HOST_NAME - نام میزبان یا آدرس IP که پلتفرم شما روی آن اجرا می‌شود.
  • $ACCESS_TOKEN - توکن دسترسی دستگاه.

اگر از سرور نسخه نمایشی زنده استفاده می‌کنید، دستور به شکل زیر خواهد بود:

				
					https://demo.thingsboard.io/api/v1/$ACCESS_TOKEN/rpc

هر دو بدنه درخواست و پاسخ باید مستندات JSON معتبر باشند. محتوای این مستندات به گره قانون (Rule Node) مربوط می‌شود که درخواست شما را پردازش خواهد کرد.

بیایید یک مثال را بررسی کنیم:

  • دو گره به زنجیره قوانین (Rule Chain) اضافه کنید: "script" و "rpc call reply"؛
  • در گره script تابع زیر را وارد کنید:
				
					return {msg: {time:String(new Date())}, metadata: metadata, msgType: msgType};
  • فایل rpc-client-request.json را در رایانه خود ذخیره کنید؛
  • حالا، درخواست را با استفاده از دستور زیر به سرور ارسال کنید. فراموش نکنید که $THINGSCONNECT_HOST_NAME را با نام میزبان خود و $ACCESS_TOKEN را با توکن دسترسی دستگاه خود جایگزین کنید:
				
					curl -X POST -d @rpc-client-request.json http://$THINGSBOARD_HOST_NAME/api/v1/$ACCESS_TOKEN/rpc --header "Content-Type:application/json"

شما باید یک پاسخ از سرور دریافت کنید:

				
					{"time":"2016 11 21 12:54:44.287"}

ادعای دستگاه‌ها

لطفاً برای دریافت اطلاعات بیشتر در مورد ویژگی ادعای دستگاه‌ها، به مقاله مربوطه مراجعه کنید.

برای شروع فرآیند ادعای دستگاه، درخواست POST را به آدرس زیر ارسال کنید:

				
					http(s)://$THINGSBOARD_HOST_NAME/api/v1/$ACCESS_TOKEN/claim
  • $THINGSCONNECT_HOST_NAME - نام میزبان یا آدرس IP که پلتفرم شما روی آن اجرا می‌شود.
  • $ACCESS_TOKEN - توکن دسترسی دستگاه.

اگر از سرور نسخه نمایشی زنده استفاده می‌کنید، دستور به شکل زیر خواهد بود:

				
					https://demo.thingsboard.io/api/v1/$ACCESS_TOKEN/claim

فرمت داده پشتیبانی شده به شرح زیر است:

				
					{"secretKey":"value", "durationMs":60000}

لطفاً توجه داشته باشید

فیلدهای فوق اختیاری هستند. در صورتی که secretKey مشخص نشود، از رشته خالی به عنوان مقدار پیش‌فرض استفاده می‌شود. در صورتی که durationMs مشخص نشود، پارامتر سیستم device.claim.duration (در فایل /etc/thingsboard/conf/thingsboard.yml) استفاده خواهد شد.

تخصیص دستگاه

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

برای شروع فرآیند تخصیص دستگاه، درخواست POST را به آدرس زیر ارسال کنید:

				
					http(s)://$THINGSBOARD_HOST_NAME/api/v1/provision

$THINGSCONNECT_HOST_NAME - نام میزبان یا آدرس IP که پلتفرم شما روی آن اجرا می‌شود.

اگر از سرور نسخه نمایشی زنده استفاده می‌کنید، دستور به شکل زیر خواهد بود:

				
					https://demo.thingsboard.io/api/v1/provision

فرمت داده پشتیبانی شده به شرح زیر است:

				
					{
  "deviceName": "DEVICE_NAME",
  "provisionDeviceKey": "u7piawkboq8v32dmcmpp",
  "provisionDeviceSecret": "jpmwdn8ptlswmf4m29bw"
}

API بروزرسانی نرم‌افزار

زمانی که ThingsConnect بروزرسانی نرم‌افزار را از طریق HTTP آغاز می‌کند، ویژگی‌های مشترک fw_title، fw_version، fw_checksum و fw_checksum_algorithm را تنظیم می‌کند. برای دریافت به‌روزرسانی ویژگی‌های مشترک، دستگاه باید درخواست GET ارسال کند.

				
					http(s)://$THINGSBOARD_HOST_NAME/api/v1/$ACCESS_TOKEN/firmware?title=$TITLE&version=$VERSION
  • $THINGSCONNECT_HOST_NAME - نام میزبان یا آدرس IP که پلتفرم شما روی آن در حال اجرا است؛
  • $ACCESS_TOKEN - توکن دسترسی دستگاه؛
  • $TITLE - عنوان نرم‌افزار؛
  • $VERSION - نسخه نرم‌افزار هدف.

اگر از سرور دمو زنده استفاده می‌کنید، دستور به شکل زیر خواهد بود:

				
					https://demo.thingsboard.io/api/v1/$ACCESS_TOKEN/firmware?title=$TITLE&version=$VERSION

سفارشی‌سازی پروتکل

انتقال HTTP می‌تواند برای استفاده خاص به‌طور کامل با تغییر ماژول مربوطه سفارشی‌سازی شود.

مراحل بعدی

  • راهنمای شروع کار - این راهنماها نمای کلی از ویژگی‌های اصلی ThingsConnect ارائه می‌دهند و برای تکمیل آن‌ها ۱۵-۳۰ دقیقه زمان نیاز است.
  • تصویربرداری داده‌ها - این راهنماها دستورالعمل‌هایی برای پیکربندی داشبوردهای پیچیده ThingsConnect ارائه می‌دهند.
  • پردازش داده‌ها و اقدامات - یاد بگیرید که چگونه از موتور قانون ThingsConnect استفاده کنید.
  • تحلیل داده‌های IoT - یاد بگیرید که چگونه از موتور قانون برای انجام وظایف تحلیلی پایه استفاده کنید.
  • نمونه‌های سخت‌افزاری - یاد بگیرید که چگونه پلتفرم‌های سخت‌افزاری مختلف را به ThingsConnect متصل کنید.
  • ویژگی‌های پیشرفته - با ویژگی‌های پیشرفته ThingsConnect آشنا شوید.
  • مشارکت و توسعه - با نحوه مشارکت و توسعه در ThingsConnect آشنا شوید.

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

aparat-icon-svg Telegram

عناوین هر بخش

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

aparat-icon-svg Telegram
بستن