batch

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

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

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:

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

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

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

[
  { /* 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.

If the flags parameter includes the 0x02 (2) flag, the following limits apply to the request. The values in the table are the default ones; the server can use other values.

If one of the size limits is exceeded, the methods that follow aren’t executed and aren’t included in the response, so the array can contain fewer elements than the request. If the element with the error doesn’t fit into the response either, the array ends with the last element that fits.

The request itself can return the following error codes:

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:

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.

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.

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.

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:

[
  {
    "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.

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.

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:

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