Упутство за употребу софтвера ДИВУС ВИСИОН АПИ

ДИВУС ВИСИОН АПИ софтвер

Спецификације

• Производ: ДИВУС ВИСИОН АПИ
• Произвођач: ДИВУС ГмбХ
• Верзија: 1.00 РЕВ0 1 – 20240528
• Локација: Пиллхоф 51, Еппан (БЗ), Италија

Информације о производу

ДИВУС ВИСИОН АПИ је софтверски алат дизајниран за повезивање са ДИВУС ВИСИОН системима. Омогућава корисницима да приступе и контролишу различите елементе унутар система користећи МКТТ протоколе.

ФАК

П: Да ли могу да користим ДИВУС ВИСИОН АПИ без претходног знања о рачунару или технологији аутоматизације?

О: Приручник је прилагођен корисницима са претходним знањем у овим областима како би се обезбедило ефикасно коришћење АПИ-ја.

ОПШТЕ ИНФОРМАЦИЈЕ

• ДИВУС ГмбХ Пиллхоф 51 И-39057 Еппан (БЗ) – Италија

Упутства за употребу, приручници и софтвер заштићени су ауторским правима. Сва права задржана. Није дозвољено копирање, умножавање, превођење, превођење у целини или делимично. Изузетак се односи на прављење резервне копије софтвера за личну употребу.
Упутство је подложно промени без претходне најаве. Не можемо гарантовати да подаци садржани у овом документу и на испорученом медију за складиштење немају грешака и да су тачни. Предлози за побољшања, као и наговештаји грешака су увек добродошли. Уговори се такође примењују на посебне анексе овог приручника. Ознаке у овом документу могу бити жигови чије коришћење од стране трећих лица у сопствене сврхе може нарушити права њихових власника. Упутства за кориснике: Молимо прочитајте ово упутство пре прве употребе и чувајте га на безбедном месту за будућу употребу. Циљна група: Приручник је написан за кориснике са претходним познавањем рачунара и технологије аутоматизације.

КОНВЕНЦИЈЕ ПРЕЗЕНТАЦИЈЕ

Увод

ОПШТИ УВОД

Овај приручник описује ВИСИОН АПИ (Апликацијски програмски интерфејс) – интерфејс преко којег се ВИСИОН може адресирати и контролисати из спољних система.
У практичном смислу, то значи да можете користити системе као што су

• МКТТ Екплорер (https://www.microsoft.com/store/… – за тестирање),
• Кућни помоћник (https://www.home-assistant.io/) или
• Чвор-РЕД (https://nodered.org/)

да контролише елементе којима управља ВИСИОН или да очита њихов статус. Приступ и комуникација се одвијају преко МКТТ протокола, који користи такозване теме за обраћање појединачним функцијама или скуповима функција или за информисање о њиховим променама. У ту сврху се користи МКТТ сервер (брокер) који се бави безбедношћу и управљањем/дистрибуцијом порука учесницима. У овом случају, МКТТ сервер се налази директно на ДИВУС КНКС ИК и посебно је конфигурисан за ову сврху. Иако се ВИСИОН АПИ може користити и без знања програмирања, ова функционалност је погодна за напредне кориснике.

ПРЕДУСЛОВИ

Као што је објашњено у ВИСИОН приручнику, корисник АПИ-ја подразумевано мора прво да буде активиран да би могао да га користи АПИ приступ ради само користећи податке за аутентификацију корисника Апи-а. Што се тиче корисничких права, активација за ову функционалност се тада може конфигурисати на свим или на појединачним елементима. Види поглавље 0. Наравно, потребан вам је и пројекат ВИСИОН у којем су елементи које желите да контролишете споља потпуно конфигурисани и веза са њима је успешно тестирана. Да бисте могли да адресирате појединачне елементе преко АПИ-ја, њихов ИД елемента мора бити познат: ово се приказује на дну обрасца за подешавања елемента

СИГУРНОСТ

Из безбедносних разлога, приступ АПИ-ју је могућ само локално (тј. не преко облака). Безбедносни ризик при активирању приступа АПИ је стога низак. Без обзира на то, елементи релевантни за безбедност не би требало да буду омогућени или експлицитно одбијени за приступ АПИ-ју.

МКТТ И ЊЕГОВИ УСЛОВИ – КРАТКО ОБЈАШЊЕЊЕ

• У МКТТ-у, улога централизованог управљања и дистрибуције свих порука је улога брокера. Иако МКТТ сервер и МКТТ брокер нису синоними (сервер је шири термин за улогу коју МКТТ клијенти такође могу да играју), у овом приручнику се увек мисли на брокера када се помиње МКТТ сервер. Сам ДИВУС КНКС ИК игра улогу МКТТ брокера / МКТТ сервера у контексту овог упутства.
• МКТТ сервер користи такозване теме: хијерархијску структуру помоћу које се подаци категоришу, управљају и објављују.
• Објављивање има примарни циљ да кроз теме учини податке доступним другим учесницима. Ако желите да промените вредност, пишете у жељену тему заједно са променом жељене вредности, такође користећи радњу објављивања. Циљни уређај или МКТТ сервер чита жељену промену која утиче на њега и усваја је у складу са тим. Да бисте проверили да ли је промена примењена, можете да погледате у претплаћеној теми у реалном времену да видите да ли се промена тамо одражава – да ли је све добро функционисало.
• Клијенти бирају теме које их занимају: ово се зове претплата. Сваки пут када се вредност промени у/испод теме, сви пријављени клијенти су обавештени – тј. без потребе да се експлицитно питају да ли се нешто променило или која је тренутна вредност.
• Можете отворити (или адресирати) посебан комуникациони канал са МКТТ сервером тако што ћете унети било који јединствени стринг који се зове цлиент_ид у тему. Цлиент_ид се мора користити у теми за обраду вредности. Ово служи за идентификацију порекла сваке промене, помаже код било каквих грешака и не утиче на друге клијенте, пошто одговарајући одговори са сервера, укључујући све кодове грешака и поруке, такође стижу до теме само са истим цлиент_ид (и самим тим само тај клијент). Цлиент_ид је јединствени низ знакова који се састоји од било које комбинације знакова 0-9, аз, АЗ, „-“, „_“.
• Генерално, теме за претплату МКТТ сервера ДИВУС КНКС ИК садрже статус кључне речи, док теме за објављивање садрже захтев за кључну реч. Они са статусом се аутоматски ажурирају чим дође до спољне промене вредности или чим сам клијент затражи промену вредности путем објаве и успешно је примењена. Оне за објављивање се даље деле на оне типа (рекуест/)гет и оне типа (рекуест/)сет.
• Промене вредности и други опциони параметри се додају у тему са такозваним корисним оптерећењем. Параметри појединачних елемената (ИД елемента, име, тип, функције)

Главна разлика између МКТТ-а и класичног клијент-сервер модела, где клијент захтева, а затим мења податке, усредсређена је на концепте претплате и објављивања. Учесници могу објављивати податке, чинећи их доступним другима, који се, ако су заинтересовани, могу претплатити на њих. Ова архитектура омогућава минимизирање размене података и даље ажурирање свих заинтересованих страна. Више о детаљима овде: и посебни параметри (ууид, филтери) се користе овде. Иако постоји неколико опција, корисни терет је у овом приручнику приказан форматиран као ЈСОН. ЈСОН користи заграде и зарезе за представљање података било које структуре и на тај начин минимизира величину пакета података који се преносе. Више детаља о носивости можете пронаћи касније у приручнику.

• За посебне намене, могуће је филтрирати према типу функције, нпр. адресирати само он/офф тј. 1-битне прекидаче. У ту сврху се користи параметар филтера у корисном учитавању. Филтрирање је тренутно могуће само према типу функције.
• Да бисте могли да адресирате појединачне елементе, потребан је њихов ИД елемента. Ово се може наћи у ВИСИОН у менију својстава елемента или се такође може прочитати директно из података који су приказани испред сваког доступног елемента у општој претплати МКТТ Екплорер-а (тамо елементи су наведени по абецедном реду према ИД-у елемента).

Конфигурација за приступ АПИ-ју

КОНФИГУРИСАЊЕ ВИЗИЈЕ ЗА ПРИСТУП КОРИСНИКА АПИ-ја

У ВИСИОН-у као администратор, идите на Конфигурација – Управљање приступом корисника/АПИ, кликните на Корисници/АПИ приступ и кликните десним тастером миша на АПИ Корисник (или притисните и држите) да бисте отворили прозор за уређивање. Тамо ћете наћи ове параметре и податке

• Омогући (поље за потврду)
  • Корисник је овде прво омогућен. Подразумевано је онемогућено
• Корисничко име
  • Овај низ је потребан за приступ преко АПИ-ја – копирајте га одавде
• Лозинка
  • Овај низ је потребан за приступ преко АПИ-ја – копирајте га одавде
• Дозволе
  • Овде се могу дефинисати подразумевана права за читање и уписивање вредности ВИСИОН елемената, односно оно што је овде дефинисано важи за све постојеће и будуће елементе. Ако желите да дозволите приступ само појединачним елементима, не би требало да мењате ова подразумевана права

ДОЗВОЛЕ НА ПОЈЕДИНАЧНИМ ЕЛЕМЕНТИМА

Препоручује се да не додељујете АПИ приступ целом пројекту, већ само жељеним елементима. Поступите на следећи начин

1. пријавите се на ВИСИОН као администратор
2. изаберите жељени елемент и отворите његов мени са подешавањима (кликните десним тастером миша или држите притиснут, а затим Подешавања)
3. под ставком менија Опште – Дозволе, активирајте „Оверриде дефаулт пермиссионс“, а затим идите на подставку Дозволе, која приказује матрицу дозвола.
4. активирајте контролну дозволу овде, што такође омогућава view дозволу директно. Ако желите само да читате податке преко АПИ приступа, довољно је да омогућите view дозволу.
5. поновите исту процедуру за све елементе којима желите да приступите

Веза преко МКТТ-а

УВОД

Као бившиampЗатим ћемо демонстрирати приступ преко МКТТ АПИ-ја ДИВУС КНКС ИК са релативно једноставним, бесплатним софтвером под називом МКТТ Екплорер (погледајте поглавље 1.1), који је доступан за Виндовс, Мац и Линук. Подразумева се основно знање и искуство са МКТТ.

ПОДАЦИ ПОТРЕБНИ ЗА ПОВЕЗИВАЊЕ

Као што је раније поменуто (погледајте одељак 2.1), потребно је корисничко име и лозинка корисника АПИ-ја. Овде је крајview од свих података који се морају прикупити пре успостављања везе:

• Корисничко име Прочитајте на страници са детаљима о кориснику АПИ-ја
• Лозинка Прочитајте на страници са детаљима о кориснику АПИ-ја
• ИП адреса Прочитајте у подешавањима покретача под Опште – Мрежа – Етернет (или преко синхронизатора)
• Порт 8884 (овај порт је резервисан за ову сврху)

ПРВА ВЕЗА СА МКТТ ЕКСПЛОРЕР-ом И ГЕНЕРАЛНА ПРЕТПЛАТНИЦА

Обично, МКТТ прави разлику између активности претплате и објаве. МКТТ Екплорер ово поједностављује аутоматским претплатом на све доступне теме (тема #) када се успостави прва веза. Као резултат тога, стабло које води до свих доступних елемената (тј. одобреног корисничког приступа АПИ-ју) може се видети директно у левој области прозора МКТТ Екплорер-а након успешне везе. Да бисте унели даље теме за претплату или да бисте заменили # конкретнијом темом, идите на Напредно у прозору везе. Тема приказана у горњем десном углу изгледа отприлике овако:

где је 7ф4к0607849к444ккк256573к3к9к983 АПИ корисничко име, а објецтс_лист садржи све доступне елементе. Ова тема се увек ажурира, односно све промене вредности се тамо одражавају у реалном времену. Ако желите да се претплатите само на појединачне елементе, унесите ИД елемента жељеног елемента након објецтс_лист/.

Напомена: Овај тип претплате отприлике одговара логици која стоји иза КНКС адреса повратних информација; приказује тренутни статус елемената и може се користити за проверу да ли су жељене промене успешно примењене. Ако желите само да читате податке, али не и да их мењате, ова врста претплате је довољна.

Један једноставан елемент изгледа отприлике овако у ЈСОН нотацији

Напомена: Све вредности имају синтаксу приказану изнад, нпр. { “валуе”: “1” } као излаз тема за претплату, док је вредност записана директно у корисном учитавању да би се променила вредност (тј. за теме за објављивање) – заграде и „вредност“ се изоставља, нпр. „искључено“: „1“.

Напредне команде

УВОД

Генерално постоје 3 врсте тема:

1. Претплатите се на тему(е) да бисте видели доступне елементе и да бисте добили промене вредности у реалном времену
2. Претплатите се на тему(е) да бисте добили одговоре на (клијентима ) објављују захтеве
3. Објавите тему(е) да бисте добили или поставили елементе са њиховим вредностима

Касније ћемо се позивати на ове врсте користећи овде приказану нумерацију (нпр. теме типа 1, 2, 3). Више детаља у наредним одељцима и у погл. 4.2.

ПРЕТПЛАТИТЕ СЕ НА ТЕМЕ ДА ВИДИТЕ ДОСТУПНЕ ЕЛЕМЕНТЕ И ДА ДОБИЈЕТЕ ПРОМЕНЕ ВРЕДНОСТИ У РЕАЛНОМ ВРЕМЕНУ

Ово је већ описано

ПРЕТПЛАТИТЕ СЕ НА ТЕМЕ ДА БИСТЕ ДОБИЛИ ОДГОВОРЕ НА ЗАХТЕВЕ КЛИЈЕНТА ЗА ОБЈАВЉИВАЊЕ

Ова врста тема је опциона. Омогућава да се

• отворите јединствени комуникациони канал са МКТТ сервером коришћењем произвољног цлиент_ид. Више о томе у погл. 4.2.2
• добити резултат захтева за објављивање на одговарајућу тему претплате: успех или неуспех са кодом грешке и поруком.

Постоје различите теме за добијање одговора или постављање команди за објављивање. Одговарајућа разлика у Када прецизирате потребне теме за ваш систем, можете одлучити да уклоните овај корак и директно користите теме за објављивање.

 ОБЈАВИТЕ ТЕМЕ ДА ДОБИЈЕТЕ ИЛИ ДА ПОСТАВИТЕ ЕЛЕМЕНТЕ СА ЊИХОВИМ ВРЕДНОСТИМА

Ове теме користе пут сличан онима за претплату – једина промена је реч „захтев“ уместо „статуса“ који се користи за претплату. Комплетне путање тема су приказане касније у погл. 4.2.2\ Гет тема ће захтевати да прочита елементе и вредности МКТТ сервера. Корисно оптерећење се може користити за филтрирање на основу типа функције елемената. Постављена тема ће захтевати да се промене неки делови елемента, као што је детаљно описано у његовом носивости.

ПРЕФИКС ЗА КОМАНДЕ И ОДГОВАРАЈУЋЕ ОДГОВОРЕ

 КРАТКО ОБЈАШЊЕЊЕ

Све команде које се шаљу на МКТТ сервер имају заједнички почетни део, и то:

ДЕТАЉНО ОБЈАШЊЕЊЕ

Теме у реалном времену (тип 1) ће имати општи префикс (види горе), а затим следи

or

За сет команде, корисно оптерећење очигледно игра главну улогу јер ће садржати жељене промене (тј. промењене вредности за функције елемента). Упозорење: Никада не користите опцију задржавања у командама типа 3 јер може изазвати проблеме на КНКС страни.

EXAMPЛЕ: ОБЈАВИТИ ЗА ПРОМЕНЕ ВРЕДНОСТИ ЈЕДНОГ ЕЛЕМЕНТА

Најједноставнији случај је да желите да промените вредност једног од елемената приказаних општим претплатом.
Уопштено говорећи, промена/промена функције ВИСИОН-а преко МКТТ-а састоји се од 3 корака, од којих све области нису апсолутно неопходне, али ми ипак препоручујемо да их извршите како је описано.

1. Тема која садржи функцију коју желимо да изменимо је претплаћена помоћу прилагођеног цлиент_ид
2. Тема за уређивање се објављује заједно са корисним оптерећењем са жељеним изменама коришћењем цлиент_ид изабраног у 1.
3. Да бисте проверили, онда можете видети одговор у теми (1.) – тј. да ли је (2.) успело или не
4. У општој претплати, где се све вредности ажурирају када се промене изврше, можете видети жељену(е) промену(е) вредности ако је све добро функционисало.

Кораци да то урадите су:

1. изаберите цлиент_ид, нпр. „Дивус“ и убаците га у путању после корисничког имена АПИ-ја
   Ово је комплетна тема за претплату на сопствени канал комуникације са МКТТ сервером. Ово говори серверу где очекујете одговоре на промене које намеравате да пошаљете. Обратите пажњу на део статуса/сета који дефинише а. да је то тема за претплату и б. да ће добити одговоре за постављање команди типа.
2. Тема објављивања ће бити иста осим за промену кључних речи статусног захтева
3. у чему би промена требало да се састоји уписано је у носивости. Ево неких бившихampлес.
   • Искључивање елемента који има функцију за укључивање/искључивање (1 бит):
   • Укључивање елемента који има функцију он/офф (1 бит). Поред тога, ако се неколико таквих команди покрене са истог клијента, параметар ууид („јединствени ИД“, обично је 128-битни низ форматиран као хексадецимални 8-4-4-4-12 цифара) може се користити за додељивање одговор на одговарајући упит, јер се овај параметар – ако је присутан у упиту – такође може наћи у одговору.
   • Укључивање и подешавање осветљености димера на 50%
   • Одговор на горе приказану и претплаћену тему (корисно оптерећење, да будемо прецизни) је онда, нпрampле.
     Горњи одговор је бившиampле у случају исправног носивости, иако елемент нема функцију затамњивања. Ако постоје озбиљнији проблеми који доводе до тога да се корисни терет не тумачи исправно, одговор ће изгледати овако (нпр.):
     за објашњење кодова грешака и порука, али генерално, као и за хттп, 200 кодова су позитивни одговори док је 400 негативни.

EXAMPЛЕ: ОБЈАВИТИ ЗА ПРОМЕЊУ ВРЕДНОСТИ ВИШЕ ЕЛЕМЕНАТА

Процедура је слична оној приказаној раније за промену једног елемента. Разлика је у томе што изостављате елемент_ид из тема, а затим указујете на скуп елемент_идова испред података унутар корисног оптерећења. Погледајте синтаксу и структуру испод.

ФИЛТРИРАЈТЕ ПРЕМА ТИПУ ФУНКЦИЈЕ У УПИТИМА

Параметар филтера у корисном учитавању дозвољава само адресирање жељене функције(е) елемента. Функција укључивања/искључивања прекидача или димера назива се „искључено“, нпрampле, а одговарајући филтер је дефинисан на овај начин:

Одговор тада изгледа овако, нпрample

Угласта заграда означава да можете филтрирати и по неколико функција, нпр

доводи до оваквог одговора:

Додатак

КОДОВИ ГРЕШАКА

Грешке у МКТТ комуникацији резултирају нумеричким кодом. Следећа табела помаже да се то разложи.

ПАРАМЕТРИ КОРИСНОГ ОПТЕРЕЋЕЊА

Корисно оптерећење подржава различите параметре у зависности од контекста. Следећа табела показује који се параметри могу појавити у којим темама

НАПОМЕНЕ ВЕРЗИЈЕ

• КСНУМКС ВЕРЗИЈА

вести:

• Прва публикација