Servicios Xml - Circutor EDS-3G Manual De Instrucciones

4.3.- Servicios XML

Las peticiones deberán seguir el estándar URI (RFC 2396) de
manera que el usuario de estas peticiones debe tener en
cuenta este detalle cuando realice este tipo de llamadas
(sobre todo en el caso que el nombre de algún dispositivo
contenga caracteres no ASCII). También debe tenerse en
cuenta que la longitud de la petición no puede superara en
ninguno de los casos los 4000 caracteres de longitud.
4.3.1.- Petición dispositivos configurados
Mediante dicha petición, el servicio XML devuelve la lista de
dispositivos conectados al gestor de eficiencia energética
EDS-3G.
http://x.x.x.x/services/user/devices.xml
http://nombre_dhcp/services/user/devices.xml
<devices>
<id> ... </id>
<devices>
- devices: campo que identifica al XML como respuesta a la
petición de lista de dispositivos
- id: nombre de cada uno de los dispositivos
4.3.2.- Información sobre el dispositivo
Mediante dicha petición, el servicio
información sobre los dispositivos. Cada uno de los
dispositivos que se desea obtener información, debe incluirse
en la petición como ?id=dispositivo1?id=dispostivo2...
http://x.x.x.x/services/user/deviceInfo.xml
http://nombre_dhcp/services/user/deviceInfo.xml?id=disp
ositivo?
<devices>
<device>
<id> ... <id>
<description> ... </description>
<type> ... </type>
<typeDescription> ... </typeDescription>
<var> ... </var>
...
</device>
...
<devices>
- description: descripción del dispositivo
- type: tipo de dispositivo
- typeDescription: descripción detalla del dispositivo
- var: nombre de cada una de las variables del dispositivo;
expresado como nombre.variable
4.3.3.- Información de la variable
El usuario puede solicitar información detallada de una o
varias variables procedentes de un dispositivo e incluso
solicitar en una sola petición, la información de todas la
variables disponibles en el dispositivo.
4.3.3.1.- Información de una o varias variables
Petición para solicitar la información detallada de una o varias
variables del dispositivo del dispositivo (en el caso de
necesitar información de más variables, encadenar el resto
de peticiones a continuación con var=dispositivo.variable?):
http://x.x.x.x/services/user/varInfo.xml?var=dispositivo.variabl
e?
http://nombre_dhcp/services/user/varInfo.xml?var=dispositivo.
variable?
4.3.3.2.- Información de todas las variables
Petición para solicitar la información detallada de todas las
variables del dispositivo (en el caso de necesitar información
de más dispositivos, encadenar el resto de peticiones a
continuación con id=dispositivo?):
http://x.x.x.x/services/user/varInfo.xml?id=dispositivo?
http://nombre_dhcp/services/user/varInfo.xml?id=dispositivo?
<varInfo>
<var>
<id> ... </id>
<title> ... </title>
<hasValue> T </hasValue>
<hasLogger> T </hasLogger>
<sampleMode> ... </sampleMode>
<measureUnits> ... </measureUnits>
<unitsFactor> ... </unitsFactor>
<decimals> ... </decimals>
</var>
...
<varInfo>
- id: nombre de la variable en formato dispositivo.variable
- title: descripción breve de la variable
- hasValue: indica si es posible solicitar el valor instantáneo
de la variable (True / False)
- hasLogger: indica si es posible solicitar el histórico de
valores de la variable (True / False)
- sampleMode: tipo de variable y modo utilizado para
agrupar valores
- measureUnits: unidad de las variables
- unitsFactor: potencia de 10
multiplicador en el fichero de históricos
- decimals: decimales de la variable
4.3.4.- Valor instantáneo de la variable
El usuario puede solicitar los valores instantáneos de una o
varias variables, e incluso solicitar la información de todos los
valores instantáneos en una sola petición.
4.3.4.1.- Valor instantáneo de una o varias variables
Petición para solicitar el valor instantáneo de una o varias
variables del dispositivo (en el caso de necesitar información
de más variables, encadenar el resto de peticiones a
continuación con var=dispositivo.variable?):
http://x.x.x.x/services/user/values.xml?var=dispositivo.variabl
e?
http://nombre_dhcp/services/user/
variable?
4.3.4.2.- Valor instantáneo de todas las variables
Petición para solicitar el valor instantáneo de todas las
variables del dispositivo (en el caso de necesitar información
de más dispositivos, encadenar el resto de peticiones a
continuación con id=dispositivo?):
http://x.x.x.x/services/user/values.xml?id=dispositivo?
http://nombre_dhcp/services/user/
XML devuelve
<values>
<variable>
<id> ... <id>
<value> ... </value>
?id=dispositivo?
</variable>
...
</values>
- id: identificador de la variable
- value: valor de la variable en el momento de la petición
4.3.5.- Datos históricos
Petición para solicitar el registro de datos históricos de una
variable incremental. Devuelve la información registrada de
una o más variables entre las fechas "begin" y "end". Cada
una de las variables que desea obtener información debe
incluirse en la petición como ?var=dispositivo.variable
Cuando se desee indicar solamente la fecha, el formato es
DDMMAAAA; cuando quiere especificarse la fecha y hora es
DDMMAAAAHHMMSS. Tano la fecha como la hora, debe
estar expresado en UTC (Universal Coordinated Time).
El período de agrupación (period) podrá definirse por
diferentes criterios:
- valor en segundos (p.e. 900): valor en segundos en los que
se agrupan los datos
- ALL: los datos se agrupan en un único valor
- AUTO: la agrupación se realiza automáticamente con
intervalos predefinidos según "begin" y "end"
- FILE: no se agrupan los datos. Devuelve la información tal y
como se registra en la base de datos
- si el parámetro period no parece en la petición, se
considerará como valor 0 y no se agruparán los datos
http://x.x.x.x/services/user/records.xml?begin=010320110000
00?end=31032011000000?var=dispositivo.variable?period=9
00
http://nombre_dhcp/services/user/records.xml?begin=010320
11000000?end=31032011000000?var=dispositivo.variable?p
eriod=900
<recordGroup>
<period> ... </period>
<record>
<dateTime> ... </ dateTime >
<field>
<id> ... </id>
<value> ... </value>
</field>
</record>
...
</recordGroup>
- recordGroup: campo que identifica al XML como respuesta
a la petición de registros de variables
- period: período de registro; tiempo entre registros
- record: identifica cada uno de los registros (dateTime:
fecha y hora de la muestra
- field: registro valor estándar (otros consultar manual PS)
- value: valor de la variable en el momento de la petición
4.3.6.- Histórico de sucesos
Tal y como se muestra en el presente manual de usuario,
mediante el Editor PowerStudio / Scada es posible
configurar eventos o alarmas, dentro del dispositivo EDS-3G
y registrarlos en su memoria interna.
Con la siguiente petición, el usuario puede solicitar el
histórico de suceso entre dos fechas definidas. Cada suceso
que quiera pedirse con una petición de históricos se definirá
como ?id=nombre_suceso
Cuando se desee indicar solamente la fecha, el formato es
DDMMAAAA; cuando quiere especificarse la fecha y hora es
indicando el factor
DDMMAAAAHHMMSS. Tanto la fecha como la hora, debe
estar expresado en UTC (Universal Coordinated Time).
http://x.x.x.x/services/user/events.xml?begin=0103201100000
0?end=31032011000000?id=nombre_suceso?
http://nombre_dhcp/services/user/events.xml?begin=0103201
1000000?end=31032011000000?id=nombre_suceso?
<main>
v
alues.xml?var=dispositivo.
<main>
-
-
-
v
alues.xml?id=dispositivo?
-
-
-
-
-
4.3.7.- Sucesos de un dispositivo
Devuelve la información de eventos registrados de uno o más
dispositivos entre las fechas "begin" y "end". Cada uno de los
dispositivos de los que se desea obtener información debe
incluirse como ?id=dispositivo
http://x.x.x.x/services/user/recordsEve.xml?begin=010320110
00000?end=31032011000000?id=dispositivo?
http://nombre_dhcp/services/user/recordsEve.xml?begin=010
32011000000?end=31032011000000?id=dispositivo?
Cuando se desee indicar solamente la fecha, el formato es
DDMMAAAA; cuando quiere especificarse la fecha y hora es
DDMMAAAAHHMMSS. Tanto la fecha como la hora, debe
estar expresado en UTC (Universal Coordinated Time).
<main>
</main>
-
-
-
-
-
-
-
-
4.3.8.- Sucesos activos
EDS-3G dispone de un servicio XML de sucesos activos cuyo
objetivo es que un agente o sistema de integración externo
pueda registrarse como oyente (listener) y registrar los
eventos o alarmas que se suceden en el equipo.
El equipo mantiene una lista de difusión con usuarios activos,
a los cuales envía los eventos que se producen de forma
local, a través de la creación de sucesos.
4.3.8.1.- Comandos de test
Antes de iniciar la implementación del sistema de sucesos
activos, y con el objetivo de comprobar la conectividad entre
ambos sistemas, existe una serie de peticiones de test tipo
PUT entre el listener (oyente) y producer (motor remoto) y
viceversa, cuyo objetivo es testear y asegurar la conectividad
entre ambos sistemas.
Para que el listener pueda comprobar la conectividad con el
motor remoto (producer), puede enviar dicha petición con el
siguiente cuerpo del mensaje:
http://ip_producer:port/services/user/testListener.xml
<listener>
</listener>
<recordGroup>
<id> ... </id>
<record>
<date> ... </date>
<eventId> ... </eventId>
<annotation> ... </annotation>
<value> ... </value>
</record>
...
</recordGroup >
...
main: campo que identifica al XML como petición
recordGroup: campo que agrupa los registros de un suceso
id: identificador del suceso
record: identifica cada uno de los registros
date: fecha y hora del suceso
eventId: identificador del suceso
annotation: anotación del suceso
value: valor del suceso
ON: suceso activo
OFF: suceso inactivo
ACK: suceso reconocido
<recordGroup>
<device> ... </device>
<record>
<dateTime> ... </dateTime>
<field>
<id> ... </id>
<value> ... </value>
</field>
...
</record>
...
</recordGroup >
...
main: campo que identifica al XML como petición
recordGroup: campo que agrupa los registros de un suceso
device: dispositivo al que hacen referencia los registros
record: identifica cada uno de los registros
dateTime: fecha y hora del suceso
field: identifica cada uno de los campos
id: identificador
value: valor del evento
<ip>ip_listener</ip>
<port>80</port>
M98240601-01-13B
EDS-3G