Now that we've done some basic standalone requests
let's work on making some more complex requests using the batch controller.
The batch controller much like the name implies allows us to batch together multiple
requests and execute multiple sub requests at once using a single message. The batch
controller even allows us to reduce the response of one sub request in another sub
request that's part of the same message. At this point you may be wondering why we
have this controller. Well by grouping these requests together we can reduce
the number of HTTP requests that need to go over the network and thus reduce the
latency which can increase the performance the application querying the PI Web API.
One important thing to note is that all of the sub requests of a batch request are handled
internally by the PI Web API service and don't return to the client application until all sub
requests have completed. The response is then returned in a single large response message.
We'll talk about some of the batch controller advantages more in depth in the performance
section of this course. Let's start with a simple example of making a single sub request
in a request to the batch controller the PI Web API home page. This may be a bit of a trivial
example but it will get us started looking at the formatting of batch requests. If we take
a look at the batch request controller in the help files we see that we need to post to the
batch controller. The batch controller end point will always be the base URL followed
by PI Web API slash batch. So let's make that HTTP verb request change in fiddler.
Batch requests have a body which is in JSON format. This is the content that we post to
the batch controller endpoint. Next we'll add a body to the request. All batch sub requests are
specified in the body of the request. We'll also need to add the HTTP content type of application
slash JSON to let the PI Web API know what format to expect the body of the request in.
So let's start off the request body with an open and closed bracket to wrap our request
in. This is our top level JSON element. Next we'll add an ID that we can use to
differentiate each of the sub requests and the corresponding sub responses.
Let's make this a useful ID for identifying the sub requests like get home page. I like to give
IDs that have a meaningful name to them so it's easier to identify exactly what each sub request
is doing. Then we'll create a JSON object. This JSON object will be the sub request,
we define the object by putting a colon after the name of the object and then another set of double
brackets so we can specify the sub request object. The sub request must have at least two parts:
an HTTP verb such as get, post, patch, put and a resource which will be the URL that we're making
the request to. We have the option of other properties that we can put in the request
such as headers or content properties if we need to have that body it to our sub request. In our
case we want to use the get method and our URL is going to be the landing page of the PI Web API.
If we go ahead and send this we see that we get a response back. We have a top level batch
response and a sub response contained within those brackets whose ID matches up with our ID for the
sub request. One important thing I'd like to note is the use of the 207 HTTP response code multi
status in the parent response. This means that each of the individual sub responses will have
their own HTTP status code. For this we see our one sub response has an HTTP status code of 200,
so it's important to check each of the individual HTTP status codes when making batch requests. It
also has some headers which tell us the content is JSON and the content length.
We see the content has the same response, the same links, if we run the request for
the landing page on its own. So now what I'm going to do is add another sub request to this
request to the batch controller. In this case what I'm going to be doing now is retrieving
the home page as well as creating a new element. Again we want to give this a uniquely identifying
name since we're going to be creating an element we'll be using a method of post.
In order to find the resource we'll need to find the web ID
of the database since we need to create an element on a particular database.
Now if we want to make a sub request that as a post for example in this case creating a new
element then we need to use the content field, content property is always expecting a string,
keep in mind that this is the body of the sub request so we'll take an example post and wrap
everything in quotes. Because this is expecting a string and because the content still needs to
have quotes in it we'll need to use back slashes to escape the quotes within our content. I'll
also need to add the slash elements endpoint. If we execute this request we see that we have
a 201 response for created on our element and we still have the get home page sub request as
well. Since this method that we use didn't have any content we see that the content is null.
We covered a lot of material in this video so let's take a quick moment to summarize. In this
video we introduced the batch controller, a powerful tool that allows us to send multiple
requests in a single message. We demonstrated that the batch controller requests are HTTP
POST requests and these requests require a specially formatted request body. This
request body is in JSON format and must be encased in curly braces. Each individual
request must have a uniquely identifying name, it must have an HTTP method whether that be get,
post, delete or something else and it must have a resource or URL to make the sub request against.
We also showed an example of a request that had more than the bare minimum fields to post a new
element. We note the use of back slashes to escape the quotes in our content field. Additionally we
showed that each individual sub request and sub response are linked by their uniquely identifying
ID. We've only just scratched the surface of the batch controller's capabilities, so please ensure
you're comfortable with this batch controller content before moving on to the next topic.