10 Motor Webservice

10.3.1 Rutas JSON#

Una ruta indica cómo llegar a un valor desde la raíz del documento JSON. Se compone de pasos separados por dos puntos (:):

La ruta de un ítem tiene que terminar en un valor simple (texto, número, booleano o null). Dado este documento:

{
  "server":   { "name": "ent01", "state": "RUNNING", "up": true },
  "jobs": [
    { "id": 1, "name": "backup", "status": "OK",     "duration": 120 },
    { "id": 2, "name": "purge",  "status": "FAILED", "duration": 30 }
  ],
  "counters": { "cpu": 12.5, "memory": 2048 },
  "note": null
}

En los casos no soportado, si el ítem tiene atributo default, se envía ese valor. Con type="INT", los booleanos se convierten en 1 y 0.

10.3.2 Parámetros en la URL#

Cada <parameter> con urlparameter añade a la URL un parámetro con ese nombre y el valor de la clave. La consulta se ejecuta una vez por cada clave distinta:

<query name="JDEInstanceState" module="JDE" type="REST" transport="GET" encode="Json">
    <url>instancestate</url>
    <parameter urlparameter="instanceName" order="1" type="STRING"/>
    <item name="ts.jde.instance.state" path="instanceState" type="STRING"/>
</query>

En cada llamada el servicio responde, por ejemplo, {"instanceState":"RUNNING"}, y la ruta instanceState extrae el valor.

10.3.3 Filtro sobre la respuesta#

Cuando el servicio devuelve de una vez la lista de todos los objetos, es más eficiente hacer una sola llamada y elegir el elemento en la respuesta, igual que una consulta FILTER de base de datos. Para ello:

• <base path="…"> indica el array que se recorre (su ruta termina en []);

• cada <parameter path="…"> indica un campo de cada elemento que se compara con un parámetro de la clave;

• las rutas de los ítems son relativas al elemento elegido.

<query name="LocalJobs" module="API" type="REST" transport="GET" encode="Json">
    <url>status</url>
    <base path="jobs:[]"/>
    <parameter path="name" order="1" type="STRING"/>
    <item name="local.api.job.status"   path="status"   type="STRING" default="UNKNOWN"/>
    <item name="local.api.job.duration" path="duration" type="INT"/>
</query>

Con el documento de la sección anterior como respuesta:

Las cinco claves se resuelven con una sola llamada al servicio. Con type="INT" en el <parameter>, la comparación es numérica (por ejemplo, parameter path="id" y la clave …[2]).

10.3.4 Descubrimientos REST#

La ruta del <item> de un descubrimiento recorre un array ([]) o los miembros de un objeto (*). Cada elemento recorrido es una entidad descubierta, y las rutas de los <field> son relativas a él:

<query name="LocalJobDiscovery" module="API" type="REST"
       transport="GET" encode="Json" discovery="yes">
    <url>status</url>
    <item name="local.api.job.discovery" path="jobs:[]"/>
    <field name="JOB"    path="name"/>
    <field name="JOBID"  path="id"/>
</query>

Con el documento de la sección 10.3.1, el valor del ítem es:

{"data":[ {"{#JOB}":"backup", "{#JOBID}":"1"},
          {"{#JOB}":"purge",  "{#JOBID}":"2"} ]}

{ "clusters": [
    { "name": "A", "nodes": [ {"host": "a1"}, {"host": "a2"} ] },
    { "name": "B", "nodes": [ {"host": "b1"} ] }
] }

<query name="LocalNodeDiscovery" module="API" type="REST"
       transport="GET" encode="Json" discovery="yes">
    <url>clusters</url>
    <script language="Javascript"><![CDATA[
        function aplanar(status_code, result) {
            if (status_code != 200) throw "ZBX_NOTSUPPORTED";
            var res = { nodes: [] };
            for (var i = 0; i < result.clusters.length; i++) {
                var c = result.clusters[i];
                for (var j = 0; j < c.nodes.length; j++)
                    res.nodes.push({ cluster: c.name, host: c.nodes[j].host });
            }
            return res;
        }
        ]]>
    </script>
    <transform language="Javascript" function="aplanar"/>
    <item name="local.api.node.discovery" path="nodes:[]"/>
    <field name="CLUSTER" path="cluster"/>
    <field name="HOST"    path="host"/>
</query>

{"data":[ {"{#CLUSTER}":"A","{#HOST}":"a1"}, {"{#CLUSTER}":"A","{#HOST}":"a2"},
          {"{#CLUSTER}":"B","{#HOST}":"b1"} ]}

10.4.1 Conversión de la respuesta SOAP a JSON#

Databbix convierte en JSON el elemento de respuesta del método, es decir, el primer hijo de <Body>. Ese elemento es la raíz del JSON: su nombre no forma parte de las rutas. La conversión sigue estas reglas:

1. Un elemento con elementos hijos se convierte en un objeto. Cada hijo es un miembro con su nombre local, sin el prefijo del espacio de nombres.

2. Si un elemento tiene varios hijos con el mismo nombre, ese miembro es un array con todos sus valores, en orden.

3. Un elemento sin hijos se convierte en un texto, aunque su contenido sea un número o un booleano, y aunque lleve un atributo xsi:type.

4. Los atributos XML se ignoran.

5. El orden de los miembros del objeto puede no coincidir con el del XML. Esto no afecta a las rutas.

Como todos los valores simples son texto, en las funciones de transformación hay que convertirlos para operar con ellos (Number(r.sessions) en JavaScript, int(r[’sessions’]) en Python). En los ítems no hace falta: type="INT" envía el texto tal cual y convierte true/false en 1/0.

Ejemplo. Respuesta del servicio:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <soap:Body>
    <ns2:getCurrentUserProfileResponse xmlns:ns2="http://oracle.e1.bssv.JP000000/">
      <addressNumber>4242</addressNumber>
      <active xsi:type="xsd:boolean">true</active>
      <sessions xsi:type="xsd:int">3</sessions>
      <userProfile>
        <language>S</language>
        <dateFormat>DMY</dateFormat>
      </userProfile>
      <role>ADMIN</role>
      <role>USER</role>
    </ns2:getCurrentUserProfileResponse>
  </soap:Body>
</soap:Envelope>

JSON que se obtiene (y que recibe la función de <transform>, si la hay):

{
  "addressNumber": "4242",
  "active": "true",
  "sessions": "3",
  "userProfile": { "language": "S", "dateFormat": "DMY" },
  "role": [ "ADMIN", "USER" ]
}

<soap:Body>
  <soap:Fault>
    <faultcode>soap:Server</faultcode>
    <faultstring>User not authorized</faultstring>
  </soap:Fault>
</soap:Body>

{ "faultcode": "soap:Server", "faultstring": "User not authorized" }

10.4.2 Transformación de respuestas SOAP#

La función de <transform> recibe (status_code, result), igual que en REST, pero status_code vale siempre 0 y result es el JSON obtenido con las reglas anteriores. Este ejemplo detecta los Fault, normaliza role para que sea siempre un array y calcula valores derivados:

<query name="LocalUserProfile" module="golive" type="SOAP" transport="POST">
    <url>FoundationEnvironmentManager</url>
    <method uri="http://oracle.e1.bssv.JP000000/" name="getCurrentUserProfile" action=""/>
    <script language="Javascript"><![CDATA[
        function perfil(status_code, r) {
            if (r.faultcode !== undefined) {
                log_info("SOAP Fault:", r.faultstring);
                throw "ZBX_NOTSUPPORTED";
            }
            var roles = r.role;
            if (roles === undefined)
                roles = [];
            else if (!(roles instanceof Array))
                roles = [ roles ];                 // un solo <role>
            return {
                address:  Number(r.addressNumber),
                nroles:   roles.length,
                admin:    roles.indexOf("ADMIN") >= 0,
                language: r.userProfile ? r.userProfile.language : ""
            };
        }
        ]]>
    </script>
    <transform language="Javascript" function="perfil"/>
    <item name="local.golive.address"  path="address"  type="INT"/>
    <item name="local.golive.nroles"   path="nroles"   type="INT"/>
    <item name="local.golive.admin"    path="admin"    type="INT"/>
    <item name="local.golive.language" path="language" type="STRING"/>
</query>

La misma función en Python:

def perfil(status_code, r):
    if 'faultcode' in r:
        log_info("SOAP Fault:", r.get('faultstring'))
        raise Exception("ZBX_NOTSUPPORTED")
    roles = r.get('role', [])
    if not isinstance(roles, list):
        roles = [roles]
    return {
        'address':  r.get('addressNumber'),
        'nroles':   len(roles),
        'admin':    'ADMIN' in roles,
        'language': r.get('userProfile', {}).get('language', '')
    }

10.6.1 Motores y métodos de autenticación#

Hay que distinguir dos cosas:

Motor de autenticación.

Está programado en C++ dentro de Databbix e implementa un mecanismo completo: cómo se envían las credenciales, cómo se obtiene y renueva un token, etc. Hay cuatro: HTTPAuth, RESTToken, JDE y Oasis.

Método de autenticación.

Se define en un fichero de consultas con <authentication>. Toma un motor (atributo type) y lo personaliza para un servicio concreto con funciones en JavaScript o Python y otros elementos (URL de login, cabeceras, dónde va el token…). Se identifica por su atributo name.

10.6.2 Cómo se elige la autenticación#

El parámetro Webservice.Authenticator del .conf contiene un nombre. Databbix lo busca en este orden:

1. Un método de autenticación en los ficheros de consultas del monitor: un <authentication> cuyo name coincida. Si lo encuentra, usa el motor que indica su type, personalizado con las funciones del método.

2. Un motor de autenticación con ese nombre. Si lo encuentra, lo usa directamente, sin personalizar, con las credenciales del .conf. (Se admite también el nombre con el sufijo Authenticator, como HTTPAuthAuthenticator.)

3. Si no encuentra ninguno de los dos, el monitor no puede conectar y lo registra en su log.

10.6.3 Ejemplos#

Motor usado directamente: no hay ningún método llamado JDE en los XML, así que se usa el motor JDE tal cual.

[Webservice]
BaseURL = http://jdesm.empresa.com:8999/manage/mgmtrestservice/
Authenticator = JDE
UserName = jde_admin
Password = secreto

Método de autenticación: el XML define AISAuth, que personaliza el motor RESTToken, y el .conf lo usa por su nombre.

<Queries engine="Webservice">
    <authentication type="RESTToken" name="AISAuth">
        <script language="Javascript"> ... </script>
        <login type="JsonPost"> ... </login>
        <token type="Header" name="jde-AIS-Auth"/>
        <verify-call language="Javascript" function="verifyCall"/>
    </authentication>
    <query ...> ... </query>
</Queries>

[Webservice]
Authenticator = AISAuth

La programación de las funciones de autenticación se describe en la sección 12.7.