mobile logo

Tillgängliga REST-anrop

Switchking / Tillgängliga REST-anrop
06
oktober

Tillgängliga REST-anrop

6 oktober, 2010
In
By maha

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