Batch support

Batch enables you to submit multiple related or unrelated requests into a single HTTPS POST and thereby reduce the number of HTTP operations and improve network latency. Individual sub-requests can be independent, or dependent on each other, so you can build relationships between sub-requests, as desired. Because all processing logic is built into a single request, PI Web API can optimize execution. PI Web API supports batching multiple logical REST requests into a single POST HTTP request.

The input is a dictionary with IDs as keys and request objects as values. Each request object specifies the HTTP method, the resource and, optionally, the content and a list of Parent IDs. The list of Parent IDs specifies which other requests must complete before the given request will execute.

The resource can be an absolute URL or a JSONPath that references the response to the parent request. JSONPath is a tool that you use to analyze, transform, and selectively extract data out of Json document. For more information, refer to JSONPath - XPath for JSON.

The following illustration and sample code shows how you can construct the batch request and the batch response you expect. The batch request is a dictionary of HTTP requests that contain an infinite set of keys. The content of each batch request is an HTTP response in which you can specify any method, such as POST, GET, PUT or PATCH. The Resource is a URL stream of the sub-request. If it is a POST request, you can include a string representation of the payload of the POST request (and if it is a GET request you can omit this property). Optionally, you can include a number of headers for the request. The Parameters and the Parent IDs identify relationships between batch requests. The batch response corresponds to the set of keys in the batch request. Each batch response contains a sub-response that contains a status, headers, and content (if any).

Batch request and response structure

Sample batch request

{
"1": {
"Method": "POST",
"Resource": "https://localhost/piwebapi/assetdatabases/D0NxzXSxtlKkGzAaZhKOB-KABJ2buwfWrkye3YhdL2FOUAUEhMQUZTMDRcQgYUUEVSRk9STUFOQ0UgVEVTVElORw/elements",
"Content": "{\"Name\":\"New Element\"}"
},
"2": {
"Method": "GET",
"Resource": "$.1.Headers.Location",
"ParentIds": [
"1"
]
},
"3": {
"Method": "POST",
"Resource": "$.2.Content.Links.Attributes",
"Content": "{\"Name\":\"New Attribute\"}",
"ParentIds": [
"2"
]
},
"4": {
"Method": "GET",
"Resource": "https://localhost/piwebapi/points?path=%5C%5CMyPIServer%5Csinusoid",
},
"5": {
"Method": "GET",
"Resource": "https://localhost/piwebapi/points?path=\\\\MyPIServer\\cdm158",
},
"6": {
"Method": "GET",
"Resource": "https://localhost/piwebapi/streamsets/value?webid={0}&webid={1}",
"Parameters": [
"$.4.Content.WebId",
"$.5.Content.WebId"
],
"ParentIds": [
"4",
"5"
]
},
"7": {
"Method": "GET",
"Resource": "https://localhost/piwebapi/assetdatabases/D0NxzXSxtlKkGzAaZhKOB-KABJ2buwfWrkye3YhdL2FOUAUEhMQUZTMDRcQgYUUEVSRk9STUFOQ0UgVEVTVElORw/elements"
},
"8": {
"Method": "GET",
"RequestTemplate": {
"Resource": "$.7.Content.Items[*].Links.Attributes"
},
"ParentIds": [
"7"
]
}
}

The input is a dictionary with IDs as keys and request objects as values. Each request object specifies the HTTP method and the resource and, optionally, the content and a list of parent IDs. The list of parent IDs specifies which other requests must complete before the given request will be executed. The example first creates an element, then gets the element by the response's Location header, then creates an attribute for the element. The batch's response is a dictionary that uses keys corresponding to those provided in the request, with response objects containing a status code, response headers, and the response body. A request can alternatively specify a request template in place of a resource. In this case, a single JSON path may select multiple tokens, and a separate sub-request will be made from the template for each token. The responses of these sub-requests will be returned as the content of a single outer response.