Quick Start¶

Getting started with using add Point Value Ingest API involves the following steps:

Create an account and a machine user.
Create a JSON Web Token (JWT) by using the machine user credentials.
Make API requests using the JWT.

Note

In the following examples we are:

1. making use of a Linux/MacOS shell in which environmental variables are
   set using the `export` command. In other environments it may be different,
   e.g. Windows uses the `set` command instead.

2. using the `curl` as a client. But the API can be used in any programming
   language with an HTTP Client, e.g. Go, Python, NodeJS, Javascript and Java.

Create an account and a machine user¶

The Getting Started page documents the required steps to get a hold of the clientId, clientSecret and partitionId.

Create a token¶

Use the values described in the Authorization section to construct the Create Token request.

Example request¶

export CLIENT_ID=<YOUR_CLIENT_ID>
export CLIENT_SECRET=<YOUR_CLIENT_SECRET>

curl https://siemens-bt-015.eu.auth0.com/oauth/token \
  -H 'content-type: application/json' \
  -d "{
            \"client_id\":\"$CLIENT_ID\",
            \"client_secret\":\"$CLIENT_SECRET\",
            \"audience\":\"https://horizon.siemens.com\",
            \"grant_type\":\"client_credentials\"
      }"

To run this example yourself, set the CLIENT_ID and CLIENT_SECRET first.

Example response¶

{
  "access_token": "eyJ0eXAiOiUSJ9.eyJpc3MiOiJdGlhbHMifQ.MJpcxLfyOt",
  "token_type": "Bearer",
  "expires_in": 86400
}

The token, or JWT (JSON Web Token), is the value of the access_token property in the response.You can now use it by passing it in the Authorization header of any subsequent API requests.The expires_in property represents the number of seconds your token is valid, usually, the value corresponds to 24 hours. When this time has elapsed you will need to create a new token.

Now you have all you need to start using the API. As a last step of preparation set the token and partitionId as environmental variables.

export PARTITION=<YOUR_PARTITION_ID>
export TOKEN=<YOUR_TOKEN>

Make API requests¶

This guide will take you through the steps you need to perform to add point values.

Add point values¶

To add point values, the Post values operation can be used.

Push 1 to 100 values for given point in a batch.

Only one pointValue per millisecond will be stored. PointValues are dropped if there are timestamp conflicts, i.e. if a pointValue with the same timestamp already exists. Example with following pointValues:

2022-07-11T11:11:30.333
2022-07-11T11:11:30.222
2022-07-11T11:11:30.333
2022-07-11T11:11:30.444

The first is accepted (it's the first for time "30.333"). The second is also accepted. The third is dropped because it's the same timestamp as the first. The fourth is accepted again. The indices of dropped pointValues are listed in the response (0-based), in this example there is one conflict with index "2".

If there is no conflict status 204 is returned instead of 202.

Note: Use query parameter 'overwrite=true' to force overwriting of conflicting values.

curl -X 'POST' \
  "https://api.bpcloud.siemens.com/ingest/partitions/$PARTITION/points/$POINTID/values" \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d "{
  \"data\": [
    {
      \"type\": \"PointValue\",
      \"attributes\": {
        \"timestamp\": \"2000-05-11T10:32:54.964Z\",
        \"value\": \"12.66\"
      }
    }
  ]
}"

In the response, you will find the values added for the pointId.