Getting started¶

Authenticate and access an HTTP API¶

To access the Bühler Insights APIs you need a OAuth Client ID and Client Secret which is provided by the Bühler Insights support.

First, you need to request an access token from the OAuth server. The following example is using cURL to retrieve an access token:

curl -X POST \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&scope=https://buhlergroup.onmicrosoft.com/35046ed1-76e6-4dcd-a430-fa2ed6c23faf/.default" \
     https://login.microsoftonline.com/ec64c433-1ee8-4dbd-837a-39f56c7cdcea/oauth2/v2.0/token

The HTTP request will respond with a JSON payload with the following contents:

{
    "token_type": "Bearer",
    "expires_in": 3600,
    "access_token": "YOUR_ACCESS_TOKEN"
}

The access token can now be used to access the Bühler Insights APIs. The available APIs, their parameters and request payloads are documented on the api-reference page. You can use the retrieved access token directly on this documentation site by clicking on the "Authorize" button on the top right.

For more details about the authentication, check the authentication page.

Query telemetry from Bühler Insights¶

The Bühler Insights Platform stores telemetry data from Bühler equipment and processes. This mostly temporal data is organized in data points with a data point name, timestamp, and value. The data is physically separated by customer and not by plant, which is the reason the plant ID should be specified in the query to avoid name conflicts over multiple plants. There is also additional metadata (dimensions) in the data metadata and message metadata, which can be used to filter and aggregate the data.

There are two main tables available for querying:

1. States: Telemetry timeseries data, which contains time-stamped data points for various parameters.
2. Events: Alarms organized as events in time, which store information about specific incidents or occurrences.

The following example shows how to query telemetry data in the production environment (please find the URLs for other environments on the api-reference page):

curl -X POST \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -d '{
       "query": "States | take 1 | project DeviceId",
       "startTime": "2023-01-01T00:00:00.000Z",
       "endTime": "2023-01-02T00:00:00.000Z"
     }' \
     https://api.buhlergroup.io/insights/v1/telemetry/query/table

In this example, the sample query retrieves the DeviceId of the first data point in the "States" table within the specified time range.

The following extended example shows how to query telemetry data for a certain plant:

{
   "query": "States | take 1 | project DeviceId, Name, Timestamp, Value, PlantId",
   "startTime": "2023-09-05T00:00:00.000Z",
   "endTime": "2023-09-05T00:00:00.000Z",
   "plantIds": ["9800000019"]
}

The response will be in JSON format and may include columns such as DeviceId, Timestamp, and Value (as specified in the query).

{
    "data": {
        "columns": [
            {
                "name": "DeviceId",
                "columnType": "string",
                "dataType": "String"
            },
            {
                "name": "Name",
                "columnType": "string",
                "dataType": "String"
            },
            {
                "name": "Timestamp",
                "columnType": "datetime",
                "dataType": "DateTime"
            },
            {
                "name": "Value",
                "columnType": "dynamic",
                "dataType": "Object"
            },
            {
                "name": "PlantId",
                "columnType": "string",
                "dataType": "String"
            }
        ],
        "rows": [
            [
                "980000001901",
                "MillerPlantUSMachine.Temperature",
                "2023-09-05T00:00:00Z",
                11.0,
                "9800000019"
            ]
        ]
    }
}

The columns field contains the column names and data types. The rows field contains the data points.

To customize the query, you can modify the query string to retrieve specific data points, filter by plant ID, or use metadata for filtering and aggregation. For example, you can change the "States" table to the "Events" table, adjust the time range, or add filters based on plant ID or other metadata.

For further information and examples, check out the documentation for the query api.

Further information¶

Limits
Versioning
API Reference v1
API Reference v0

{"environments":[],"pdf-download":true}