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. # Tutorial: Installation des Geräte-SDK und Ausführen der Beispielanwendung für Geräteschatten In diesem Abschnitt wird gezeigt, wie Sie die erforderliche Software und das AWS IoT Device SDK für Python installieren und die `shadow.py` Beispielanwendung ausführen können, um das Shadow-Dokument zu bearbeiten und den Status des Shadows zu kontrollieren. **In diesem Kurs lernen Sie Folgendes:** + Verwenden Sie die installierte Software und AWS IoT das Geräte-SDK für Python, um die Beispiel-App auszuführen. + Lernen, wie die Eingabe eines Werts mithilfe der Beispiel-App den gewünschten Wert in der AWS IoT Konsole veröffentlicht. + Prüfen der `shadow.py` Beispiel-App an und wie sie das MQTT-Protokoll verwendet, um den Status des Schattens zu aktualisieren. **Bevor Sie dieses Tutorial ausführen:** Sie müssen Ihr Raspberry Pi-Gerät eingerichtet AWS-Konto, konfiguriert und eine AWS IoT Sache und Richtlinie erstellt haben, die dem Gerät die Erlaubnis geben, die MQTT-reservierten Themen des Device Shadow-Dienstes zu veröffentlichen und zu abonnieren. Weitere Informationen finden Sie unter [Tutorial: Ihren Raspberry Pi für die Ausführung der Schattenanwendung vorbereiten](create-resources-shadow.md). Sie müssen auch Git, Python und das AWS IoT Device SDK für Python installiert haben. Dieses Tutorial baut auf den im Tutorial [Verbinden eines Raspberry Pi oder eines anderes Gerätes](connecting-to-existing-device.md) vorgestellten Konzepten auf. Wenn Sie dieses Tutorial noch nicht ausprobiert haben, empfehlen wir Ihnen, die in diesem Tutorial beschriebenen Schritte zu befolgen, um die Zertifikatsdateien und das Geräte-SDK zu installieren, und dann zu diesem Tutorial zurückzukehren, um die `shadow.py` Beispiel-App auszuführen. **Topics** + [Schritt 1: shadow.py-Beispiel-App ausführen](#run-sample-application-shadows) + [Schritt 2: Geräte-SDK-Beispiel-App shadow.py prüfen](#review-shadow-sample-code) + [Schritt 3: Probleme mit der `shadow.py`-Beispiel-App beheben](#shadow-sample-app-troubleshoot) + [Schritt 4: Ergebnisse überprüfen und nächste Schritte](#sample-app-shadow-review) Für dieses Tutorial brauchen Sie ungefähr 20 Minuten. ## Schritt 1: shadow.py-Beispiel-App ausführen Bevor Sie die `shadow.py` Beispiel-App ausführen, benötigen Sie zusätzlich zu den Namen und dem Speicherort der installierten Zertifikatsdateien die folgenden Informationen. **Werte für Anwendungsparameter** | Parameter | Wo der Wert gefunden werden kann | | --- | --- | | your-iot-thing-name | Name der AWS IoT Sache, die Sie zuvor erstellt haben[Schritt 2: Erstellen Sie eine Objekt-Ressource und fügen Sie die Richtlinie dem Objekt hinzu](shadow-provision-cloud.md#create-thing-shadow). Um diesen Wert zu finden, wählen Sie in der [AWS IoT Konsole](https://console.aws.amazon.com/iot/home) **Verwalten** und dann **Objekte** aus. | | your-iot-endpoint | Der *your-iot-endpoint* Wert hat das Format:`endpoint_id-ats.iot.region.amazonaws.com`, zum Beispiel`a3qj468EXAMPLE-ats.iot.us-west-2.amazonaws.com`. So finden Sie diesen Wert: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/de_de/iot/latest/developerguide/lightbulb-shadow-application.html) | **Installieren und Ausführen der Beispiel-App** 1. Navigieren Sie zum Verzeichnis der Beispiel-App. ``` cd ~/aws-iot-device-sdk-python-v2/samples/service-clients ``` 1. Ersetzen Sie im Befehlszeilenfenster *your-iot-endpoint* und *your-iot-thing-name* wie angegeben und führen Sie diesen Befehl aus. ``` python3 shadow.py --ca_file ~/certs/Amazon-root-CA-1.pem --cert ~/certs/device.pem.crt --key ~/certs/private.pem.key --endpoint your-iot-endpoint --thing_name your-iot-thing-name ``` 1. Beachten Sie, dass die Beispiel-App: 1. Stellt eine Verbindung zum AWS IoT-Dienst für Ihr Konto her. 1. `Delta`-Ereignisse und `Update` und `Get`-Antworten abonniert. 1. Sie dazu auffordert, einen gewünschten Wert in das Terminal einzugeben. 1. Die Ausgabe sieht ähnlich aus wie: ``` Connecting to a3qEXAMPLEffp-ats.iot.us-west-2.amazonaws.com with client ID 'test-0c8ae2ff-cc87-49d2-a82a-ae7ba1d0ca5a'... Connected! Subscribing to Delta events... Subscribing to Update responses... Subscribing to Get responses... Requesting current shadow state... Launching thread to read user input... Finished getting initial shadow state. Shadow contains reported value 'off'. Enter desired value: ``` **Anmerkung** Wenn Sie Probleme beim Ausführen der `shadow.py`-Beispiel-App haben, überprüfen Sie [Schritt 3: Probleme mit der `shadow.py`-Beispiel-App beheben](#shadow-sample-app-troubleshoot). Um zusätzliche Informationen zu erhalten, die Ihnen bei der Behebung des Problems helfen könnten, fügen Sie den `--verbosity debug` Parameter zur Befehlszeile hinzu, sodass die Beispiel-App detaillierte Meldungen darüber anzeigt, was sie tut. **Geben Sie Werte ein und beobachten Sie die Aktualisierungen im Schattendokument** Sie können Werte in das Terminal eingeben, um den `desired`-Wert anzugeben, wodurch auch der `reported`-Wert aktualisiert wird. Angenommen, Sie geben die Farbe `yellow` im Terminal ein. Der `reported`-Wert wird ebenfalls auf die Farbe `yellow` aktualisiert. Im Folgenden werden die im Terminal angezeigten Meldungen angezeigt: ``` Enter desired value: yellow Changed local shadow value to 'yellow'. Updating reported shadow value to 'yellow'... Update request published. Finished updating reported shadow value to 'yellow'. ``` Wenn Sie diese Aktualisierungsanforderung veröffentlichen, AWS IoT wird ein klassischer Standard-Shadow für die Ding-Ressource erstellt. Sie können die Aktualisierungsanforderung beobachten, die Sie für die `desired` Werte `reported` und in der AWS IoT Konsole veröffentlicht haben, indem Sie sich das Shadow-Dokument für die von Ihnen erstellte Ding-Ressource ansehen (z. B.`My_light_bulb`). Um das Update im Schattendokument zu sehen: 1. Wählen Sie in der AWS IoT Konsole „**Verwalten**“ und anschließend „**Dinge**“ aus. 1. Wählen Sie in der angezeigten Liste das Objekt aus, das Sie erstellt haben, wählen Sie **Schatten** und anschließend **Klassischer Schatten**. Das Schattendokument sollte wie folgt aussehen und für die `reported`- und `desired`-Werte die Farbe `yellow` anzeigen. Sie sehen diese Werte im Abschnitt **Schattenstatus** des Dokuments. ``` { "desired": { "welcome": "aws-iot", "color": "yellow" }, "reported": { "welcome": "aws-iot", "color": "yellow" } } ``` Sie sehen auch einen Abschnitt mit den **Metadaten**, der die Zeitstempelinformationen und die Versionsnummer der Anfrage enthält. Sie können die Version des Statusdokuments verwenden, um sicherzustellen, dass Sie die neueste Version eines Geräteschattendokuments aktualisieren. Wenn Sie eine weitere Aktualisierungsanfrage senden, wird die Versionsnummer um 1 erhöht. Geben Sie bei einer Aktualisierungsanfrage eine Version an, lehnt der Service die Anfrage mit einem Konflikt-Antwortcode HTTP 409 ab, wenn die aktuelle Version des Statusdokuments nicht der angegebenen Version entspricht. ``` { "metadata": { "desired": { "welcome": { "timestamp": 1620156892 }, "color": { "timestamp": 1620156893 } }, "reported": { "welcome": { "timestamp": 1620156892 }, "color": { "timestamp": 1620156893 } } }, "version": 10 } ``` Um mehr über das Schattendokument zu erfahren und Änderungen an den Statusinformationen einzusehen, fahren Sie mit dem nächsten Tutorial [Tutorial: Interaktion mit Geräteschatten mithilfe der Beispiel-App und des MQTT-Testclients](interact-lights-device-shadows.md) fort, wie im [Schritt 4: Ergebnisse überprüfen und nächste Schritte](#sample-app-shadow-review) Abschnitt dieses Tutorials beschrieben. Optional können Sie im folgenden Abschnitt auch mehr über den `shadow.py`-Beispielcode und dessen Verwendung des MQTT-Protokolls erfahren. ## Schritt 2: Geräte-SDK-Beispiel-App shadow.py prüfen In diesem Abschnitt wird die `shadow.py`-Beispiel-App aus dem **AWS IoT -Geräte-SDK v2 für Python** beschrieben, die in diesem Tutorial verwendet wird. Hier werden wir uns ansehen, wie es AWS IoT Core mithilfe des MQTT- und MQTT-über-WSS-Protokolls eine Verbindung herstellt. Die [AWS Common Runtime (AWS-CRT)](https://github.com/awslabs/aws-crt-python#aws-crt-python) -Bibliothek bietet Unterstützung für Low-Level-Kommunikationsprotokolle und ist im AWS IoT Device SDK v2 für Python enthalten. Dieses Tutorial verwendet zwar MQTT und MQTT über WSS, AWS IoT unterstützt aber Geräte, die HTTPS-Anfragen veröffentlichen. Ein Beispiel für ein Python-Programm, das eine HTTP-Nachricht von einem Gerät sendet, finden Sie im [HTTPS-Codebeispiel](http.md#codeexample) unter Verwendung der Python `requests`-Bibliothek. Informationen darüber, wie Sie eine fundierte Entscheidung darüber treffen können, welches Protokoll Sie für die Kommunikation mit Ihrem Gerät verwenden möchten, finden Sie unter [Wählen Sie ein Anwendungsprotokoll für Ihre Gerätekommunikation](protocols.md#protocol-selection). **MQTT** Das `shadow.py` Beispiel ruft `mtls_from_path` (hier gezeigt) in [https://github.com/awslabs/aws-crt-python/blob/89207bcf1387177034e02fe29e8e469ca45e39b7/awscrt/awsiot_mqtt_connection_builder.py](https://github.com/awslabs/aws-crt-python/blob/89207bcf1387177034e02fe29e8e469ca45e39b7/awscrt/awsiot_mqtt_connection_builder.py), um AWS IoT Core mithilfe des MQTT-Protokolls eine Verbindung herzustellen. `mtls_from_path`verwendet X.509-Zertifikate und TLS v1.2 zur Authentifizierung des Geräts. Die AWS-CRT-Bibliothek verarbeitet die untergeordneten Details dieser Verbindung. ``` mqtt_connection = mqtt_connection_builder.mtls_from_path( endpoint=args.endpoint, cert_filepath=args.cert, pri_key_filepath=args.key, ca_filepath=args.ca_file, client_bootstrap=client_bootstrap, on_connection_interrupted=on_connection_interrupted, on_connection_resumed=on_connection_resumed, client_id=args.client_id, clean_session=False, keep_alive_secs=6 ) ``` + `endpoint`ist Ihr AWS IoT Endpunkt, den Sie über die Befehlszeile eingegeben haben, und `client_id` ist die ID, die dieses Gerät in der eindeutig identifiziert. AWS-Region + `cert_filepath`, `pri_key_filepath` und `ca_filepath` sind die Pfade zu den Zertifikats- und privaten Schlüsseldateien des Geräts sowie zur Root-CA-Datei. + `client_bootstrap` ist das allgemeine Runtime-Objekt, das Socket-Kommunikationsaktivitäten verarbeitet und vor dem Aufruf von `mqtt_connection_builder.mtls_from_path` instanziiert wird. + `on_connection_interrupted` und `on_connection_resumed` sind Callback-Funktionen, die aufgerufen werden, wenn die Verbindung des Geräts unterbrochen und wieder aufgenommen wird. + `clean_session` gibt an, ob eine neue, persistente Sitzung gestartet werden soll oder ob, falls eine vorhanden ist, die Verbindung zu einer bestehenden wiederhergestellt werden soll. `keep_alive_secs` ist der Keep-Alive-Wert in Sekunden, der in der `CONNECT`-Anfrage gesendet werden soll. In diesem Intervall wird automatisch ein Ping gesendet. Der Server geht davon aus, dass die Verbindung unterbrochen ist, wenn er nach dem 1,5-fachen dieses Werts keinen Ping erhält. Das `shadow.py` Beispiel ruft auch `websockets_with_default_aws_signing` in [https://github.com/awslabs/aws-crt-python/blob/89207bcf1387177034e02fe29e8e469ca45e39b7/awscrt/awsiot_mqtt_connection_builder.py](https://github.com/awslabs/aws-crt-python/blob/89207bcf1387177034e02fe29e8e469ca45e39b7/awscrt/awsiot_mqtt_connection_builder.py) auf, um mithilfe des MQTT-Protokolls über WSS eine Verbindung zu AWS IoT Core herzustellen. MQTT über WSS verwendet ebenfalls dieselben Parameter wie MQTT und verwendet diese zusätzlichen Parameter: + `region`ist die AWS Signaturregion, die von der Signature V4-Authentifizierung verwendet `credentials_provider` wird, und sind die AWS Anmeldeinformationen, die für die Authentifizierung bereitgestellt werden. Die Region wird von der Befehlszeile aus übergeben, und das `credentials_provider`-Objekt wird unmittelbar vor dem Aufruf von `mqtt_connection_builder.websockets_with_default_aws_signing` instanziiert. + `websocket_proxy_options` sind die HTTP-Proxyoptionen, wenn ein Proxyhost verwendet wird. In der `shadow.py` Beispiel-App wird dieser Wert unmittelbar vor dem Aufruf von `mqtt_connection_builder.websockets_with_default_aws_signing` instanziiert. **Abonnieren von Shadow-Themen und -Ereignissen** Das `shadow.py`-Beispiel versucht, eine Verbindung herzustellen, und wartet, bis die Verbindung vollständig hergestellt ist. Wenn es nicht verbunden ist, werden Befehle in die Warteschlange gestellt. Sobald die Verbindung hergestellt ist, abonniert das Beispiel Delta-Ereignisse und Aktualisierungs- und Abrufnachrichten und veröffentlicht Nachrichten mit einer QoS-Stufe (Quality of Service) von 1 (`mqtt.QoS.AT_LEAST_ONCE`). Wenn ein Gerät eine Nachricht mit QoS Level 1 abonniert, speichert der Message Broker die Nachrichten, die das Gerät abonniert hat, bis sie an das Gerät gesendet werden können. Der Message Broker sendet die Nachrichten erneut, bis er eine `PUBACK`-Antwort vom Gerät erhält. Weitere Informationen zum MQTT-Protokoll finden Sie unter [Ansehen des MQTT-Protokolls](sdk-tutorials.md#sdk-tutorials-mqtt-review) und [MQTT](mqtt.md). Weitere Informationen zur Verwendung von MQTT, MQTT über WSS, persistente Sitzungen und QoS-Stufen, die in diesem Tutorial verwendet werden, finden Sie unter [Ansehen der Beispiel-App „pubsub.py“ des Device SDK](sdk-tutorials.md#sdk-tutorials-explore-sample). ## Schritt 3: Probleme mit der `shadow.py`-Beispiel-App beheben Wenn Sie die `shadow.py`-Beispiel-App ausführen, sollten im Terminal einige Meldungen und eine Aufforderung zur Eingabe eines `desired`-Werts angezeigt werden. Wenn das Programm einen Fehler ausgibt, können Sie zum Debuggen des Fehlers zunächst überprüfen, ob Sie den richtigen Befehl für Ihr System ausgeführt haben. In einigen Fällen weist die Fehlermeldung möglicherweise auf Verbindungsprobleme hin und sieht ähnlich aus wie: `Host name was invalid for dns resolution` oder `Connection was closed unexpectedly`. In solchen Fällen können Sie Folgendes überprüfen: + **Die Endpunktadresse im Befehl** Das `endpoint`-Argument in dem Befehl, den Sie zum Ausführen der Beispiel-App eingegeben haben (z. B. `a3qEXAMPLEffp-ats.iot.us-west-2.amazonaws.com`). Diesen Wert können Sie auch in der **AWS IoT Konsole** prüfen. Um zu überprüfen, ob Sie den richtigen Wert verwendet haben: 1. Wählen Sie in der **AWS IoT -Konsole** **Verwalten** und danach **Objekte**. 1. Wählen Sie das Objekt aus, das Sie für Ihre Beispiel-App erstellt haben (z. B. **My\$1Light\$1Bulb**), und wählen Sie dann **Interagieren**. Ihr Endpunkt wird im Abschnitt **HTTPS** auf der Seite mit den Objekt-Details angezeigt. Sie sollten auch eine Meldung sehen, die besagt: `This thing already appears to be connected.` + **Aktivierung des Zertifikats überprüfen** Zertifikate authentifizieren Ihr Gerät mit AWS IoT Core. Um zu überprüfen, ob Ihr Zertifikat aktiv ist: 1. Wählen Sie in der **AWS IoT -Konsole** **Verwalten** und danach **Objekte**. 1. Wählen Sie das Objekt aus, das Sie für Ihre Beispiel-App erstellt haben (z. B. **My\$1Light\$1Bulb**), und wählen Sie dann **Sicherheit**. 1. Wählen Sie das Zertifikat aus und wählen Sie dann auf der Detailseite des Zertifikats die Option „Zertifikat auswählen“ und dann auf der Detailseite des Zertifikats die Option **Aktionen** aus. Wenn in der Dropdownliste **Aktivieren** nicht verfügbar ist und Sie nur **Deaktivieren** auswählen können, ist Ihr Zertifikat aktiv. Wenn nicht, wählen Sie **Aktivieren** und führen Sie das Beispielprogramm erneut aus. Wenn das Programm immer noch nicht ausgeführt wird, überprüfen Sie die Namen der Zertifikatsdateien im `certs`-Ordner. + **Überprüfen der mit der Objekt-Ressource verknüpften Richtlinie** Zertifikate authentifizieren zwar Ihr Gerät, aber AWS IoT Richtlinien gestatten es dem Gerät, bestimmte AWS IoT Vorgänge auszuführen, wie z. B. das Abonnieren oder Veröffentlichen von MQTT-Themen, die für MQTT reserviert sind. Um zu überprüfen, ob die richtige Richtlinie angehängt ist: 1. Suchen Sie das Zertifikat wie zuvor beschrieben und wählen Sie dann **Richtlinien** aus. 1. Wählen Sie die angezeigte Richtlinie aus und überprüfen Sie, ob sie die Aktionen `connect`, `subscribe`, `receive` und `publish` beschreibt, die dem Gerät die Erlaubnis geben, die reservierten MQTT-Themen zu veröffentlichen und zu abonnieren. Eine Beispielrichtlinie finden Sie unter [Schritt 1: Erstellen Sie eine AWS IoT Richtlinie für den Device Shadow](shadow-provision-cloud.md#create-policy-shadow). Wenn Ihnen Fehlermeldungen angezeigt werden, die auf Probleme beim Herstellen einer Verbindung hinweisen AWS IoT, kann dies an den Berechtigungen liegen, die Sie für die Richtlinie verwenden. In diesem Fall empfehlen wir, mit einer Richtlinie zu beginnen, die vollen Zugriff auf AWS IoT Ressourcen gewährt, und dann das Beispielprogramm erneut auszuführen. Sie können entweder die aktuelle Richtlinie bearbeiten oder die aktuelle Richtlinie auswählen, **Trennen** auswählen und dann eine weitere Richtlinie erstellen, die vollen Zugriff gewährt, und diese an Ihre Objekt-Ressource anhängen. Sie können die Richtlinie später nur auf die Aktionen und Richtlinien beschränken, die Sie zur Ausführung des Programms benötigen. **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:*" ], "Resource": "*" } ] } ``` + **Überprüfen der Installation Ihres Geräte-SDKs** Wenn das Programm immer noch nicht ausgeführt wird, können Sie das Geräte-SDK erneut installieren, um sicherzustellen, dass Ihre SDK-Installation vollständig und korrekt ist. ## Schritt 4: Ergebnisse überprüfen und nächste Schritte **In diesem Kurs haben Sie gelernt, wie Sie:** + Installieren Sie die erforderliche Software, Tools und das AWS IoT Geräte-SDK für Python. + Die Beispiel-App `shadow.py` das MQTT-Protokoll zum Abrufen und Aktualisieren des aktuellen Status des Schattens verwendet. + Führen Sie die Beispiel-App für Device Shadows aus und beobachten Sie die Aktualisierung des Shadow-Dokuments in der AWS IoT Konsole. Sie haben darüber hinaus gelernt, Probleme und Fehler bei der Ausführung des Programms zu beheben. **Nächste Schritte** Sie können jetzt die `shadow.py`-Beispielanwendung ausführen und Geräteschatten verwenden, um den Status zu kontrollieren. Sie können die Aktualisierungen des Schattendokuments in der AWS IoT -Konsole verfolgen und Delta-Ereignisse beobachten, auf die die Beispiel-App reagiert. Mit dem MQTT-Testclient können Sie die reservierten Schattenthemen abonnieren und die Nachrichten beobachten, die die Themen bei der Ausführung des Beispielprogramms erhalten. Weitere Informationen darüber, wie Sie dieses Tutorial ausführen, finden Sie unter [Tutorial: Interaktion mit Geräteschatten mithilfe der Beispiel-App und des MQTT-Testclients](interact-lights-device-shadows.md).