Exploring Time Series Insights queries with Postman
As with any other service in Microsoft Azure, there are RESTful APIs to interact with. Time Series Insights (TSI) is no exception.
One of the best ways to explore the Azure REST APIs is to use Postman. Postman has been maturing for the past few years and is nowadays used widely to build modern software for the API-first world. Besides the sleek UI allows you to publish, monitor, document, test, but mostly to design and mock APIs.
One of the biggest blocker when using Azure REST APIs is related to authentication, requiring a Bearer Token Authorization header. Read the documentation, has it is extremely relevant when working with any service in Microsoft Azure. However, the documentation doesn’t explain you how to get started quick-and-dirty!
Coming back to TSI, when working on IoT projects we follow the IoT Reference architecture and implement specific scenarios accordingly to the requirements. One of the usual requirements is related to providing an always easily accessible UI for analysis purposes, especially oriented to the operator’s daily needs. TSI offers out-of-the-box a powerful TSI explorer – a UI that corresponds to a managed visualization service for managing IoT-scale time-series data in the cloud.
Yes, it’s the perfect tool factory or power plant operators/advanced users that require granular, free-text query and point & click exploration.
Beyond this, TSI exposes REST Query APIs, enabling you to build applications that use time series data. And this fact makes TSI even more flexible for your needs!
Querying TSI will be one of the first things you’ll try before getting into more advanced topics – such as capacity, managing input data throttling, scaling the environment or even building applications with TSI data.
To use Postman and Azure Rest APIs, let’s start by authentication. By creating an Azure Active Directory Service Principal and using Postman to generate a Bearer Token, we’ll have things ready to start calling the TSI query APIs.
Generally speaking, in Azure, authorization is implemented with Service Principal and application objects and their relationships. Here we’ll configure a default Service Principal. For Production scenarios/applications, you should constrain to specific areas of your Azure resources. I’ll assume you have azure cli installed and ready to run on your Windows/Mac/Linux box. If not, check it here.
First authentication on your Azure subscription:
Just do as you’re told. Head to http://aka.ms/devicelogin and enter the code shown in your shell.
If you’re like me, you’ll have access to several azure subscriptions, so make sure you explicitly pick one:
az account set --subscription "subscription name or id"
Next, we’ll create the default Service Principal
az ad sp create-for-rbac -n "your service principal name"
I always copy the output to a temp location, because we’ll need it later.
For additional information on Azure CLI commands related to Service Principal, just take a look here.
I’ll assume you’ll have Postman installed. If not just check here. For every Azure REST API call, you must provide your client code to authenticate with valid credentials. This is called the access token and represents a proof of the authentication – it is sent to the Azure service in the HTTP Authorization header of any subsequent REST API requests.
In accordance with the OAuth2 Authorization Framework, Azure Platform makes available a platform- and language-neutral OAuth2 service endpoint (OAuth2 /token endpoint), that you use to authenticate your client and acquire an access token. Depending on how you use it, you’ll probably following an OAuth2 authorization grant flow.
Now close (yes, make sure your Postman is closed), and click this button:
You’ll notice your browser popped up with the following screen:
Whether you use postman in your browser or the app, make your pick!
Now, there will be a new collection in Postman, once it opens. It’s called TSI Azure REST and includes a set of calls that will help you tackle authorization for Azure REST API calls. Let’s take a closer look and get familiar with them:
The Get AAD Token Request will POST to https://login.microsoftonline.com/oauth2/token with our Service Principal settings and then, in the “Tests” tab there is a script that will set a Postman Global Variable called azure_bearerToken with the access_token in the response.
The TSI ENVIRONMENTS will GET https://api.timeseries.azure.com/environments?api-version=2016-12-12 with an Authorization header set to the Bearer Token collected with the ‘Get AAD Token’ call.
Like TSI ENVIRONMENTS, the following requests also target the TSI REST API: TSI AVAILABILITY, TSI METADATA, TSI QUERY AGGREGATES and TSI QUERY EVENTS. The purpose of this requests is for you to be able to quickly query your data, changing the queries accordingly to your data. At the end of this post, I leave a brief explanation about these requests.
Because we will be executing several REST requests to TSI REST API, let’s use Postman environments. By clicking Run in Postman an environment was already created for your use. Next step is to set your Service Principal settings in the environment and be used in the requests. Click the gears icon in the upper right-hand corner, and select Manage Environments:
Click on the TSI Azure Rest Environment and you will see all the required settings:
Now, get back to the Service Principal settings info you saved temporarily. Set the values accordingly. Some info may be confusing – but no worries – you should put appID into clientId and password into clientSecret. The rest, as the name implies.
Close all dialogs, and in main Postman screen, check if the TSI Azure REST environment is selected: In the Environment dropdown in the upper right-hand corner of Postman.
OK, all configuration has been done, and we’re ready to execute the requests!
Let’s start by executing the Get AAD Token request. This will provide you your Bearer Token and set it in a Postman global variable. Open the Get AAD Token request and click the Send button.
The expected output should be similar to:
This request has ‘Test’ script setup, and it was executed immediately after the request. The script set the access_token property in the Postman global variable, named azure_bearerToken.
To access data in TSI, it’s necessary to data access policy to Azure Active Directory principals (users or apps). This will allow principals to issue data queries, manipulate reference data in the environment, and share saved queries and perspectives.
In this case, we will provide data access to the Service Principal we created initially. In Azure Portal, add a new Data Access Policy in TSI. When asked for the selected user, place the appID (taken from your notes, when creating the Service Principal).
Now that we have the access token and the correct TSI Data Access policies, we can call any TSI REST API endpoint. To start, we’ll use TSI ENVIRONMENTS request.
Open the TSI ENVIRONMENTS request and click the Send button.
You will see the following output:
Again, this request has ‘Test’ script setup, that will create a new Postman global variable called tsi_environmentFqdn with the first environment FQDN returned.
That’s all there is to it. Now you can explore all the other TSI Azure REST APIs, and use this same method to generate the required Bearer Token Authorization header.
Feel free to provide feedback or ping me if you hit a blocker.
Here, I’ll summarize the rest of TSI queries included in the shared Postman collection:
TSI AVAILABILITY: this request will query TSI for the distribution of event count over the event timestamp $ts. This means you’ll be able to understand the time range of data ingested into TSI. Also, you’ll be able to understand the volume of events in a 1h distribution.
Also notice, that you will be hitting your TSI environment FQDN, through the usage of tsi_environmentFqdn.
The ‘Tests’ tab will execute a script creating the global Postman variables named tsi_range_from and tsi_range_to. These variables will be used in subsequent queries.
TSI METADATA: A request to collect your TSI environment metadata for a given search span. The metadata returned is as a set of property references.
Notice how we’re using tsi_range_from and tsi_range_to in the request body, to define the search span. Feel free to play with your search ranges.
TSI QUERY AGGREGATES will group events by given property with optionally measuring values of other properties.
NOTE: The query used in the request body is an example query taken from the documentation. You should change the query accordingly to your data schema.
TSI QUERY EVENTS: This query will probably be the one you’ll use the most, specially when understanding query patterns. It will return a list of raw events matching the search span and predicate.
NOTE The query used in the request body is an example query taken from the documentation. You should change the query accordingly to your data schema.