Entwicklungs-API: Erstellen und Verwalten Ihrer App

Zweck

Dieser Leitfaden erklärt, wie man eine Market-App registriert, sie in einem Konto installiert, die Authentifizierung abschließt und beginnt, die API v3 zu verwenden. Er ist absichtlich kein vollständiges API-Referenzhandbuch – verwenden Sie das Entwicklerportal für eine umfassende Endpunktdokumentation.

Voraussetzungen

Sie benötigen:

• Einen Plattformbenutzer mit Superadmin-Rechten, um die App zu registrieren.
• Einen Backend-Server mit einer öffentlichen HTTPS-URL und der Fähigkeit, HTTP-Anfragen zu verarbeiten.
• Grundkenntnisse in REST, HTTP-Headern und JSON.

Schnellstart zur Authentifizierung

Wenn Sie keine Benutzeroberfläche entwickeln müssen, die mit der Plattform interagiert, und nur ein Token benötigen, um Daten von der API abzurufen, können Sie die Abschnitte App-Einrichtung sowie Handshake- und Authentifizierungsmodell überspringen und einfach die Access Token App installieren.

Dieses Token hat nur Lesezugriff. Wenn Sie weitere Berechtigungen benötigen, folgen Sie bitte den Anweisungen zur App-Einrichtung und zum Handshake.

App-Einrichtung

Registrieren Sie Ihre App (Organisationsverwaltung → Market Apps)

• Öffnen Sie im Benutzer-Menü oben rechts die Organisationsverwaltung.
• Gehen Sie zu Market Apps und klicken Sie auf Neue Market App.
• Füllen Sie aus:
  • Allgemeine Informationen (Name, Beschreibung, Symbol, Sichtbarkeit privat/öffentlich).
  • URLs: Installations-URL (erforderlich), optionale Bereinigungs-/Deinstallations-URL; optionale eingebettete UI-Ansichten/Berichte/Datenquellen.
  • Berechtigungen: Gewähren Sie die Lese-/Schreibbereiche, die Ihre App benötigt (fehlende Berechtigungen können den Zugriff blockieren).
• Speichern Sie die App und notieren Sie App-ID und App-Geheimnis (benötigt für den Token-Austausch bei der Installation). 

Hinweis: Private Apps können in den Konten Ihrer eigenen Organisation ohne weitere Maßnahmen installiert werden, während öffentliche Apps (sichtbar für Plattformkunden) eine Genehmigung benötigen. Kontaktieren Sie den Support für die Genehmigung, sobald die App fertig ist und Sie sie öffentlich machen möchten.

Installieren Sie Ihre App in einem Konto (Apps Market)

• Öffnen Sie im Zielkonto den Apps Market und installieren Sie Ihre App.

Handshake- und Authentifizierungsmodell

Wenn ein Benutzer Ihre App installiert:

• ruft die Plattform Ihre Installations-URL mit dep_id und temp_token auf
• tauscht Ihr Backend temp_token gegen ein permanentes Token aus, das in API v3 verwendet wird (x-dexcell-token).
• gibt Ihre App HTTP 200 OK zurück, um die Installation abzuschließen.

Beispiel: Verwendung des permanenten Tokens in API v3-Aufrufen

curl --request GET \
  --url "https://api.dexma.com/v3/locations" \
  --header "x-dexcell-token: <PERMANENT_TOKEN>"

Rate Limits

Standardmäßige Limits sind 10.000 Anfragen/Tag und 1.000 Anfragen/Stunde, die in den Headern jeder Anfrage eingesehen werden können.

Diese Limits können auf Anfrage erhöht werden, indem Sie eine E-Mail an den Support senden. Die E-Mail sollte die gewünschten Limits und eine Begründung enthalten, warum diese Kapazität notwendig ist.

Eingebettete Benutzeroberfläche (optional)

Es ist möglich, Benutzeroberflächen in verschiedenen Bereichen der Plattform anzuzeigen, einschließlich Dashboards, Analysebereich, Berichte und Datenquellen.

Die Plattform-Sitzung stellt Informationen bereit, die Sie zum Erstellen dieser Schnittstellen verwenden können, darunter:

• Konto
• Aktueller Standort
• Standort-Tags
• Untergeordnete Standorte
• Benutzer (einschließlich Benutzerrolle und Gebietsschema)
• Benutzerdefinierte Domain

Beste Praktiken (Sicherheit + Bedienbarkeit)

• Bewahren Sie Tokens serverseitig auf; geben Sie x-dexcell-token nicht im Frontend-Code preis.
• Berücksichtigen Sie Neuinstallation/Deinstallation: Jede Installation erzeugt ein neues Token, und eine Deinstallation macht es ungültig.
• Cachen und bündeln Sie API v3-Lesezugriffe, um eine Erschöpfung des Kontingents zu vermeiden. 

Beispielaufrufe

Mit der registrierten und erfolgreich in einem Ihrer Konten installierten App sollten Sie das x-dexcell-token erhalten und in Ihrer App gespeichert haben. Mit diesem Token können Sie Anfragen an die verschiedenen API-Endpunkte stellen. Alle verfügbaren Abfragen sind im Entwicklerportal der Plattform beschrieben: developers.dexma.com.

Liste aller meiner Standorte abrufen

• URL: https://api.dexcell.com/v3/locations
• Header: x-dexcell-token

Spezifische Informationen eines Standorts abrufen

• URL: https://api.dexcell.com/v3/locations/XXX
• Header: x-dexcell-token 

Messwerte abrufen

• URL:  http://api.dexcell.com/v3/readings?device_id=XXXXX&operation=DELTA&parameter_key=EACTIVE&resolution=D&from=2015-05-08T00:00:00&to=2015-05-09T23:59:59​
• Parameter:
  • device_id: Von /devices erhalten. Nicht identisch mit dem Geräte-Schlüssel.
  • parameter key: Siehe Parameterliste und Einführung in Parameter
  • operation: 
    • für Instant-Messwerte: RAW
    • für Zeitintervall-Messwerte:
      • DELTA für akkumulierte Parameter (Energie, Volumen, Masse, ...)
      • AVG, MAX, MIN für Momentanwerte (Leistung, Temperatur, Luftfeuchtigkeit, ...)
  • resolution:
    • wenn operation = RAW, dann muss resolution = B sein
    • wenn operation != RAW, dann kann resolution einer der Werte FM, TM, QH, HH, H, D, M sein
  • from / to: YYYY-MM-DDThh:mm:ss (in Ortszeit)
• Header: x-dexcell-token 

Verwandte Links

• Datasource Type Apps: Erstellen Sie Ihren Datenconnector
• Verwendung der Insertion API zur Datenübertragung in ein Gateway
• Access Token App
• APIv3 - Entwicklerportal