Tillgängliga REST-anrop
Den här artikeln är i första hand tänkt för dig som utvecklar tillägg till Switch King.
REST-tjänsterna lever normalt sett en undanskymd tillvaro - en "vanlig" användare har i regel ingen större nytta av att veta hur dessa tjänster fungerar.
Från och med Switch King v0.7.2 finns en REST-tjänst inbyggd i servern. REST-tjänsten används för att kommunicera med servern. iPhone-appen och Android-appen är två exempel på tillägg som använder REST-tjänsten.
Via tjänsten finns möjlighet att:
- Hämta information om enheter i Switch King
- Hämta information om datakällor som finns lagrade i Switch King
- Hämta information om vilka scenario som finns tillgängliga
- Skicka kommandon till enheter
- Hämta logginformation
Vad REST-tjänsten levererar för resultat kan enklast ses genom att man navigerar till servern med en webbläsare.
Adressen som REST-tjänsten finns på är normalt:
http://servernamn:8800/sökt_tjänst
Informationstjänster
Nedan beskrivs kort de informationstjänster som finns tillgängliga i servern. Med informationstjänster menas tjänster där en klient kan fråga efter specifik information utan att serverns arbete påverkas.
Observera att användarnamn och lösenord för åtkomst till tjänsterna sätts i Windows-klienten.Enheter
Från v0.7
Enheter, deras namn, status och grundinställningar finns tillgängliga på adressen:
http://servernamn:8800/devices
För att få information om en enskild enhet kan enhetens ID läggas i slutet av adressen:
http://servernamn:8800/devices/1
REST-tjänsten stödjer inte direkt uppdatering av en enhet (exempelvis namnändring).
Enhetsgrupper
v0.7-v0.8
Ej tillgänligt
Från v0.9
Enhetsgrupper finns tillgängliga på adressen:
http://servernamn:8800/devicegroups
För att få information om en enskild enhet kan enhetens ID läggas i slutet av adressen:
http://servernamn:8800/devicegroups/1
REST-tjänsten stödjer inte direkt uppdatering av en enhetsgrupp (exempelvis namnändring).
Det är även möjligt att få information om enheterna i en grupp i samband med att gruppen hämtas.
http://servernamn:8800/devicegroups?includedevices=true
http://servernamn:8800/devicegroups/1?includedevices=true
Datakällor
Datakällor, deras namn, status och grundinställningar finns tillgängliga på adressen:
http://servernamn:8800/datasources
För att få information om en enskild datakälla kan källans ID läggas i slutet av adressen:
http://servernamn:8800/datasources/1
REST-tjänsten stödjer inte direkt uppdatering av en datakälla (exempelvis namnändring).
Grafer för datakällor
Från v3.0.0
http://servernamn:8800/datasources/{id}/graph.png?
width={width}&height={height}&minutesofhistory={minutesOfHistory}
Byt ut följande:
- {id} - mot datakällans ID
- {width} - grafens bredd i antal pixlar
- {height} - grafens höjd i antal pixlar
- {minutesOfHistory} - antal minuter grafen ska visualisera
Värden från datakällor
v0.7-v0.9
Ej tillgängligt
Från v1.10
Information om insamlade värden för en viss datakälla finns tillgänglig på adressen:
http://servernamn:8800/datasources/{id}/values?maxcount={maxCount}&
newerthan={newerThan}
Byt ut följande:
- {id} - mot datakällans ID
- {maxCount} - mot det maximala antalet värden som ska returneras
- {newerThan} - datum på formatet YYYY-MM-DD
Scenario
Scenarior, deras namn och status finns tillgängliga på adressen:
http://servernamn:8800/scenarios
REST-tjänsten stödjer inte direkt uppdatering av ett scenario (exempelvis namnändring).
System Mode
Från v3.0.0
System Mode, deras namn och status finns tillgängliga på adressen:
http://servernamn:8800/systemmodes
Aktivt System Mode finns på adressen:
http://servernamn:8800/systemmode/active
REST-tjänsten stödjer inte direkt uppdatering av ett system mode (exempelvis namnändring).
Kommande händelser
Information om kommande schemalagda händelser finns tillgängliga på adressen:
http://servernamn:8800/events/future?maxCount=20
Mottagna signaler (Duo/Telldus Center)
v0.7-1.x
Ej tillgänligt
Från v2.0
http://servernamn:8800/events/intercepted
Utökade tjänster
Under "Extended Services" finns tjänster som kan användas för att hämta information från servern som sedan kan användas som input till ett regelstyrt schema.
v0.7-0.9
Ej tillgängligt
Från v1.10
För samtliga anrop gäller att den text som står innanför "måsvingarna" ("{" och "}") måste bytas ut.
Exempelvis ska anropet:
http://servernamn:8800/extendedservices/calendar/dayofweekstring?mon={monday}&
tue={tuesday}&wed={wednesday}&
thu={thursday}&fri={friday}&sat={saturday}&sun={sunday}
...justeras för att ge veckodagar på svenska:
http://servernamn:8800/extendedservices/calendar/dayofweekstring?mon=mandag&
tue=tisdag&wed=onsdag&
thu=torsdag&fri=fredag&sat=lordag&sun=sondag
Följande tjänster finns:
http://servernamn:8800/extendedservices/calendar/dayofweekstring?mon={monday}&
tue={tuesday}&wed={wednesday}&
thu={thursday}&fri={friday}&sat={saturday}&sun={sunday}
http://servernamn:8800/extendedservices/calendar/dayofweek
http://servernamn:8800/extendedservices/calendar/oddweek?
returnwhentrue={returnWhenTrue}&returnwhenfalse={returnWhenFalse}
http://servernamn:8800/extendedservices/calendar/oddweek
http://servernamn:8800/extendedservices/calendar/evenweek?
returnwhentrue={returnWhenTrue}&returnwhenfalse={returnWhenFalse}
http://servernamn:8800/extendedservices/calendar/evenweek
http://servernamn:8800/extendedservices/calendar/holiday?
returnwhentrue={returnWhenTrue}&returnwhenfalse={returnWhenFalse}
http://servernamn:8800/extendedservices/calendar/holiday
http://servernamn:8800/extendedservices/calendar/month
http://servernamn:8800/extendedservices/calendar/year
http://servernamn:8800/extendedservices/calendar/day
http://servernamn:8800/extendedservices/calendar/week
http://servernamn:8800/extendedservices/calendar/date
http://servernamn:8800/extendedservices/calendar/time
Följande tjänster finns också i 1.10 men var inte dokumenterade på denna sidas första version:
http://servernamn:8800/extendedservices/calculations/sunstate?date={date}&
returnwhenup={returnWhenUp}&returnwhendown={returnWhenDown}&offset={offset}
Kommandotjänster
Det är möjligt att skicka kommandon till en eller flera enheter eller aktivera ett scenario. Kommandon skickas via en HTTP GET.
Färdiga kommandovägar finns för att bl.a. tända, släcka och dimma enheter och grupper. ID på enhet eller grupp krävs och erhålls via informationstjänsterna.
Enheter
Från v0.7
http://servernamn:8800/devices/{id}/turnon
http://servernamn:8800/devices/{id}/turnoff
http://servernamn:8800/devices/{id}/dim/{level}
http://servernamn:8800/devices/{id}/synchronize
http://servernamn:8800/devices/{id}/cancelsemiauto
Från v2.0.4
http://servernamn:8800/devices/{id}/turnonfake
http://servernamn:8800/devices/{id}/turnofffale
http://servernamn:8800/devices/{id}/dimfake/{level}
Enhetsgrupper
Från v0.9
http://servernamn:8800/devicegroups/{id}/turnon
http://servernamn:8800/devicegroups/{id}/turnoff
http://servernamn:8800/devicegroups/{id}/dim/{level}
http://servernamn:8800/devicegroups/{id}/cancelsemiauto
Från v2.0
http://servernamn:8800/devicegroups/{id}/synchronize
Värden till datakällor
Från v0.9
Det är möjligt att skicka in ett värde till en datakälla via följande adress:
http://servernamn:8800/datasources/{id}/addvalue?value={value}
Från v2.0.0
Från v2.0.0 finns möjlighet att sätta ett relativt värde på en datakälla.
http://servernamn:8800/datasources/{id}/setvaluerelative?value={value}&action={action}&
minvalue={minValue}&
maxvalue={maxValue}
Från v2.0.2
Från v2.0.2 finns möjlighet att lägga till ett framtida värde. Ej möjligt att garantera att regler som knyts till framtida värden utvärderas korrekt förrän versionen efter 2.0.2.
http://servernamn:8800/datasources/{id}/addfuturevalue?value={value}&
timestamp={timestamp}
Byte av scenario
Från v0.9
Byte av scenario görs genom adressen:
http://servernamn:8800/commandqueue?operation={operation}&target={target}&
param1={param1}¶m2={param2}¶m3={param3}
Ange parametrar enligt följande:
- {operation} = changescenario
- {target} = scenariots ID
- {param1} = lämnas tom
- {param2} = lämnas tom
- {param3} = lämnas tom
Byte av "System Mode"
Från v3.0.0
Byte av schedule mode görs genom adressen:
http://servernamn:8800/systemmodes/{id}/activate
Alternativt
http://servernamn:8800/commandqueue?operation={operation}&target={target}&
param1={param1}¶m2={param2}¶m3={param3}
Ange parametrar enligt följande:
- {operation} = changesystemmode
- {target} = schedule mode ID
- {param1} = lämnas tom
- {param2} = lämnas tom
- {param3} = lämnas tom
Senaste händelser i server
Switch King loggar internt vad som händer i servern. Detta bl.a. för att klienter ska kunna veta när information har uppdaterats.
v0.7-1.x
Ej tillgänligt
Från v2.0
http://servernamn:8800/entitylogentries?maxcount={maxCount}&newerthan={newerThan}
http://servernamn:8800/entitylogentries/latest