1.0 Authentifizierung

Die zevvy API unterstützt die Flows "authorization_code" und "device". Der "device Flow" wird bevorzugt für mobile oder eingebettete Anwendungen verwendet, während der "authorization_code Flow" für Webanwendungen genutzt wird.

Für unsere Anwendung wird normalerweise der "device Flow" verwendet.

Folgende Daten werden für eine erfolgreiche Authentifizierung benötigt:

• client_id
• client_secret

(Wenn Sie noch keine Client ID haben, können Sie uns für die Erstellung der Client ID kontaktieren)

Sie erhalten anschließend eine Antwort mit folgenden Daten:

• device_code
• user_code
• client_secret
• verification_uri
• verification_uri_complete
• interval

Code Beispiel

java python javascript shell php

														import okhttp3.OkHttpClient;
import okhttp3.MediaType;
import okhttp3.RequestBody;
import okhttp3.Request;
import okhttp3.Response;
import java.io.IOException;

public class Main {
    public static void main(String[] args) {
        OkHttpClient client = new OkHttpClient().newBuilder()
          .build();
        MediaType mediaType = MediaType.parse("application/x-www-form-urlencoded");
        RequestBody body = RequestBody.create(mediaType, "client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>&scope=measurement register device offline_access");
        Request request = new Request.Builder()
          .url("https://iam.zevvy.org/realms/zevvy-prod/protocol/openid-connect/auth/device")
          .method("POST", body)
          .addHeader("Content-Type", "application/x-www-form-urlencoded")
          .build();

        try {
            Response response = client.newCall(request).execute();
            System.out.println(response.body().string());
        } catch (IOException e) {
            e.printStackTrace();
        }
    }
}

														                                

													

														import http.client

conn = http.client.HTTPSConnection("iam.zevvy.org")
payload = 'client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>&scope=measurement%20register%20device%20offline_access'
headers = {
  'Content-Type': 'application/x-www-form-urlencoded'
}
conn.request("POST", "/realms/zevvy-prod/protocol/openid-connect/auth/device", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

														                                

													

														var settings = {
  "url": "https://iam.zevvy.org/realms/zevvy-prod/protocol/openid-connect/auth/device",
  "method": "POST",
  "timeout": 0,
  "headers": {
    "Content-Type": "application/x-www-form-urlencoded"
  },
  "data": {
    "client_id": "<CLIENT_ID>",
    "client_secret": "<CLIENT_SECRET>",
    "scope": "measurement register device offline_access"
  }
};

$.ajax(settings).done(function (response) {
  console.log(response);
});

														                                

													

														wget --no-check-certificate --quiet \
  --method POST \
  --timeout=0 \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --body-data 'client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>&scope=measurement%20register%20device%20offline_access' \
   'https://iam.zevvy.org/realms/zevvy-prod/protocol/openid-connect/auth/device'

														                                

													

														<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://iam.zevvy.org/realms/zevvy-prod/protocol/openid-connect/auth/device',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => 'client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>&scope=measurement%20register%20device%20offline_access',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/x-www-form-urlencoded'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;


														                                

													

Antwort

json

1.2 Access Token generieren

Um einen Access Token abzurufen, müssen Sie eine Anfrage mit den folgenden Angaben aus dem vorherigen Request senden:

• device_code
• client_id
• client_secret

Zusätzlich müssen Sie den scope und grant_type angeben.

Hier sind die verfügbaren Scopes:

• offline_access: Erforderlich, damit das Aktualisierungstoken eine längere Gültigkeitsdauer für den langfristigen Gebrauch hat.
• measurement: Erforderlich zur Verwaltung von Messungen.
• register: Erforderlich zur Verwaltung von Registern.
• device: Erforderlich zur Verwaltung von Geräten.

Stellen Sie sicher, dass Sie diese Angaben in Ihrer Anfrage korrekt übermitteln, um einen gültigen Access Token zu erhalten.

Code Beispiel

java python javascript shell php

														import okhttp3.OkHttpClient;
import okhttp3.MediaType;
import okhttp3.RequestBody;
import okhttp3.Request;
import okhttp3.Response;

public class Main {
    public static void main(String[] args) {
		OkHttpClient client = new OkHttpClient().newBuilder()
		.build();
		MediaType mediaType = MediaType.parse("application/x-www-form-urlencoded");
		RequestBody body = RequestBody.create(mediaType, "client_id=<CLIENT_ID>&grant_type=urn:ietf:params:oauth:grant-type:device_code&client_secret=<CLIENT_SECRET>&device_code=<DEVICE_CODE>&scope=measurement register device offline_access");
		Request request = new Request.Builder()
			.url("https://iam.zevvy.org/realms/zevvy-prod/protocol/openid-connect/token")
			.method("POST", body)
			.addHeader("Content-Type", "application/x-www-form-urlencoded")
			.addHeader("Cookie", "AWSALB=k/cVRilmdofo5OtWeHNok/wUnw6bThROPdmBlVGb6bixazTswvLUEHyPwBW7JryCpAfiCzZ6QFWEIDCsyM0bnj7W+dGoVPtBZL0PHdIEd9OH6EDuycxA+f2Pubx5; AWSALBCORS=k/cVRilmdofo5OtWeHNok/wUnw6bThROPdmBlVGb6bixazTswvLUEHyPwBW7JryCpAfiCzZ6QFWEIDCsyM0bnj7W+dGoVPtBZL0PHdIEd9OH6EDuycxA+f2Pubx5")
			.build();

		try {
            Response response = client.newCall(request).execute();
            System.out.println(response.body().string());
        } catch (IOException e) {
            e.printStackTrace();
        }
    }
}

														                                

													

														import http.client

conn = http.client.HTTPSConnection("iam.zevvy.org")
payload = 'client_id=<CLIENT_ID>&grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code&client_secret=<CLIENT_SECRET>&device_code=<DEVICE_CODE>&scope=measurement%20register%20device%20offline_access'
headers = {
  'Content-Type': 'application/x-www-form-urlencoded'
}
conn.request("POST", "/realms/zevvy-prod/protocol/openid-connect/token", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

														                                

													

														var settings = {
  "url": "https://iam.zevvy.org/realms/zevvy-prod/protocol/openid-connect/token",
  "method": "POST",
  "timeout": 0,
  "headers": {
    "Content-Type": "application/x-www-form-urlencoded",
    "Cookie": "AWSALB=k/cVRilmdofo5OtWeHNok/wUnw6bThROPdmBlVGb6bixazTswvLUEHyPwBW7JryCpAfiCzZ6QFWEIDCsyM0bnj7W+dGoVPtBZL0PHdIEd9OH6EDuycxA+f2Pubx5; AWSALBCORS=k/cVRilmdofo5OtWeHNok/wUnw6bThROPdmBlVGb6bixazTswvLUEHyPwBW7JryCpAfiCzZ6QFWEIDCsyM0bnj7W+dGoVPtBZL0PHdIEd9OH6EDuycxA+f2Pubx5"
  },
  "data": {
    "client_id": "<CLIENT_ID>",
    "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
    "client_secret": "<CLIENT_SECRET>",
    "device_code": "<DEVICE_CODE>",
    "scope": "measurement register device offline_access"
  }
};

$.ajax(settings).done(function (response) {
  console.log(response);
});

														                                

													

														wget --no-check-certificate --quiet \
  --method POST \
  --timeout=0 \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --body-data 'client_id=<CLIENT_ID>&grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code&client_secret=<CLIENT_SECRET>&device_code=<DEVICE_CODE>&scope=measurement%20register%20device%20offline_access' \
   'https://iam.zevvy.org/realms/zevvy-prod/protocol/openid-connect/token'

														                                

													

														<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://iam.zevvy.org/realms/zevvy-prod/protocol/openid-connect/token',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => 'client_id=<CLIENT_ID>&grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code&client_secret=<CLIENT_SECRET>&device_code=<DEVICE_CODE>&scope=measurement%20register%20device%20offline_access',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/x-www-form-urlencoded'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;


														                                

													

Antwort

json

2.0 Gerät in zevvy erstellen

Mit dem Token vom vorherigen Schritt (<LONG_ACCESS_TOKEN>) kann die API nun genutzt werden, um zum Beispiel ein Gerät zu erstellen.

Dabei müssen lediglich folgende Daten an den Endpunkt gesendet werden:

• Access Token
• Name
• Referenz (optional)

Bitte darauf achten, dass der Access Token im Header untergebracht ist und der Name (Name) sowie die Referenz (Reference) als JSON im Body mitgesendet werden sollen.

Code Beispiel

java python javascript shell php

														import okhttp3.OkHttpClient;
import okhttp3.MediaType;
import okhttp3.RequestBody;
import okhttp3.Request;
import okhttp3.Response;

public class Main {
    public static void main(String[] args) {
		OkHttpClient client = new OkHttpClient().newBuilder()
		.build();
		MediaType mediaType = MediaType.parse("application/json");
		RequestBody body = RequestBody.create(mediaType, "{\r\n    \"name\": \"Mein neues Gerät\",\r\n    \"reference\": \"reference_001\"\r\n}");
		Request request = new Request.Builder()
			.url("https://api.zevvy.org/devices")
			.method("POST", body)
			.addHeader("Content-Type", "application/json")
			.addHeader("Authorization", "Bearer <LONG_ACCESS_TOKEN>")
			.build();

		try {
            Response response = client.newCall(request).execute();
            System.out.println(response.body().string());
        } catch (IOException e) {
            e.printStackTrace();
        }
    }
}

														                                

													

														import http.client
import json

conn = http.client.HTTPSConnection("api.zevvy.org")
payload = json.dumps({
  "name": "Mein neues Gerät",
  "reference": "reference_001"
})
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer <LONG_ACCESS_TOKEN>'
}
conn.request("POST", "/devices", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

														                                

													

														var settings = {
  "url": "https://api.zevvy.org/devices",
  "method": "POST",
  "timeout": 0,
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "Bearer <LONG_ACCESS_TOKEN>"
  },
  "data": JSON.stringify({
    "name": "Mein neues Gerät",
    "reference": "reference_001"
  }),
};

$.ajax(settings).done(function (response) {
  console.log(response);
});

														                                

													

														wget --no-check-certificate --quiet \
  --method POST \
  --timeout=0 \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <LONG_ACCESS_TOKEN>' \
  --body-data '{
    "name": "Mein neues Gerät",
    "reference": "reference_001"
}' \
   'https://api.zevvy.org/devices'

														                                

													

														<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.zevvy.org/devices',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
    "name": "Mein neues Gerät",
    "reference": "reference_001"
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Authorization: Bearer <LONG_ACCESS_TOKEN>',
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;


														                                

													

Antwort

json

3.0 Beispiel: Ladestation mit 15min Werte

Im vorherigen Beispiel haben wir angeschaut, wie man einzelne Geräte in Zevvy per API eröffnen kann. Bei grossen Datenmengen ist es aber von Vorteil, wenn die Geräte nicht mit einzelnen API-Verbindungen erstellt werden müssen.

Unsere API erkennt automatisch, ob ein Gerät oder Register existiert oder nicht. Falls nicht, wird das Gerät oder das Register automatisch erstellt.

Dazu verwenden wir den "_bulk_create" Endpunkt.

Dabei wird folgendes benötigt:

• deviceName
• registerName

Im Beispiel verwenden wir folgende Werte:

deviceName: Zevvy Test Gerät Beispiel Ladestation
registerName: Zevvy Test Register Beispiel Ladestation

Da das Gerät und das Register noch nicht existieren, wird die API beide automatisch erstellen und die dazu gesendeten Daten importieren.

Nach dem Import können die Geräte sowie Register in Zevvy angeschaut werden und einem Messpunkt zugeteilt werden. (Siehe Video)

Code Beispiel

java python javascript shell php

														import okhttp3.OkHttpClient;
import okhttp3.MediaType;
import okhttp3.RequestBody;
import okhttp3.Request;
import okhttp3.Response;

public class Main {
    public static void main(String[] args) {
		OkHttpClient client = new OkHttpClient().newBuilder()
		.build();
		MediaType mediaType = MediaType.parse("application/json");
		RequestBody body = RequestBody.create(mediaType, "[\r\n   {\r\n     \"value\": 690.0,\r\n     \"readAt\": \"2023-05-30T04:00:00\"\r\n   },\r\n   {\r\n     \"value\": 691.2,\r\n     \"readAt\": \"2023-05-30T04:15:00\"\r\n   },\r\n   {\r\n     \"value\": 691.5,\r\n     \"readAt\": \"2023-05-30T04:30:00\"\r\n   },\r\n   {\r\n     \"value\": 691.6,\r\n     \"readAt\": \"2023-05-30T04:45:00\"\r\n   },\r\n   {\r\n     \"value\": 691.6,\r\n     \"readAt\": \"2023-05-30T05:00:00\"\r\n   },\r\n   {\r\n     \"value\": 691.7,\r\n     \"readAt\": \"2023-05-30T05:15:00\"\r\n   }\r\n  ]");
		Request request = new Request.Builder()
			.url("https://api.zevvy.org/deviceRef/{deviceReference}/registerRef/{registerReference}/measurements/_bulk_create")
			.method("POST", body)
			.addHeader("Content-Type", "application/json")
			.build();

		try {
            Response response = client.newCall(request).execute();
            System.out.println(response.body().string());
        } catch (IOException e) {
            e.printStackTrace();
        }
    }
}

														                                

													

														import http.client
import json

conn = http.client.HTTPSConnection("api.zevvy.org")
payload = json.dumps([
  {
    "value": 690,
    "readAt": "2023-05-30T04:00:00"
  },
  {
    "value": 691.2,
    "readAt": "2023-05-30T04:15:00"
  },
  {
    "value": 691.5,
    "readAt": "2023-05-30T04:30:00"
  },
  {
    "value": 691.6,
    "readAt": "2023-05-30T04:45:00"
  },
  {
    "value": 691.6,
    "readAt": "2023-05-30T05:00:00"
  },
  {
    "value": 691.7,
    "readAt": "2023-05-30T05:15:00"
  }
])
headers = {
  'Content-Type': 'application/json',
}
conn.request("POST", "/deviceRef/{deviceReference}/registerRef/{registerReference}/measurements/_bulk_create", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

														                                

													

														var settings = {
  "url": "https://api.zevvy.org/deviceRef/{deviceReference}/registerRef/{registerReference}/measurements/_bulk_create",
  "method": "POST",
  "timeout": 0,
  "headers": {
    "Content-Type": "application/json",
  },
  "data": JSON.stringify([
    {
      "value": 690,
      "readAt": "2023-05-30T04:00:00"
    },
    {
      "value": 691.2,
      "readAt": "2023-05-30T04:15:00"
    },
    {
      "value": 691.5,
      "readAt": "2023-05-30T04:30:00"
    },
    {
      "value": 691.6,
      "readAt": "2023-05-30T04:45:00"
    },
    {
      "value": 691.6,
      "readAt": "2023-05-30T05:00:00"
    },
    {
      "value": 691.7,
      "readAt": "2023-05-30T05:15:00"
    }
  ]),
};

$.ajax(settings).done(function (response) {
  console.log(response);
});

														                                

													

														wget --no-check-certificate --quiet \
  --method POST \
  --timeout=0 \
  --header 'Content-Type: application/json' \
  --body-data '[
   {
     "value": 690.0,
     "readAt": "2023-05-30T04:00:00"
   },
   {
     "value": 691.2,
     "readAt": "2023-05-30T04:15:00"
   },
   {
     "value": 691.5,
     "readAt": "2023-05-30T04:30:00"
   },
   {
     "value": 691.6,
     "readAt": "2023-05-30T04:45:00"
   },
   {
     "value": 691.6,
     "readAt": "2023-05-30T05:00:00"
   },
   {
     "value": 691.7,
     "readAt": "2023-05-30T05:15:00"
   }
  ]' \
   'https://api.zevvy.org/deviceRef/{deviceReference}/registerRef/{registerReference}/measurements/_bulk_create'

														                                

													

														<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.zevvy.org/deviceRef/{deviceReference}/registerRef/{registerReference}/measurements/_bulk_create',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'[
   {
     "value": 690.0,
     "readAt": "2023-05-30T04:00:00"
   },
   {
     "value": 691.2,
     "readAt": "2023-05-30T04:15:00"
   },
   {
     "value": 691.5,
     "readAt": "2023-05-30T04:30:00"
   },
   {
     "value": 691.6,
     "readAt": "2023-05-30T04:45:00"
   },
   {
     "value": 691.6,
     "readAt": "2023-05-30T05:00:00"
   },
   {
     "value": 691.7,
     "readAt": "2023-05-30T05:15:00"
   }
  ]',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;


														                                

													

Antwort

json

1.0 Authentifizierung

Code Beispiel

Antwort

1.2 Access Token generieren

Code Beispiel

Antwort

2.0 Gerät in zevvy erstellen

Code Beispiel

Antwort

3.0 Beispiel: Ladestation mit 15min Werte

Code Beispiel

Antwort

API Feedback

Software

Help Center

Abrechnungen

Über Uns

1.0 Authentifizierung

Code Beispiel

Antwort

1.2 Access Token generieren

Code Beispiel

Antwort

2.0 Gerät in zevvy erstellen

Code Beispiel

Antwort

3.0 Beispiel: Ladestation mit 15min Werte

Code Beispiel

Antwort

API Feedback

Newsletter

Cookie Einstellungen