Wialon for developers User guide API reference core batch

batch

To execute several methods in one request, use the core/batch method.

Endpoint

The request can be sent in one of two forms. In the first form, the params parameter contains an array of methods:

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

In the second form, the params parameter contains an object, which also allows you to use the flags parameter:

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

Parameters

The svc and params parameters are specified for each method of the array. The flags parameter is specified for the request as a whole.

Name Description
svc The name of the method to execute, for example, core/search_items.
params The parameters of the method.
flags A bitmask that can include the following flag:
  • 0x01 (1): stop the request if one of the methods returns an error.
Specify 0 to execute all the methods. The parameter is available only in the second form of the request. If you omit it in this form, the request returns error 4.

Returned result

If the request is completed successfully, the result is returned in the following format:

Copied!
[
  { /* Object with data if there are no errors. */
    ...
  },
  { /* Error code if an error has occurred. */
    "error": <int>
  },
  ...
]

Each element of the array is the result of the corresponding method, without an additional wrapper. If a method returns an error, its element contains the error code of this method.

If the flags parameter includes the 0x01 (1) flag and one of the methods returns an error, all the methods that follow it return error code 10.

Error codes

The request itself can return the following error codes:

Code Description
4 Wrong input parameters. This happens in one of the following cases:
  • the request doesn’t match either of the two forms, for example, the second form doesn’t contain the flags parameter. In this case, the response has no reason field
  • one of the elements of the array isn’t a valid method. In this case, the reason field contains BATCH_INVALID_INTERNAL_REQUEST index=<i>, where <i> is the position of this element in the array, starting from 0
6 The returned result is too large.

A separate method can return its own error code in its element of the array. Apart from the codes of the method itself, the following codes are possible:

Code Description
2 Wrong method name in the svc parameter.
10 The method isn’t executed. This happens in one of the following cases:
  • one of the previous methods has returned an error and the flags parameter includes the 0x01 (1) flag
  • the request has exceeded the time limit set on the server

Examples

All the examples below send the same two methods: the first one refers to the item with ID 1004, to which the user has no access rights, and the second one gets the properties of the resource with ID 1003. Add the sid parameter with your session identifier to each request.

Executing all the methods despite an error

In the first form, the params parameter contains only the array of methods, so there’s nowhere to specify the flags parameter. All the methods are executed.

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

The second form gives the same result if the value of the flags parameter is 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
}

Response:

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

The error of the first method doesn’t affect the second one.

Stopping the request after the first error

To stop the execution after the first error, use the second form of the request and specify the 0x01 (1) flag. The methods are the same, but now the second one isn’t executed and returns 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
}

Response:

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

If you find a mistake in the text, please select it and press Ctrl+Enter.