Use Case

Use the Bazefield API to programmatically access data stored in Bazefield for advanced analytics and integration purposes.


Background

The Bazefield API is a REST API which enables developers and power users to access data stored in Bazefield for other purposes. Since it is a web-based API, it requires no specific installations on the client machine and is compatible with a wide array of programming languages.


This Quick Start guide is intended to help developers and power users set up their environment and familiarize themselves with the Bazefield API quickly. This guide is not intended as a replacement for the API's full documentation. For more details on API specifics, please see the in-product API documentation located in Bazefield Help > Bazefield Super User Documentation > Bazefield API Developer Guide, as well as the documentation at https://<YourBazefieldSubdomain>.bazefield.com/Bazefield.Services/api. NOTE: The in-product documentation at Bazefield.Services/api is disabled by default -- please contact Bazefield Support to have it enabled.


Prerequisites

This article assumes some prior experience with RESTful APIs and interacting with web services in general, as well as knowledge of how to interact with JSON objects.


Steps


Step 1: Decide how you wish to interact with the Bazefield API


Bazefield supports the OpenAPI 2.0 specification (also known as Swagger), and the Bazefield Swagger specification can be used to automatically generate client libraries for a wide array of programming languages. See [INSERT LINK TO BAZEFIELD SWAGGER QUICK START] for more details.


Alternatively, you can choose not to use a client library and manually compose HTTP requests instead. In this quick start article, we will manually compose web requests.


Depending on the programming language or framework you are using, there may be special considerations.


Step 2: Obtain an API key


To use the Bazefield API, you must authenticate as a particular Bazefield user with a unique API key. You can generate an API key via the Bazefield Portal.

  1. Navigate to the User Manager > Find the user you wish to grant access to > Select "Edit"

  2. Generate an API key for the user on the "API Keys" tab

  3. Use the generated API key to authenticate to Bazefield


Step 3: HTTP Authorization Header


To authenticate, use the Authorization HTTP header with bearer authentication: 

Authorization: "Bearer <YourApiKeyHere>"


Step 4: API functions


A list of API calls is available at https://<YourBazefieldSubdomainHere>.bazefield.com/Bazefield.Services/api/metadata. You can click on the JSON or XML links beside each function to view the structure of the request and response. Functions with the key icon require an API key in order to authenticate.



Table of commonly used functions:


FunctionDescriptionUse Cases
ReadMeasurements

Read last known value and timestamp of a tag(s)

All raw data queries, or live monitoring applications

SubscribeMeasurements

Subscribe to all new live values of a tag(s) in certain sampling rates

Live monitoring applications requiring constant refresh of data
ReadAggregatedTimeSeriesQuery aggregate level data  for a tag(s) for a defined interval

Analytics and historical data queries

GetActiveAlarmsQuery all active alarms

Real time monitoring

GetAlarmLogQuery historical alarmsHistorical analytics
GetAllocationsGet raw allocations from Availability applicationAnalytics of historical downtime events & availability
FindTurbineAllocationStatisticsQuery all lost production, revenue, and statistics for a given allocation type

Historical lost energy analytics

GetSitesReturn all sites in BazefieldMeta-data reporting
FindTurbinesReturn all assets in BazefieldMeta-data reporting
DomainModelsGetRequestReturn all domain models (e.g. turbine models, inverter models, etc)Meta data reporting
FindTurbineModelAlarmsReturn all alarms configured to asset models

Meta data reporting

FindAllocationTypesReturn all allocation systems configuredMeta data reporting


Step 5: API example - Renaming tags in bulk with PowerShell


<#
.Description
This script bulk renames Bazefield tags by replacing $subStringOld with $subStringNew in the tag name.
#>

#region TOP LEVEL PARAMETERS
$customerSubDomain = "" # Supply parameter - your Bazefield subdomain
$apiKey = "" # Supply parameter - your API key
$baseurl = "https://$customerSubDomain.bazefield.com/BazeField.Services/api/"
$GetHeader = @{"Authorization" = "Bearer $apiKey";
            "Accept" = "application/json"}
$PostHeader = @{"Authorization" = "Bearer $apiKey";
            "Accept" = "application/json";
            "Content-Type" = "application/json"}
#endregion TOP LEVEL PARAMETERS

#region TAG RENAMING PARAMETERS
$tagSearchString = "" # Supply parameter - the tag search string, e.g. MySite-MyTurbine-MyTag
$filterNotLike = '' # Optional parameter - additional filter to rule out tags with this substring
$subStringOld = "" # Supply parameter - what substring are you trying to replace?
$subStringNew = "" # Supply parameter - what is the new substring?
$tagSearchString = $tagSearchString.Replace("%", "%25") # Percent encoding of % character required
#endregion TAG RENAMING PARAMETERS


#region GET TAGS
$urlEndpoint = "tags/search"
$urlQuery = "?TagNames=$tagSearchString&take=1000"
$url = $baseurl + $urlEndpoint + $urlQuery

$response = Invoke-WebRequest -Uri $url -Headers $GetHeader -UseBasicParsing -Method GET
If ($response.StatusCode -eq 200) # verify good response
{
    $content = $response | ConvertFrom-Json
}
Else { Write-Host "failed web request $url $($response.StatusCode)"}
$response = $null # reset response

# Remove tags with a NotLike filter
if ($filterNotLike)
{
    $content = $content | where {$_.tagName -notlike "*$filterNotLike*"}
}

# Track tagids you'll be editing
$TagIds = $content.id
#endregion GET TAGS


#region RENAME TAGS
$urlEndpoint = "measurements/metadata/save"
$url = $baseurl + $urlEndpoint

foreach ($tag in $content)
{
    ###INSERT TAG EDITS HERE###
    $tag.tagName = $tag.tagName -replace "$subStringOld", "$subStringNew"

    $PostContent = $tag | ConvertTo-Json # include entire tag config, even unchanged items, when posting
    $response = Invoke-WebRequest -Uri $url -Headers $PostHeader -UseBasicParsing -Body $PostContent -Method POST
    If ($response.StatusCode -ne 200) # verify good response
    {
        Write-Host "failed web request $url $($response.StatusCode)"
        Write-Host $PostContent
    }
    Else {Write-Host "Updated tag $($tag.tagName)" } 
}
$response = $null # reset response
#endregion RENAME TAGS




Product Environment and Version

Bazefield API

Last updated for Bazefield 8.0.14.4