Erste Schritte

Einführung


Dieses Tutorial macht dich in wenigen kurzen Schritten mit den Grundlagen vertraut und schafft die Basis für den Zugriff auf die Viessmann APIs. Ganz gleich, ob du selbstständiger Entwickler bist oder für ein großes Unternehmen arbeitest, wir stellen die richtigen Werkzeuge zur Verfügung.

Voraussetzungen


Jeder Endpunkt der Viessmann API erfordert eine Authentifizierung mit einem Zugriffstoken. Ein solches Token erhälst du durch Befolgen des OAuth 2.0-Verfahrens, d. h. du musst zunächst einen neuen OAuth 2.0-Client unter Angabe des gewünschten Namens und einer Liste von Redirect-URIs registrieren.

Wenn du mit OAuth nicht vertraut bist, registriere den Client mit einer beliebigen gültigen URI als Redirect URI. Für dieses Tutorial sind keine Kenntnisse über OAuth erforderlich. Es wird relevant, wenn du eine Anwendung erstellen möchtest, die auf benutzerzentrierte Funktionen unserer API zugreift. Dies würde jedoch den Rahmen dieses Tutorials überschreiten.

Aus Sicherheitsgründen verwenden wir das Autorisierungscode Verfahren mit PKCE (Proof Key for Code Exchange). Außerdem ist das Authentifizierungs Formular unserer IAM Plattform mit Google reCAPTCHA gegen Missbrauch geschützt.

In diesem Tutorial stellen wir alle HTTP-Anfragen als cURL-Befehle dar, auch wenn einige aufgrund unserer Captcha-Validierung nur über den Browser ausgeführt werden können.

Weitere Informationen zur Autorisierung findest du im Abschnitt Authentifizierung.

Zugriffstoken erhalten


Nachdem du deinen Client erstellt hast, können wir mit dem Verfahren zum Anfordern eines Zugriffstokens beginnen. Wir werden folgende Beispieldaten verwenden:

username: User123
password: Secret123
redirect uri(s): "http://my-website.com/oauth-callback"
client id: my_oauth_client_id

Um unser Token zu erhalten, müssen wir zwei Anfragen auf unserer IAM-Plattform mit mehreren Parametern durchführen:

  • client_id
  • redirect_uri
  • response_type (= code)
  • code_challenge / code_verifier
  • scope (= Iot User)

Die erste Anfrage muss über den Browser erfolgen, da der aufgerufene Endpunkt mit einem Captcha geschützt ist. Anstatt also einen cURL-Befehl in deinem Terminal abzugeben (oder ein Tool wie Postman zu verwenden), musst du einen Browser mit der folgenden URL öffnen und dich dann mit deinem Account anmelden (in einem realen Szenario würde deine Anwendung den Benutzer zu dieser URL umleiten):

HTTP
https://iam.viessmann.com/idp/v2/authorize?client_id=my_oauth_client_id&redirect_uri=http://my-website.com/oauth-callback&response_type=code&code_challenge=2e21faa1-db2c-4d0b-a10f-575fd372bc8c-575fd372bc8c&scope=IoT%20User

zur Vollständigkeit auch als cURL-Befehl dargestellt:

curl Befehl
curl -X POST "https://iam.viessmann.com/idp/v2/authorize?
client_id=my_oauth_client_id
&redirect_uri=http://my-website.com/oauth-callback
&response_type=code
&code_challenge=2e21faa1-db2c-4d0b-a10f-575fd372bc8c-575fd372bc8c
&scope=IoT%20User"

Stelle sicher, dass du die rot hervorgehobenen Werte durch die deines oAuth Clients ersetzt.

code_challenge bzw. code_verifier ist, einfach gesagt, eine zufällige Zeichenfolge, die in beiden Anfragen gleich sein muss. Er wird in unserem Abschnitt Authentifizierung ausführlicher behandelt. In diesem Tutorial kannst du einfach den oben angegebenen Wert verwenden.

Die HTTP-Antwort, die du erhälst, hat den Statuscode 302 und enthält eine Umleitung zur Redirect-URI mit dem Autorisierungscode (dein Browser wird dich wahrscheinlich direkt weiterleiten):

HTTP
HTTP/1.1 302 FOUND
Location: http://my-website.com/oauth-callback/?code=m0wqM4ksQ7w3OnarOqjW2iDrO7e7Capn5dSlQL6aUZ4
Content-Type: text/html

<HTML>
<TITLE>302 Found</TITLE>
<H1>Found</H1>
The document has moved
<A HREF="http://my-website.com/oauth-callback/?code=m0wqM4ksQ7w3OnarOqjW2iDrO7e7Capn5dSlQL6aUZ4"
>here</A>.
</BODY></HTML>

Im zweiten Request benutzen wir diesen Code um letztlich unser Zugriffstoken zu bekommen:

curl Befehl
curl -X POST "https://iam.viessmann.com/idp/v2/token" 
--header "Content-Type: application/x-www-form-urlencoded" 
--data-urlencode "grant_type=authorization_code" 
--data-urlencode "code_verifier=2e21faa1-db2c-4d0b-a10f-575fd372bc8c-575fd372bc8c" 
--data-urlencode "client_id=my_oauth_client_id" 
--data-urlencode "redirect_uri=http://my-website.com/oauth-callback" 
--data-urlencode "code=m0wqM4ksQ7w3OnarOqjW2iDrO7e7Capn5dSlQL6aUZ4"

Die HTTP-Antwort, die du erhälst, hat den Statuscode 200 OK und enthält das Zugriffstoken im JSON-Format:

HTTP
HTTP/1.1 200 OK
Content-Type: application/json

{
    "access_token": "eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAtMjU...",
    "token_type": "Bearer",
    "expires_in": 3600
}

Jetzt kannst du das Token benutzen, um Abfragen an unsere API zu stellen.

Abfrage der API


Du hast erfolgreich ein Zugriffstoken angefordert. Höchste Zeit, damit einen Beispielaufruf an unsere Plattform API durchzuführen. Wie eingangs erwähnt, musst du bei einem API-Aufruf immer das Zugriffstoken im HTTP-Autorisierungs-Header als Bearer Token mitsenden.

Nehmen wir als Beispiel den users service unserer API, mit dem wir Informationen über unseren Benutzeraccount abfragen können:

curl Befehl
curl -X GET "https://api.viessmann.com/users/v1/users/me?sections=identity" 
-H "Authorization: Bearer eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAtMjU..."

Voilà! Das Ergebnis wird beispielsweise so aussehen:

HTTP
HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8

{
    "properties": {
        "loginId": "your-login-id@yourcompany.com",
        "address": {
            "postalCode": "12345",
            "city": "some city",
            "street": "Teststreet",
            "houseNumber": "42",
            "countryCode": "de"
        },
        "clientExtId": "100",
        "languageCode": "de",
        "userState": "ACTIVE",
        "name": {
            "firstName": "your first name",
            "familyName": "your last name"
        },
        "validity": {
            "from": "2018-06-11T07:14:47+0200"
        },
        "contacts": {
            "telephone": "+49 1234 5678",
            "telefax": "+48100234234",
            "email": "user@viessmann.com"
        },
        ...
    },
    ...
}

Das Vorgehen ist bei allen in unserer Dokumentation beschriebenen Endpunkten gleich, also zögere nicht und probier es einfach direkt aus!