Introduction
This document aims to show the usage of the Tech Insights Monitoring Query API when using the queries related to calls, endpoints, systems, meetings and trunks.
These calls are illustrated by means of examples provided as Postman calls - it is assumed that the reader is familiar with Postman before starting. The examples comprise an integral part of this document.
How Postman is Used
The examples are provided, attached to this article, as a Postman Collection and a Postman Environment. The purpose of the environment file is two-fold
- When performing the Authorization function (see How Do I Authenticate to use the Query Service API?) the authorization token is captured as a variable and re-used in all of the subsequent tests. Once the token has expired, all that is necessary is to re-run the authorization step to obtain and store a new token.
- Many of the API calls require time and/or identification parameters. These can either be set in the environment file, or can be obtained from the results of a previous call by highlighting the desired value and right-clicking.
See Using Data Variables for more information
Tech Insights Monitoring API Queries and Responses
Path Parameters
All request parameters are sent as URL path parameters, with the exception of the Authorization query, which is the only query to use the request body (payload).
Query Responses
All responses are returned as JSON documents.
At the head of the actual content, a header section provides information regarding result set size, pagination etc. The values returned are
Query Parameters - options
Queries can be refined with options passed as URL queries.
The common options are:
| Parameter | Description |
|---|---|
|
|
The beginning of a time window for the data |
|
|
The end of the time window |
|
|
The criteria / filter for searching (optional) |
|
|
The page of results (optional, defaults to 0) |
|
|
The number of results per page (optional, defaults to 20) |
|
|
The field and direction for sorting (optional) - asc or desc Multiple sorts can be performed on separate fields, each taking an order |
Other values are specified per-query. All relevant options are documented in the Postman query
Filtering
A filter, when available can be set on any value within a result set - filters may be chained with a semi-colon (;) - the resulting filter is a logical AND of the chain.
The following operators can be used in filters:
| Operator | Description |
|---|---|
|
== |
Equal To |
|
!= |
Not Equal To |
|
=lt= or < |
Less Than |
|
=le= or ⇐ |
Less Than or Equal To |
|
=gt= or > |
Greater Than |
|
=ge= or >= |
Greater Than or Equal To |
As an example, a filter of
target==BlueJeans;quality==GOOD
would return the BlueJeans calls with good quality. A filter of
target==Blue*;quality==GOOD
Will return the same, along with any other calls matching a target beginning Blue
How to Use the Examples
In order to use the examples, first configure the environment with your credentials and organisation ID. If you do not know your organisation ID then please raise a helpdesk ticket and request that Vyopta provide this.
Once configured, run the Authorization query in the Postman Connection - this will set your access token as a variable in the environment. Please note that the token is valid for 300 seconds (5 minutes) only, and the Authorisation step must be repeated in order to obtain a new token.
Setting a windowStart and windowEnd will allow you to perform the initial tests. These values are dates in ISO format - examples are present in the environment file.
It is suggested that you run the examples that interest you - setting any values needed from previous results - for instance, running the Get Calls query to obtain the callID and startTime values needed for Get Call Details.
The Examples And Environment
Each example contains all of the relevant query parameters, with description.
The environment file contains the following values:-
| Variable Name | Meaning |
| vyoptaU | Vyopta Username (name.name@org.tld) |
| vyoptaP | Vyopta password |
| accessToken | The bearer access token used to authenticate all requests. Automatically set by the Authorization query |
| orgID | The Vyopta Organisation ID number corresponding to your organisation. See above. |
| CallID | The callID for a specific call returned by Get Calls |
| callStartTime | The start time of the call specified by CallID. Returned by Get Calls |
| endpointID | The endpoint ID as returned by Get Endpoints |
| peripheralID | A peripheralID as returned by Get Endpoint Details (must be prefixed with one of camera-, display-, mic-, or touchPanel-) |
| windowStart | The beginning of a time window for a query, in ISO format (eg 2020-02-22T23:00:00Z |
| windowEnd | The end of a time window for a query, in ISO format (eg 2020-02-23T10:00:00Z |
| meetingID | A Meeting ID as returned by Get Meetings |
| meetingStartTime | The start time of the call specified by MeetingID - returned by Get Meetings |
Returned results for the examples are described in Tech Insights Monitoring API - Query Responses
The examples provided are as follows:-
| Example Name | Purpose |
| Authorization | A call to the authorization API - stored the access token automatically. This token is used by all other queries. |
| Get Calls | Obtains a list of calls between the times of windowStart and windowEnd |
| Get Call Details | Obtain the details for a specific call |
| Get Call Quality Details | Obtain details information regarding the call quality information available for this call. See Categories and Metrics specification in Postman request to tailor data returned. |
| Get Call Records | Return the call data record information for this call, or a 404 if not found |
| Get Endpoints | Return a list of endpoints |
| Get Endpoints By Status | The endpoint list sorted by the status field, illustrating sorting |
|
Get Endpoint Details |
Return information held for a specific endpoint |
| Delete a Peripheral from an Endpoint | Remove a specified peripheral from an endpoint |
| Get Systems |
Return a list of configured systems |
| Get Systems by Status | The systems list sorted by the status field, illustrating the use of filtering |
| Get Systems With Status Not=OK |
The list of systems filtered to return only those that are not in OK status |
| Get Trunks |
Return a list of configured trunks |
| Get Meetings |
Obtain a list of meetings between windowStart and windowEnd |
| Get Meeting Participants |
Return the list of participants for a specific meeting |
Comments
Please sign in to leave a comment.