Einführung

Die HTTP-Bridge ist eine Funktion der Gear Studio-Plattform, die die Geräteintegration über die HTTP-API durch MQTT ermöglicht. Dies macht es möglich, Geräte, die die HTTP-Schnittstelle verwenden, mit minimalen Änderungen auf MQTT zu migrieren.

Wichtig: Die HTTP-Bridge ist in erster Linie für die Migration von Geräten von HTTP zu MQTT konzipiert, aber für neue Geräte wird empfohlen, den flexiblen Datenaustausch zu verwenden, der hier zu finden ist. Der flexible Datenaustausch ermöglicht es, Daten mit wesentlich mehr Flexibilität und in der Regel in kompakterer Form darzustellen.

Anfragen

Um eine Anfrage über die HTTP-Bridge zu senden, muss die folgende Topic-Struktur verwendet werden:

{client-secure-id}/HttpApi/DeviceIntegration

Wobei client-secure-id der Benutzername ist, der bei der Verbindung verwendet wird. Die Topic-Struktur enthält die Benutzer-ID als erstes Element, da jeder Benutzer nur Berechtigungen für Topics hat, die mit dieser ID beginnen.

Jede Anfrage muss eine JSON-Nachricht enthalten, deren Struktur vom Nachrichtentyp abhängt. Einige Felder sind jedoch allen Nachrichtentypen gemeinsam:

accessToken: Dieses Feld gibt das Zugriffs-Token an, das zur Authentifizierung und Autorisierung der Anfrage verwendet werden muss.
mqttMethod: Dieses Feld gibt den Anfragetyp an. Um beispielsweise einen Temperaturwert zu melden, wird der Wert "UpdateTemperatureSensorStatus" verwendet.
mqttRID: Dies ist ein optionales Feld, das einen beliebigen Wert annehmen kann, der typischerweise zufällig gewählt wird. Wenn dieses Feld angegeben wird, generiert die Plattform automatisch eine Antwort auf den gesendeten Befehl und fügt dieselbe mqttRID in diese Antwort ein, sodass der Client die Antwort mit der ursprünglichen Anfrage verknüpfen kann.

Optional kann ein Antwort-Subtopic angegeben werden, indem am Anfang der mqttRID ein Schrägstrich und ein Wert angehängt werden. Das heißt, {subtopic}/{random value} Zum Beispiel unter Verwendung des Subtopics /device1 und der RID 1238j9. Die vollständige mqttRID wäre device1/1238j9

Einfache und mehrfache Anfragen

Einfache Anfragen

Einfache Anfragen ermöglichen das Senden eines einzelnen Datenwerts an die Plattform. Sie werden in der Regel verwendet, um den Status eines einzelnen Endpunkts zu melden.

Beispiel für eine einfache Anfrage:

{
	"accessToken": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
	"endpointID": 1,
	"temperatureCelsius": 25,
	"timestamp": "2021-02-23T14:55:03",
	"mqttMethod": "UpdateTemperatureSensorStatus",
	"mqttRID": "RXmp123"
}

Mehrfache Anfragen (Arrays)

Mehrfache Anfragen ermöglichen das Senden mehrerer Daten in einer einzigen MQTT-Nachricht. Es wird die JSON-Array-Syntax verwendet, mit eckigen Klammern am Anfang und Ende, die die durch Kommas getrennten Daten enthalten. Mehrfache Anfragen werden normalerweise verwendet, um den Status mehrerer Endpunkte in einer einzigen Nachricht zu melden. Sie sind auch nützlich, wenn ein Gerät Daten senden möchte, die während einer Periode ohne Kommunikation gespeichert wurden. In jedem Fall können die Daten verschiedene Endpunkte desselben Geräts oder sogar Endpunkte verschiedener Geräte umfassen.

Beispiel für eine mehrfache Anfrage:

[
	{
		"accessToken": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
		"endpointID": 1,
		"temperatureCelsius": 25,
		"timestamp": "2021-02-23T14:55:03",
		"mqttMethod": "UpdateTemperatureSensorStatus",
		"mqttRID": "RXmp123"
	},
	{
		"accessToken": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
		"endpointID": 2,
		"humidityPercentage": 30,
		"timestamp": "2021-02-23T15:55:03",
		"mqttMethod": "UpdateHumiditySensorStatus",
		"mqttRID": "xQzt395"
	}
]

Antworten

Wenn ein Wert im Feld mqttRID angegeben wird, erstellt die Plattform eine Antwortnachricht im Topic

{client-secure-id}/HttpApi/DeviceIntegrationResponse

Wenn ein Subtopic am Anfang der mqttRID angehängt wird, wird es an das Antwort-Topic angefügt:

{client-secure-id}/HttpApi/DeviceIntegrationResponse/{subtopic}

Dies ermöglicht es, den endgültigen Status der Anfrage zu erfahren und optional Antwortinformationen zu erhalten, falls der Befehl dies erfordert.

Die Antwort-Payload hat typischerweise das folgende Format:

{
    "mqttRID":"RXmp123",
    "mqttStatus":200,
    "mqttData":"{}"
}

Name	Description	Type
mqttRID	Unique identifier for each request	string
mqttStatus	Returns the server status code (200, 500, 400, etc). If the request executed successfully, it will be 200. In case of error, it can return any code (400 or 500)	integer
mqttData	The body of the server response. It is a string containing JSON.	string