Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.
Entwickeln AWS IoT TwinMaker Konnektoren für Zeitreihen-Daten
In diesem Abschnitt wird Schritt für Schritt erklärt, wie Sie einen Zeitreihen-Datenkonnektor entwickeln. Darüber hinaus stellen wir ein Beispiel für einen Zeitreihen-Datenkonnektor vor, der auf dem gesamten Cookie Factory-Beispiel basiert und 3D-Modelle, Entitäten, Komponenten, Alarme und Konnektoren umfasst. Die Beispielquelle für die Cookie Factory ist im AWS IoT TwinMaker GitHub Beispiel-Repository
Themen
AWS IoT TwinMaker Voraussetzungen für den Time-Series-Datenkonnektor
Bevor Sie Ihren Zeitreihen-Datenkonnektor entwickeln, empfehlen wir Ihnen, die folgenden Aufgaben auszuführen:
Erstellen Sie einen AWS IoT TwinMaker Arbeitsbereich.
-
Erstellen Sie AWS IoT TwinMaker Komponententypen.
(Optional) Lesen Sie Komponententypen verwenden und erstellen.
(Optional) Lesen Sie die AWS IoT TwinMaker Datenkonnektor-Schnittstelle, um sich ein allgemeines Verständnis von AWS IoT TwinMaker Datenkonnektoren zu verschaffen.
Anmerkung
Ein Beispiel für einen vollständig implementierten Connector finden Sie in unserer Beispielimplementierung für eine Cookie Factory.
Time-series Hintergrund des Datenkonnektors
Stellen Sie sich vor, Sie arbeiten mit einer Fabrik zusammen, die über eine Reihe von Keksmischern und einen Wassertank verfügt. Sie möchten AWS IoT TwinMaker digitale Zwillinge dieser physischen Einheiten erstellen, sodass Sie deren Betriebszustand überwachen können, indem Sie verschiedene Zeitreihenmetriken überprüfen.
Sie haben Sensoren vor Ort eingerichtet und streamen bereits Messdaten in eine Timestream-Datenbank. Sie möchten in der Lage sein, die Messdaten AWS IoT TwinMaker mit minimalem Aufwand anzuzeigen und zu organisieren. Sie können diese Aufgabe mithilfe eines Zeitreihen-Datenkonnektors ausführen. Die folgende Abbildung zeigt ein Beispiel für eine Telemetrietabelle, die mithilfe eines Zeitreihenkonnektors gefüllt wird.
.png)
Die in diesem Screenshot verwendeten Datensätze und die Timestream-Tabelle sind im Beispiel-Repository verfügbar. AWS IoT TwinMaker GitHub
Time-series Datenfluss des Datenkonnektors
AWS IoT TwinMaker Ruft bei Abfragen auf Datenebene die entsprechenden Eigenschaften sowohl der Komponenten als auch der Komponententypen aus den Definitionen von Komponenten und Komponententypen ab. AWS IoT TwinMaker leitet Eigenschaften zusammen mit allen API-Abfrageparametern in der Abfrage an AWS Lambda Funktionen weiter.
AWS IoT TwinMaker verwendet Lambda-Funktionen, um auf Abfragen aus Datenquellen zuzugreifen und diese zu lösen und die Ergebnisse dieser Abfragen zurückzugeben. Die Lambda-Funktionen verwenden die Komponenten- und Komponententypeigenschaften der Datenebene, um die ursprüngliche Anfrage zu lösen.
Die Ergebnisse der Lambda-Abfrage werden einer API-Antwort zugeordnet und an Sie zurückgegeben.
AWS IoT TwinMaker definiert die Datenkonnektor-Schnittstelle und verwendet diese für die Interaktion mit Lambda-Funktionen. Mithilfe von Datenkonnektoren können Sie Ihre Datenquelle ohne Datenmigrationsaufwand über die AWS IoT TwinMaker API abfragen. Die folgende Abbildung zeigt den grundlegenden Datenfluss, der in den vorherigen Absätzen beschrieben wurde.
Entwicklung eines Zeitreihen-Datenkonnektors
Das folgende Verfahren skizziert ein Entwicklungsmodell, das schrittweise zu einem funktionalen Zeitreihen-Datenkonnektor aufgebaut wird. Die grundlegenden Schritte sind wie folgt:
-
Erstellen Sie einen gültigen Basiskomponententyp
In einem Komponententyp definieren Sie gemeinsame Eigenschaften, die allen Komponenten gemeinsam sind. Weitere Informationen zum Definieren von Komponententypen finden Sie unter Komponententypen verwenden und erstellen.
AWS IoT TwinMaker verwendet ein Modellierungsmuster für Entitätskomponenten
, sodass jede Komponente einer Entität zugeordnet ist. Wir empfehlen, dass Sie jedes physische Objekt als Einheit modellieren und verschiedene Datenquellen mit ihren eigenen Komponententypen modellieren. Das folgende Beispiel zeigt einen Timestream-Vorlagenkomponententyp mit einer Eigenschaft:
{"componentTypeId": "com.example.timestream-telemetry", "workspaceId": "MyWorkspace", "functions": { "dataReader": { "implementedBy": { "lambda": { "arn": "lambdaArn" } } } }, "propertyDefinitions": { "telemetryType": { "dataType": { "type": "STRING" }, "isExternalId": false, "isStoredExternally": false, "isTimeSeries": false, "isRequiredInEntity": true }, "telemetryId": { "dataType": { "type": "STRING" }, "isExternalId": true, "isStoredExternally": false, "isTimeSeries": false, "isRequiredInEntity": true }, "Temperature": { "dataType": { "type": "DOUBLE" }, "isExternalId": false, "isTimeSeries": true, "isStoredExternally": true, "isRequiredInEntity": false } } }Die wichtigsten Elemente des Komponententyps sind die folgenden:
-
Die
telemetryIdEigenschaft identifiziert den eindeutigen Schlüssel des physischen Elements in der entsprechenden Datenquelle. Der Datenkonnektor verwendet diese Eigenschaft als Filterbedingung, um nur Werte abzufragen, die dem angegebenen Element zugeordnet sind. Wenn Sie außerdem dentelemetryIdEigenschaftswert in die API-Antwort der Datenebene aufnehmen, verwendet die Clientseite die ID und kann bei Bedarf eine umgekehrte Suche durchführen. -
Das
lambdaArnFeld identifiziert die Lambda-Funktion, mit der der Komponententyp interagiert. -
Das
isRequiredInEntityFlag erzwingt die ID-Erstellung. Dieses Flag ist erforderlich, damit bei der Erstellung der Komponente auch die ID des Elements instanziiert wird. -
Die
TelemetryIdwird dem Komponententyp als externe ID hinzugefügt, sodass das Element in der Timestream-Tabelle identifiziert werden kann.
-
Erstellen Sie eine Komponente mit dem Komponententyp
Um den von Ihnen erstellten Komponententyp zu verwenden, müssen Sie eine Komponente erstellen und sie an die Entität anhängen, von der Sie Daten abrufen möchten. In den folgenden Schritten wird der Prozess der Erstellung dieser Komponente detailliert beschrieben:
Navigieren Sie zur AWS IoT TwinMaker -Konsole
. Wählen Sie denselben Arbeitsbereich aus, in dem Sie die Komponententypen erstellt haben, und öffnen Sie ihn.
Navigieren Sie zur Entitätsseite.
Erstellen Sie eine neue Entität oder wählen Sie eine vorhandene Entität aus der Tabelle aus.
Nachdem Sie die Entität ausgewählt haben, die Sie verwenden möchten, wählen Sie Komponente hinzufügen, um die Seite Komponente hinzufügen zu öffnen.
Geben Sie der Komponente einen Namen und wählen Sie als Typ den Komponententyp aus, den Sie mit der Vorlage in 1 erstellt haben. Erstellen Sie einen gültigen Basiskomponententyp.
-
Rufen Sie für Ihren Komponententyp einen Lambda-Connector auf
Der Lambda-Connector muss auf die Datenquelle zugreifen und die Abfrageanweisung auf der Grundlage der Eingabe generieren und an die Datenquelle weiterleiten. Das folgende Beispiel zeigt eine JSON-Anforderungsvorlage, die dies tut.
{ "workspaceId": "MyWorkspace", "entityId": "MyEntity", "componentName": "TelemetryData", "selectedProperties": ["Temperature"], "startTime": "2022-08-25T00:00:00Z", "endTime": "2022-08-25T00:00:05Z", "maxResults": 3, "orderByTime": "ASCENDING", "properties": { "telemetryType": { "definition": { "dataType": { "type": "STRING" }, "isExternalId": false, "isFinal": false, "isImported": false, "isInherited": false, "isRequiredInEntity": false, "isStoredExternally": false, "isTimeSeries": false }, "value": { "stringValue": "Mixer" } }, "telemetryId": { "definition": { "dataType": { "type": "STRING" }, "isExternalId": true, "isFinal": true, "isImported": false, "isInherited": false, "isRequiredInEntity": true, "isStoredExternally": false, "isTimeSeries": false }, "value": { "stringValue": "item_A001" } }, "Temperature": { "definition": { "dataType": { "type": "DOUBLE", }, "isExternalId": false, "isFinal": false, "isImported": true, "isInherited": false, "isRequiredInEntity": false, "isStoredExternally": false, "isTimeSeries": true } } } }Die wichtigsten Elemente der Anfrage:
-
Die
selectedPropertiesist eine Liste, die Sie mit den Eigenschaften füllen, für die Sie Timestream-Messungen wünschen. -
Die
endTimeFelderstartDateTimestartTime,EndDateTime, und geben einen Zeitraum für die Anfrage an. Dies bestimmt den Probenbereich für die zurückgegebenen Messungen. -
Das
entityIdist der Name der Entität, von der aus Sie Daten abfragen. -
Das
componentNameist der Name der Komponente, von der aus Sie Daten abfragen. -
Verwenden Sie das
orderByTimeFeld, um die Reihenfolge zu organisieren, in der die Ergebnisse angezeigt werden.
In der vorherigen Beispielanfrage würden wir erwarten, dass wir innerhalb des angegebenen Zeitfensters für das angegebene Element eine Reihe von Stichproben für die ausgewählten Eigenschaften in der ausgewählten Zeitreihenfolge erhalten. Die Antwortanweisung kann wie folgt zusammengefasst werden:
{ "propertyValues": [ { "entityPropertyReference": { "entityId": "MyEntity", "componentName": "TelemetryData", "propertyName": "Temperature" }, "values": [ { "time": "2022-08-25T00:00:00Z", "value": { "doubleValue": 588.168 } }, { "time": "2022-08-25T00:00:01Z", "value": { "doubleValue": 592.4224 } }, { "time": "2022-08-25T00:00:02Z", "value": { "doubleValue": 594.9383 } } ] } ], "nextToken": "..." } -
Aktualisieren Sie Ihren Komponententyp, sodass er über zwei Eigenschaften verfügt
Die folgende JSON-Vorlage zeigt einen gültigen Komponententyp mit zwei Eigenschaften:
{ "componentTypeId": "com.example.timestream-telemetry", "workspaceId": "MyWorkspace", "functions": { "dataReader": { "implementedBy": { "lambda": { "arn": "lambdaArn" } } } }, "propertyDefinitions": { "telemetryType": { "dataType": { "type": "STRING" }, "isExternalId": false, "isStoredExternally": false, "isTimeSeries": false, "isRequiredInEntity": true }, "telemetryId": { "dataType": { "type": "STRING" }, "isExternalId": true, "isStoredExternally": false, "isTimeSeries": false, "isRequiredInEntity": true }, "Temperature": { "dataType": { "type": "DOUBLE" }, "isExternalId": false, "isTimeSeries": true, "isStoredExternally": true, "isRequiredInEntity": false }, "RPM": { "dataType": { "type": "DOUBLE" }, "isExternalId": false, "isTimeSeries": true, "isStoredExternally": true, "isRequiredInEntity": false } } }Aktualisieren Sie den Lambda-Connector, um die zweite Eigenschaft zu verarbeiten
Die AWS IoT TwinMaker Datenebenen-API unterstützt das Abfragen mehrerer Eigenschaften in einer einzigen Anfrage und AWS IoT TwinMaker folgt einer einzelnen Anfrage an einen Connector, indem sie eine Liste von bereitstellt.
selectedPropertiesDie folgende JSON-Anfrage zeigt eine geänderte Vorlage, die jetzt eine Anforderung für zwei Eigenschaften unterstützt.
{ "workspaceId": "MyWorkspace", "entityId": "MyEntity", "componentName": "TelemetryData", "selectedProperties": ["Temperature", "RPM"], "startTime": "2022-08-25T00:00:00Z", "endTime": "2022-08-25T00:00:05Z", "maxResults": 3, "orderByTime": "ASCENDING", "properties": { "telemetryType": { "definition": { "dataType": { "type": "STRING" }, "isExternalId": false, "isFinal": false, "isImported": false, "isInherited": false, "isRequiredInEntity": false, "isStoredExternally": false, "isTimeSeries": false }, "value": { "stringValue": "Mixer" } }, "telemetryId": { "definition": { "dataType": { "type": "STRING" }, "isExternalId": true, "isFinal": true, "isImported": false, "isInherited": false, "isRequiredInEntity": true, "isStoredExternally": false, "isTimeSeries": false }, "value": { "stringValue": "item_A001" } }, "Temperature": { "definition": { "dataType": { "type": "DOUBLE" }, "isExternalId": false, "isFinal": false, "isImported": true, "isInherited": false, "isRequiredInEntity": false, "isStoredExternally": false, "isTimeSeries": true } }, "RPM": { "definition": { "dataType": { "type": "DOUBLE" }, "isExternalId": false, "isFinal": false, "isImported": true, "isInherited": false, "isRequiredInEntity": false, "isStoredExternally": false, "isTimeSeries": true } } } }In ähnlicher Weise wird auch die entsprechende Antwort aktualisiert, wie im folgenden Beispiel gezeigt:
{ "propertyValues": [ { "entityPropertyReference": { "entityId": "MyEntity", "componentName": "TelemetryData", "propertyName": "Temperature" }, "values": [ { "time": "2022-08-25T00:00:00Z", "value": { "doubleValue": 588.168 } }, { "time": "2022-08-25T00:00:01Z", "value": { "doubleValue": 592.4224 } }, { "time": "2022-08-25T00:00:02Z", "value": { "doubleValue": 594.9383 } } ] }, { "entityPropertyReference": { "entityId": "MyEntity", "componentName": "TelemetryData", "propertyName": "RPM" }, "values": [ { "time": "2022-08-25T00:00:00Z", "value": { "doubleValue": 59 } }, { "time": "2022-08-25T00:00:01Z", "value": { "doubleValue": 60 } }, { "time": "2022-08-25T00:00:02Z", "value": { "doubleValue": 60 } } ] } ], "nextToken": "..." }Anmerkung
In Bezug auf die Paginierung in diesem Fall gilt die Seitengröße in der Anfrage für alle Eigenschaften. Das heißt, bei fünf Eigenschaften in der Abfrage und einer Seitengröße von 100 sollten Sie, wenn genügend Datenpunkte in der Quelle vorhanden sind, mit 100 Datenpunkten pro Eigenschaft rechnen, also insgesamt 500 Datenpunkte.
Eine Beispielimplementierung finden Sie unter Snowflake-Connector-Beispiel
unter. GitHub
Verbessern Sie Ihren Datenkonnektor
Umgang mit Ausnahmen
Es ist sicher, dass der Lambda-Connector Ausnahmen auslöst. Beim API-Aufruf der Datenebene wartet der AWS IoT TwinMaker Dienst darauf, dass die Lambda-Funktion eine Antwort zurückgibt. Wenn die Connector-Implementierung eine Ausnahme auslöst, AWS IoT TwinMaker übersetzt sie den Ausnahmetyp in den Typ B und macht den API-Client darauf aufmerksamConnectorFailure, dass ein Problem innerhalb des Connectors aufgetreten ist.
Umgang mit der Paginierung
Im Beispiel bietet Timestream eine Hilfsfunktion, mit der
Wenn das neue Token AWS IoT TwinMaker über die Connector-Antwortschnittstelle zurückgegeben wird, wird das Token verschlüsselt, bevor es an den API-Client zurückgegeben wird. Wenn das Token in einer anderen Anfrage enthalten ist, wird es AWS IoT TwinMaker entschlüsselt, bevor es an den Lambda-Connector weitergeleitet wird. Wir empfehlen, dass Sie vermeiden, dem Token vertrauliche Informationen hinzuzufügen.
Testen Sie Ihren Connector
Sie können die Implementierung zwar immer noch aktualisieren, nachdem Sie den Connector mit dem Komponententyp verknüpft haben, wir empfehlen jedoch dringend, den Lambda-Connector zu überprüfen, bevor Sie ihn integrieren AWS IoT TwinMaker.
Es gibt mehrere Möglichkeiten, Ihren Lambda-Connector zu testen: Sie können den Lambda-Connector in der Lambda-Konsole oder lokal in der testen. AWS CDK
Weitere Informationen zum Testen Ihrer Lambda-Funktionen finden Sie unter Testen von Lambda-Funktionen und Lokales Testen von Anwendungen. AWS CDK
Sicherheit
Eine Dokumentation zu den bewährten Sicherheitsmethoden mit Timestream finden Sie unter Sicherheit in Timestream.
Ein Beispiel für den Schutz vor SQL-Injection finden Sie im folgenden Python-Skript
Erstellen AWS IoT TwinMaker Ressourcen
Sobald Sie die Lambda-Funktion implementiert haben, können Sie AWS IoT TwinMaker Ressourcen wie Komponententypen, Entitäten und Komponenten über die AWS IoT TwinMaker Konsole
Anmerkung
Wenn Sie die Einrichtungsanweisungen im GitHub Beispiel befolgen, sind alle AWS IoT TwinMaker Ressourcen automatisch verfügbar. Sie können die Definitionen der Komponententypen im AWS IoT TwinMaker GitHub Beispiel überprüfen
Integrationstests
Wir empfehlen, einen integrierten Test durchzuführen, AWS IoT TwinMaker um zu überprüfen, ob die Datenebenenabfrage durchgängig funktioniert. Sie können dies über die GetPropertyValueHistory API oder einfach in der AWS IoT TwinMaker Konsole durchführen
.png)
Gehen Sie in der AWS IoT TwinMaker Konsole zu den Komponentendetails, und dann werden Sie unter Test sehen, dass alle Eigenschaften der Komponente dort aufgelistet sind. Im Testbereich der Konsole können Sie sowohl Eigenschaften von Zeitreihen als auch Eigenschaften testen, die keine Zeitreihen sind. Für Zeitreiheneigenschaften können Sie auch die API verwenden und für Eigenschaften, die keine Zeitreihen sind, die GetPropertyValueHistory API. GetPropertyValue Wenn Ihr Lambda-Connector mehrere Eigenschaftsabfragen unterstützt, können Sie mehr als eine Eigenschaft auswählen.
.png)
Was kommt als Nächstes
Sie können jetzt ein AWS IoT TwinMaker Grafana-Dashboard einrichten, um Metriken zu visualisieren. Sie können auch andere Beispiele für Datenkonnektoren im AWS IoT TwinMaker GitHub Beispiel-Repository untersuchen
