API-Dokumentation – Erste Schritte

Beschreibung:

Dieser Leitfaden hilft Ihnen beim Einstieg in die LANCOM Management Cloud (LMC) API. Sie erfahren, wie Sie einen API-Schlüssel erstellen, der mit Ihrem Benutzerprofil in der LMC verknüpft ist, und wie Sie damit über JavaScript mit der API interagieren und Gerätestatistikdaten abrufen können.

1. Einführung in die LMC API

Die LANCOM Management Cloud (LMC) API bietet Entwicklern die Möglichkeit, programmgesteuert auf Ressourcen in Ihrem LMC-Konto zuzugreifen und diese zu verwalten. Über die API können Sie verschiedene Daten abrufen, darunter Gerätedaten, Netzwerkkonfigurationen, Überwachungsdaten und vieles mehr.

Wichtige Begriffe

API-Schlüssel und Autorisierung: Hierbei handelt es sich um einen Authentifizierungsschlüssel, der zur Autorisierung von API-Anfragen über externe Clients verwendet wird. LMC erfordert, dass Sie API-Aufrufe mit einem gültigen API-Schlüssel im Request-Header authentifizieren.
Endpunkt: Eine URL, über die Sie auf eine bestimmte Ressource oder einen bestimmten Dienst zugreifen können, z. B. zum Abrufen von Gerätestatistiken.

2. Erstellen eines benutzergebundenen API-Schlüssels in der LMC

Um mit der LMC API zu interagieren, müssen Sie zunächst einen API-Schlüssel erstellen, der mit Ihrem Benutzerprofil verknüpft ist. Gehen Sie dazu wie folgt vor:

Schritt 1: Anmelden bei der LMC

1. Navigieren Sie zur LANCOM Management Cloud.
2. Melden Sie sich mit Ihren Zugangsdaten (Benutzername und Passwort) an.

Schritt 2: Navigieren Sie zu Ihrem Benutzerprofil

1. Nach der Anmeldung gehen Sie zum Benutzerprofil. Sie finden es in der oberen rechten Ecke.
2. Klicken Sie auf Ihren <Benutzernamen> → Mein Profil.

Schritt 3: Erstellen Sie einen API-Schlüssel

1. Öffnen Sie in Ihren Benutzereinstellungen den Abschnitt API-Keys.
2. Stellen Sie sicher, dass API-Schlüssel für das jeweilige Projekt aktiviert sind (weitere Informationen finden Sie unter API-Schlüssel für ein Projekt aktivieren).
3. Klicken Sie auf Neuen API-Key erstellen und geben Sie einen Namen ein. Dadurch wird ein API-Schlüssel generiert, der mit Ihrem Benutzerkonto verknüpft ist.
4. Wählen Sie ein Projekt aus um den Zugriff einzuschränken.
5. Klicken Sie auf Erstellen.
6. Kopieren Sie den neu generierten API-Schlüssel, um ihn in Ihren API-Anfragen zu verwenden. Dieser Schlüssel wird zur Authentifizierung Ihrer API-Aufrufe verwendet.

Schritt 4: API-Schlüssel sicher speichern

Speichern Sie Ihren API-Schlüssel sicher, da er Zugriff auf Ihr LMC-Konto und dessen Ressourcen gewährt. Geben Sie ihn nicht öffentlich weiter.

Die LMC speichert den erzeugten API-Schlüssel nicht, daher kann dieser im Falle eines Verlusts nicht reproduziert werden!

3. Beispiel für einen grundlegenden API-Aufruf

Sobald Sie Ihren API-Schlüssel haben, können Sie API-Anfragen stellen, um Informationen aus dem LMC abzurufen.

In diesem Beispiel verwenden wir den Endpunkt devices, um Gerätestatistikdaten abzurufen, die unter Ihrem LMC-Projekt registriert sind.

Beispiel für einen cURL-Befehl

Hier ist ein Beispiel für einen cURL-Befehl zum Abrufen von Gerätestatistiken. Sie müssen <accountId> durch Ihre tatsächliche Konto-ID und <API_KEY> durch Ihren generierten API-Schlüssel ersetzen.

# Linux / MacOS (terminal)

curl -v -X 'GET' \
'https://cloud.lancom.de/cloud-service-devices/accounts/<accountId>/device_statistics' \
 -H 'accept: application/json' \
 -H 'Authorization: LMC-API-KEY <API_KEY>'


# Windows (cmd)

curl -v -X GET ^
"https://cloud.lancom.de/cloud-service-devices/accounts/<accountId>/device_statistics" ^
-H "accept: application/json" ^
-H "Authorization: LMC-API-KEY <API_KEY>"

Parameter

GET: HTTP-Methode zum Abrufen von Daten vom angegebenen Endpunkt.
accept: application/json: Gibt an, dass die Antwort im JSON-Format erfolgen soll.
Authorization: Hier übergeben Sie Ihren API-Schlüssel im Format LMC-API-KEY <Ihr_API-Schlüssel>.

Ersetzen Sie <accountId> und <API_KEY> durch die tatsächlichen Werte aus Ihrem Konto und Ihrem API-Schlüssel.

Beispielantwort

Die Antwort sollte in etwa so aussehen (Beispieldaten):

{
  "id": "<accountId>",
  "heartbeatState": {
    "_unset": 0,
    "_matched": 0,
    "_total": 6,
    "active": 5,
    "inactive": 1
  },
  ...
}

4. API mit JavaScript anfordern

Um den Prozess des Abrufens von Daten zu automatisieren, können Sie JavaScript (JS) zum Senden von API-Anfragen verwenden.

Schritt 1: Node.JS installieren

Zunächst müssen Sie Node.JS installieren, um JavaScript-Dateien ausführen zu können. Stellen Sie sicher, dass die Node.JS-Laufzeitbibliothek erfolgreich installiert wurde, indem Sie den folgenden Befehl in Ihrem Terminal ausführen:

node -v

Schritt 2: JavaScript-Code-Beispiel

Nachfolgend finden Sie ein JS-Beispiel zum Abrufen von Gerätestatistikdaten durch Senden einer GET-Anfrage an die LMC-API.

main.ts

// Replace with your actual API key and account ID
const apiKey = 'eyJr...UQ19E';  // API Key
const accountId = 'your_account_id';  // Replace with your account ID

// Define the endpoint URL
const endpoint = `https://cloud.lancom.de/cloud-service-devices/accounts/${accountId}/device_statistics`;

// Function to fetch device statistics
async function fetchDeviceStatistics() {
    try {
        const response = await fetch(endpoint, {
            method: 'GET',
            headers: {
                'Authorization': `LMC-API-KEY ${apiKey}`,
                'Accept': 'application/json'
            }
        });

        if (!response.ok) {
            throw new Error(`HTTP error! Status: ${response.status}`);
        }

        const data = await response.json();
        console.log('Device Statistics:', data);
    } catch (error) {
        console.error('Error fetching device statistics:', error);
    }
}

// Call the function
fetchDeviceStatistics();

Schritt 3: Führen Sie den JavaScript-Code aus

Führen Sie den Code im Terminal mit der JavaScript-Laufzeitumgebung Node.js aus.

node <yourfilename>.js

Dadurch werden die von der LMC-API abgerufenen Gerätestatistiken protokolliert.

Wenn Sie sehen möchten, wie Sie mit Python eine Beispielanfrage an die LMC-API stellen können ist im Artikel Code-Beispiel: Alle Geräte für einen Standort mit Python auflisten beschrieben.

5. Best Practices für die Arbeit mit der LMC-API

Sichern Sie Ihren API-Schlüssel: Halten Sie Ihren API-Schlüssel immer geheim. Geben Sie ihn niemals in öffentlichen Repositorys oder gemeinsam genutztem Code preis.
Fehlerbehandlung: Implementieren Sie eine ordnungsgemäße Fehlerbehandlung in Ihrer Anwendung, um potenzielle Probleme wie Zeitüberschreitungen, falsche API-Schlüssel oder Serverfehler zu beheben.
API-Dokumentation: Ausführliche Informationen zu allen verfügbaren Endpunkten, Parametern und Antwortformaten finden Sie in der offiziellen LANCOM API-Dokumentation.

6. Fazit

Dieser Leitfaden hat Ihnen gezeigt, wie Sie mit der LANCOM Management Cloud API beginnen können. Sie haben gelernt, wie Sie einen benutzergebundenen API-Schlüssel generieren, eine einfache API-Anfrage mit cURL stellen und mit der API in einer JavaScript-Anwendung interagieren können.

Weitere Informationen und fortgeschrittene Anwendungsfälle finden Sie in der offiziellen LANCOM API-Dokumentation.

Seitenhierarchie