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

HTTP API

شروع به کار #

آشنایی با HTTP #

HTTP پرکاربرد ترین پروتکل تحت وب است که میتوان در برنامه های دستگاه های IoT استفاده کرد. برای اطلاعات بیشتر در رابطه با پروتکل HTTP میتوانید به سایت w3.org مراجعه فرمایید. پروتکل HTTP مبتنی بر مدل درخواست-پاسخ (request-response) است.
پلتفرم ویرالینک به عنوان یک سرور HTTP عمل میکند و به دلایل امنیتی تنها پروتکل امن HTTPS را پشتیبانی میکند.

نصب کتابخانه های پیش نیاز #

برای اتصال به سرور های HTTP پلتفرم ویرالینک شما نیاز به کتابخانه های سمت کاربر (HTTP Client Libraries) دارید. بسته به نوع محیطی که در آن کار میکنید کتابخانه های متعددی وجود دارد که میتوانید به سادگی آن ها را متناسب با نیاز خود پیدا کنید. در مثال های این مستندات از کتابخانه curl استفاده میشود. برای
نصب این ابزار ها میتوانید به بخش شروع به کار با ویرالینک مراجعه فرمایید.

اتصال به HTTP و خطاهای احتمالی #

ما برای اتصال به HTTP از توکن دسترسی (access token) استفاده خواهیم کرد که جلوتر در مثال ها ACCESS_TOKEN$ می نامیم. برنامه هایی که میخواهند درخواست HTTP دهند بایستی توکن دسترسی ACCESS_TOKEN$ را به عنوان پارامتر همراه با درخواست خود ارسال کنند. کد ها و خطا های احتمالی به شرح زیر است:

400 Bad Request – آدرس، پارامتر و یا بدنه پیام نا معتبر
401 Unauthorized – توکن دسترسی نا معتبر
404 Not Found – خطای عدم وجودیت

فرمت کلید-مقدار (Key-value format) #

به صورت پیشفرض ویرالینک محتوای کلید-ارزش در قالب json را پشتیبانی میکند. کلید همیشه به صورت یک رشته متن (String) بوده و نام صفت را مشخص میکند. مقدار یک صفت میتواند شامل string (رشته), boolean (منطقی), double (عدد اعشاری) , integer (عدد صحیح) و یا json باشد. برای مثال:

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

API ارسال داده های زمانی #

برای ارسال داده های زمانی به سرور کافیست درخواست POST خود را به آدرس زیر ارسال کنید.

https://console.viralink.ir/api/v1/$ACCESS_TOKEN/telemetry

ساده ترین شکل فرمت داده ها

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

یا

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

توجه داشته باشید که در هنگام دریافت پیام به صورت پیشفرض زمان timestamp آن لحظه ثبت خواهد شد. در صورتی که بخواهید زمان timestamp دلخواه خود و یا دستگاه را برای پیام مد نظر ثبت کنید میتوانید آن را در فرمت زیر ارسال نمایید.

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

در مثال بالا مقدار 1451649600512 زمان timestamp در واحد میلی ثانیه است. بنابراین این زمان معادل است با Fri, 01 Jan 2016 12:00:00.512 GMT.

telemetry-data-with-ts.json

telemetry-data-as-array.json

telemetry-data-as-object.json

Example

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

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

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

# Publish data as an object without timestamp (server-side timestamp will be used)
curl -v -X POST --data "{"temperature":42,"humidity":73}" https://console.viralink.ir/api/v1/$ACCESS_TOKEN/telemetry --header "Content-Type:application/json"

# Publish data as an object without timestamp (server-side timestamp will be used) using data from file
curl -v -X POST -d @telemetry-data-as-object.json https://console.viralink.ir/api/v1/$ACCESS_TOKEN/telemetry --header "Content-Type:application/json"

# Publish data as an array of objects without timestamp (server-side timestamp will be used)  using data from file
curl -v -X POST -d @telemetry-data-as-array.json https://console.viralink.ir/api/v1/$ACCESS_TOKEN/telemetry --header "Content-Type:application/json"

# Publish data as an object with timestamp (telemetry timestamp will be used)  using data from file
curl -v -X POST -d @telemetry-data-with-ts.json https://console.viralink.ir/api/v1/$ACCESS_TOKEN/telemetry --header "Content-Type:application/json"

API صفت ها #

به کمک API صفت ها میتوانید:

ارسال صفت های سمت کاربر (client-side attributes) به سرور
درخواست مقادیر صفت های سمت کاربر و مشترک (shared attributes) از سرور
subscribe کردن به صفت های مشترک از سرور (تا در زمان تغییر صفت ها در لحظه با خبر شوید).

ارسال صفت ها به سرور #

برای ارسال صفت های سمت کاربر (یا همان صفت های سمت دستگاه) به سرور کافیست درخواست POST را به آدرس زیر ارسال کنید.

https://console.viralink.ir/api/v1/$ACCESS_TOKEN/attributes

new-attributes-values.json

Example

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

# Publish client-side attributes update
curl -v -X POST --data "{"attribute1": "value1", "attribute2":true, "attribute3": 43.0}" https://console.viralink.ir/api/v1/$ACCESS_TOKEN/attributes --header "Content-Type:application/json"

# Publish client-side attributes update from file
curl -v -X POST -d @new-attributes-values.json https://console.viralink.ir/api/v1/$ACCESS_TOKEN/attributes --header "Content-Type:application/json"

API درخواست مقادیر صفت ها از سرور #

برای درخواست مقادیر صفت های سمت کاربر و یا صفت های مشترک از سرور کافیست درخواست GET را به آدرس زیر ارسال کنید.

https://console.viralink.ir/api/v1/$ACCESS_TOKEN/attributes?clientKeys=attribute1,attribute2&sharedKeys=shared1,shared2

Result

Example

{"key1":"value1"}

# Send HTTP attributes request
curl -v -X GET "https://console.viralink.ir/api/v1/$ACCESS_TOKEN/attributes?clientKeys=attribute1,attribute2&sharedKeys=shared1,shared2"

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

برای subscribe کردن مقادیر صفت های مشترک از سرور کافیست درخواست GET را همراه با پارامتر timeout به آدرس زیر ارسال کنید.با این کار هنگام تغییر مقادیر صفت ها در همان لحظه به شما اطلاع داده میشود.

https://console.viralink.ir/api/v1/$ACCESS_TOKEN/attributes/updates

زمانیکه که مقدار یک صفت مشترک توسط برنامه های سرور (از قبیل REST API یا زنجیره قواعد) تغییر پیدا کند، کاربر یا همان برنامه دستگاه در فرمت زیر آن تغییرات را دریافت خواهد کرد.

Result

Example

{"key1":"value1"}

# Send HTTP attributes request
curl -v -X GET https://console.viralink.ir/api/v1/$ACCESS_TOKEN/attributes/updates?timeout=20000

RPC API #

RPC سمت سرور (Server-side RPC) #

RPC های سمت سرور دستورات RPC درخواستی از سمت سرور هستند که به دستگاه ارسال می شوند. دستگاه بایستی پس از اجرای دستورات نتیجه آن را به سرور ارسال کند.
برای subscribe کردن دستورات RPC از سرور کافیست درخواست GET را همراه با پارامتر timeout به آدرس زیر ارسال کنید. با این کار دستورات RPC درخواستی از سمت سرور را در همان لحظه دریافت خواهید کرد.

https://console.viralink.ir/api/v1/$ACCESS_TOKEN/rpc

پس از subscribe کردن کاربر دستورات RPC درخواستی را که در زمان timeout ممکن است به دستگاه ارسال شده باشد را در فرمت زیر دریافت خواهد کرد.

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

توضیح پارامتر ها:

id – آیدی درخواست
method – نام تابع RPC, string
params – پارامتر های تابع RPC, json object

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

https://console.viralink.io/api/v1/$ACCESS_TOKEN/rpc/{$id}

که id$ آیدی درخواست میباشد.

Response Body

Examle Reply

Example Subscribe

{"result":"ok"}

# Publish response to RPC request
curl -v -X POST -d @rpc-response.json https://console.viralink.ir/api/v1/$ACCESS_TOKEN/rpc/1 --header "Content-Type:application/json"

# Send HTTP attributes request
curl -v -X GET https://console.viralink.ir/api/v1/$ACCESS_TOKEN/rpc?timeout=20000

RPC سمت کاربر (Client-side RPC) #

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

https://console.viralink.ir/api/v1/$ACCESS_TOKEN/rpc

بدنه اصلی (body) هم درخواست و هم پاسخ آن باید به فرمت json باشد. محتوای پیام باید به گونه ای باشد که گره مد نظر در زنجیره قواعد بتواند آن را پردازش کند.

Request Body

Request Reply

Example Request

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

{"method": "getTime", "params":{}}

# Send HTTP attributes request
curl -X POST -d @rpc-client-request.json https://console.viralink.ir/api/v1/$ACCESS_TOKEN/rpc --header "Content-Type:application/json"

درخواست تخصیص دستگاه #

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

https://console.viralink.ir/api/v1/$ACCESS_TOKEN/claim

فرمت پشتیانی شده برای محتوای پیام

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

توجه نمایید که فیلد های بالا اختیاری است. در صورتی که secretKey در پیام وجود نداشته باشد، یک رشته متن (string) خالی به عنوان مقدار پیشفرض ارسال میشود و همچنین در صورتی که durationMs وجود نداشته باشد، مقدار پیشفرض device.claim.duration استفاده خواهد شد.

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

راه‌اندازی اولیه

راهنمای ویرالینک

API

دستگاه‌ها

گیتوی اینترنت اشیا

مثال‌های کاربردی

HTTP API

شروع به کار #

آشنایی با HTTP #

نصب کتابخانه های پیش نیاز #

اتصال به HTTP و خطاهای احتمالی #

فرمت کلید-مقدار (Key-value format) #

API ارسال داده های زمانی #

API صفت ها #

ارسال صفت ها به سرور #

API درخواست مقادیر صفت ها از سرور #

RPC API #

RPC سمت سرور (Server-side RPC) #

RPC سمت کاربر (Client-side RPC) #

درخواست تخصیص دستگاه #

شروع ویرالینک در کمتر از یک دقیقه

لینک های مهم

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

HTTP API

شروع به کار #

آشنایی با HTTP #

نصب کتابخانه های پیش نیاز #

اتصال به HTTP و خطاهای احتمالی #

فرمت کلید-مقدار (Key-value format) #

API ارسال داده های زمانی #

API صفت ها #

ارسال صفت ها به سرور #

API درخواست مقادیر صفت ها از سرور #

subscribe کردن به بروزرسانی های صفت های مشترک #

RPC API #

RPC سمت سرور (Server-side RPC) #

RPC سمت کاربر (Client-side RPC) #

درخواست تخصیص دستگاه #

اشتراک گذاری از طریق :

شروع ویرالینک در کمتر از یک دقیقه

لینک های مهم