Dataset API
This article provides sample API calls used for obtaining a list of Datasets, creating and modifying individual Datasets, as well as obtaining and manipulating their data.
To query Datasets data and metadata, the following Item functions are used:
-
dataset (to fetch metadata, to edit and to apply Access Maps to Datasets)
- available since Version 5.4.0
-
dataset_data (to obtain data from specific Datasets)
- available since Version 5.3.1
-
dataset_instance (to get a list of Dataset Instances)
- available since Version 5.4.0
PREREQUISITES:
To be able to make API calls, you need to obtain an access Token
For more information, see:
Go to Admin > Utilities > API Toolkit > API Test Tool
- Item: from the dropdown, select get_token
-
ID: enter External Application ID
- For details, refer to Set up API Access and Test API Access / Get API Token via MI API Test Tool
- Request: input User Name after "user": in the Request
- Run request: click to get the Token
Since all API calls require a Token, you need to copy the token from the Raw Response field and enter it in the provided Token field.
You can use any of the available Datasets as a model for a new Dataset.
The example provided below shows how create a new Dataset from an existing Dataset.
- Token: enter the Token that you have previously obtained as noted in the PREREQUISITES
- Item: from the dropdown, select dataset
- Methods: choose GET
- Run request: click to get a list of all Datasets and their metadata
Raw response will contain information about Datasets in Metric Insights.
1. Create a new Dataset
- Token: enter the Token that you have previously obtained as noted in the PREREQUISITES
- Item: from the dropdown, select dataset
- Methods: choose POST
-
ID: input the ID of an existing Dataset that you want to use as a model for a new Dataset
- After you input the Dataset ID, the Request field will display the settings for that Dataset
-
Request: type in the name for the new Dataset
- Optionally, you can change the Dataset description, snapshotting options and other settings
- Run request: click to create a new Dataset
Raw response will contain metadata for the new Dataset. The newly created Dataset will be assigned an ID that can be used in subsequent API calls (e.g.: when validating, enabling and updating your Dataset)
2. Modify your Dataset via the API action calls
PUT Method (used in API calls to Metric Insights) supports the following actions:
- Validate
- Delete data
- Get Access Map
- Set Access Map
- Enable
- Update Dataset
2.1. Validate and enable your Dataset
-
Token: enter the Token that you have previously obtained as noted in the PREREQUISITES
- The same Token can be used for a series of subsequent API calls
- Actions: from the dropdown, select the relevant option
-
Request: if you choose to validate, enter the date against which Dataset data will be validated
- measurement_time parameter must be in the following format: year-month-day
- Run request: click to run the API action call
After you validate and enable your Dataset, you can get the Dataset data by following the steps described in Section 4 of this article.
2.2. Update a Dataset
After modifying your Dataset, update the Dataset to make the changes effective.
- Token: enter the Token that you have previously obtained as noted in the PREREQUISITES
- Actions: from the dropdown, select Update Dataset
-
Request: measurement_time can be changed from default
- measurement_time parameter must have the following format: year-month-day
- Run request: click to run the API action call
If the API update call is successful, the "status":"OK" message will be displayed in the Raw response
2.3. Query a Dataset Access Map
Dataset API calls allow you to query the Access (User) Map of any existing Dataset that has an Access (User) Map.
- Token: enter the Token that you have previously obtained as noted in the PREREQUISITES
- Actions: from the dropdown, select Get Access Map
- Run request: click to run the API action call
Raw response will contain the Dataset columns mapped to Access Map columns.
For more information on Access (User) Maps, refer to:
2.4. Apply an Access Map to a Dataset
- Token: enter the Token that you have previously obtained as noted in the PREREQUISITES
- ID: input the ID of a Dataset
-
Actions: choose Set Access Map
- After you input the Dataset ID, the Request field will display Dataset columns that have already been mapped to Access (User) Map columns
- Note: for the Set Access Map action to work, at least one Access (User) Map column should already be mapped to the corresponding Dataset column
-
Request: input additional columns from the Dataset and User Map that will be mapped against one another
- To get a list of all available columns in an Access (User) Map, use the dataset_data item since Acces Maps are treated as Datasets by the system. For more information, check Fetch Dataset Data
- Run request: click to run the API action call
3. Fetch Dataset Data
You can either query all the data contained in that (All Data) View of the Dataset or specify a particular View and/or Time Instance.
3.1. Get data from an "All Data" View
- Token: enter a Token that you have previously obtained as noted in the PREREQUISITES
- Item: select "dataset_data" from the drop-down
- Methods: GET
- ID: must be left blank
- dataset: enter the Dataset ID. Learn how to find your Dataset ID
- Request URL (generated automatically): https://yourcompany.metricinsights.com/api/dataset_data?dataset=<id>
- Run request
3.2. Get data from a Specific View
To see a specific View, additionally enter a View ID. Learn how to find you Dataset View ID.
Request URL (generated automatically): https://yourcompany.metricinsights.com/api/dataset_data?dataset=<id>&view=<id> .
3.3. Get data from a Specific Dataset Instance
In the example below, the data displayed in the Raw Response was pre-filtered for a specific View and Date.
- dataset: required
- View ID: optional
- Measurement_time: type in the date that you need to fetch your information for (only the following format is supported: yyyy-mm-dd). If Dataset is NOT "set to keep history", the "measurement_time" parameter is ignored during the API call. The Raw Response returns data exclusively for the last time the data was collected.
Request URL (generated automatically): https://yourcompany.metricinsights.com/api/dataset_data?dataset=<id>&view=<id>&measurement_time=yyyy-mm-dd .
Dataset ID can be found in the the web browser URL of the Dataset Viewer or Dataset Editor:
https://stg530.metricinsights.com/dataset/index/index/ds/474
Dataset View ID can be found in the the web browser URL of the Dataset Viewer.
https://stg530.metricinsights.com/dataset/index/index/ds/474/filter/211
4. Query all Dataset Instances
- Token: enter a Token that you have previously obtained as noted in the PREREQUISITES
- Item: select "dataset_data" from the drop-down
- Methods: only GET is currently supported
- ID: must be left blank
- dataset: enter the Dataset ID
- Request URL (generated automatically): https://yourcompany.metricinsights.com/api/dataset_data?dataset=<id>
- Run request
Raw response will contain a list of Dataset Instances