MQTT Broker REST API Dokumentation

Einleitung

Beim Aufbau einer IoT-Anwendung besteht die Notwendigkeit, zu kontrollieren und Verwaltung der Edge-Geräte aus der Manager-Anwendung. Also, unsereMQTT Broker(CrystalMQ) wurde mit REST integriert API Sie können Ihre Edge-Geräte über die REST API steuern. Sie können Nachrichten senden, neue hinzufügen Authentifizierungsschlüssel, erhalten Sie Client-Details und tun Sie mehr über die API. Diese Dokumentation bietet komplette Anleitung für die Entwickler, IoT-Anwendungen mit der RESTful API von unser Messaging-Broker. Wir empfehlen MQT Broker Integration mit REST APIBlog, um mehr zu wissen.


Grundlagen

Für die Post

Stellen Sie Rohdaten im Körper fest.

Alle Parameterfelder sollten als Parameter angegeben werden.

Sobald die von Ihnen eingegebenen Authentifizierungsdaten überprüft werden, werden Sie wird empfangen Antwort. Dann erstellen Sie Autorisierung und setzen Bearer Token. Und für alle API Befehle außer Anmeldung, Es ist notwendig, die Berechtigung festzulegen.

Für dich

Get Method sendet Anfragen an den Server, um Daten zu sammeln. Setzen Sie die ANHANG Parameter wie gerichtet.

  • Schlüssel und Wert im Headertyp.
  • Inhaltstyp und Autorisierung im Schlüsselfeld.
  • Wert für den Inhaltstyp als Applikation/Json und den Trager-Tokenwert.
MQTT Angaben

Zugriff auf eine Liste von MQTT Benutzernamen zusammen mit den Kunden, die haben Zugriff auf jeden Benutzernamen. Dies hilft bei der Überwachung und Verwaltung akzeptable Nutzung.

Methode:

GET

/Kristall/api/v1/mqt-Erzeugung

Beispiel Anfrage

Curl --location '//kristallmq/api/v1/mqt-credentials' \
--header 'Accept: Anwendung/Json' \
--Header 'Autorisierung: Bearer'

Antwort:

Auf Erfolg:

{\cHFFFF}
"Status": "Erfolg",
"Daten": {\cHFFFF}
"Erklärungen": [
{\cHFFFF}
"mqtt_username": "mqtt_user1",
"Clients": "client1,client2"
}
!
},
"Nachricht": "MQTT-Erstellung und die entsprechenden Client-Ids"
}

Unbefugt

{\cHFFFF}
"Status": "error",
"Nachricht": "Unautorisierter Benutzer"
}

Interner Server-Fehler

{\cHFFFF}
"Status": "error",
"Nachricht": "Failed"
}

MQTT hinzufügen Angaben

Fügen Sie neue MQTT-Anmeldeinformationen hinzu oder aktualisieren Sie bestehende zusammen mit die zugehörige Liste der zugelassenen Kunden. Diese Operation ermöglicht es Ihnen zu verwalten und Benutzername-Client-Mappings konfigurieren, um eine ordnungsgemäße Zugriffskontrolle und Anmeldepflicht zu gewährleisten Management.

Methode:

Post

/Kristall/api/v1/mqt-Erzeugung

Beispiel Anfrage
{\cHFFFF}
"mqtt_username": "mqtt_user1",
"mqtt_password": "mqtt_pass1",
"Clients": "client1,client.,dev*"
}
Antwort:
Auf Erfolg:

{\cHFFFF}
"Status": "Erfolg",
"Nachricht": "Added MQTT Credentials - MQTT Benutzername: mqtt_user1 für Client Id List: client1,client.,dev*"
}

Schlechte Anfrage - fehlende oder ungültige Parameter

{\cHFFFF}
"Status": "error",
"message": "Missing erforderliche Parameter: mqtt_username / mqt_password / Kunden"
}

Unbefugt

{\cHFFFF}
"Status": "error",
"Nachricht": "Unautorisierter Benutzer"
}

Interner Server-Fehler

{\cHFFFF}
"Status": "error",
"Nachricht": "Failed"
}

Löschen Sie MQTT Angaben

Löscht alle erstellten MQTT Credentials. Diese Aktion verdeutlicht alle Benutzernamen-Client-Mappings, effektiv Zugriff zurückrufen und sicherstellen, dass keine Anmeldeinformationen bleiben aktiv.

Methode:

Löschen

/Kristall/api/v1/mqt-Erzeugung

Antwort:

Auf Erfolg

{\cHFFFF}
"Status": "Erfolg",
"message": "Deleted MQTT Username: mqtt_user1"
}

Fehlende oder ungültige Parameter

{\cHFFFF}
"Status": "error",
"message": "Missing erforderliche Parameter: mqtt_username"
}

Unbefugt

{\cHFFFF}
"Status": "error",
"Nachricht": "Unautorisierter Benutzer"
}

Interner Server-Fehler

{\cHFFFF}
"Status": "error",
"Nachricht": "Failed"
}

ACL

Topic Access Control List

Erhalten Sie die Thema Access Control List (ACL) für den angegebenen Client IDs und/oder MQTT Benutzernamen. Dies liefert detaillierte Informationen zu den Themen, die jeweils Client oder Benutzer ist berechtigt, zuzugreifen und Ihnen dabei zu helfen, die Berechtigungen auf dem Thema zu verwalten effektiv.

Methode:
GET

/ Kristallmq/api/v1/acl

Beispiel Anfrage
curl --location '//kristallmq/api/v1/acl?clientid=%3Cstring%3E&mqt_username=%3Cstring%3E' (
--header 'Accept: Anwendung/Json' \
--header 'Authorization: Bearer <token> '

Antwort:

Auf Erfolg:

{\cHFFFF}
"Status": "Erfolg",
"Daten": {\cHFFFF}
"acl":
"Clients": {\cHFFFF}
"Additionsprop1":
"publish":
"access": "allow",
"Topics": [
"topic1",
"topic2"
!
},
"Abonnieren": {\cHFFFF}
"access": "allow",
"Topics": [
"topic1",
"topic2"
!
}
},
"Additionsprop2":
"publish":
"access": "allow",
"Topics": [
"topic1",
"topic2"
!
},
"Abonnieren": {\cHFFFF}
"access": "allow",
"Topics": [
"topic1",
"topic2"
!
}
},
"Additionsprop3":
"publish":
"access": "allow",
"Topics": [
"topic1",
"topic2"
!
},
"Abonnieren": {\cHFFFF}
"access": "allow",
"Topics": [
"topic1",
"topic2"
!
}
}
},
"mqtt_username": {\cHFFFF}
"Additionsprop1":
"publish":
"access": "allow",
"Topics": [
"topic1",
"topic2"
!
},
"Abonnieren": {\cHFFFF}
"access": "allow",
"Topics": [
"topic1",
"topic2"
!
}
},
"Nachricht": "Topic based Access Control List"
}

Schlechte Anfrage - fehlende oder ungültige Parameter

{\cHFFFF}
"Status": "error",
"message": "Missing erforderlicher Parameter: clientid / mqtt_username"
}

Unbefugt

{\cHFFFF}
"Status": "error",
"Nachricht": "Unautorisierter Benutzer"
}

Interner Server-Fehler

{\cHFFFF}
"Status": "error",
"Nachricht": "Failed"
}

Liste der Zugriffssteuerungen für einen Client ID oder MQTT hinzufügen/aktualisieren Benutzername

Hinzufügen oder Update der Topic Access Control List (ACL) für eine Client-ID oder MQTT Username. Stellen Sie sicher, dass nur einer von mqtt_username oder clientid in der anfordern.

Methode:
Post

/ Kristallmq/api/v1/acl

Beispielwert

{\cHFFFF}
"mqtt_username": "string",
"clientid": "string",
"publish_access": "allow",
"publish_topics": "#",
"subscribe_access": "allow",
"subscribe_topics": "#"
}

Antwort:

Auf Erfolg

{\cHFFFF}
"Status": "Erfolg",
"message": "Updated Access Control List for Client: clientid"
}

Schlechte Anfrage - Entweder mqtt_username ODER Klient muss gegeben, aber nicht beide

{\cHFFFF}
"Status": "error",
"message": "Missing benötigter Parameter: Entweder mqtt_username OR clientid muss gegeben
}

Unautorisiert - fehlende oder ungültige API-Token

{\cHFFFF}
"Status": "error",
"Nachricht": "Unautorisiert"
}

Interner Server-Fehler

{\cHFFFF}
"Status": "error",
"Nachricht": "Failed"
}

Topic Access Control List löschen für eine Client-ID oder MQTT Username

Löschen Sie die Topic Access Control List (ACL) für eine Client-ID oder MQTT Benutzername. Stellen Sie sicher, dass nur ein, entweder mqtt_username oder clientid, in der Anfrage-Körper zur Verfügung gestellt wird.

Methode:
DEUTSCHLAND

/ Kristallmq/api/v1/acl

Parameter:

Name Warenbezeichnung
Kunden
<string>		 ID des Clients

Antwort:

Auf Erfolg

{\cHFFFF}
"Status": "Erfolg",
"message": "Deleted Access Control List for ClientId: mqt_client1 wenn der ClientId existiert. MQTT Username basierte ACL wird für diesen Client angewendet."
}

Schlechte Anfrage - fehlende oder ungültige Parameter

{\cHFFFF}
"Status": "error",
"message": "Missing erforderliche Parameter: clientid"
}

Unbefugt

{\cHFFFF}
"Status": "error",
"Nachricht": "Unautorisierter Benutzer"
}

Interner Server-Fehler

{\cHFFFF}
"Status": "error",
"Nachricht": "Failed"
}

Kunden

Kaufen Sie Clients Count

Erhalten Sie die Gesamtzahl der Kunden, die durch ihren aktuellen Status kategorisiert werden. Dies stellt eine ausführliche Übersicht der aktiven, inaktive und andere Client-Staaten helfen bei der effektiven Überwachung und Verwaltung.

Methode:
Los!

/kristallmq/api/v1/clients/counts

Beispiel Anfrage

curl --location '//kristallmq/api/v1/clients/count?status=all' \
--header 'Accept: Anwendung/Json' \
--header 'Authorization: Bearer <token> '

Antwort:

Auf Erfolg

{\cHFFFF}
"Status": "Erfolg",
"Daten": {\cHFFFF}
"aktiv": 100,
"inaktiv": 50,
"alle": 150
},
"Nachricht": "Anzahl der Kunden"
}

Schlechte Anfragen - ungültige Parameter

{\cHFFFF}
"Status": "error",
"message": "Invalider Parameterwert für den Status"
}

Unbefugt

{\cHFFFF}
"Status": "error",
"Nachricht": "Unautorisierter Benutzer"
}

Interner Server-Fehler

{\cHFFFF}
"Status": "error",
"Nachricht": "Failed"
}

Kundeninformationen erhalten

Bietet detaillierte Informationen über einen bestimmten Client. Das hilft bei der Überwachung und Fehlerbehebung einzelner Kunden durch umfassende Bereitstellung Einblicke in ihre Aktivität und Konfiguration.

Methode:
Los!

/kristallmq/api/v1/clients/info

Beispiel Anfrage

Curl --location '//kristallmq/api/v1/clients/info?clientid=%3Cstring%3E' \
--header 'Accept: Anwendung/Json' \
--header 'Authorization: Bearer <token> '

Antwort:

Auf Erfolg

{\cHFFFF}
"Status": "Erfolg",
"Daten": {\cHFFFF}
"clientid": "client123",
"mqtt_version": 5.
"Status": "aktiv",
"status_timestamp": "2024-07-17T12:00Z",
"ip": "192.168.1.100",
"keep_alive": 60,
"clean_session": wahr,
"session_expiry_interval": 3600
},
"message": "Detailinformationen des Clients123"
}

Schlechte Anfragen - fehlende oder ungültige Parameter

{\cHFFFF}
"Status": "error",
"message": "Missing erforderliche Parameter: clientid"
}

Unbefugt

{\cHFFFF}
"Status": "error",
"Nachricht": "Unautorisierter Benutzer"
}

Interner Server-Fehler

{\cHFFFF}
"Status": "error",
"Nachricht": "Failed"
}

Client Last Will herunterladen

Holen Sie die letzten Informationen für einen bestimmten MQTT-Client oder für alle Kunden. Dies bietet Details zu der letzten Willensnachricht für Clients, die wird verwendet, um anderen Kunden eine unerwartete Abschaltung zu melden.

Methode:
Los!

/kristallmq/api/v1/clients/last-will

Parameter:

PARAMETER VALUE DETAIL
Kunden-ID Die ID des Clients, für den die letzten Informationen angefordert werden.

Beispiel Anfrage

Curl --location '//kristallmq/api/v1/clients/last-will?clientid=%3Cstring%3E' (
--header 'Accept: Anwendung/Json' \
--header 'Authorization: Bearer <token> '

Antwort:

Wenn Gerät angeschlossen ist:

{\cHFFFF}
"Status": "Erfolg",
"Daten": {\cHFFFF}
"client_id": {\cHFFFF}
"Additionsprop1":
"last_will": {\cHFFFF}
"topisch": "letzte/will",
"Nachricht": "Dies ist die letzte Willensnachricht",
"qos": 1,
"enthalten": wahr,
"Eigenschaften": {\cHFFFF}
"Additionsprop1": 300,
"Additionsprop2": 300,
"Additionsprop3": 300
}
}
},
"Additionsprop2":
"last_will": {\cHFFFF}
"topisch": "letzte/will",
"Nachricht": "Dies ist die letzte Willensnachricht",
"qos": 1,
"enthalten": wahr,
"Eigenschaften": {\cHFFFF}
"Additionsprop1": 300,
"Additionsprop2": 300,
"Additionsprop3": 300
}
}
},
"Nachricht": "Last Will of Client(s)"
}

Schlechte Anfrage - fehlendes oder ungültiges Paremeter

{\cHFFFF}
"Status": "error",
"Nachricht": "Failed to call last will information"
}

Unbefugt

{\cHFFFF}
"Status": "error",
"Nachricht": "Unautorisierter Benutzer"
}

Interner Server-Fehler

{\cHFFFF}
"Status": "error",
"Nachricht": "Failed"
}

MQTT5 Client deaktivieren

Trennt einen bestimmten MQTT5 Client. Diese Aktion beendet den aktuellen Client Sitzung, ständige Kommunikation zu stoppen und Ressourcen zu befreien.

Methode:
POST

/kristallmq/api/v1/clients/disconnect

Antwort:

Auf Erfolg, wenn Grenze ist 5:

{\cHFFFF}
"Status": "Erfolg",
"Nachricht": "Disconnected the Client: client123"
}

Schlechte Anfrage - fehlende oder ungültige Parameter

{\cHFFFF}
"Status": "error",
"message": "Missing erforderliche Parameter: clientid"
}

Unbefugt

{\cHFFFF}
"Status": "error",
"Nachricht": "Unautorisierter Benutzer"
}

Interner Server-Fehler

{\cHFFFF}
"Status": "error",
"Nachricht": "Failed"
}

Client-Abonnements erhalten

Holen Sie die Liste der Abonnements für alle Kunden oder für einen bestimmten Client, wenn ein Client Eine ID ist vorhanden. Damit können Sie anzeigen, welche Themen jeder Kunde abonniert hat, indem Sie Abonnement-Management.

Methode:
Los!

/kristallmq/api/v1/clients/Unterschriften

Parameter:

PARAMETER VALUE DETAIL
Client-ID Die ID des Clients, dessen Abonnements abgerufen werden sollen.

Beispiel Anfrage

curl --location '//kristallmq/api/v1/clients/subscriptions?clientid=%3Cstring%3E ' (
--header 'Accept: Anwendung/Json' \
--header 'Authorization: Bearer <token> '

Antwort:

Auf Erfolg

{\cHFFFF}
"Status": "Erfolg",
"Daten": {\cHFFFF}
"Clients": {\cHFFFF}
"Additionsprop1":
"Unterschriften": (
{\cHFFFF}
"filter": "topic/filter",
"qos": 1,
"subscription_options": {\cHFFFF}
"subscription_identifier": 1.
"user_property": "property_value",
"no_local": wahr,
"retain_handling": 0,
"retain_as_published": 1
}
}
!
},
"Additionsprop2":
"Unterschriften": (
{\cHFFFF}
"filter": "topic/filter",
"qos": 1,
"subscription_options": {\cHFFFF}
"subscription_identifier": 1.
"user_property": "property_value",
"no_local": wahr,
"retain_handling": 0,
"retain_as_published": 1
}
}
!
},
"Nachricht": "Client Abonnements"
}

Schlechte Anfrage - fehlende oder ungültige Parameter

{\cHFFFF}
"Status": "error",
"message": "Missing erforderliche Parameter: clientid"
}

Unbefugt

{\cHFFFF}
"Status": "error",
"Nachricht": "Unautorisierter Benutzer"
}

Interner Server-Fehler

{\cHFFFF}
"Status": "error",
"Nachricht": "Failed"
}

Kunden erhalten

Erhalten Sie eine umfassende Liste von Kunden, die durch ihren aktuellen Status kategorisiert werden. Das retrieval gibt Einblick in die Client-Aktivität und den Status, damit Sie überwachen und Client-Verbindungen effektiv verwalten.

Methode:
Los!

/Kristall/api/v1/clients

Antwort:

Auf Erfolg

{\cHFFFF}
"Status": "Erfolg",
"Daten": {\cHFFFF}
"aktiv": [
"client1",
"client2"
,
"inaktiv": [
"client3",
"client4"
!
},
"Nachricht": "Client Ids"
}

Schlechte Anfrage - ungültiger Parameter

{\cHFFFF}
"Status": "error",
"message": "Invalider Parameterwert für den Status"
}

Unbefugt

{\cHFFFF}
"Status": "error",
"Nachricht": "Unautorisierter Benutzer"
}

Interner Server-Fehler

{\cHFFFF}
"Status": "error",
"Nachricht": "Failed"
}

Themen

Clients zum Thema abonnieren

Holen Sie sich eine Liste von Kunden, die derzeit ein bestimmtes MQTT-Thema abonniert haben. Dies bietet Einblicke, in welche Kunden Nachrichten aus dem Thema erhalten.

Methode:
Los!

/kristallmq/api/v1/topics/subscriptions

Beispiel Anfrage

curl --location '//kristallmq/api/v1/topics/subscriptions?topic=%3Cstring%3E' (
--header 'Accept: Anwendung/Json' \
--header 'Authorization: Bearer <token> '

Antwort:

Auf Erfolg

{\cHFFFF}
"Status": "Erfolg",
"Daten": {\cHFFFF}
"Clients": {\cHFFFF}
"Additionsprop1":
"filter": "topic/filter",
"qos": 1,
"subscription_options": {\cHFFFF}
"subscription_identifier": 1.
"user_property": "property_value",
"no_local": wahr,
"retain_handling": 0,
"retain_as_published": 1
}
},
"Additionsprop2":
"filter": "topic/filter",
"qos": 1,
"subscription_options": {\cHFFFF}
"subscription_identifier": 1.
"user_property": "property_value",
"no_local": wahr,
"retain_handling": 0,
"retain_as_published": 1
}
},
"Nachricht": "Clients abonniert zum Thema"
}

Schlechte Anfragen - fehlende oder ungültige Parameter

{\cHFFFF}
"Status": "error",
"message": "Missing erforderliche Parameter: Thema"
}

Unbefugt

{\cHFFFF}
"Status": "error",
"Nachricht": "Unautorisierter Benutzer"
}

Interner Server-Fehler

{\cHFFFF}
"Status": "error",
"Nachricht": "Failed"
}

Aktuelle Veranstaltungen

Zugriff auf die neuesten Ereignisse des Brokers, die Einblicke in die jüngsten Aktivitäten und Systeminteraktionen. Diese Funktion hilft dabei, aktuelle Veranstaltungstrends zu überwachen und Probleme umgehend beheben.

Methode:
GET

/kristallmq/api/v1/recent-events

Beispiel Anfrage

Curl --location '//kristallmq/api/v1/recent-events?clientid=%3Cstring%3E&topic=%3C String%3E&Limit=1' \
--header 'Accept: Anwendung/Json' \
--header 'Authorization: Bearer <token> '

Antwort:

Auf Erfolg

{\cHFFFF}
"Status": "Erfolg",
"Daten": [
{\cHFFFF}
"client": "client001",
"topisch": "/Geräte/+/Daten",
"event": "Ereignisdaten hier",
"Zeitstempel": "2024-07-17T14:30:00Z",
"Eigenschaften": {\cHFFFF}
"qos": 1
}
}
,
"Nachricht": "Ereignisse(n) von Client(s)"
} {\cHFFFF}
"Status": "Erfolg",
"Daten": [
{\cHFFFF}
"client": "client001",
"topisch": "/Geräte/+/Daten",
"event": "Ereignisdaten hier",
"Zeitstempel": "2024-07-17T14:30:00Z",
"Eigenschaften": {\cHFFFF}
"qos": 1
}
}
,
"Nachricht": "Ereignisse(n) von Client(s)"
}

Schlechte Anfrage aufgrund fehlender oder ungültiger Daten

{\cHFFFF}
"Status": "error",
"message": "Missing erforderliche Parameter: Thema"
}

Unbefugt

{\cHFFFF}
"Status": "error",
"Nachricht": "Unautorisiert"
}

Interner Server-Fehler

{\cHFFFF}
"Status": "error",
"Nachricht": "Failed"
}

Aktuelle Befehle erhalten

Holen Sie sich eine Liste der neuesten Befehle an Clients. Diese Funktion bietet Einblicke in jüngste Befehlsaktivitäten, helfen Ihnen, Kundeninteraktionen zu verfolgen und zu überprüfen effektiv.

Methode:
GET

/kristallmq/api/v1/recent-commands

Antwort:

Auf Erfolg

{\cHFFFF}
"Status": "Erfolg",
"Daten": [
{\cHFFFF}
"client": "client001",
"topisch": "/Geräte/+/Daten",
"Befehl": "GET",
"Zeitstempel": "2024-07-17T14:30:00Z",
"Eigenschaften": {\cHFFFF}
"qos": "1"
}
}
!
}

Schlechte Anfrage aufgrund fehlender oder ungültiger Daten

Parameter fehlen:

{\cHFFFF}
"Status": "error",
"message": "Missing erforderliche Parameter: Thema"
}

Unbefugt

{\cHFFFF}
"Status": "error",
"Nachricht": "Unautorisiert"
}

Interner Server-Fehler

{\cHFFFF}
"Status": "error",
"Nachricht": "Failed"
}

Befehl an den Client senden

Senden Sie einen Befehl an einen bestimmten Client, indem Sie ihn an ein bestimmtes Thema veröffentlichen. Diese Aktion Sie können Clients auf Basis ihrer abonnierten Themen remote steuern oder anweisen.

Methode:
GET

/kristallmq/api/v1/send-command

Beispiel Anfrage

{\cHFFFF}
"clientid": "client123",
"topisch": "/Geräte/+/Daten",
"Nachricht": "Mitteilung",
"qos": 1,
"enthalten": 1
}

Antwort:

Auf Erfolg

{\cHFFFF}
"Status": "Erfolg",
"Nachricht": "Anforderung an den Client gesendet: client123"
}

Schlechte Anfrage aufgrund fehlender oder ungültiger Daten

Parameter fehlen:

{\cHFFFF}
"Status": "error",
"message": "Missing benötigter Parameter: clientid / topic"
}

Unbefugt

{\cHFFFF}
"Status": "error",
"Nachricht": "Unautorisiert"
}

Interner Server-Fehler

{\cHFFFF}
"Status": "error",
"Nachricht": "Failed"
}