Query assets

A workspace in Veracity Data Workbench functions both as a repository for operational data related to assets and as the access control boundary. Hence, to access asset information you must be member of the workspace in Data Workbench in which the asset instance is associated.

Before you start

Before you call the MMS Query API, make sure you have:

• Access to the Data Workbench workspace that contains the asset data you want to query.
• A service account created in API management and the following values you can get from it:
  • The service account client ID.
  • The service account secret.
  • An API subscription key.
• Your tenant alias.

The tenant alias is the path segment used in your Data Workbench URL, for example: https://dw.veracity.com/{tenant-alias}/ws/{workspace-id}

If you call the API from Databricks, store these values as Databricks secrets instead of hardcoding them in notebooks.

API

Explore the API.

Each request is within a tenant, and the tenant is part of the query path. In each example, replace {_tenant_} with your tenant alias.

Base URL for this API is:

https://api.veracity.com/veracity/mms/query

Each request must include the following headers:

Authorization: Bearer {access_token}
Ocp-Apim-Subscription-Key: {api_key}
Content-Type: application/json

Check details on the authentication page.

List systems

Use this endpoint to retrieve a paginated list of systems available to your service account:

GET: {baseurl}/{_tenant_}/api/v1/systems

This endpoint is useful when you need to discover which systems you can access and find the id value to use in later API calls.

Example:

{baseurl}/{_tenant_}/api/v1/systems?top=50

Field	Description
id	Internal system ID. Use this value as systemId in other API calls.
name	Human-readable system name.
externalId	Optional external identifier.
modelType	Model type, for example WindTurbine or SolarPanel.
technology	Technology category, for example wind or solar.
isRoot	Indicates whether this is a top-level system in the hierarchy.

Get asset by id

Retrieve one asset/system by ID:

GET: {baseurl}/{_tenant_}/api/v1/systems/{systemId}

Use the id value returned by the list systems endpoint as systemId. In some workflows, you may also have an external identifier from a source system or analytical dataset. If the identifier is valid for your environment, you can use it directly.

Get portfolios

Get root assets in portfolios

Get root assets by workspace id

Search for assets

You can search for asset models using metadata as criteria with OData queries. You can combine search criteria and decide which metadata to return in order to reduce the response.

GET: {baseurl}/{_tenant_}/api/v1/odata/systems

Use the /systems endpoint when you want to list and inspect systems available to your service account.

Use the /odata/systems endpoint when you need more precise query control, for example to:

• Filter by metadata such as capacity or location.
• Select only specific fields.
• Limit the number of returned results.
• Build more complex search conditions.

The /systems endpoint uses parameters such as top. The OData endpoint uses OData parameters such as $top, $filter, and $select. Do not mix these query styles in the same request.

ODATA system query option	Description
$filter	To add a filter to an OData URI, add $filter= to the end of the name of the published web service. See filter supported
$select	To request a specific subset of properties (columns/fields) for each entity in the response, rather than all available properties.
$orderby	specifies a custom sort order for search results.
$top	used to limit the number of entries returned in a collection
$skip	requests the number of items in the queried collection that are to be skipped and not included in the result

Example

This example returns all asset models (user has access to) with Capacity AC greater than 70 and where City contains 'EL'. In addition the metadata in the response is reduced to only list SiteName, SiteId, City, Latitude and CapacityAC

{baseurl}/{_tenant_}/api/v1/odata/systems?$filter=CapacityAC gt 70 and contains(City, 'El')&$select=SiteName, SiteId, City, Latitude, CapacityAC

NOTE: There should be no space between ?$filter= and &$select=. Avoid adding spaces inside the query string.

Filter Operator	Description	Example
eq	Equal	$filter=Altitude eq 385
ne	Not Equal	$filter=CapacityAC ne 900
gt	Greater than	$filter=CapacityAC gt 900
ge	Greater than or equal	$filter=CapacityAC ge 900
lt	Less than	$filter=CapacityAC lt 900
le	Less than or equal	$filter=CapacityAC le 900
and	Logical and	$filter=Altitude gt 700 and contains(City, 'El')&$select=Altitude, City, Latitude, CapacityAC
or	Logical or	$filter=Altitude gt 700 or contains(City, 'El')&$select=Altitude, City, Latitude, CapacityAC
not	Logical not	$filter=not contains(City, 'El')
contains	string contains	$filter=contains(City, 'El')
endswith	string ends with	$filter=endswith(City, 'KO')
startswith	string starts with	$filter=startswith(City, 'El')

Troubleshooting

401 Unauthorized

This usually means that the access token is missing, invalid, or expired. Check that:

• The request includes the Authorization: Bearer {access_token} header.
• The service account client ID and secret are correct.
• The token request parameters are correct.
• The service account secret has not expired.

403 Forbidden

This usually means that the request is authenticated, but access is not allowed. Check that:

• The request includes a valid Ocp-Apim-Subscription-Key header.
• The service account has access to the workspace data you are trying to query.
• The service account was created with the required API Management permissions.

404 Not Found

Check that:

• The tenant alias is correct.
• The asset/system ID is correct.
• The asset/system is available to your service account.

Empty or unexpected results

Check that:

• The selected field names exist for the assets you are querying.
• The filter expression is valid.
• The service account has access to the assets you are querying.

GraphQL

GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more.

GraphQL in Veracity Asset Model is based on "Hot Chocolate" - an open-source GraphQL server for the Microsoft .NET platform that is compliant with the newest GraphQL October 2021 spec + Drafts. Hot Chocolate is compatible to all GraphQL compliant clients like Strawberry Shake, Relay, Apollo Client, and various other GraphQL clients and tools.

The GraphQL endpoint uses the same authentication as the REST API.

Veracity Asset Model only supports queries in GraphQL, not mutations.