Wialon para desarrolladores Manual de usuario Documentación de API core batch

batch

Para ejecutar varios métodos en una solicitud, utilice el método core/batch.

Endpoint

La solicitud se puede enviar de dos formas. En la primera forma, el parámetro params contiene una matriz de métodos:

Copied!
svc=core/batch&params=[
  {
    "svc": "<text>",
    "params": {}
  }
]

En la segunda forma, el parámetro params contiene un objeto, lo que además permite utilizar el parámetro flags:

Copied!
svc=core/batch&params={
  "params": [{
    "svc": "<text>",
    "params": {}
  }],
  "flags": <uint>
}

Parámetros

Los parámetros svc y params se especifican para cada método de la matriz. El parámetro flags se especifica para la solicitud en su conjunto.

Nombre Descripción
svc Nombre del método que se debe ejecutar, por ejemplo, core/search_items.
params Parámetros del método.
flags Máscara de bits que puede incluir el siguiente flag:
  • 0x01 (1): detener la solicitud si uno de los métodos devuelve un error.
Especifique 0 para ejecutar todos los métodos. El parámetro solo está disponible en la segunda forma de la solicitud. Si lo omite en esta forma, la solicitud devuelve el error 4.

Resultado devuelto

Si la solicitud se completa correctamente, el resultado se devuelve con el siguiente formato:

Copied!
[
  { /* Objeto con datos si no hay errores. */
    ...
  },
  { /* Código de error si se ha producido un error. */
    "error": <int>
  },
  ...
]

Cada elemento de la matriz es el resultado del método correspondiente, sin ningún contenedor adicional. Si un método devuelve un error, su elemento contiene el código de error de ese método.

Si el parámetro flags incluye el flag 0x01 (1) y uno de los métodos devuelve un error, todos los métodos que siguen a este devuelven el código de error 10.

Códigos de error

La solicitud en sí puede devolver los siguientes códigos de error:

Código Descripción
4 Parámetros de entrada incorrectos. Esto sucede en uno de los siguientes casos:
  • la solicitud no corresponde a ninguna de las dos formas, por ejemplo, la segunda forma no contiene el parámetro flags. En este caso, la respuesta no tiene el campo reason
  • uno de los elementos de la matriz no es un método válido. En este caso, el campo reason contiene BATCH_INVALID_INTERNAL_REQUEST index=<i>, donde <i> es la posición de ese elemento en la matriz, empezando por 0
6 El resultado devuelto es demasiado grande.

Un método concreto puede devolver su propio código de error en su elemento de la matriz. Además de los códigos del propio método, son posibles los siguientes códigos:

Código Descripción
2 Nombre de método incorrecto en el parámetro svc.
10 El método no se ejecuta. Esto sucede en uno de los siguientes casos:
  • uno de los métodos anteriores ha devuelto un error y el parámetro flags incluye el flag 0x01 (1)
  • la solicitud ha superado el límite de tiempo establecido en el servidor

Ejemplos

Todos los ejemplos que se muestran a continuación envían los mismos dos métodos: el primero se refiere al elemento con el ID 1004, al que el usuario no tiene derechos de acceso, y el segundo obtiene las propiedades del recurso con el ID 1003. Agregue a cada solicitud el parámetro sid con el identificador de su sesión.

Ejecución de todos los métodos a pesar de un error

En la primera forma, el parámetro params contiene solo la matriz de métodos, por lo que no hay dónde especificar el parámetro flags. Se ejecutan todos los métodos.

Copied!
svc=core/batch&params=[
  {
    "svc": "core/search_item",
    "params": {
      "id": 1004,
      "flags": 1
    }
  },
  {
    "svc": "core/search_item",
    "params": {
      "id": 1003,
      "flags": 1
    }
  }
]

La segunda forma da el mismo resultado si el valor del parámetro flags es 0.

Copied!
svc=core/batch&params={
  "params": [
    {
      "svc": "core/search_item",
      "params": {
        "id": 1004,
        "flags": 1
      }
    },
    {
      "svc": "core/search_item",
      "params": {
        "id": 1003,
        "flags": 1
      }
    }
  ],
  "flags": 0
}

Respuesta:

Copied!
[
  {
    "error": 7
  },
  {
    "item": {
      "nm": "Resource",
      "cls": 3,
      "id": 1003,
      "mu": 0,
      "uacl": 19826928009763
    },
    "flags": 1
  }
]

El error del primer método no afecta al segundo.

Detención de la solicitud después del primer error

Para detener la ejecución después del primer error, utilice la segunda forma de la solicitud y especifique el flag 0x01 (1). Los métodos son los mismos, pero ahora el segundo no se ejecuta y devuelve el error 10.

Copied!
svc=core/batch&params={
  "params": [
    {
      "svc": "core/search_item",
      "params": {
        "id": 1004,
        "flags": 1
      }
    },
    {
      "svc": "core/search_item",
      "params": {
        "id": 1003,
        "flags": 1
      }
    }
  ],
  "flags": 1
}

Respuesta:

Copied!
[
  {
    "error": 7
  },
  {
    "error": 10
  }
]

Si nota un error en el texto, por favor resáltelo y presione Ctrl+Intro.